1 .TH LDAP_GET_OPTION 3 "RELEASEDATE" "OpenLDAP LDVERSION"
3 .\" Copyright 1998-2014 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.
41 This is a read-only option.
49 pointing to an already allocated struct.
50 This is a read-only option.
52 .B LDAP_OPT_CLIENT_CONTROLS
53 Sets/gets the client-side controls to be used for all operations.
54 This is now deprecated as modern LDAP C API provides replacements
55 for all main operations which accepts client-side controls as
56 explicit arguments; see for example
57 .BR ldap_search_ext (3),
59 .BR ldap_modify_ext (3)
63 .BR "LDAPControl ***" ,
64 and the caller is responsible of freeing the returned controls, if any,
66 .BR ldap_controls_free (3),
70 .BR "LDAPControl *const *" ;
71 the library duplicates the controls passed via
74 .B LDAP_OPT_CONNECT_ASYNC
75 Sets/gets the status of the asynchronous connect flag.
84 When set, the library will call
86 and return, without waiting for response.
87 This leaves the handle in a connecting state.
88 Subsequent calls to library routines will poll for completion
89 of the connect before performing further operations.
90 As a consequence, library calls that need to establish a connection
91 with a DSA do not block even for the network timeout
93 .BR LDAP_OPT_NETWORK_TIMEOUT ).
94 This option is OpenLDAP specific.
96 .B LDAP_OPT_CONNECT_CB
97 This option allows to set a connect callback.
100 .BR "const struct ldap_conncb *" .
101 Callbacks are executed in last in-first served order.
102 Handle-specific callbacks are executed first, followed by global ones.
103 Right before freeing the callback structure, the
105 callback handler is passed a
109 .BR ldap_get_option (3)
110 for this option removes the callback whose pointer matches
112 This option is OpenLDAP specific.
114 .B LDAP_OPT_DEBUG_LEVEL
115 Sets/gets the debug level of the client library.
122 Valid debug levels are
124 .BR LDAP_DEBUG_ARGS ,
126 .BR LDAP_DEBUG_CONNS ,
127 .BR LDAP_DEBUG_NONE ,
128 .BR LDAP_DEBUG_PACKETS ,
129 .BR LDAP_DEBUG_PARSE ,
131 .BR LDAP_DEBUG_TRACE .
132 This option is OpenLDAP specific.
135 Sets/gets a string containing the DN to be used as default base
136 for search operations.
140 and the caller is responsible of freeing the returned string by calling
141 .BR ldap_memfree (3),
146 the library duplicates the corresponding string.
147 This option is OpenLDAP specific.
150 Sets/gets the value that defines when alias dereferencing must occur.
163 .BR LDAP_DEREF_SEARCHING ,
164 .BR LDAP_DEREF_FINDING ,
166 .BR LDAP_DEREF_ALWAYS .
167 Note that this has ever been the only means to determine alias dereferencing
168 within search operations.
171 Returns the file descriptor associated to the socket buffer
172 of the LDAP handle passed in as
177 This is a read-only, handle-specific option.
179 .B LDAP_OPT_DIAGNOSTIC_MESSAGE
180 Sets/gets a string containing the error string associated to the LDAP handle.
181 This option was formerly known as
182 .BR LDAP_OPT_ERROR_STRING .
186 and the caller is responsible of freeing the returned string by calling
187 .BR ldap_memfree (3),
192 the library duplicates the corresponding string.
194 .B LDAP_OPT_HOST_NAME
195 Sets/gets a space-separated list of hosts to be contacted by the library
196 when trying to establish a connection.
197 This is now deprecated in favor of
202 and the caller is responsible of freeing the resulting string by calling
203 .BR ldap_memfree (3),
208 the library duplicates the corresponding string.
210 .B LDAP_OPT_MATCHED_DN
211 Sets/gets a string containing the matched DN associated to the LDAP handle.
215 and the caller is responsible of freeing the returned string by calling
216 .BR ldap_memfree (3),
221 the library duplicates the corresponding string.
223 .B LDAP_OPT_NETWORK_TIMEOUT
224 Sets/gets the network timeout value after which
225 .BR poll (2)/ select (2)
228 returns in case of no activity.
231 .BR "struct timeval **"
232 (the caller has to free
237 .BR "const struct timeval *" .
238 They cannot be NULL. Using a struct with seconds set to \-1 results
239 in an infinite timeout, which is the default.
240 This option is OpenLDAP specific.
242 .B LDAP_OPT_PROTOCOL_VERSION
243 Sets/gets the protocol version.
250 .B LDAP_OPT_REFERRAL_URLS
251 Sets/gets an array containing the referral URIs associated to the LDAP handle.
255 and the caller is responsible of freeing the returned string by calling
256 .BR ldap_memvfree (3),
259 must be a NULL-terminated
260 .BR "char *const *" ;
261 the library duplicates the corresponding string.
262 This option is OpenLDAP specific.
264 .B LDAP_OPT_REFERRALS
265 Determines whether the library should implicitly chase referrals or not.
269 its value should either be
277 .\".B LDAP_OPT_REFHOPLIMIT
278 .\"This option is OpenLDAP specific.
279 .\"It is not currently implemented.
282 Determines whether the library should implicitly restart connections (FIXME).
286 its value should either be
294 .B LDAP_OPT_RESULT_CODE
295 Sets/gets the LDAP result code associated to the handle.
296 This option was formerly known as
297 .BR LDAP_OPT_ERROR_NUMBER .
305 .B LDAP_OPT_SERVER_CONTROLS
306 Sets/gets the server-side controls to be used for all operations.
307 This is now deprecated as modern LDAP C API provides replacements
308 for all main operations which accepts server-side controls as
309 explicit arguments; see for example
310 .BR ldap_search_ext (3),
311 .BR ldap_add_ext (3),
312 .BR ldap_modify_ext (3)
316 .BR "LDAPControl ***" ,
317 and the caller is responsible of freeing the returned controls, if any,
319 .BR ldap_controls_free (3),
323 .BR "LDAPControl *const *" ;
324 the library duplicates the controls passed via
327 .B LDAP_OPT_SESSION_REFCNT
328 Returns the reference count associated with the LDAP handle passed in as
333 This is a read-only, handle-specific option.
334 This option is OpenLDAP specific.
336 .B LDAP_OPT_SIZELIMIT
337 Sets/gets the value that defines the maximum number of entries
338 to be returned by a search operation.
349 Returns a pointer to the socket buffer of the LDAP handle passed in as
354 This is a read-only, handle-specific option.
355 This option is OpenLDAP specific.
357 .B LDAP_OPT_TIMELIMIT
358 Sets/gets the value that defines the time limit after which
359 a search operation should be terminated by the server.
367 and they cannot be NULL.
370 Sets/gets a timeout value for the synchronous API calls.
373 .BR "struct timeval **"
374 (the caller has to free
379 .BR "struct timeval *" ,
380 and they cannot be NULL. Using a struct with seconds set to \-1 results
381 in an infinite timeout, which is the default.
382 This option is OpenLDAP specific.
385 Sets/gets a comma- or space-separated list of URIs to be contacted by the library
386 when trying to establish a connection.
390 and the caller is responsible of freeing the resulting string by calling
391 .BR ldap_memfree (3),
396 the library parses the string into a list of
398 structures, so the invocation of
399 .BR ldap_set_option (3)
400 may fail if URL parsing fails.
401 URIs may only contain the
408 This option is OpenLDAP specific.
410 The SASL options are OpenLDAP specific.
412 .B LDAP_OPT_X_SASL_AUTHCID
413 Gets the SASL authentication identity;
417 its content needs to be freed by the caller using
418 .BR ldap_memfree (3).
420 .B LDAP_OPT_X_SASL_AUTHZID
421 Gets the SASL authorization identity;
425 its content needs to be freed by the caller using
426 .BR ldap_memfree (3).
428 .B LDAP_OPT_X_SASL_MAXBUFSIZE
429 Gets/sets SASL maximum buffer size;
432 .BR "const ber_len_t *" ,
438 .BR LDAP_OPT_X_SASL_SECPROPS .
440 .B LDAP_OPT_X_SASL_MECH
441 Gets the SASL mechanism;
445 its content needs to be freed by the caller using
446 .BR ldap_memfree (3).
448 .B LDAP_OPT_X_SASL_MECHLIST
449 Gets the list of the available mechanisms,
450 in form of a NULL-terminated array of strings;
454 The caller must not free or otherwise muck with it.
456 .B LDAP_OPT_X_SASL_NOCANON
457 Sets/gets the NOCANON flag.
458 When unset, the hostname is canonicalized.
462 its value should either be
470 .B LDAP_OPT_X_SASL_REALM
475 its content needs to be freed by the caller using
476 .BR ldap_memfree (3).
478 .B LDAP_OPT_X_SASL_SECPROPS
479 Sets the SASL secprops;
483 containing a comma-separated list of properties.
492 .BR minssf=<minssf> ,
493 .BR maxssf=<maxssf> ,
494 .BR maxbufsize=<maxbufsize> .
496 .B LDAP_OPT_X_SASL_SSF
502 .B LDAP_OPT_X_SASL_SSF_EXTERNAL
503 Sets the SASL SSF value related to an authentication
504 performed using an EXTERNAL mechanism;
507 .BR "const ber_len_t *" .
509 .B LDAP_OPT_X_SASL_SSF_MAX
510 Gets/sets SASL maximum SSF;
513 .BR "const ber_len_t *" ,
519 .BR LDAP_OPT_X_SASL_SECPROPS .
521 .B LDAP_OPT_X_SASL_SSF_MIN
522 Gets/sets SASL minimum SSF;
525 .BR "const ber_len_t *" ,
531 .BR LDAP_OPT_X_SASL_SECPROPS .
533 .B LDAP_OPT_X_SASL_USERNAME
534 Gets the SASL username;
538 Its content needs to be freed by the caller using
539 .BR ldap_memfree (3).
541 The TCP options are OpenLDAP specific.
542 Mainly intended for use with Linux, they may not be portable.
544 .B LDAP_OPT_X_KEEPALIVE_IDLE
545 Sets/gets the number of seconds a connection needs to remain idle
546 before TCP starts sending keepalive probes.
554 .B LDAP_OPT_X_KEEPALIVE_PROBES
555 Sets/gets the maximum number of keepalive probes TCP should send
556 before dropping the connection.
564 .B LDAP_OPT_X_KEEPALIVE_INTERVAL
565 Sets/gets the interval in seconds between individual keepalive probes.
573 The TLS options are OpenLDAP specific.
576 .\"Sets/gets the TLS mode.
578 .B LDAP_OPT_X_TLS_CACERTDIR
579 Sets/gets the path of the directory containing CA certificates.
586 and its contents need to be freed by the caller using
587 .BR ldap_memfree (3).
589 .B LDAP_OPT_X_TLS_CACERTFILE
590 Sets/gets the full-path of the CA certificate file.
597 and its contents need to be freed by the caller using
598 .BR ldap_memfree (3).
600 .B LDAP_OPT_X_TLS_CERTFILE
601 Sets/gets the full-path of the certificate file.
608 and its contents need to be freed by the caller using
609 .BR ldap_memfree (3).
611 .B LDAP_OPT_X_TLS_CIPHER
612 Gets the cipher being used on an established TLS session.
616 and its contents need to be freed by the caller using
617 .BR ldap_memfree (3).
619 .B LDAP_OPT_X_TLS_CIPHER_SUITE
620 Sets/gets the allowed cipher suite.
627 and its contents need to be freed by the caller using
628 .BR ldap_memfree (3).
630 .B LDAP_OPT_X_TLS_CONNECT_ARG
631 Sets/gets the connection callback argument.
639 .B LDAP_OPT_X_TLS_CONNECT_CB
640 Sets/gets the connection callback handle.
643 .BR "const LDAP_TLS_CONNECT_CB *" ;
646 .BR "LDAP_TLS_CONNECT_CB **" .
648 .B LDAP_OPT_X_TLS_CRLCHECK
649 Sets/gets the CRL evaluation strategy, one of
650 .BR LDAP_OPT_X_TLS_CRL_NONE ,
651 .BR LDAP_OPT_X_TLS_CRL_PEER ,
653 .BR LDAP_OPT_X_TLS_CRL_ALL .
662 .B LDAP_OPT_X_TLS_CRLFILE
663 Sets/gets the full-path of the CRL file.
670 and its contents need to be freed by the caller using
671 .BR ldap_memfree (3).
672 This option is only valid for GnuTLS.
674 .B LDAP_OPT_X_TLS_CTX
675 Sets/gets the TLS library context. New TLS sessions will inherit their
676 default settings from this library context.
683 When using the OpenSSL library this is an SSL_CTX*. When using other
684 crypto libraries this is a pointer to an OpenLDAP private structure.
685 Applications generally should not use this option or attempt to
686 manipulate this structure.
688 .B LDAP_OPT_X_TLS_DHFILE
689 Gets/sets the full-path of the file containing the parameters
690 for Diffie-Hellman ephemeral key exchange.
697 and its contents need to be freed by the caller using
698 .BR ldap_memfree (3).
699 Ignored by Mozilla NSS.
701 .B LDAP_OPT_X_TLS_ECNAME
702 Gets/sets the name of the curve used for
703 elliptic curve key exchanges.
710 and its contents need to be freed by the caller using
711 .BR ldap_memfree (3).
712 Ignored by GnuTLS and Mozilla NSS. In GnuTLS a curve may be selected
713 in the cipher suite specification.
715 .B LDAP_OPT_X_TLS_KEYFILE
716 Sets/gets the full-path of the certificate key file.
723 and its contents need to be freed by the caller using
724 .BR ldap_memfree (3).
726 .B LDAP_OPT_X_TLS_NEWCTX
727 Instructs the library to create a new TLS library context.
731 A non-zero value pointed to by
733 tells the library to create a context for a server.
735 .B LDAP_OPT_X_TLS_PEERCERT
736 Gets the peer's certificate in DER format from an established TLS session.
739 .BR "struct berval *" ,
740 and the data it returns needs to be freed by the caller using
741 .BR ldap_memfree (3).
743 .B LDAP_OPT_X_TLS_PROTOCOL_MIN
744 Sets/gets the minimum protocol version.
752 .B LDAP_OPT_X_TLS_RANDOM_FILE
753 Sets/gets the random file when
764 and its contents need to be freed by the caller using
765 .BR ldap_memfree (3).
766 Ignored by GnuTLS older than version 2.2. Ignored by Mozilla NSS.
768 .B LDAP_OPT_X_TLS_REQUIRE_CERT
769 Sets/gets the peer certificate checking strategy,
771 .BR LDAP_OPT_X_TLS_NEVER ,
772 .BR LDAP_OPT_X_TLS_HARD ,
773 .BR LDAP_OPT_X_TLS_DEMAND ,
774 .BR LDAP_OPT_X_TLS_ALLOW ,
775 .BR LDAP_OPT_X_TLS_TRY .
777 .B LDAP_OPT_X_TLS_SSL_CTX
778 Gets the TLS session context associated with this handle.
782 When using the OpenSSL library this is an SSL*. When using other
783 crypto libraries this is a pointer to an OpenLDAP private structure.
784 Applications generally should not use this option.
786 .B LDAP_OPT_X_TLS_VERSION
787 Gets the TLS version being used on an established TLS session.
791 and its contents need to be freed by the caller using
792 .BR ldap_memfree (3).
794 On success, the functions return
795 .BR LDAP_OPT_SUCCESS ,
796 while they may return
798 to indicate a generic option handling error.
799 Occasionally, more specific errors can be returned, like
801 to indicate a failure in memory allocation.
803 The LDAP libraries with the
804 .B LDAP_OPT_REFERRALS
807 (default value) automatically follow referrals using an anonymous bind.
808 Application developers are encouraged to either implement consistent
809 referral chasing features, or explicitly disable referral chasing
810 by setting that option to
813 The protocol version used by the library defaults to LDAPv2 (now historic),
814 which corresponds to the
817 Application developers are encouraged to explicitly set
818 .B LDAP_OPT_PROTOCOL_VERSION
821 macro, or to allow users to select the protocol version.
826 (http://www.rfc-editor.org),