1 .TH LDAP_GET_OPTION 3 "RELEASEDATE" "OpenLDAP LDVERSION"
3 .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved.
4 .\" Copying restrictions apply. See COPYRIGHT/LICENSE.
6 ldap_get_option, ldap_set_option \- LDAP option handling routines
8 OpenLDAP LDAP (libldap, \-lldap)
13 .BI "int ldap_get_option(LDAP *" ld ", int " option ", void *" outvalue ");"
15 .BI "int ldap_set_option(LDAP *" ld ", int " option ", const void *" invalue ");"
18 These routines provide access to options stored either in a LDAP handle
19 or as global options, where applicable.
20 They make use of a neutral interface, where the type of the value
22 .BR ldap_get_option (3)
24 .BR ldap_set_option (3)
27 The actual type is determined based on the value of the
30 Global options are set/retrieved by passing a NULL LDAP handle. LDAP handles
31 inherit their default settings from the global options in effect at the time
32 the handle is created.
34 .B LDAP_OPT_API_FEATURE_INFO
36 .BR "LDAPAPIFeatureInfo" ;
39 .BR "LDAPAPIFeatureInfo *" ,
40 pointing to an already allocated struct.
42 .B ldapaif_info_version
43 field of the struct must be initialized to
44 .B LDAP_FEATURE_INFO_VERSION
45 before making the call. The
47 field must be set to the name of a feature to query.
48 This is a read-only option.
56 pointing to an already allocated struct. The
57 .B ldapai_info_version
58 field of the struct must be initialized to
59 .B LDAP_API_INFO_VERSION
60 before making the call.
61 If the version passed in does not match the current library
62 version, the expected version number will be stored in the
63 struct and the call will fail.
64 The caller is responsible for freeing the elements of the
66 array and the array itself using
68 The caller must also free the
69 .BR ldapi_vendor_name .
70 This is a read-only option.
72 .B LDAP_OPT_CLIENT_CONTROLS
73 Sets/gets the client-side controls to be used for all operations.
74 This is now deprecated as modern LDAP C API provides replacements
75 for all main operations which accepts client-side controls as
76 explicit arguments; see for example
77 .BR ldap_search_ext (3),
79 .BR ldap_modify_ext (3)
83 .BR "LDAPControl ***" ,
84 and the caller is responsible of freeing the returned controls, if any,
86 .BR ldap_controls_free (3),
90 .BR "LDAPControl *const *" ;
91 the library duplicates the controls passed via
94 .B LDAP_OPT_CONNECT_ASYNC
95 Sets/gets the status of the asynchronous connect flag.
104 When set, the library will call
106 and return, without waiting for response.
107 This leaves the handle in a connecting state.
108 Subsequent calls to library routines will poll for completion
109 of the connect before performing further operations.
110 As a consequence, library calls that need to establish a connection
111 with a DSA do not block even for the network timeout
113 .BR LDAP_OPT_NETWORK_TIMEOUT ).
114 This option is OpenLDAP specific.
116 .B LDAP_OPT_CONNECT_CB
117 This option allows to set a connect callback.
120 .BR "const struct ldap_conncb *" .
121 Callbacks are executed in last in-first served order.
122 Handle-specific callbacks are executed first, followed by global ones.
123 Right before freeing the callback structure, the
125 callback handler is passed a
129 .BR ldap_get_option (3)
130 for this option removes the callback whose pointer matches
132 This option is OpenLDAP specific.
134 .B LDAP_OPT_DEBUG_LEVEL
135 Sets/gets the debug level of the client library.
142 Valid debug levels are
144 .BR LDAP_DEBUG_ARGS ,
146 .BR LDAP_DEBUG_CONNS ,
147 .BR LDAP_DEBUG_NONE ,
148 .BR LDAP_DEBUG_PACKETS ,
149 .BR LDAP_DEBUG_PARSE ,
151 .BR LDAP_DEBUG_TRACE .
152 This option is OpenLDAP specific.
155 Sets/gets a string containing the DN to be used as default base
156 for search operations.
160 and the caller is responsible of freeing the returned string by calling
161 .BR ldap_memfree (3),
166 the library duplicates the corresponding string.
167 This option is OpenLDAP specific.
170 Sets/gets the value that defines when alias dereferencing must occur.
183 .BR LDAP_DEREF_SEARCHING ,
184 .BR LDAP_DEREF_FINDING ,
186 .BR LDAP_DEREF_ALWAYS .
187 Note that this has ever been the only means to determine alias dereferencing
188 within search operations.
191 Returns the file descriptor associated to the socket buffer
192 of the LDAP handle passed in as
197 This is a read-only, handle-specific option.
199 .B LDAP_OPT_DIAGNOSTIC_MESSAGE
200 Sets/gets a string containing the error string associated to the LDAP handle.
201 This option was formerly known as
202 .BR LDAP_OPT_ERROR_STRING .
206 and the caller is responsible of freeing the returned string by calling
207 .BR ldap_memfree (3),
212 the library duplicates the corresponding string.
214 .B LDAP_OPT_HOST_NAME
215 Sets/gets a space-separated list of hosts to be contacted by the library
216 when trying to establish a connection.
217 This is now deprecated in favor of
222 and the caller is responsible of freeing the resulting string by calling
223 .BR ldap_memfree (3),
228 the library duplicates the corresponding string.
230 .B LDAP_OPT_MATCHED_DN
231 Sets/gets a string containing the matched DN associated to the LDAP handle.
235 and the caller is responsible of freeing the returned string by calling
236 .BR ldap_memfree (3),
241 the library duplicates the corresponding string.
243 .B LDAP_OPT_NETWORK_TIMEOUT
244 Sets/gets the network timeout value after which
245 .BR poll (2)/ select (2)
248 returns in case of no activity.
251 .BR "struct timeval **"
252 (the caller has to free
257 .BR "const struct timeval *" .
258 They cannot be NULL. Using a struct with seconds set to \-1 results
259 in an infinite timeout, which is the default.
260 This option is OpenLDAP specific.
262 .B LDAP_OPT_PROTOCOL_VERSION
263 Sets/gets the protocol version.
270 .B LDAP_OPT_REFERRAL_URLS
271 Sets/gets an array containing the referral URIs associated to the LDAP handle.
275 and the caller is responsible of freeing the returned string by calling
276 .BR ldap_memvfree (3),
279 must be a NULL-terminated
280 .BR "char *const *" ;
281 the library duplicates the corresponding string.
282 This option is OpenLDAP specific.
284 .B LDAP_OPT_REFERRALS
285 Determines whether the library should implicitly chase referrals or not.
289 its value should either be
297 .\".B LDAP_OPT_REFHOPLIMIT
298 .\"This option is OpenLDAP specific.
299 .\"It is not currently implemented.
302 Determines whether the library should implicitly restart connections (FIXME).
306 its value should either be
314 .B LDAP_OPT_RESULT_CODE
315 Sets/gets the LDAP result code associated to the handle.
316 This option was formerly known as
317 .BR LDAP_OPT_ERROR_NUMBER .
325 .B LDAP_OPT_SERVER_CONTROLS
326 Sets/gets the server-side controls to be used for all operations.
327 This is now deprecated as modern LDAP C API provides replacements
328 for all main operations which accepts server-side controls as
329 explicit arguments; see for example
330 .BR ldap_search_ext (3),
331 .BR ldap_add_ext (3),
332 .BR ldap_modify_ext (3)
336 .BR "LDAPControl ***" ,
337 and the caller is responsible of freeing the returned controls, if any,
339 .BR ldap_controls_free (3),
343 .BR "LDAPControl *const *" ;
344 the library duplicates the controls passed via
347 .B LDAP_OPT_SESSION_REFCNT
348 Returns the reference count associated with the LDAP handle passed in as
353 This is a read-only, handle-specific option.
354 This option is OpenLDAP specific.
356 .B LDAP_OPT_SIZELIMIT
357 Sets/gets the value that defines the maximum number of entries
358 to be returned by a search operation.
369 Returns a pointer to the socket buffer of the LDAP handle passed in as
374 This is a read-only, handle-specific option.
375 This option is OpenLDAP specific.
377 .B LDAP_OPT_TIMELIMIT
378 Sets/gets the value that defines the time limit after which
379 a search operation should be terminated by the server.
387 and they cannot be NULL.
390 Sets/gets a timeout value for the synchronous API calls.
393 .BR "struct timeval **"
394 (the caller has to free
399 .BR "struct timeval *" ,
400 and they cannot be NULL. Using a struct with seconds set to \-1 results
401 in an infinite timeout, which is the default.
402 This option is OpenLDAP specific.
405 Sets/gets a comma- or space-separated list of URIs to be contacted by the library
406 when trying to establish a connection.
410 and the caller is responsible of freeing the resulting string by calling
411 .BR ldap_memfree (3),
416 the library parses the string into a list of
418 structures, so the invocation of
419 .BR ldap_set_option (3)
420 may fail if URL parsing fails.
421 URIs may only contain the
428 This option is OpenLDAP specific.
430 The SASL options are OpenLDAP specific.
432 .B LDAP_OPT_X_SASL_AUTHCID
433 Gets the SASL authentication identity;
437 its content needs to be freed by the caller using
438 .BR ldap_memfree (3).
440 .B LDAP_OPT_X_SASL_AUTHZID
441 Gets the SASL authorization identity;
445 its content needs to be freed by the caller using
446 .BR ldap_memfree (3).
448 .B LDAP_OPT_X_SASL_MAXBUFSIZE
449 Gets/sets SASL maximum buffer size;
452 .BR "const ber_len_t *" ,
458 .BR LDAP_OPT_X_SASL_SECPROPS .
460 .B LDAP_OPT_X_SASL_MECH
461 Gets the SASL mechanism;
465 its content needs to be freed by the caller using
466 .BR ldap_memfree (3).
468 .B LDAP_OPT_X_SASL_MECHLIST
469 Gets the list of the available mechanisms,
470 in form of a NULL-terminated array of strings;
474 The caller must not free or otherwise muck with it.
476 .B LDAP_OPT_X_SASL_NOCANON
477 Sets/gets the NOCANON flag.
478 When unset, the hostname is canonicalized.
482 its value should either be
490 .B LDAP_OPT_X_SASL_REALM
495 its content needs to be freed by the caller using
496 .BR ldap_memfree (3).
498 .B LDAP_OPT_X_SASL_SECPROPS
499 Sets the SASL secprops;
503 containing a comma-separated list of properties.
512 .BR minssf=<minssf> ,
513 .BR maxssf=<maxssf> ,
514 .BR maxbufsize=<maxbufsize> .
516 .B LDAP_OPT_X_SASL_SSF
522 .B LDAP_OPT_X_SASL_SSF_EXTERNAL
523 Sets the SASL SSF value related to an authentication
524 performed using an EXTERNAL mechanism;
527 .BR "const ber_len_t *" .
529 .B LDAP_OPT_X_SASL_SSF_MAX
530 Gets/sets SASL maximum SSF;
533 .BR "const ber_len_t *" ,
539 .BR LDAP_OPT_X_SASL_SECPROPS .
541 .B LDAP_OPT_X_SASL_SSF_MIN
542 Gets/sets SASL minimum SSF;
545 .BR "const ber_len_t *" ,
551 .BR LDAP_OPT_X_SASL_SECPROPS .
553 .B LDAP_OPT_X_SASL_USERNAME
554 Gets the SASL username;
558 Its content needs to be freed by the caller using
559 .BR ldap_memfree (3).
561 The TCP options are OpenLDAP specific.
562 Mainly intended for use with Linux, they may not be portable.
564 .B LDAP_OPT_X_KEEPALIVE_IDLE
565 Sets/gets the number of seconds a connection needs to remain idle
566 before TCP starts sending keepalive probes.
574 .B LDAP_OPT_X_KEEPALIVE_PROBES
575 Sets/gets the maximum number of keepalive probes TCP should send
576 before dropping the connection.
584 .B LDAP_OPT_X_KEEPALIVE_INTERVAL
585 Sets/gets the interval in seconds between individual keepalive probes.
593 The TLS options are OpenLDAP specific.
596 .\"Sets/gets the TLS mode.
598 .B LDAP_OPT_X_TLS_CACERTDIR
599 Sets/gets the path of the directory containing CA certificates.
606 and its contents need to be freed by the caller using
607 .BR ldap_memfree (3).
609 .B LDAP_OPT_X_TLS_CACERTFILE
610 Sets/gets the full-path of the CA certificate file.
617 and its contents need to be freed by the caller using
618 .BR ldap_memfree (3).
620 .B LDAP_OPT_X_TLS_CERTFILE
621 Sets/gets the full-path of the certificate file.
628 and its contents need to be freed by the caller using
629 .BR ldap_memfree (3).
631 .B LDAP_OPT_X_TLS_CIPHER
632 Gets the cipher being used on an established TLS session.
636 and its contents need to be freed by the caller using
637 .BR ldap_memfree (3).
639 .B LDAP_OPT_X_TLS_CIPHER_SUITE
640 Sets/gets the allowed cipher suite.
647 and its contents need to be freed by the caller using
648 .BR ldap_memfree (3).
650 .B LDAP_OPT_X_TLS_CONNECT_ARG
651 Sets/gets the connection callback argument.
659 .B LDAP_OPT_X_TLS_CONNECT_CB
660 Sets/gets the connection callback handle.
663 .BR "const LDAP_TLS_CONNECT_CB *" ;
666 .BR "LDAP_TLS_CONNECT_CB **" .
668 .B LDAP_OPT_X_TLS_CRLCHECK
669 Sets/gets the CRL evaluation strategy, one of
670 .BR LDAP_OPT_X_TLS_CRL_NONE ,
671 .BR LDAP_OPT_X_TLS_CRL_PEER ,
673 .BR LDAP_OPT_X_TLS_CRL_ALL .
682 .B LDAP_OPT_X_TLS_CRLFILE
683 Sets/gets the full-path of the CRL file.
690 and its contents need to be freed by the caller using
691 .BR ldap_memfree (3).
692 This option is only valid for GnuTLS.
694 .B LDAP_OPT_X_TLS_CTX
695 Sets/gets the TLS library context. New TLS sessions will inherit their
696 default settings from this library context.
703 When using the OpenSSL library this is an SSL_CTX*. When using other
704 crypto libraries this is a pointer to an OpenLDAP private structure.
705 Applications generally should not use this option or attempt to
706 manipulate this structure.
708 .B LDAP_OPT_X_TLS_DHFILE
709 Gets/sets the full-path of the file containing the parameters
710 for Diffie-Hellman ephemeral key exchange.
717 and its contents need to be freed by the caller using
718 .BR ldap_memfree (3).
719 Ignored by Mozilla NSS.
721 .B LDAP_OPT_X_TLS_ECNAME
722 Gets/sets the name of the curve used for
723 elliptic curve key exchanges.
730 and its contents need to be freed by the caller using
731 .BR ldap_memfree (3).
732 Ignored by GnuTLS and Mozilla NSS. In GnuTLS a curve may be selected
733 in the cipher suite specification.
735 .B LDAP_OPT_X_TLS_KEYFILE
736 Sets/gets the full-path of the certificate key file.
743 and its contents need to be freed by the caller using
744 .BR ldap_memfree (3).
746 .B LDAP_OPT_X_TLS_NEWCTX
747 Instructs the library to create a new TLS library context.
751 A non-zero value pointed to by
753 tells the library to create a context for a server.
755 .B LDAP_OPT_X_TLS_PEERCERT
756 Gets the peer's certificate in DER format from an established TLS session.
759 .BR "struct berval *" ,
760 and the data it returns needs to be freed by the caller using
761 .BR ldap_memfree (3).
763 .B LDAP_OPT_X_TLS_PROTOCOL_MIN
764 Sets/gets the minimum protocol version.
772 .B LDAP_OPT_X_TLS_RANDOM_FILE
773 Sets/gets the random file when
784 and its contents need to be freed by the caller using
785 .BR ldap_memfree (3).
786 Ignored by GnuTLS older than version 2.2. Ignored by Mozilla NSS.
788 .B LDAP_OPT_X_TLS_REQUIRE_CERT
789 Sets/gets the peer certificate checking strategy,
791 .BR LDAP_OPT_X_TLS_NEVER ,
792 .BR LDAP_OPT_X_TLS_HARD ,
793 .BR LDAP_OPT_X_TLS_DEMAND ,
794 .BR LDAP_OPT_X_TLS_ALLOW ,
795 .BR LDAP_OPT_X_TLS_TRY .
797 .B LDAP_OPT_X_TLS_SSL_CTX
798 Gets the TLS session context associated with this handle.
802 When using the OpenSSL library this is an SSL*. When using other
803 crypto libraries this is a pointer to an OpenLDAP private structure.
804 Applications generally should not use this option.
806 .B LDAP_OPT_X_TLS_VERSION
807 Gets the TLS version being used on an established TLS session.
811 and its contents need to be freed by the caller using
812 .BR ldap_memfree (3).
814 On success, the functions return
815 .BR LDAP_OPT_SUCCESS ,
816 while they may return
818 to indicate a generic option handling error.
819 Occasionally, more specific errors can be returned, like
821 to indicate a failure in memory allocation.
823 The LDAP libraries with the
824 .B LDAP_OPT_REFERRALS
827 (default value) automatically follow referrals using an anonymous bind.
828 Application developers are encouraged to either implement consistent
829 referral chasing features, or explicitly disable referral chasing
830 by setting that option to
833 The protocol version used by the library defaults to LDAPv2 (now historic),
834 which corresponds to the
837 Application developers are encouraged to explicitly set
838 .B LDAP_OPT_PROTOCOL_VERSION
841 macro, or to allow users to select the protocol version.
846 (http://www.rfc-editor.org),