--- name: "ldap_get_option" section: "3" platform: "macos" package: "OpenLDAP" version: "561" release: "macOS 26.5" platforms: ["linux", "macos"] url: "https://new.carta.tech/ldap_get_option" --- # ldap\_get\_option(3) LDAP option handling routines ## NAME ldap\_get\_option, ldap\_set\_option - LDAP option handling routines ## LIBRARY OpenLDAP LDAP (libldap, -lldap) ## SYNOPSIS ``` #include ``` **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)](/ldap_get_option/3.md) or set by [**ldap\_set\_option**(3)](/ldap_set_option/3.md) 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\_OPT\_API\_FEATURE\_INFO** Fills-in a **LDAPAPIFeatureInfo**; **outvalue** must be a **LDAPAPIFeatureInfo \***, pointing to an already allocated struct. 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. 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_search_ext/3.md), [**ldap\_add\_ext**(3)](/ldap_add_ext/3.md), [**ldap\_modify\_ext**(3)](/ldap_modify_ext/3.md) 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)](/ldap_controls_free/3.md), while **invalue** must be **LDAPControl \*const \***; the library duplicates the controls 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)](/connect/2.md) 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 (option **LDAP\_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, the **lc\_del** callback handler is passed a **NULL** **Sockbuf**. Calling [**ldap\_get\_option**(3)](/ldap_get_option/3.md) 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\_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)](/ldap_memfree/3.md), while **invalue** 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 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\_ERROR\_STRING**. **outvalue** must be a **char \*\***, and the caller is responsible of freeing the returned string by calling [**ldap\_memfree**(3)](/ldap_memfree/3.md), 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 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)](/ldap_memfree/3.md), 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)](/ldap_memfree/3.md), while **invalue** 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)](/poll/2.md)/[**select**(2)](/select/2.md) following a [**connect**(2)](/connect/2.md) returns in case of no activity. **outvalue** must be a **struct timeval \*\*** (the caller has to free **\*outvalue**)**,** 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 OpenLDAP 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 responsible of freeing the returned string by calling [**ldap\_memvfree**(3)](/ldap_memvfree/3.md), while **invalue** 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 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 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_search_ext/3.md), [**ldap\_add\_ext**(3)](/ldap_add_ext/3.md), [**ldap\_modify\_ext**(3)](/ldap_modify_ext/3.md) 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)](/ldap_controls_free/3.md), while **invalue** must be **LDAPControl \*const \***; the library duplicates the controls 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\_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**)**,** 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)](/ldap_memfree/3.md), 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)](/ldap_set_option/3.md) may fail if URL parsing fails. URIs may only contain the **schema**, the **host**, and the **port** 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_memfree/3.md). - **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_memfree/3.md). - **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_memfree/3.md). - **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 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_memfree/3.md). - **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=\**, **maxssf=\**, **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_memfree/3.md). ## 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_memfree/3.md). When using SecureTransport this option is not valid. Instead use the **LDAP\_OPT\_X\_TLS\_TRUSTED\_CERTS** option. - **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_memfree/3.md). When using SecureTransport this option is not valid. Instead use the **LDAP\_OPT\_X\_TLS\_TRUSTED\_CERTS** option. - **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_memfree/3.md). When using SecureTransport this option is not valid. Instead use the **LDAP\_OPT\_X\_TLS\_IDENTITY** option. - **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_memfree/3.md). - **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 SecureTransport or 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)](/ldap_memfree/3.md). 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)](/ldap_memfree/3.md). Ignored by GnuTLS and Mozilla NSS. - **LDAP\_OPT\_X\_TLS\_IDENTITY** Gets/sets the name of the identity in the system keychain. An identity is a certificate paired with a private key. **invalue** must be **const char \***; **outvalue** must be **char \*\***, and its contents need to be freed by the caller using [**ldap\_memfree**(3)](/ldap_memfree/3.md). Used by SecureTransport. Ignored by OpenSSL, 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_memfree/3.md). When using SecureTransport this option is not valid. Instead use the **LDAP\_OPT\_X\_TLS\_IDENTITY** option. - **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\_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)](/ldap_memfree/3.md). Ignored by GnuTLS older than version 2.2. Ignored by SecureTransport and 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. - **LDAP\_OPT\_X\_TLS\_TRUSTED\_CERTS** Gets/sets the list of the trusted certificates in the system keychain. **invalue** must be **const char \***; **outvalue** must be **char \*\***, and its contents need to be freed by the caller using [**ldap\_memfree**(3)](/ldap_memfree/3.md). Used by SecureTransport. Ignored by OpenSSL, GnuTLS and Mozilla NSS. ## 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. ## SEE ALSO [**ldap**(3)](/ldap/3.md), [**ldap\_error**(3)](/ldap_error/3.md), **RFC 4422** (http://www.rfc-editor.org), ## ACKNOWLEDGEMENTS