1 .TH LDAP_GET_OPTION 3 "RELEASEDATE" "OpenLDAP LDVERSION"
3 .\" Copyright 1998-2010 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_SIZELIMIT
326 Sets/gets the value that defines the maximum number of entries
327 to be returned by a search operation.
338 Returns a pointer to the socket buffer of the LDAP handle passed in as
343 This is a read-only, handle-specific option.
344 This option is OpenLDAP specific.
346 .B LDAP_OPT_TIMELIMIT
347 Sets/gets the value that defines the time limit after which
348 a search operation should be terminated by the server.
356 and they cannot be NULL.
359 Sets/gets a timeout value for the synchronous API calls.
362 .BR "struct timeval **"
363 (the caller has to free
368 .BR "struct timeval *" ,
369 and they cannot be NULL. Using a struct with seconds set to \-1 results
370 in an infinite timeout, which is the default.
371 This option is OpenLDAP specific.
374 Sets/gets a comma- or space-separated list of URIs to be contacted by the library
375 when trying to establish a connection.
379 and the caller is responsible of freeing the resulting string by calling
380 .BR ldap_memfree (3),
385 the library parses the string into a list of
387 structures, so the invocation of
388 .BR ldap_set_option (3)
389 may fail if URL parsing fails.
390 URIs may only contain the
397 This option is OpenLDAP specific.
399 The SASL options are OpenLDAP specific.
401 .B LDAP_OPT_X_SASL_AUTHCID
402 Gets the SASL authentication identity;
406 its content needs to be freed by the caller using
407 .BR ldap_memfree (3).
409 .B LDAP_OPT_X_SASL_AUTHZID
410 Gets the SASL authorization identity;
414 its content needs to be freed by the caller using
415 .BR ldap_memfree (3).
417 .B LDAP_OPT_X_SASL_MAXBUFSIZE
418 Gets/sets SASL maximum buffer size;
421 .BR "const ber_len_t *" ,
427 .BR LDAP_OPT_X_SASL_SECPROPS .
429 .B LDAP_OPT_X_SASL_MECH
430 Gets the SASL mechanism;
434 its content needs to be freed by the caller using
435 .BR ldap_memfree (3).
437 .B LDAP_OPT_X_SASL_MECHLIST
438 Gets the list of the available mechanisms,
439 in form of a NULL-terminated array of strings;
443 The caller must not free or otherwise muck with it.
445 .B LDAP_OPT_X_SASL_NOCANON
446 Sets/gets the NOCANON flag.
447 When unset, the hostname is canonicalized.
451 its value should either be
459 .B LDAP_OPT_X_SASL_REALM
464 its content needs to be freed by the caller using
465 .BR ldap_memfree (3).
467 .B LDAP_OPT_X_SASL_SECPROPS
468 Sets the SASL secprops;
472 containing a comma-separated list of properties.
481 .BR minssf=<minssf> ,
482 .BR maxssf=<maxssf> ,
483 .BR maxbufsize=<maxbufsize> .
485 .B LDAP_OPT_X_SASL_SSF
491 .B LDAP_OPT_X_SASL_SSF_EXTERNAL
492 Sets the SASL SSF value related to an authentication
493 performed using an EXTERNAL mechanism;
496 .BR "const ber_len_t *" .
498 .B LDAP_OPT_X_SASL_SSF_MAX
499 Gets/sets SASL maximum SSF;
502 .BR "const ber_len_t *" ,
508 .BR LDAP_OPT_X_SASL_SECPROPS .
510 .B LDAP_OPT_X_SASL_SSF_MIN
511 Gets/sets SASL minimum SSF;
514 .BR "const ber_len_t *" ,
520 .BR LDAP_OPT_X_SASL_SECPROPS .
522 .B LDAP_OPT_X_SASL_USERNAME
523 Gets the SASL username;
527 Its content needs to be freed by the caller using
528 .BR ldap_memfree (3).
530 The TCP options are OpenLDAP specific.
531 Mainly intended for use with Linux, they may not be portable.
533 .B LDAP_OPT_X_KEEPALIVE_IDLE
534 Sets/gets the number of seconds a connection needs to remain idle
535 before TCP starts sending keepalive probes.
543 .B LDAP_OPT_X_KEEPALIVE_PROBES
544 Sets/gets the maximum number of keepalive probes TCP should send
545 before dropping the connection.
553 .B LDAP_OPT_X_KEEPALIVE_INTERVAL
554 Sets/gets the interval in seconds between individual keepalive probes.
562 The TLS options are OpenLDAP specific.
565 .\"Sets/gets the TLS mode.
567 .B LDAP_OPT_X_TLS_CACERTDIR
568 Sets/gets the path of the directory containing CA certificates.
575 and its contents need to be freed by the caller using
576 .BR ldap_memfree (3).
578 .B LDAP_OPT_X_TLS_CACERTFILE
579 Sets/gets the full-path of the CA certificate file.
586 and its contents need to be freed by the caller using
587 .BR ldap_memfree (3).
589 .B LDAP_OPT_X_TLS_CERTFILE
590 Sets/gets the full-path of the 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_CIPHER_SUITE
601 Sets/gets the allowed cipher suite.
608 and its contents need to be freed by the caller using
609 .BR ldap_memfree (3).
611 .B LDAP_OPT_X_TLS_CONNECT_ARG
612 Sets/gets the connection callback argument.
620 .B LDAP_OPT_X_TLS_CONNECT_CB
621 Sets/gets the connection callback handle.
624 .BR "const LDAP_TLS_CONNECT_CB *" ;
627 .BR "LDAP_TLS_CONNECT_CB **" .
629 .B LDAP_OPT_X_TLS_CRLCHECK
630 Sets/gets the CRL evaluation strategy, one of
631 .BR LDAP_OPT_X_TLS_CRL_NONE ,
632 .BR LDAP_OPT_X_TLS_CRL_PEER ,
634 .BR LDAP_OPT_X_TLS_CRL_ALL .
643 .B LDAP_OPT_X_TLS_CRLFILE
644 Sets/gets the full-path of the CRL file.
651 and its contents need to be freed by the caller using
652 .BR ldap_memfree (3).
653 This option is only valid for GnuTLS.
655 .B LDAP_OPT_X_TLS_CTX
656 Sets/gets the TLS library context. New TLS sessions will inherit their
657 default settings from this library context.
664 When using the OpenSSL library this is an SSL_CTX*. When using other
665 crypto libraries this is a pointer to an OpenLDAP private structure.
666 Applications generally should not use this option or attempt to
667 manipulate this structure.
669 .B LDAP_OPT_X_TLS_DHFILE
670 Gets/sets the full-path of the file containing the parameters
671 for Diffie-Hellman ephemeral key exchange.
678 and its contents need to be freed by the caller using
679 .BR ldap_memfree (3).
682 .B LDAP_OPT_X_TLS_KEYFILE
683 Sets/gets the full-path of the certificate key file.
690 and its contents need to be freed by the caller using
691 .BR ldap_memfree (3).
693 .B LDAP_OPT_X_TLS_NEWCTX
694 Instructs the library to create a new TLS library context.
698 A non-zero value pointed to by
700 tells the library to create a context for a server.
702 .B LDAP_OPT_X_TLS_PROTOCOL_MIN
703 Sets/gets the minimum protocol version.
711 .B LDAP_OPT_X_TLS_RANDOM_FILE
712 Sets/gets the random file when
723 and its contents need to be freed by the caller using
724 .BR ldap_memfree (3).
725 Ignored by GnuTLS older than version 2.2.
727 .B LDAP_OPT_X_TLS_REQUIRE_CERT
728 Sets/gets the peer certificate checking strategy,
730 .BR LDAP_OPT_X_TLS_NEVER ,
731 .BR LDAP_OPT_X_TLS_HARD ,
732 .BR LDAP_OPT_X_TLS_DEMAND ,
733 .BR LDAP_OPT_X_TLS_ALLOW ,
734 .BR LDAP_OPT_X_TLS_TRY .
736 .B LDAP_OPT_X_TLS_SSL_CTX
737 Gets the TLS session context associated with this handle.
741 When using the OpenSSL library this is an SSL*. When using other
742 crypto libraries this is a pointer to an OpenLDAP private structure.
743 Applications generally should not use this option.
745 On success, the functions return
746 .BR LDAP_OPT_SUCCESS ,
747 while they may return
749 to indicate a generic option handling error.
750 Occasionally, more specific errors can be returned, like
752 to indicate a failure in memory allocation.
754 The LDAP libraries with the
755 .B LDAP_OPT_REFERRALS
758 (default value) automatically follow referrals using an anonymous bind.
759 Application developers are encouraged to either implement consistent
760 referral chasing features, or explicitly disable referral chasing
761 by setting that option to
764 The protocol version used by the library defaults to LDAPv2 (now historic),
765 which corresponds to the
768 Application developers are encouraged to explicitly set
769 .B LDAP_OPT_PROTOCOL_VERSION
772 macro, or to allow users to select the protocol version.
777 (http://www.rfc-editor.org),