FreeBSD Manual Pages
LDAP_GET_OPTION(3) Library Functions Manual LDAP_GET_OPTION(3) NAME ldap_get_option, ldap_set_option - LDAP option handling routines LIBRARY OpenLDAP LDAP (libldap, -lldap) 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/re- trieved by passing a NULL LDAP handle. LDAP handles inherit their default settings from the global options in effect at the time the handle is cre- ated. LDAP_OPT_API_FEATURE_INFO Fills-in a LDAPAPIFeatureInfo; outvalue must be a LDAPAPIFeatureInfo *, pointing to an already allocated struct. The ldapaif_info_ver- sion field of the struct must be initialized to LDAP_FEA- TURE_INFO_VERSION before making the call. The ldapaif_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. The ldapai_info_version field of the struct must be initialized to LDAP_API_INFO_VERSION before making the call. If the version passed in does not match the current li- brary version, the expected version number will be stored in the struct and the call will fail. The caller is responsible for free- ing the elements of the ldapai_extensions array and the array itself using ldap_memfree(3). The caller must also free the ldapi_ven- dor_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 ex- plicit 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 re- turned controls, if any, by calling ldap_controls_free(3), while in- value must be LDAPControl *const *; the library duplicates the con- trols passed via invalue. LDAP_OPT_CONNECT_ASYNC Sets/gets the status of the asynchronous connect flag. invalue should either be LDAP_OPT_OFF or LDAP_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, li- brary calls that need to establish a connection with a DSA do not block even for the network timeout (option LDAP_OPT_NETWORK_TIME- OUT). 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, fol- lowed by global ones. Right before freeing the callback structure, the lc_del callback handler is passed a NULL Sockbuf. Calling ldap_get_option(3) for this option removes the callback whose pointer matches outvalue. 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 are LDAP_DEBUG_ANY, LDAP_DEBUG_ARGS, LDAP_DEBUG_BER, LDAP_DEBUG_CONNS, LDAP_DEBUG_NONE, LDAP_DEBUG_PACKETS, LDAP_DEBUG_PARSE, and LDAP_DE- BUG_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_mem- free(3), while invalue must be a const char *; the library dupli- cates the corresponding string. This option is OpenLDAP specific. LDAP_OPT_DEREF Sets/gets the value that defines when alias dereferencing must oc- cur. invalue must be const int *; outvalue must be int *. They cannot be NULL. The value of *invalue should be one of LDAP_DEREF_NEVER (the default), LDAP_DEREF_SEARCHING, LDAP_DEREF_FINDING, or LDAP_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_ER- ROR_STRING. outvalue must be a char **, and the caller is responsi- ble of freeing the returned string by calling ldap_memfree(3), while invalue 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 li- brary 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), while invalue 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), while in- value must be a const char *; the library duplicates the correspond- ing 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 using ldap_memfree(3)), and invalue 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 OpenL- DAP specific. LDAP_OPT_PROTOCOL_VERSION Sets/gets the protocol version. outvalue and invalue 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 respon- sible of freeing the returned string by calling ldap_memvfree(3), while invalue must be a NULL-terminated char *const *; the library duplicates the corresponding string. This option is OpenLDAP spe- cific. LDAP_OPT_REFERRALS Determines whether the library should implicitly chase referrals or not. invalue must be const int *; its value should either be LDAP_OPT_OFF or LDAP_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 be LDAP_OPT_OFF or LDAP_OPT_ON. outvalue must be int *. LDAP_OPT_RESULT_CODE Sets/gets the LDAP result code associated to the handle. This op- tion 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 ex- plicit 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 re- turned controls, if any, by calling ldap_controls_free(3), while in- value must be LDAPControl *const *; the library duplicates the con- trols passed via invalue. 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 *, while outvalue 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_SOCKET_BIND_ADDRESSES Sets/gets a space-separated list of IP Addresses used as binding in- terface to remote server when trying to establish a connection. Only one valid IPv4 address and/or one valid IPv6 address are allowed in the list. outvalue must be a char **, and the caller is responsible of freeing the returned string by calling ldap_memfree(3), while in- value must be a const char *; the library duplicates the correspond- ing string. 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 *, while outvalue 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 using ldap_memfree(3)), and invalue 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), while invalue must be a const char *; the library parses the string into a list of LDAPURLDesc structures, so the invocation of ldap_set_option(3) may fail if URL parsing fails. URIs may only contain the schema, the host, and the port fields. This option is OpenLDAP specific. LDAP_OPT_KEEPCONN Instructs ldap_result(3) to keep the connection open on read error or if Notice of Disconnection is received. In these cases, the con- nection should be closed by the caller. This option is OpenLDAP specific. LDAP_OPT_TCP_USER_TIMEOUT Allows to configure TCP_USER_TIMEOUT in milliseconds on the connec- tion, overriding the operating system setting. This option is OpenLDAP specific and supported only on Linux 2.6.37 or higher. in- value must be a const unsigned int *; outvalue must be an unsigned int *. SASL OPTIONS The SASL options are OpenLDAP specific and unless otherwise noted, require an LDAP handle to be passed. 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 *, while outvalue must be ber_len_t *. See also LDAP_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-termi- nated array of strings; outvalue must be char ***. The caller must not free or otherwise muck with it. This option can be used glob- ally. LDAP_OPT_X_SASL_NOCANON Sets/gets the NOCANON flag. When unset, the hostname is canonical- ized. invalue must be const int *; its value should either be LDAP_OPT_OFF or LDAP_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 *, while outvalue must be ber_len_t *. See also LDAP_OPT_X_SASL_SECPROPS. LDAP_OPT_X_SASL_SSF_MIN Gets/sets SASL minimum SSF; invalue must be const ber_len_t *, while outvalue must be ber_len_t *. See also LDAP_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). LDAP_OPT_X_SASL_CBINDING Sets/gets the channel-binding type to use in SASL, one of LDAP_OPT_X_SASL_CBINDING_NONE (the default), LDAP_OPT_X_SASL_CBIND- ING_TLS_UNIQUE the "tls-unique" type from RFC 5929. LDAP_OPT_X_SASL_CBINDING_TLS_ENDPOINT the "tls-server-end-point" from RFC 5929, compatible with Windows. invalue must be const int *; outvalue must be int *. 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 be- fore 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 directories containing CA certificates. Multiple directories may be specified, separated by a semi-colon. invalue must be const char *; outvalue must be char **, and its con- tents 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 Gets the cipher being used on an established TLS session. outvalue must be char **, and its contents need to be freed by the caller us- ing 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, or LDAP_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 li- brary 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). LDAP_OPT_X_TLS_ECNAME Gets/sets the name of the curve(s) used for elliptic curve key ex- changes. invalue must be const char *; outvalue must be char **, and its contents need to be freed by the caller using ldap_mem- free(3). Ignored by GnuTLS. In GnuTLS a curve may be selected in the cipher suite specification. 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 by invalue tells the library to create a context for a server. LDAP_OPT_X_TLS_PEERCERT Gets the peer's certificate in DER format from an established TLS session. outvalue must be struct berval *, and the data it returns needs to be freed by the caller using ldap_memfree(3). LDAP_OPT_X_TLS_PROTOCOL_MAX Sets/gets the maximum protocol version. invalue must be const int *; outvalue must be int *. 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_mem- free(3). Ignored by GnuTLS older than version 2.2. 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_REQUIRE_SAN Sets/gets the peer certificate subjectAlternativeName 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 op- tion. LDAP_OPT_X_TLS_VERSION Gets the TLS version being used on an established TLS session. out- value must be char **, and its contents need to be freed by the caller using ldap_memfree(3). LDAP_OPT_X_TLS_PEERKEY_HASH Sets the (public) key that the application expects the peer to be using. invalue must be const char * containing the base64 encoding of the expected peer's key or in the format <hashalg>:<peerkey hash base64 encoded> where as a TLS session is established, the library will hash the peer's key with the provided hash algorithm and com- pare it with value provided and will only allow the session to con- tinue if they match. This happens regardless of certificate checking strategy. The list of supported hashalg values depends on the crypto library used, check its documentation to get a list. 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 refer- ral 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. SEE ALSO ldap(3), ldap_error(3), RFC 4422 (http://www.rfc-editor.org), ACKNOWLEDGEMENTS OpenLDAP Software is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. OpenLDAP Software is derived from the Univer- sity of Michigan LDAP 3.3 Release. OpenLDAP 2.6.13 2026/03/09 LDAP_GET_OPTION(3)
NAME | LIBRARY | SYNOPSIS | DESCRIPTION | SASL OPTIONS | TCP OPTIONS | TLS OPTIONS | ERRORS | NOTES | SEE ALSO | ACKNOWLEDGEMENTS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=ldap_get_option&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>