HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. |  |
NAME |LIBRARY |SYNOPSIS |DESCRIPTION |SASL OPTIONS |TCP OPTIONS |TLS OPTIONS |ERRORS |NOTES |SEE ALSO |ACKNOWLEDGEMENTS |COLOPHON | |
LDAP_GET_OPTION(3) Library Functions ManualLDAP_GET_OPTION(3)ldap_get_option, ldap_set_option - LDAP option handling routines
OpenLDAP LDAP (libldap, -lldap)
#include <ldap.h>int ldap_get_option(LDAP *ld, intoption, void *outvalue);int ldap_set_option(LDAP *ld, intoption, const void *invalue);
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 byldap_get_option(3) or set byldap_set_option(3) is cast tovoid *. The actual type is determined based on the value of theoption 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 aLDAPAPIFeatureInfo;outvaluemust be aLDAPAPIFeatureInfo *, pointing to an already allocated struct. Theldapaif_info_versionfield of the struct must be initialized toLDAP_FEATURE_INFO_VERSIONbefore making the call. Theldapaif_namefield must be set to the name of a feature to query. This is a read-only option.LDAP_OPT_API_INFO Fills-in aLDAPAPIInfo;outvaluemust be aLDAPAPIInfo *, pointing to an already allocated struct. Theldapai_info_versionfield of the struct must be initialized toLDAP_API_INFO_VERSIONbefore 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_extensionsarray and the array itself usingldap_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 exampleldap_search_ext(3),ldap_add_ext(3),ldap_modify_ext(3) and so on.outvaluemust beLDAPControl ***, and the caller is responsible of freeing the returned controls, if any, by callingldap_controls_free(3), whileinvaluemust beLDAPControl *const *; the library duplicates the controls passed viainvalue.LDAP_OPT_CONNECT_ASYNC Sets/gets the status of the asynchronous connect flag.invalueshould either beLDAP_OPT_OFForLDAP_OPT_ON;outvaluemust beint *. When set, the library will callconnect(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.invaluemust be aconst 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_delcallback handler is passed aNULL Sockbuf. Callingldap_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 aconst int *;outvaluemust be aint *. 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.outvaluemust be achar **, and the caller is responsible of freeing the returned string by callingldap_memfree(3), whileinvaluemust be aconst 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.invaluemust beconst int *;outvaluemust beint *. They cannot be NULL. The value of*invalueshould 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 asld;outvaluemust be aint*. 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 asLDAP_OPT_ERROR_STRING.outvaluemust be achar **, and the caller is responsible of freeing the returned string by callingldap_memfree(3), whileinvaluemust be achar *; 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 ofLDAP_OPT_URI.outvaluemust be achar **, and the caller is responsible of freeing the resulting string by callingldap_memfree(3), whileinvalue must be aconst char *; the library duplicates the corresponding string.LDAP_OPT_MATCHED_DN Sets/gets a string containing the matched DN associated to the LDAP handle.outvaluemust be achar **, and the caller is responsible of freeing the returned string by callingldap_memfree(3), whileinvaluemust be aconst char*; the library duplicates the corresponding string.LDAP_OPT_NETWORK_TIMEOUT Sets/gets the network timeout value after whichpoll(2)/select(2) following aconnect(2) returns in case of no activity.outvaluemust be astruct timeval **(the caller has to free*outvalueusingldap_memfree(3)), andinvaluemust be aconst 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.outvalueandinvaluemust beint *.LDAP_OPT_REFERRAL_URLS Sets/gets an array containing the referral URIs associated to the LDAP handle.outvaluemust be achar ***, and the caller is responsible of freeing the returned string by callingldap_memvfree(3), whileinvaluemust be a NULL- terminatedchar *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.invaluemust beconst int *; its value should either beLDAP_OPT_OFForLDAP_OPT_ON.outvalue must beint *.LDAP_OPT_REFHOPLIMIT Set the maximum number of referrals to chase for a request.invaluemust beconst int *;outvaluemust be aint *. They cannot be NULL. This option is OpenLDAP specific.LDAP_OPT_RESTART Determines whether the library should implicitly restart connections (FIXME).invaluemust beconst int *; its value should either beLDAP_OPT_OFForLDAP_OPT_ON.outvaluemust beint *.LDAP_OPT_RESULT_CODE Sets/gets the LDAP result code associated to the handle. This option was formerly known asLDAP_OPT_ERROR_NUMBER.invaluemust be aconst int *.outvaluemust be aint *.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 exampleldap_search_ext(3),ldap_add_ext(3),ldap_modify_ext(3) and so on.outvaluemust beLDAPControl ***, and the caller is responsible of freeing the returned controls, if any, by callingldap_controls_free(3), whileinvaluemust beLDAPControl *const *; the library duplicates the controls passed viainvalue.LDAP_OPT_SESSION_REFCNT Returns the reference count associated with the LDAP handle passed in asld;outvaluemust be aint *. 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.invaluemust beconst int *, whileoutvaluemust beint *; They cannot be NULL.LDAP_OPT_SOCKBUF Returns a pointer to the socket buffer of the LDAP handle passed in asld;outvaluemust be aSockbuf **. 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 interface 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.outvaluemust be achar **, and the caller is responsible of freeing the returned string by callingldap_memfree(3), whileinvalue must be aconst char *; the library duplicates the corresponding string.LDAP_OPT_TIMELIMIT Sets/gets the value that defines the time limit after which a search operation should be terminated by the server.invaluemust beconst int *, whileoutvaluemust beint *, and they cannot be NULL.LDAP_OPT_TIMEOUT Sets/gets a timeout value for the synchronous API calls.outvaluemust be astruct timeval **(the caller has to free*outvalueusingldap_memfree(3)), andinvaluemust be astruct 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.outvaluemust be achar **, and the caller is responsible of freeing the resulting string by callingldap_memfree(3), whileinvaluemust be aconst char *; the library parses the string into a list ofLDAPURLDesc structures, so the invocation ofldap_set_option(3) may fail if URL parsing fails. URIs may only contain theschema, thehost, and theportfields. This option is OpenLDAP specific.LDAP_OPT_KEEPCONN Instructsldap_result(3) to keep the connection open on read error or if Notice of Disconnection is received. In these cases, the connection 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 connection, overriding the operating system setting. This option is OpenLDAP specific and supported only on Linux 2.6.37 or higher.invaluemust be aconst unsigned int *;outvaluemust be anunsigned int *.
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;outvaluemust be achar **, its content needs to be freed by the caller usingldap_memfree(3).LDAP_OPT_X_SASL_AUTHZID Gets the SASL authorization identity;outvaluemust be achar **, its content needs to be freed by the caller usingldap_memfree(3).LDAP_OPT_X_SASL_MAXBUFSIZE Gets/sets SASL maximum buffer size;invaluemust beconstber_len_t *, whileoutvaluemust beber_len_t *. See alsoLDAP_OPT_X_SASL_SECPROPS.LDAP_OPT_X_SASL_MECH Gets the SASL mechanism;outvaluemust be achar **, its content needs to be freed by the caller usingldap_memfree(3).LDAP_OPT_X_SASL_MECHLIST Gets the list of the available mechanisms, in form of a NULL-terminated array of strings;outvaluemust bechar***. The caller must not free or otherwise muck with it. This option can be used globally.LDAP_OPT_X_SASL_NOCANON Sets/gets the NOCANON flag. When unset, the hostname is canonicalized.invaluemust beconst int *; its value should either beLDAP_OPT_OFForLDAP_OPT_ON.outvalue must beint *.LDAP_OPT_X_SASL_REALM Gets the SASL realm;outvaluemust be achar **, its content needs to be freed by the caller usingldap_memfree(3).LDAP_OPT_X_SASL_SECPROPS Sets the SASL secprops;invaluemust be achar *, containing a comma-separated list of properties. Legal values are:none,nodict,noplain,noactive,passcred,forwardsec,noanonymous,nonstdcbind,minssf=<minssf>,maxssf=<maxssf>,maxbufsize=<maxbufsize>.LDAP_OPT_X_SASL_SSF Gets the SASL SSF;outvaluemust be aber_len_t *.LDAP_OPT_X_SASL_SSF_EXTERNAL Sets the SASL SSF value related to an authentication performed using an EXTERNAL mechanism;invaluemust be aconst ber_len_t *.LDAP_OPT_X_SASL_SSF_MAX Gets/sets SASL maximum SSF;invaluemust beconst ber_len_t*, whileoutvaluemust beber_len_t *. See alsoLDAP_OPT_X_SASL_SECPROPS.LDAP_OPT_X_SASL_SSF_MIN Gets/sets SASL minimum SSF;invaluemust beconst ber_len_t*, whileoutvaluemust beber_len_t *. See alsoLDAP_OPT_X_SASL_SECPROPS.LDAP_OPT_X_SASL_USERNAME Gets the SASL username;outvaluemust be achar **. Its content needs to be freed by the caller usingldap_memfree(3).LDAP_OPT_X_SASL_CBINDING Sets/gets the channel-binding type to use in SASL, one ofLDAP_OPT_X_SASL_CBINDING_NONE(the default),LDAP_OPT_X_SASL_CBINDING_TLS_UNIQUEthe "tls-unique" type from RFC 5929.LDAP_OPT_X_SASL_CBINDING_TLS_ENDPOINTthe "tls-server-end-point" from RFC 5929, compatible with Windows.invaluemust beconst int *;outvaluemust beint*.
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.invaluemust beconst int *;outvaluemust beint *.LDAP_OPT_X_KEEPALIVE_PROBES Sets/gets the maximum number of keepalive probes TCP should send before dropping the connection.invaluemust beconstint *;outvaluemust beint *.LDAP_OPT_X_KEEPALIVE_INTERVAL Sets/gets the interval in seconds between individual keepalive probes.invaluemust beconst int *;outvalue must beint *.
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.invaluemust beconst char *;outvaluemust bechar **, and its contents need to be freed by the caller usingldap_memfree(3).LDAP_OPT_X_TLS_CACERTFILE Sets/gets the full-path of the CA certificate file.invaluemust beconst char *;outvaluemust bechar **, and its contents need to be freed by the caller usingldap_memfree(3).LDAP_OPT_X_TLS_CERTFILE Sets/gets the full-path of the certificate file.invalue must beconst char *;outvaluemust bechar **, and its contents need to be freed by the caller usingldap_memfree(3).LDAP_OPT_X_TLS_CIPHER Gets the cipher being used on an established TLS session.outvaluemust bechar **, and its contents need to be freed by the caller usingldap_memfree(3).LDAP_OPT_X_TLS_CIPHER_SUITE Sets/gets the allowed cipher suite. This directive is not supported when using MbedTLS.invaluemust beconst char*;outvaluemust bechar **, and its contents need to be freed by the caller usingldap_memfree(3).LDAP_OPT_X_TLS_CONNECT_ARG Sets/gets the connection callback argument.invaluemust beconst void *;outvaluemust bevoid **.LDAP_OPT_X_TLS_CONNECT_CB Sets/gets the connection callback handle.invaluemust beconst LDAP_TLS_CONNECT_CB *;outvaluemust beLDAP_TLS_CONNECT_CB **.LDAP_OPT_X_TLS_CRLCHECK Sets/gets the CRL evaluation strategy, one ofLDAP_OPT_X_TLS_CRL_NONE,LDAP_OPT_X_TLS_CRL_PEER, orLDAP_OPT_X_TLS_CRL_ALL.invaluemust beconst int *;outvaluemust beint *. Requires OpenSSL.LDAP_OPT_X_TLS_CRLFILE Sets/gets the full-path of the CRL file.invaluemust beconst char *;outvaluemust bechar **, and its contents need to be freed by the caller usingldap_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.invaluemust beconst void *;outvaluemust bevoid **. 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. This directive is not supported when using MbedTLS.invalue must beconst char *;outvaluemust bechar **, and its contents need to be freed by the caller usingldap_memfree(3).LDAP_OPT_X_TLS_ECNAME Gets/sets the name of the curve(s) used for elliptic curve key exchanges.invaluemust beconst char *;outvaluemust bechar **, and its contents need to be freed by the caller usingldap_memfree(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.invaluemust beconst char *;outvaluemust bechar **, and its contents need to be freed by the caller usingldap_memfree(3).LDAP_OPT_X_TLS_NEWCTX Instructs the library to create a new TLS library context.invaluemust beconst int *. A non-zero value pointed to byinvaluetells 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.outvaluemust bestruct berval *, and the data it returns needs to be freed by the caller usingldap_memfree(3).LDAP_OPT_X_TLS_PROTOCOL_MAX Sets/gets the maximum protocol version.invaluemust beconst int *;outvaluemust beint *.LDAP_OPT_X_TLS_PROTOCOL_MIN Sets/gets the minimum protocol version.invaluemust beconst int *;outvaluemust beint *.LDAP_OPT_X_TLS_RANDOM_FILE Sets/gets the random file when/dev/randomand/dev/urandom are not available.invaluemust beconst char *;outvalue must bechar **, and its contents need to be freed by the caller usingldap_memfree(3). Ignored by GnuTLS older than version 2.2.LDAP_OPT_X_TLS_REQUIRE_CERT Sets/gets the peer certificate checking strategy, one ofLDAP_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 ofLDAP_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.outvaluemust bevoid **. 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.LDAP_OPT_X_TLS_VERSION Gets the TLS version being used on an established TLS session.outvaluemust bechar **, and its contents need to be freed by the caller usingldap_memfree(3).LDAP_OPT_X_TLS_PEERKEY_HASH Sets the (public) key that the application expects the peer to be using.invaluemust beconst 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 compare it with value provided and will only allow the session to continue if they match. This happens regardless of certificate checking strategy. The list of supportedhashalgvalues depends on the crypto library used, check its documentation to get a list.
On success, the functions returnLDAP_OPT_SUCCESS, while they may returnLDAP_OPT_ERRORto indicate a generic option handling error. Occasionally, more specific errors can be returned, likeLDAP_NO_MEMORYto indicate a failure in memory allocation.
The LDAP libraries with theLDAP_OPT_REFERRALSoption set toLDAP_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 toLDAP_OPT_OFF. The protocol version used by the library defaults to LDAPv2 (now historic), which corresponds to theLDAP_VERSION2macro. Application developers are encouraged to explicitly setLDAP_OPT_PROTOCOL_VERSIONto LDAPv3, using theLDAP_VERSION3 macro, or to allow users to select the protocol version.
ldap(3),ldap_error(3),RFC 4422(http://www.rfc-editor.org),
OpenLDAP Softwareis developed and maintained by The OpenLDAP Project <http://www.openldap.org/>.OpenLDAP Softwareis derived from the University of Michigan LDAP 3.3 Release.
This page is part of theOpenLDAP (an open source implementation of the Lightweight Directory Access Protocol) project. Information about the project can be found at ⟨http://www.openldap.org/⟩. If you have a bug report for this manual page, see ⟨http://www.openldap.org/its/⟩. This page was obtained from the project's upstream Git repository ⟨https://git.openldap.org/openldap/openldap.git⟩ on 2025-08-11. (At that time, the date of the most recent commit that was found in the repository was 2025-08-05.) If you discover any rendering problems in this HTML version of the page, or you believe there is a better or more up-to-date source for the page, or you have corrections or improvements to the information in this COLOPHON (which isnot part of the original manual page), send a mail to man-pages@man7.orgOpenLDAP LDVERSION RELEASEDATELDAP_GET_OPTION(3)Pages that refer to this page:lber-sockbuf(3), ldap(3), ldap_bind(3), ldap_error(3), ldap_get_option(3), ldap_open(3), ldap_result(3), ldap.conf(5)
HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. | |