1LDAP_GET_OPTION(3) Library Functions Manual LDAP_GET_OPTION(3)
2
6 ldap_get_option, ldap_set_option - LDAP option handling routines
7
9 OpenLDAP LDAP (libldap, -lldap)
10
12 #include <ldap.h>
13 int ldap_get_option(LDAP *ld, int option, void *outvalue);
15 int ldap_set_option(LDAP *ld, int option, const void *invalue);
17
19 These routines provide access to options stored either in a LDAP handle
20 or as global options, where applicable. They make use of a neutral
21 interface, where the type of the value either retrieved by
22 ldap_get_option(3) or set by ldap_set_option(3) is cast to void *. The
23 actual type is determined based on the value of the option argument.
24 Global options are set/retrieved by passing a NULL LDAP handle. LDAP
25 handles inherit their default settings from the global options in
26 effect at the time the handle is created.
27 LDAP_OPT_API_FEATURE_INFO
29 Fills-in a LDAPAPIFeatureInfo; outvalue must be a LDAPAPIFea‐
30 tureInfo *, pointing to an already allocated struct. The lda‐
31 paif_info_version field of the struct must be initialized to
32 LDAP_FEATURE_INFO_VERSION before making the call. The lda‐
33 paif_name field must be set to the name of a feature to query.
34 This is a read-only option.
35 LDAP_OPT_API_INFO
37 Fills-in a LDAPAPIInfo; outvalue must be a LDAPAPIInfo *, point‐
38 ing to an already allocated struct. The ldapai_info_version
39 field of the struct must be initialized to LDAP_API_INFO_VERSION
40 before making the call. If the version passed in does not match
41 the current library version, the expected version number will be
42 stored in the struct and the call will fail. The caller is
43 responsible for freeing the elements of the ldapai_extensions
44 array and the array itself using ldap_memfree(3). The caller
45 must also free the ldapi_vendor_name. This is a read-only
46 option.
47 LDAP_OPT_CLIENT_CONTROLS
49 Sets/gets the client-side controls to be used for all opera‐
50 tions. This is now deprecated as modern LDAP C API provides
51 replacements for all main operations which accepts client-side
52 controls as explicit arguments; see for example
53 ldap_search_ext(3), ldap_add_ext(3), ldap_modify_ext(3) and so
54 on. outvalue must be LDAPControl ***, and the caller is respon‐
55 sible of freeing the returned controls, if any, by calling
56 ldap_controls_free(3), while invalue must be LDAPControl *const
57 *; the library duplicates the controls passed via invalue.
58 LDAP_OPT_CONNECT_ASYNC
60 Sets/gets the status of the asynchronous connect flag. invalue
61 should either be LDAP_OPT_OFF or LDAP_OPT_ON; outvalue must be
62 int *. When set, the library will call connect(2) and return,
63 without waiting for response. This leaves the handle in a con‐
64 necting state. Subsequent calls to library routines will poll
65 for completion of the connect before performing further opera‐
66 tions. As a consequence, library calls that need to establish a
67 connection with a DSA do not block even for the network timeout
68 (option LDAP_OPT_NETWORK_TIMEOUT). This option is OpenLDAP spe‐
69 cific.
70 LDAP_OPT_CONNECT_CB
72 This option allows to set a connect callback. invalue must be a
73 const struct ldap_conncb *. Callbacks are executed in last in-
74 first served order. Handle-specific callbacks are executed
75 first, followed by global ones. Right before freeing the call‐
76 back structure, the lc_del callback handler is passed a NULL
77 Sockbuf. Calling ldap_get_option(3) for this option removes the
78 callback whose pointer matches outvalue. This option is OpenL‐
79 DAP specific.
80 LDAP_OPT_DEBUG_LEVEL
82 Sets/gets the debug level of the client library. invalue must
83 be a const int *; outvalue must be a int *. Valid debug levels
84 are LDAP_DEBUG_ANY, LDAP_DEBUG_ARGS, LDAP_DEBUG_BER,
85 LDAP_DEBUG_CONNS, LDAP_DEBUG_NONE, LDAP_DEBUG_PACKETS,
86 LDAP_DEBUG_PARSE, and LDAP_DEBUG_TRACE. This option is OpenLDAP
87 specific.
88 LDAP_OPT_DEFBASE
90 Sets/gets a string containing the DN to be used as default base
91 for search operations. outvalue must be a char **, and the
92 caller is responsible of freeing the returned string by calling
93 ldap_memfree(3), while invalue must be a const char *; the
94 library duplicates the corresponding string. This option is
95 OpenLDAP specific.
96 LDAP_OPT_DEREF
98 Sets/gets the value that defines when alias dereferencing must
99 occur. invalue must be const int *; outvalue must be int *.
100 They cannot be NULL. The value of *invalue should be one of
101 LDAP_DEREF_NEVER (the default), LDAP_DEREF_SEARCHING,
102 LDAP_DEREF_FINDING, or LDAP_DEREF_ALWAYS. Note that this has
103 ever been the only means to determine alias dereferencing within
104 search operations.
105 LDAP_OPT_DESC
107 Returns the file descriptor associated to the socket buffer of
108 the LDAP handle passed in as ld; outvalue must be a int *. This
109 is a read-only, handle-specific option.
110 LDAP_OPT_DIAGNOSTIC_MESSAGE
112 Sets/gets a string containing the error string associated to the
113 LDAP handle. This option was formerly known as
114 LDAP_OPT_ERROR_STRING. outvalue must be a char **, and the
115 caller is responsible of freeing the returned string by calling
116 ldap_memfree(3), while invalue must be a char *; the library
117 duplicates the corresponding string.
118 LDAP_OPT_HOST_NAME
120 Sets/gets a space-separated list of hosts to be contacted by the
121 library when trying to establish a connection. This is now dep‐
122 recated in favor of LDAP_OPT_URI. outvalue must be a char **,
123 and the caller is responsible of freeing the resulting string by
124 calling ldap_memfree(3), while invalue must be a const char *;
125 the library duplicates the corresponding string.
126 LDAP_OPT_MATCHED_DN
128 Sets/gets a string containing the matched DN associated to the
129 LDAP handle. outvalue must be a char **, and the caller is
130 responsible of freeing the returned string by calling ldap_mem‐
131 free(3), while invalue must be a const char *; the library
132 duplicates the corresponding string.
133 LDAP_OPT_NETWORK_TIMEOUT
135 Sets/gets the network timeout value after which
136 poll(2)/select(2) following a connect(2) returns in case of no
137 activity. outvalue must be a struct timeval ** (the caller has
138 to free *outvalue), and invalue must be a const struct timeval
139 *. They cannot be NULL. Using a struct with seconds set to -1
140 results in an infinite timeout, which is the default. This
141 option is OpenLDAP specific.
142 LDAP_OPT_PROTOCOL_VERSION
144 Sets/gets the protocol version. outvalue and invalue must be
145 int *.
146 LDAP_OPT_REFERRAL_URLS
148 Sets/gets an array containing the referral URIs associated to
149 the LDAP handle. outvalue must be a char ***, and the caller is
150 responsible of freeing the returned string by calling
151 ldap_memvfree(3), while invalue must be a NULL-terminated char
152 *const *; the library duplicates the corresponding string. This
153 option is OpenLDAP specific.
154 LDAP_OPT_REFERRALS
156 Determines whether the library should implicitly chase referrals
157 or not. invalue must be const int *; its value should either be
158 LDAP_OPT_OFF or LDAP_OPT_ON. outvalue must be int *.
159 LDAP_OPT_RESTART
161 Determines whether the library should implicitly restart connec‐
162 tions (FIXME). invalue must be const int *; its value should
163 either be LDAP_OPT_OFF or LDAP_OPT_ON. outvalue must be int *.
164 LDAP_OPT_RESULT_CODE
166 Sets/gets the LDAP result code associated to the handle. This
167 option was formerly known as LDAP_OPT_ERROR_NUMBER. invalue
168 must be a const int *. outvalue must be a int *.
169 LDAP_OPT_SERVER_CONTROLS
171 Sets/gets the server-side controls to be used for all opera‐
172 tions. This is now deprecated as modern LDAP C API provides
173 replacements for all main operations which accepts server-side
174 controls as explicit arguments; see for example
175 ldap_search_ext(3), ldap_add_ext(3), ldap_modify_ext(3) and so
176 on. outvalue must be LDAPControl ***, and the caller is respon‐
177 sible of freeing the returned controls, if any, by calling
178 ldap_controls_free(3), while invalue must be LDAPControl *const
179 *; the library duplicates the controls passed via invalue.
180 LDAP_OPT_SESSION_REFCNT
182 Returns the reference count associated with the LDAP handle
183 passed in as ld; outvalue must be a int *. This is a read-only,
184 handle-specific option. This option is OpenLDAP specific.
185 LDAP_OPT_SIZELIMIT
187 Sets/gets the value that defines the maximum number of entries
188 to be returned by a search operation. invalue must be const int
189 *, while outvalue must be int *; They cannot be NULL.
190 LDAP_OPT_SOCKBUF
192 Returns a pointer to the socket buffer of the LDAP handle passed
193 in as ld; outvalue must be a Sockbuf **. This is a read-only,
194 handle-specific option. This option is OpenLDAP specific.
195 LDAP_OPT_TIMELIMIT
197 Sets/gets the value that defines the time limit after which a
198 search operation should be terminated by the server. invalue
199 must be const int *, while outvalue must be int *, and they can‐
200 not be NULL.
201 LDAP_OPT_TIMEOUT
203 Sets/gets a timeout value for the synchronous API calls. out‐
204 value must be a struct timeval ** (the caller has to free *out‐
205 value), and invalue must be a struct timeval *, and they cannot
206 be NULL. Using a struct with seconds set to -1 results in an
207 infinite timeout, which is the default. This option is OpenLDAP
208 specific.
209 LDAP_OPT_URI
211 Sets/gets a comma- or space-separated list of URIs to be con‐
212 tacted by the library when trying to establish a connection.
213 outvalue must be a char **, and the caller is responsible of
214 freeing the resulting string by calling ldap_memfree(3), while
215 invalue must be a const char *; the library parses the string
216 into a list of LDAPURLDesc structures, so the invocation of
217 ldap_set_option(3) may fail if URL parsing fails. URIs may only
218 contain the schema, the host, and the port fields. This option
219 is OpenLDAP specific.
220
222 The SASL options are OpenLDAP specific.
223 LDAP_OPT_X_SASL_AUTHCID
225 Gets the SASL authentication identity; outvalue must be a char
226 **, its content needs to be freed by the caller using ldap_mem‐
227 free(3).
228 LDAP_OPT_X_SASL_AUTHZID
230 Gets the SASL authorization identity; outvalue must be a char
231 **, its content needs to be freed by the caller using ldap_mem‐
232 free(3).
233 LDAP_OPT_X_SASL_MAXBUFSIZE
235 Gets/sets SASL maximum buffer size; invalue must be const
236 ber_len_t *, while outvalue must be ber_len_t *. See also
237 LDAP_OPT_X_SASL_SECPROPS.
238 LDAP_OPT_X_SASL_MECH
240 Gets the SASL mechanism; outvalue must be a char **, its content
241 needs to be freed by the caller using ldap_memfree(3).
242 LDAP_OPT_X_SASL_MECHLIST
244 Gets the list of the available mechanisms, in form of a NULL-
245 terminated array of strings; outvalue must be char ***. The
246 caller must not free or otherwise muck with it.
247 LDAP_OPT_X_SASL_NOCANON
249 Sets/gets the NOCANON flag. When unset, the hostname is canoni‐
250 calized. invalue must be const int *; its value should either
251 be LDAP_OPT_OFF or LDAP_OPT_ON. outvalue must be int *.
252 LDAP_OPT_X_SASL_REALM
254 Gets the SASL realm; outvalue must be a char **, its content
255 needs to be freed by the caller using ldap_memfree(3).
256 LDAP_OPT_X_SASL_SECPROPS
258 Sets the SASL secprops; invalue must be a char *, containing a
259 comma-separated list of properties. Legal values are: none,
260 nodict, noplain, noactive, passcred, forwardsec, noanonymous,
261 minssf=<minssf>, maxssf=<maxssf>, maxbufsize=<maxbufsize>.
262 LDAP_OPT_X_SASL_SSF
264 Gets the SASL SSF; outvalue must be a ber_len_t *.
265 LDAP_OPT_X_SASL_SSF_EXTERNAL
267 Sets the SASL SSF value related to an authentication performed
268 using an EXTERNAL mechanism; invalue must be a const ber_len_t
269 *.
270 LDAP_OPT_X_SASL_SSF_MAX
272 Gets/sets SASL maximum SSF; invalue must be const ber_len_t *,
273 while outvalue must be ber_len_t *. See also
274 LDAP_OPT_X_SASL_SECPROPS.
275 LDAP_OPT_X_SASL_SSF_MIN
277 Gets/sets SASL minimum SSF; invalue must be const ber_len_t *,
278 while outvalue must be ber_len_t *. See also
279 LDAP_OPT_X_SASL_SECPROPS.
280 LDAP_OPT_X_SASL_USERNAME
282 Gets the SASL username; outvalue must be a char **. Its content
283 needs to be freed by the caller using ldap_memfree(3).
284
286 The TCP options are OpenLDAP specific. Mainly intended for use with
287 Linux, they may not be portable.
288 LDAP_OPT_X_KEEPALIVE_IDLE
290 Sets/gets the number of seconds a connection needs to remain
291 idle before TCP starts sending keepalive probes. invalue must
292 be const int *; outvalue must be int *.
293 LDAP_OPT_X_KEEPALIVE_PROBES
295 Sets/gets the maximum number of keepalive probes TCP should send
296 before dropping the connection. invalue must be const int *;
297 outvalue must be int *.
298 LDAP_OPT_X_KEEPALIVE_INTERVAL
300 Sets/gets the interval in seconds between individual keepalive
301 probes. invalue must be const int *; outvalue must be int *.
302
304 The TLS options are OpenLDAP specific.
305 LDAP_OPT_X_TLS_CACERTDIR
307 Sets/gets the path of the directory containing CA certificates.
308 invalue must be const char *; outvalue must be char **, and its
309 contents need to be freed by the caller using ldap_memfree(3).
310 LDAP_OPT_X_TLS_CACERTFILE
312 Sets/gets the full-path of the CA certificate file. invalue
313 must be const char *; outvalue must be char **, and its contents
314 need to be freed by the caller using ldap_memfree(3).
315 LDAP_OPT_X_TLS_CERTFILE
317 Sets/gets the full-path of the certificate file. invalue must
318 be const char *; outvalue must be char **, and its contents need
319 to be freed by the caller using ldap_memfree(3).
320 LDAP_OPT_X_TLS_CIPHER_SUITE
322 Sets/gets the allowed cipher suite. invalue must be const char
323 *; outvalue must be char **, and its contents need to be freed
324 by the caller using ldap_memfree(3).
325 LDAP_OPT_X_TLS_CONNECT_ARG
327 Sets/gets the connection callback argument. invalue must be
328 const void *; outvalue must be void **.
329 LDAP_OPT_X_TLS_CONNECT_CB
331 Sets/gets the connection callback handle. invalue must be const
332 LDAP_TLS_CONNECT_CB *; outvalue must be LDAP_TLS_CONNECT_CB **.
333 LDAP_OPT_X_TLS_CRLCHECK
335 Sets/gets the CRL evaluation strategy, one of
336 LDAP_OPT_X_TLS_CRL_NONE, LDAP_OPT_X_TLS_CRL_PEER, or
337 LDAP_OPT_X_TLS_CRL_ALL. invalue must be const int *; outvalue
338 must be int *. Requires OpenSSL.
339 LDAP_OPT_X_TLS_CRLFILE
341 Sets/gets the full-path of the CRL file. invalue must be const
342 char *; outvalue must be char **, and its contents need to be
343 freed by the caller using ldap_memfree(3). This option is only
344 valid for GnuTLS.
345 LDAP_OPT_X_TLS_CTX
347 Sets/gets the TLS library context. New TLS sessions will inherit
348 their default settings from this library context. invalue must
349 be const void *; outvalue must be void **. When using the
350 OpenSSL library this is an SSL_CTX*. When using other crypto
351 libraries this is a pointer to an OpenLDAP private structure.
352 Applications generally should not use this option or attempt to
353 manipulate this structure.
354 LDAP_OPT_X_TLS_DHFILE
356 Gets/sets the full-path of the file containing the parameters
357 for Diffie-Hellman ephemeral key exchange. invalue must be
358 const char *; outvalue must be char **, and its contents need to
359 be freed by the caller using ldap_memfree(3). Ignored by GnuTLS
360 and Mozilla NSS.
361 LDAP_OPT_X_TLS_KEYFILE
363 Sets/gets the full-path of the certificate key file. invalue
364 must be const char *; outvalue must be char **, and its contents
365 need to be freed by the caller using ldap_memfree(3).
366 LDAP_OPT_X_TLS_NEWCTX
368 Instructs the library to create a new TLS library context.
369 invalue must be const int *. A non-zero value pointed to by
370 invalue tells the library to create a context for a server.
371 LDAP_OPT_X_TLS_PROTOCOL_MIN
373 Sets/gets the minimum protocol version. invalue must be const
374 int *; outvalue must be int *.
375 LDAP_OPT_X_TLS_RANDOM_FILE
377 Sets/gets the random file when /dev/random and /dev/urandom are
378 not available. invalue must be const char *; outvalue must be
379 char **, and its contents need to be freed by the caller using
380 ldap_memfree(3). Ignored by GnuTLS older than version 2.2.
381 Ignored by Mozilla NSS.
382 LDAP_OPT_X_TLS_REQUIRE_CERT
384 Sets/gets the peer certificate checking strategy, one of
385 LDAP_OPT_X_TLS_NEVER, LDAP_OPT_X_TLS_HARD,
386 LDAP_OPT_X_TLS_DEMAND, LDAP_OPT_X_TLS_ALLOW, LDAP_OPT_X_TLS_TRY.
387 LDAP_OPT_X_TLS_SSL_CTX
389 Gets the TLS session context associated with this handle. out‐
390 value must be void **. When using the OpenSSL library this is
391 an SSL*. When using other crypto libraries this is a pointer to
392 an OpenLDAP private structure. Applications generally should
393 not use this option.
394 LDAP_OPT_X_TLS_MOZNSS_COMPATIBILITY
396 Sets/gets the status of the MozNSS database compatibility layer
397 for TLS options. This options is available only if OpenLDAP is
398 compiled with OpenSSL. This has effect only before the TLS con‐
399 text is established. This option defaults to be on. invalue
400 should either be LDAP_OPT_OFF or LDAP_OPT_ON; outvalue must be
401 int *. When set, just before TLS context initialization the
402 library will first check if TLS settings are MozNSS-specific and
403 if so it will export certificates from a preconfigured database
404 and set other TLS settings so that OpenSSL can continue without
405 issues.
406
408 On success, the functions return LDAP_OPT_SUCCESS, while they may
409 return LDAP_OPT_ERROR to indicate a generic option handling error.
410 Occasionally, more specific errors can be returned, like LDAP_NO_MEMORY
411 to indicate a failure in memory allocation.
412
414 The LDAP libraries with the LDAP_OPT_REFERRALS option set to
415 LDAP_OPT_ON (default value) automatically follow referrals using an
416 anonymous bind. Application developers are encouraged to either imple‐
417 ment consistent referral chasing features, or explicitly disable refer‐
418 ral chasing by setting that option to LDAP_OPT_OFF.
419 The protocol version used by the library defaults to LDAPv2 (now his‐
421 toric), which corresponds to the LDAP_VERSION2 macro. Application
422 developers are encouraged to explicitly set LDAP_OPT_PROTOCOL_VERSION
423 to LDAPv3, using the LDAP_VERSION3 macro, or to allow users to select
424 the protocol version.
425
427 ldap(3), ldap_error(3), RFC 4422 (http://www.rfc-editor.org),
428
430 OpenLDAP Software is developed and maintained by The OpenLDAP Project
431 <http://www.openldap.org/>. OpenLDAP Software is derived from Univer‐
432 sity of Michigan LDAP 3.3 Release.
433OpenLDAP 2.4.44 2016/02/05 LDAP_GET_OPTION(3)