Section (3) ldap_get_option
Name
ldap_get_option, ldap_set_option — LDAP option handling routines
Synopsis
#include <ldap.h>
int
ldap_get_option( |
LDAP *ld, |
int option, | |
void *outvalue) ; |
int
ldap_set_option( |
LDAP *ld, |
int option, | |
const void *invalue) ; |
DESCRIPTION
These routines provide access to options stored either in
a LDAP handle or as global options, where applicable. They
make use of a neutral interface, where the type of the value
either retrieved by ldap_get_option(3) or set
by ldap_set_option(3) is cast
to void *. The actual
type is determined based on the value of the option
argument. Global options
are set/retrieved by passing a NULL LDAP handle. LDAP handles
inherit their default settings from the global options in
effect at the time the handle is created.
LDAP_OPT_API_FEATURE_INFO
-
Fills-in a LDAPAPIFeatureInfo;
outvalue
must be a LDAPAPIFeatureInfo *, pointing to an already allocated struct. Theldapaif_info_version
field of the struct must be initialized toLDAP_FEATURE_INFO_VERSION
before making the call. Theldapaif_name
field must be set to the name of a feature to query. This is a read-only option. LDAP_OPT_API_INFO
-
Fills-in a LDAPAPIInfo;
outvalue
must be a LDAPAPIInfo *, pointing to an already allocated struct. Theldapai_info_version
field of the struct must be initialized toLDAP_API_INFO_VERSION
before making the call. If the version passed in does not match the current library version, the expected version number will be stored in the struct and the call will fail. The caller is responsible for freeing the elements of theldapai_extensions
array and the array itself using ldap_memfree(3). The caller must also free theldapi_vendor_name
. This is a read-only option. LDAP_OPT_CLIENT_CONTROLS
-
Sets/gets the client-side controls to be used for all operations. This is now deprecated as modern LDAP C API provides replacements for all main operations which accepts client-side controls as explicit arguments; see for example ldap_search_ext(3), ldap_add_ext(3), ldap_modify_ext(3) and so on.
outvalue
must be LDAPControl ***, and the caller is responsible of freeing the returned controls, if any, by calling ldap_controls_free(3), whileinvalue
must be LDAPControl *const *; the library duplicates the controls passed viainvalue
. LDAP_OPT_CONNECT_ASYNC
-
Sets/gets the status of the asynchronous connect flag.
invalue
should either beLDAP_OPT_OFF
orLDAP_OPT_ON
;outvalue
must be int *. When set, the library will call connect(2) and return, without waiting for response. This leaves the handle in a connecting state. Subsequent calls to library routines will poll for completion of the connect before performing further operations. As a consequence, library calls that need to establish a connection with a DSA do not block even for the network timeout (optionLDAP_OPT_NETWORK_TIMEOUT
). This option is OpenLDAP specific. LDAP_OPT_CONNECT_CB
-
This option allows to set a connect callback.
invalue
must be a const struct ldap_conncb *. Callbacks are executed in last in-first served order. Handle-specific callbacks are executed first, followed by global ones. Right before freeing the callback structure, thelc_del
callback handler is passed aNULL
Sockbuf. Calling ldap_get_option(3) for this option removes the callback whose pointer matchesoutvalue
. This option is OpenLDAP specific. LDAP_OPT_DEBUG_LEVEL
-
Sets/gets the debug level of the client library.
invalue
must be a const int *;outvalue
must be a int *. Valid debug levels areLDAP_DEBUG_ANY
,LDAP_DEBUG_ARGS
,LDAP_DEBUG_BER
,LDAP_DEBUG_CONNS
,LDAP_DEBUG_NONE
,LDAP_DEBUG_PACKETS
,LDAP_DEBUG_PARSE
, andLDAP_DEBUG_TRACE
. This option is OpenLDAP specific. LDAP_OPT_DEFBASE
-
Sets/gets a string containing the DN to be used as default base for search operations.
outvalue
must be a char **, and the caller is responsible of freeing the returned string by calling ldap_memfree(3), whileinvalue
must be a const char *; the library duplicates the corresponding string. This option is OpenLDAP specific. LDAP_OPT_DEREF
-
Sets/gets the value that defines when alias dereferencing must occur.
invalue
must be const int *;outvalue
must be int *. They cannot be NULL. The value of *invalue
should be one ofLDAP_DEREF_NEVER
(the default),LDAP_DEREF_SEARCHING
,LDAP_DEREF_FINDING
, orLDAP_DEREF_ALWAYS
. Note that this has ever been the only means to determine alias dereferencing within search operations. LDAP_OPT_DESC
-
Returns the file descriptor associated to the socket buffer of the LDAP handle passed in as
ld
;outvalue
must be a int *. This is a read-only, handle-specific option. LDAP_OPT_DIAGNOSTIC_MESSAGE
-
Sets/gets a string containing the error string associated to the LDAP handle. This option was formerly known as
LDAP_OPT_ERROR_STRING
.outvalue
must be a char **, and the caller is responsible of freeing the returned string by calling ldap_memfree(3), whileinvalue
must be a char *; the library duplicates the corresponding string. LDAP_OPT_HOST_NAME
-
Sets/gets a space-separated list of hosts to be contacted by the library when trying to establish a connection. This is now deprecated in favor of
LDAP_OPT_URI
.outvalue
must be a char **, and the caller is responsible of freeing the resulting string by calling ldap_memfree(3), whileinvalue
must be a const char *; the library duplicates the corresponding string. LDAP_OPT_MATCHED_DN
-
Sets/gets a string containing the matched DN associated to the LDAP handle.
outvalue
must be a char **, and the caller is responsible of freeing the returned string by calling ldap_memfree(3), whileinvalue
must be a const char *; the library duplicates the corresponding string. LDAP_OPT_NETWORK_TIMEOUT
-
Sets/gets the network timeout value after which poll(2)/select(2) following a connect(2) returns in case of no activity.
outvalue
must be a struct timeval ** (the caller has to free *outvalue
),
andinvalue
must be a const struct timeval *. They cannot be NULL. Using a struct with seconds set to −1 results in an infinite timeout, which is the default. This option is OpenLDAP specific. LDAP_OPT_PROTOCOL_VERSION
-
Sets/gets the protocol version.
outvalue
andinvalue
must be int *. LDAP_OPT_REFERRAL_URLS
-
Sets/gets an array containing the referral URIs associated to the LDAP handle.
outvalue
must be a char ***, and the caller is responsible of freeing the returned string by calling ldap_memvfree(3), whileinvalue
must be a NULL-terminated char *const *; the library duplicates the corresponding string. This option is OpenLDAP specific. LDAP_OPT_REFERRALS
-
Determines whether the library should implicitly chase referrals or not.
invalue
must be const int *; its value should either beLDAP_OPT_OFF
orLDAP_OPT_ON
.outvalue
must be int *. LDAP_OPT_RESTART
-
Determines whether the library should implicitly restart connections (FIXME).
invalue
must be const int *; its value should either beLDAP_OPT_OFF
orLDAP_OPT_ON
.outvalue
must be int *. LDAP_OPT_RESULT_CODE
-
Sets/gets the LDAP result code associated to the handle. This option was formerly known as
LDAP_OPT_ERROR_NUMBER
.invalue
must be a const int *.outvalue
must be a int *. LDAP_OPT_SERVER_CONTROLS
-
Sets/gets the server-side controls to be used for all operations. This is now deprecated as modern LDAP C API provides replacements for all main operations which accepts server-side controls as explicit arguments; see for example ldap_search_ext(3), ldap_add_ext(3), ldap_modify_ext(3) and so on.
outvalue
must be LDAPControl ***, and the caller is responsible of freeing the returned controls, if any, by calling ldap_controls_free(3), whileinvalue
must be LDAPControl *const *; the library duplicates the controls passed viainvalue
. LDAP_OPT_SESSION_REFCNT
-
Returns the reference count associated with the LDAP handle passed in as
ld
;outvalue
must be a int *. This is a read-only, handle-specific option. This option is OpenLDAP specific. LDAP_OPT_SIZELIMIT
-
Sets/gets the value that defines the maximum number of entries to be returned by a search operation.
invalue
must be const int *, whileoutvalue
must be int *; They cannot be NULL. LDAP_OPT_SOCKBUF
-
Returns a pointer to the socket buffer of the LDAP handle passed in as
ld
;outvalue
must be a Sockbuf **. This is a read-only, handle-specific option. This option is OpenLDAP specific. LDAP_OPT_TIMELIMIT
-
Sets/gets the value that defines the time limit after which a search operation should be terminated by the server.
invalue
must be const int *, whileoutvalue
must be int *, and they cannot be NULL. LDAP_OPT_TIMEOUT
-
Sets/gets a timeout value for the synchronous API calls.
outvalue
must be a struct timeval ** (the caller has to free *outvalue
),
andinvalue
must be a struct timeval *, and they cannot be NULL. Using a struct with seconds set to −1 results in an infinite timeout, which is the default. This option is OpenLDAP specific. LDAP_OPT_URI
-
Sets/gets a comma- or space-separated list of URIs to be contacted by the library when trying to establish a connection.
outvalue
must be a char **, and the caller is responsible of freeing the resulting string by calling ldap_memfree(3), whileinvalue
must be a const char *; the library parses the string into a list ofLDAPURLDesc
structures, so the invocation of ldap_set_option(3) may fail if URL parsing fails. URIs may only contain theschema
, thehost
, and theport
fields. This option is OpenLDAP specific.
SASL OPTIONS
The SASL options are OpenLDAP specific.
LDAP_OPT_X_SASL_AUTHCID
-
Gets the SASL authentication identity;
outvalue
must be a char **, its content needs to be freed by the caller using ldap_memfree(3). LDAP_OPT_X_SASL_AUTHZID
-
Gets the SASL authorization identity;
outvalue
must be a char **, its content needs to be freed by the caller using ldap_memfree(3). LDAP_OPT_X_SASL_MAXBUFSIZE
-
Gets/sets SASL maximum buffer size;
invalue
must be const ber_len_t *, whileoutvalue
must be ber_len_t *. See alsoLDAP_OPT_X_SASL_SECPROPS
. LDAP_OPT_X_SASL_MECH
-
Gets the SASL mechanism;
outvalue
must be a char **, its content needs to be freed by the caller using ldap_memfree(3). LDAP_OPT_X_SASL_MECHLIST
-
Gets the list of the available mechanisms, in form of a NULL-terminated array of strings;
outvalue
must be char ***. The caller must not free or otherwise muck with it. LDAP_OPT_X_SASL_NOCANON
-
Sets/gets the NOCANON flag. When unset, the hostname is canonicalized.
invalue
must be const int *; its value should either beLDAP_OPT_OFF
orLDAP_OPT_ON
.outvalue
must be int *. LDAP_OPT_X_SASL_REALM
-
Gets the SASL realm;
outvalue
must be a char **, its content needs to be freed by the caller using ldap_memfree(3). LDAP_OPT_X_SASL_SECPROPS
-
Sets the SASL secprops;
invalue
must be a char *, containing a comma-separated list of properties. Legal values are:none
,nodict
,noplain
,noactive
,passcred
,forwardsec
,noanonymous
,minssf=<minssf>
,maxssf=<maxssf>
,maxbufsize=<maxbufsize>
. LDAP_OPT_X_SASL_SSF
-
Gets the SASL SSF;
outvalue
must be a ber_len_t *. LDAP_OPT_X_SASL_SSF_EXTERNAL
-
Sets the SASL SSF value related to an authentication performed using an EXTERNAL mechanism;
invalue
must be a const ber_len_t *. LDAP_OPT_X_SASL_SSF_MAX
-
Gets/sets SASL maximum SSF;
invalue
must be const ber_len_t *, whileoutvalue
must be ber_len_t *. See alsoLDAP_OPT_X_SASL_SECPROPS
. LDAP_OPT_X_SASL_SSF_MIN
-
Gets/sets SASL minimum SSF;
invalue
must be const ber_len_t *, whileoutvalue
must be ber_len_t *. See alsoLDAP_OPT_X_SASL_SECPROPS
. LDAP_OPT_X_SASL_USERNAME
-
Gets the SASL username;
outvalue
must be a char **. Its content needs to be freed by the caller using ldap_memfree(3).
TCP OPTIONS
The TCP options are OpenLDAP specific. Mainly intended for use with Linux, they may not be portable.
LDAP_OPT_X_KEEPALIVE_IDLE
-
Sets/gets the number of seconds a connection needs to remain idle before TCP starts sending keepalive probes.
invalue
must be const int *;outvalue
must be int *. LDAP_OPT_X_KEEPALIVE_PROBES
-
Sets/gets the maximum number of keepalive probes TCP should send before dropping the connection.
invalue
must be const int *;outvalue
must be int *. LDAP_OPT_X_KEEPALIVE_INTERVAL
-
Sets/gets the interval in seconds between individual keepalive probes.
invalue
must be const int *;outvalue
must be int *.
TLS OPTIONS
The TLS options are OpenLDAP specific.
LDAP_OPT_X_TLS_CACERTDIR
-
Sets/gets the path of the directory containing CA certificates.
invalue
must be const char *;outvalue
must be char **, and its contents need to be freed by the caller using ldap_memfree(3). LDAP_OPT_X_TLS_CACERTFILE
-
Sets/gets the full-path of the CA certificate file.
invalue
must be const char *;outvalue
must be char **, and its contents need to be freed by the caller using ldap_memfree(3). LDAP_OPT_X_TLS_CERTFILE
-
Sets/gets the full-path of the certificate file.
invalue
must be const char *;outvalue
must be char **, and its contents need to be freed by the caller using ldap_memfree(3). LDAP_OPT_X_TLS_CIPHER_SUITE
-
Sets/gets the allowed cipher suite.
invalue
must be const char *;outvalue
must be char **, and its contents need to be freed by the caller using ldap_memfree(3). LDAP_OPT_X_TLS_CONNECT_ARG
-
Sets/gets the connection callback argument.
invalue
must be const void *;outvalue
must be void **. LDAP_OPT_X_TLS_CONNECT_CB
-
Sets/gets the connection callback handle.
invalue
must be const LDAP_TLS_CONNECT_CB *;outvalue
must be LDAP_TLS_CONNECT_CB **. LDAP_OPT_X_TLS_CRLCHECK
-
Sets/gets the CRL evaluation strategy, one of
LDAP_OPT_X_TLS_CRL_NONE
,LDAP_OPT_X_TLS_CRL_PEER
, orLDAP_OPT_X_TLS_CRL_ALL
.invalue
must be const int *;outvalue
must be int *. Requires OpenSSL. LDAP_OPT_X_TLS_CRLFILE
-
Sets/gets the full-path of the CRL file.
invalue
must be const char *;outvalue
must be char **, and its contents need to be freed by the caller using ldap_memfree(3). This option is only valid for GnuTLS. LDAP_OPT_X_TLS_CTX
-
Sets/gets the TLS library context. New TLS sessions will inherit their default settings from this library context.
invalue
must be const void *;outvalue
must be void **. When using the OpenSSL library this is an SSL_CTX*. When using other crypto libraries this is a pointer to an OpenLDAP private structure. Applications generally should not use this option or attempt to manipulate this structure. LDAP_OPT_X_TLS_DHFILE
-
Gets/sets the full-path of the file containing the parameters for Diffie-Hellman ephemeral key exchange.
invalue
must be const char *;outvalue
must be char **, and its contents need to be freed by the caller using ldap_memfree(3). Ignored by GnuTLS and Mozilla NSS. LDAP_OPT_X_TLS_KEYFILE
-
Sets/gets the full-path of the certificate key file.
invalue
must be const char *;outvalue
must be char **, and its contents need to be freed by the caller using ldap_memfree(3). LDAP_OPT_X_TLS_NEWCTX
-
Instructs the library to create a new TLS library context.
invalue
must be const int *. A non-zero value pointed to byinvalue
tells the library to create a context for a server. LDAP_OPT_X_TLS_PROTOCOL_MIN
-
Sets/gets the minimum protocol version.
invalue
must be const int *;outvalue
must be int *. LDAP_OPT_X_TLS_RANDOM_FILE
-
Sets/gets the random file when
/dev/random
and/dev/urandom
are not available.invalue
must be const char *;outvalue
must be char **, and its contents need to be freed by the caller using ldap_memfree(3). Ignored by GnuTLS older than version 2.2. Ignored by Mozilla NSS. LDAP_OPT_X_TLS_REQUIRE_CERT
-
Sets/gets the peer certificate checking strategy, one of
LDAP_OPT_X_TLS_NEVER
,LDAP_OPT_X_TLS_HARD
,LDAP_OPT_X_TLS_DEMAND
,LDAP_OPT_X_TLS_ALLOW
,LDAP_OPT_X_TLS_TRY
. LDAP_OPT_X_TLS_SSL_CTX
-
Gets the TLS session context associated with this handle.
outvalue
must be void **. When using the OpenSSL library this is an SSL*. When using other crypto libraries this is a pointer to an OpenLDAP private structure. Applications generally should not use this option.
ERRORS
On success, the functions return LDAP_OPT_SUCCESS
, while they may return
LDAP_OPT_ERROR
to indicate a
generic option handling error. Occasionally, more specific
errors can be returned, like LDAP_NO_MEMORY to indicate a failure in
memory allocation.
NOTES
The LDAP libraries with the LDAP_OPT_REFERRALS
option set to
LDAP_OPT_ON
(default value)
automatically follow referrals using an anonymous bind.
Application developers are encouraged to either implement
consistent referral chasing features, or explicitly disable
referral chasing by setting that option to LDAP_OPT_OFF
.
The protocol version used by the library defaults to
LDAPv2 (now historic), which corresponds to the LDAP_VERSION2
macro. Application developers
are encouraged to explicitly set LDAP_OPT_PROTOCOL_VERSION
to LDAPv3, using
the LDAP_VERSION3
macro, or to
allow users to select the protocol version.
ACKNOWLEDGEMENTS
OpenLDAP Software is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. OpenLDAP Software is derived from the University of Michigan LDAP 3.3 Release.