1 .TH LDAP_GET_OPTION 3 "RELEASEDATE" "OpenLDAP LDVERSION"
3 .\" Copyright 1998-2011 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.
32 .B LDAP_OPT_API_FEATURE_INFO
34 .BR "LDAPAPIFeatureInfo" ;
37 .BR "LDAPAPIFeatureInfo *" ,
38 pointing to an already allocated struct.
39 This is a read-only option.
47 pointing to an already allocated struct.
48 This is a read-only option.
50 .B LDAP_OPT_CLIENT_CONTROLS
51 Sets/gets the client-side controls to be used for all operations.
52 This is now deprecated as modern LDAP C API provides replacements
53 for all main operations which accepts client-side controls as
54 explicit arguments; see for example
55 .BR ldap_search_ext (3),
57 .BR ldap_modify_ext (3)
61 .BR "LDAPControl ***" ,
62 and the caller is responsible of freeing the returned controls, if any,
64 .BR ldap_controls_free (3),
68 .BR "LDAPControl *const *" ;
69 the library duplicates the controls passed via
72 .B LDAP_OPT_CONNECT_ASYNC
73 Sets/gets the status of the asynchronous connect flag.
82 When set, the library will call
84 and return, without waiting for response.
85 This leaves the handle in a connecting state.
86 Subsequent calls to library routines will poll for completion
87 of the connect before performing further operations.
88 As a consequence, library calls that need to establish a connection
89 with a DSA do not block even for the network timeout
91 .BR LDAP_OPT_NETWORK_TIMEOUT ).
92 This option is OpenLDAP specific.
94 .B LDAP_OPT_CONNECT_CB
95 This option allows to set a connect callback.
98 .BR "const struct ldap_conncb *" .
99 Callbacks are executed in last in-first served order.
100 Handle-specific callbacks are executed first, followed by global ones.
101 Right before freeing the callback structure, the
103 callback handler is passed a
107 .BR ldap_get_option (3)
108 for this option removes the callback whose pointer matches
110 This option is OpenLDAP specific.
112 .B LDAP_OPT_DEBUG_LEVEL
113 Sets/gets the debug level of the client library.
120 Valid debug levels are
122 .BR LDAP_DEBUG_ARGS ,
124 .BR LDAP_DEBUG_CONNS ,
125 .BR LDAP_DEBUG_NONE ,
126 .BR LDAP_DEBUG_PACKETS ,
127 .BR LDAP_DEBUG_PARSE ,
129 .BR LDAP_DEBUG_TRACE .
130 This option is OpenLDAP specific.
133 Sets/gets a string containing the DN to be used as default base
134 for search operations.
138 and the caller is responsible of freeing the returned string by calling
139 .BR ldap_memfree (3),
144 the library duplicates the corresponding string.
145 This option is OpenLDAP specific.
148 Sets/gets the value that defines when alias dereferencing must occur.
161 .BR LDAP_DEREF_SEARCHING ,
162 .BR LDAP_DEREF_FINDING ,
164 .BR LDAP_DEREF_ALWAYS .
165 Note that this has ever been the only means to determine alias dereferencing
166 within search operations.
169 Returns the file descriptor associated to the socket buffer
170 of the LDAP handle passed in as
175 This is a read-only, handle-specific option.
177 .B LDAP_OPT_DIAGNOSTIC_MESSAGE
178 Sets/gets a string containing the error string associated to the LDAP handle.
179 This option was formerly known as
180 .BR LDAP_OPT_ERROR_STRING .
184 and the caller is responsible of freeing the returned string by calling
185 .BR ldap_memfree (3),
190 the library duplicates the corresponding string.
192 .B LDAP_OPT_HOST_NAME
193 Sets/gets a space-separated list of hosts to be contacted by the library
194 when trying to establish a connection.
195 This is now deprecated in favor of
200 and the caller is responsible of freeing the resulting string by calling
201 .BR ldap_memfree (3),
206 the library duplicates the corresponding string.
208 .B LDAP_OPT_MATCHED_DN
209 Sets/gets a string containing the matched DN associated to the LDAP handle.
213 and the caller is responsible of freeing the returned string by calling
214 .BR ldap_memfree (3),
219 the library duplicates the corresponding string.
221 .B LDAP_OPT_NETWORK_TIMEOUT
222 Sets/gets the network timeout value after which
223 .BR poll (2)/ select (2)
226 returns in case of no activity.
229 .BR "struct timeval **"
230 (the caller has to free
235 .BR "const struct timeval *" .
236 They cannot be NULL. Using a struct with seconds set to \-1 results
237 in an infinite timeout, which is the default.
238 This option is OpenLDAP specific.
240 .B LDAP_OPT_PROTOCOL_VERSION
241 Sets/gets the protocol version.
248 .B LDAP_OPT_REFERRAL_URLS
249 Sets/gets an array containing the referral URIs associated to the LDAP handle.
253 and the caller is responsible of freeing the returned string by calling
254 .BR ldap_memvfree (3),
257 must be a NULL-terminated
258 .BR "char *const *" ;
259 the library duplicates the corresponding string.
260 This option is OpenLDAP specific.
262 .B LDAP_OPT_REFERRALS
263 Determines whether the library should implicitly chase referrals or not.
267 its value should either be
275 .\".B LDAP_OPT_REFHOPLIMIT
276 .\"This option is OpenLDAP specific.
277 .\"It is not currently implemented.
280 Determines whether the library should implicitly restart connections (FIXME).
284 its value should either be
292 .B LDAP_OPT_RESULT_CODE
293 Sets/gets the LDAP result code associated to the handle.
294 This option was formerly known as
295 .BR LDAP_OPT_ERROR_NUMBER .
303 .B LDAP_OPT_SERVER_CONTROLS
304 Sets/gets the server-side controls to be used for all operations.
305 This is now deprecated as modern LDAP C API provides replacements
306 for all main operations which accepts server-side controls as
307 explicit arguments; see for example
308 .BR ldap_search_ext (3),
309 .BR ldap_add_ext (3),
310 .BR ldap_modify_ext (3)
314 .BR "LDAPControl ***" ,
315 and the caller is responsible of freeing the returned controls, if any,
317 .BR ldap_controls_free (3),
321 .BR "LDAPControl *const *" ;
322 the library duplicates the controls passed via
325 .B LDAP_OPT_SESSION_REFCNT
326 Returns the reference count associated with the LDAP handle passed in as
331 This is a read-only, handle-specific option.
332 This option is OpenLDAP specific.
334 .B LDAP_OPT_SIZELIMIT
335 Sets/gets the value that defines the maximum number of entries
336 to be returned by a search operation.
347 Returns a pointer to the socket buffer of the LDAP handle passed in as
352 This is a read-only, handle-specific option.
353 This option is OpenLDAP specific.
355 .B LDAP_OPT_TIMELIMIT
356 Sets/gets the value that defines the time limit after which
357 a search operation should be terminated by the server.
365 and they cannot be NULL.
368 Sets/gets a timeout value for the synchronous API calls.
371 .BR "struct timeval **"
372 (the caller has to free
377 .BR "struct timeval *" ,
378 and they cannot be NULL. Using a struct with seconds set to \-1 results
379 in an infinite timeout, which is the default.
380 This option is OpenLDAP specific.
383 Sets/gets a comma- or space-separated list of URIs to be contacted by the library
384 when trying to establish a connection.
388 and the caller is responsible of freeing the resulting string by calling
389 .BR ldap_memfree (3),
394 the library parses the string into a list of
396 structures, so the invocation of
397 .BR ldap_set_option (3)
398 may fail if URL parsing fails.
399 URIs may only contain the
406 This option is OpenLDAP specific.
408 The SASL options are OpenLDAP specific.
410 .B LDAP_OPT_X_SASL_AUTHCID
411 Gets the SASL authentication identity;
415 its content needs to be freed by the caller using
416 .BR ldap_memfree (3).
418 .B LDAP_OPT_X_SASL_AUTHZID
419 Gets the SASL authorization identity;
423 its content needs to be freed by the caller using
424 .BR ldap_memfree (3).
426 .B LDAP_OPT_X_SASL_MAXBUFSIZE
427 Gets/sets SASL maximum buffer size;
430 .BR "const ber_len_t *" ,
436 .BR LDAP_OPT_X_SASL_SECPROPS .
438 .B LDAP_OPT_X_SASL_MECH
439 Gets the SASL mechanism;
443 its content needs to be freed by the caller using
444 .BR ldap_memfree (3).
446 .B LDAP_OPT_X_SASL_MECHLIST
447 Gets the list of the available mechanisms,
448 in form of a NULL-terminated array of strings;
452 The caller must not free or otherwise muck with it.
454 .B LDAP_OPT_X_SASL_NOCANON
455 Sets/gets the NOCANON flag.
456 When unset, the hostname is canonicalized.
460 its value should either be
468 .B LDAP_OPT_X_SASL_REALM
473 its content needs to be freed by the caller using
474 .BR ldap_memfree (3).
476 .B LDAP_OPT_X_SASL_SECPROPS
477 Sets the SASL secprops;
481 containing a comma-separated list of properties.
490 .BR minssf=<minssf> ,
491 .BR maxssf=<maxssf> ,
492 .BR maxbufsize=<maxbufsize> .
494 .B LDAP_OPT_X_SASL_SSF
500 .B LDAP_OPT_X_SASL_SSF_EXTERNAL
501 Sets the SASL SSF value related to an authentication
502 performed using an EXTERNAL mechanism;
505 .BR "const ber_len_t *" .
507 .B LDAP_OPT_X_SASL_SSF_MAX
508 Gets/sets SASL maximum SSF;
511 .BR "const ber_len_t *" ,
517 .BR LDAP_OPT_X_SASL_SECPROPS .
519 .B LDAP_OPT_X_SASL_SSF_MIN
520 Gets/sets SASL minimum SSF;
523 .BR "const ber_len_t *" ,
529 .BR LDAP_OPT_X_SASL_SECPROPS .
531 .B LDAP_OPT_X_SASL_USERNAME
532 Gets the SASL username;
536 Its content needs to be freed by the caller using
537 .BR ldap_memfree (3).
539 The TCP options are OpenLDAP specific.
540 Mainly intended for use with Linux, they may not be portable.
542 .B LDAP_OPT_X_KEEPALIVE_IDLE
543 Sets/gets the number of seconds a connection needs to remain idle
544 before TCP starts sending keepalive probes.
552 .B LDAP_OPT_X_KEEPALIVE_PROBES
553 Sets/gets the maximum number of keepalive probes TCP should send
554 before dropping the connection.
562 .B LDAP_OPT_X_KEEPALIVE_INTERVAL
563 Sets/gets the interval in seconds between individual keepalive probes.
571 The TLS options are OpenLDAP specific.
574 .\"Sets/gets the TLS mode.
576 .B LDAP_OPT_X_TLS_CACERTDIR
577 Sets/gets the path of the directory containing CA certificates.
584 and its contents need to be freed by the caller using
585 .BR ldap_memfree (3).
587 .B LDAP_OPT_X_TLS_CACERTFILE
588 Sets/gets the full-path of the CA certificate file.
595 and its contents need to be freed by the caller using
596 .BR ldap_memfree (3).
598 .B LDAP_OPT_X_TLS_CERTFILE
599 Sets/gets the full-path of the certificate file.
606 and its contents need to be freed by the caller using
607 .BR ldap_memfree (3).
609 .B LDAP_OPT_X_TLS_CIPHER_SUITE
610 Sets/gets the allowed cipher suite.
617 and its contents need to be freed by the caller using
618 .BR ldap_memfree (3).
620 .B LDAP_OPT_X_TLS_CONNECT_ARG
621 Sets/gets the connection callback argument.
629 .B LDAP_OPT_X_TLS_CONNECT_CB
630 Sets/gets the connection callback handle.
633 .BR "const LDAP_TLS_CONNECT_CB *" ;
636 .BR "LDAP_TLS_CONNECT_CB **" .
638 .B LDAP_OPT_X_TLS_CRLCHECK
639 Sets/gets the CRL evaluation strategy, one of
640 .BR LDAP_OPT_X_TLS_CRL_NONE ,
641 .BR LDAP_OPT_X_TLS_CRL_PEER ,
643 .BR LDAP_OPT_X_TLS_CRL_ALL .
652 .B LDAP_OPT_X_TLS_CRLFILE
653 Sets/gets the full-path of the CRL file.
660 and its contents need to be freed by the caller using
661 .BR ldap_memfree (3).
662 This option is only valid for GnuTLS.
664 .B LDAP_OPT_X_TLS_CTX
665 Sets/gets the TLS library context. New TLS sessions will inherit their
666 default settings from this library context.
673 When using the OpenSSL library this is an SSL_CTX*. When using other
674 crypto libraries this is a pointer to an OpenLDAP private structure.
675 Applications generally should not use this option or attempt to
676 manipulate this structure.
678 .B LDAP_OPT_X_TLS_DHFILE
679 Gets/sets the full-path of the file containing the parameters
680 for Diffie-Hellman ephemeral key exchange.
687 and its contents need to be freed by the caller using
688 .BR ldap_memfree (3).
689 Ignored by GnuTLS and Mozilla NSS.
691 .B LDAP_OPT_X_TLS_KEYFILE
692 Sets/gets the full-path of the certificate key file.
699 and its contents need to be freed by the caller using
700 .BR ldap_memfree (3).
702 .B LDAP_OPT_X_TLS_NEWCTX
703 Instructs the library to create a new TLS library context.
707 A non-zero value pointed to by
709 tells the library to create a context for a server.
711 .B LDAP_OPT_X_TLS_PROTOCOL_MIN
712 Sets/gets the minimum protocol version.
720 .B LDAP_OPT_X_TLS_RANDOM_FILE
721 Sets/gets the random file when
732 and its contents need to be freed by the caller using
733 .BR ldap_memfree (3).
734 Ignored by GnuTLS older than version 2.2. Ignored by Mozilla NSS.
736 .B LDAP_OPT_X_TLS_REQUIRE_CERT
737 Sets/gets the peer certificate checking strategy,
739 .BR LDAP_OPT_X_TLS_NEVER ,
740 .BR LDAP_OPT_X_TLS_HARD ,
741 .BR LDAP_OPT_X_TLS_DEMAND ,
742 .BR LDAP_OPT_X_TLS_ALLOW ,
743 .BR LDAP_OPT_X_TLS_TRY .
745 .B LDAP_OPT_X_TLS_SSL_CTX
746 Gets the TLS session context associated with this handle.
750 When using the OpenSSL library this is an SSL*. When using other
751 crypto libraries this is a pointer to an OpenLDAP private structure.
752 Applications generally should not use this option.
754 On success, the functions return
755 .BR LDAP_OPT_SUCCESS ,
756 while they may return
758 to indicate a generic option handling error.
759 Occasionally, more specific errors can be returned, like
761 to indicate a failure in memory allocation.
763 The LDAP libraries with the
764 .B LDAP_OPT_REFERRALS
767 (default value) automatically follow referrals using an anonymous bind.
768 Application developers are encouraged to either implement consistent
769 referral chasing features, or explicitly disable referral chasing
770 by setting that option to
773 The protocol version used by the library defaults to LDAPv2 (now historic),
774 which corresponds to the
777 Application developers are encouraged to explicitly set
778 .B LDAP_OPT_PROTOCOL_VERSION
781 macro, or to allow users to select the protocol version.
786 (http://www.rfc-editor.org),