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. This is a
31 read-only option.
32 LDAP_OPT_API_INFO
34 Fills-in a LDAPAPIInfo; outvalue must be a LDAPAPIInfo *, point‐
35 ing to an already allocated struct. This is a read-only option.
36 LDAP_OPT_CLIENT_CONTROLS
38 Sets/gets the client-side controls to be used for all opera‐
39 tions. This is now deprecated as modern LDAP C API provides
40 replacements for all main operations which accepts client-side
41 controls as explicit arguments; see for example
42 ldap_search_ext(3), ldap_add_ext(3), ldap_modify_ext(3) and so
43 on. outvalue must be LDAPControl ***, and the caller is respon‐
44 sible of freeing the returned controls, if any, by calling
45 ldap_controls_free(3), while invalue must be LDAPControl *const
46 *; the library duplicates the controls passed via invalue.
47 LDAP_OPT_CONNECT_ASYNC
49 Sets/gets the status of the asynchronous connect flag. invalue
50 should either be LDAP_OPT_OFF or LDAP_OPT_ON; outvalue must be
51 int *. When set, the library will call connect(2) and return,
52 without waiting for response. This leaves the handle in a con‐
53 necting state. Subsequent calls to library routines will poll
54 for completion of the connect before performing further opera‐
55 tions. As a consequence, library calls that need to establish a
56 connection with a DSA do not block even for the network timeout
57 (option LDAP_OPT_NETWORK_TIMEOUT). This option is OpenLDAP spe‐
58 cific.
59 LDAP_OPT_CONNECT_CB
61 This option allows to set a connect callback. invalue must be a
62 const struct ldap_conncb *. Callbacks are executed in last in-
63 first served order. Handle-specific callbacks are executed
64 first, followed by global ones. Right before freeing the call‐
65 back structure, the lc_del callback handler is passed a NULL
66 Sockbuf. Calling ldap_get_option(3) for this option removes the
67 callback whose pointer matches outvalue. This option is OpenL‐
68 DAP specific.
69 LDAP_OPT_DEBUG_LEVEL
71 Sets/gets the debug level of the client library. invalue must
72 be a const int *; outvalue must be a int *. Valid debug levels
73 are LDAP_DEBUG_ANY, LDAP_DEBUG_ARGS, LDAP_DEBUG_BER,
74 LDAP_DEBUG_CONNS, LDAP_DEBUG_NONE, LDAP_DEBUG_PACKETS,
75 LDAP_DEBUG_PARSE, and LDAP_DEBUG_TRACE. This option is OpenLDAP
76 specific.
77 LDAP_OPT_DEFBASE
79 Sets/gets a string containing the DN to be used as default base
80 for search operations. outvalue must be a char **, and the
81 caller is responsible of freeing the returned string by calling
82 ldap_memfree(3), while invalue must be a const char *; the
83 library duplicates the corresponding string. This option is
84 OpenLDAP specific.
85 LDAP_OPT_DEREF
87 Sets/gets the value that defines when alias dereferencing must
88 occur. invalue must be const int *; outvalue must be int *.
89 They cannot be NULL. The value of *invalue should be one of
90 LDAP_DEREF_NEVER (the default), LDAP_DEREF_SEARCHING,
91 LDAP_DEREF_FINDING, or LDAP_DEREF_ALWAYS. Note that this has
92 ever been the only means to determine alias dereferencing within
93 search operations.
94 LDAP_OPT_DESC
96 Returns the file descriptor associated to the socket buffer of
97 the LDAP handle passed in as ld; outvalue must be a int *. This
98 is a read-only, handle-specific option.
99 LDAP_OPT_DIAGNOSTIC_MESSAGE
101 Sets/gets a string containing the error string associated to the
102 LDAP handle. This option was formerly known as
103 LDAP_OPT_ERROR_STRING. outvalue must be a char **, and the
104 caller is responsible of freeing the returned string by calling
105 ldap_memfree(3), while invalue must be a char *; the library
106 duplicates the corresponding string.
107 LDAP_OPT_HOST_NAME
109 Sets/gets a space-separated list of hosts to be contacted by the
110 library when trying to establish a connection. This is now dep‐
111 recated in favor of LDAP_OPT_URI. outvalue must be a char **,
112 and the caller is responsible of freeing the resulting string by
113 calling ldap_memfree(3), while invalue must be a const char *;
114 the library duplicates the corresponding string.
115 LDAP_OPT_MATCHED_DN
117 Sets/gets a string containing the matched DN associated to the
118 LDAP handle. outvalue must be a char **, and the caller is
119 responsible of freeing the returned string by calling ldap_mem‐
120 free(3), while invalue must be a const char *; the library
121 duplicates the corresponding string.
122 LDAP_OPT_NETWORK_TIMEOUT
124 Sets/gets the network timeout value after which
125 poll(2)/select(2) following a connect(2) returns in case of no
126 activity. outvalue must be a struct timeval ** (the caller has
127 to free *outvalue), and invalue must be a const struct timeval
128 *. They cannot be NULL. Using a struct with seconds set to -1
129 results in an infinite timeout, which is the default. This
130 option is OpenLDAP specific.
131 LDAP_OPT_PROTOCOL_VERSION
133 Sets/gets the protocol version. outvalue and invalue must be
134 int *.
135 LDAP_OPT_REFERRAL_URLS
137 Sets/gets an array containing the referral URIs associated to
138 the LDAP handle. outvalue must be a char ***, and the caller is
139 responsible of freeing the returned string by calling
140 ldap_memvfree(3), while invalue must be a NULL-terminated char
141 *const *; the library duplicates the corresponding string. This
142 option is OpenLDAP specific.
143 LDAP_OPT_REFERRALS
145 Determines whether the library should implicitly chase referrals
146 or not. invalue must be const int *; its value should either be
147 LDAP_OPT_OFF or LDAP_OPT_ON. outvalue must be int *.
148 LDAP_OPT_RESTART
150 Determines whether the library should implicitly restart connec‐
151 tions (FIXME). invalue must be const int *; its value should
152 either be LDAP_OPT_OFF or LDAP_OPT_ON. outvalue must be int *.
153 LDAP_OPT_RESULT_CODE
155 Sets/gets the LDAP result code associated to the handle. This
156 option was formerly known as LDAP_OPT_ERROR_NUMBER. invalue
157 must be a const int *. outvalue must be a int *.
158 LDAP_OPT_SERVER_CONTROLS
160 Sets/gets the server-side controls to be used for all opera‐
161 tions. This is now deprecated as modern LDAP C API provides
162 replacements for all main operations which accepts server-side
163 controls as explicit arguments; see for example
164 ldap_search_ext(3), ldap_add_ext(3), ldap_modify_ext(3) and so
165 on. outvalue must be LDAPControl ***, and the caller is respon‐
166 sible of freeing the returned controls, if any, by calling
167 ldap_controls_free(3), while invalue must be LDAPControl *const
168 *; the library duplicates the controls passed via invalue.
169 LDAP_OPT_SESSION_REFCNT
171 Returns the reference count associated with the LDAP handle
172 passed in as ld; outvalue must be a int *. This is a read-only,
173 handle-specific option. This option is OpenLDAP specific.
174 LDAP_OPT_SIZELIMIT
176 Sets/gets the value that defines the maximum number of entries
177 to be returned by a search operation. invalue must be const int
178 *, while outvalue must be int *; They cannot be NULL.
179 LDAP_OPT_SOCKBUF
181 Returns a pointer to the socket buffer of the LDAP handle passed
182 in as ld; outvalue must be a Sockbuf **. This is a read-only,
183 handle-specific option. This option is OpenLDAP specific.
184 LDAP_OPT_TIMELIMIT
186 Sets/gets the value that defines the time limit after which a
187 search operation should be terminated by the server. invalue
188 must be const int *, while outvalue must be int *, and they can‐
189 not be NULL.
190 LDAP_OPT_TIMEOUT
192 Sets/gets a timeout value for the synchronous API calls. out‐
193 value must be a struct timeval ** (the caller has to free *out‐
194 value), and invalue must be a struct timeval *, and they cannot
195 be NULL. Using a struct with seconds set to -1 results in an
196 infinite timeout, which is the default. This option is OpenLDAP
197 specific.
198 LDAP_OPT_URI
200 Sets/gets a comma- or space-separated list of URIs to be con‐
201 tacted by the library when trying to establish a connection.
202 outvalue must be a char **, and the caller is responsible of
203 freeing the resulting string by calling ldap_memfree(3), while
204 invalue must be a const char *; the library parses the string
205 into a list of LDAPURLDesc structures, so the invocation of
206 ldap_set_option(3) may fail if URL parsing fails. URIs may only
207 contain the schema, the host, and the port fields. This option
208 is OpenLDAP specific.
209
211 The SASL options are OpenLDAP specific.
212 LDAP_OPT_X_SASL_AUTHCID
214 Gets the SASL authentication identity; outvalue must be a char
215 **, its content needs to be freed by the caller using ldap_mem‐
216 free(3).
217 LDAP_OPT_X_SASL_AUTHZID
219 Gets the SASL authorization identity; outvalue must be a char
220 **, its content needs to be freed by the caller using ldap_mem‐
221 free(3).
222 LDAP_OPT_X_SASL_MAXBUFSIZE
224 Gets/sets SASL maximum buffer size; invalue must be const
225 ber_len_t *, while outvalue must be ber_len_t *. See also
226 LDAP_OPT_X_SASL_SECPROPS.
227 LDAP_OPT_X_SASL_MECH
229 Gets the SASL mechanism; outvalue must be a char **, its content
230 needs to be freed by the caller using ldap_memfree(3).
231 LDAP_OPT_X_SASL_MECHLIST
233 Gets the list of the available mechanisms, in form of a NULL-
234 terminated array of strings; outvalue must be char ***. The
235 caller must not free or otherwise muck with it.
236 LDAP_OPT_X_SASL_NOCANON
238 Sets/gets the NOCANON flag. When unset, the hostname is canoni‐
239 calized. invalue must be const int *; its value should either
240 be LDAP_OPT_OFF or LDAP_OPT_ON. outvalue must be int *.
241 LDAP_OPT_X_SASL_REALM
243 Gets the SASL realm; outvalue must be a char **, its content
244 needs to be freed by the caller using ldap_memfree(3).
245 LDAP_OPT_X_SASL_SECPROPS
247 Sets the SASL secprops; invalue must be a char *, containing a
248 comma-separated list of properties. Legal values are: none,
249 nodict, noplain, noactive, passcred, forwardsec, noanonymous,
250 minssf=<minssf>, maxssf=<maxssf>, maxbufsize=<maxbufsize>.
251 LDAP_OPT_X_SASL_SSF
253 Gets the SASL SSF; outvalue must be a ber_len_t *.
254 LDAP_OPT_X_SASL_SSF_EXTERNAL
256 Sets the SASL SSF value related to an authentication performed
257 using an EXTERNAL mechanism; invalue must be a const ber_len_t
258 *.
259 LDAP_OPT_X_SASL_SSF_MAX
261 Gets/sets SASL maximum SSF; invalue must be const ber_len_t *,
262 while outvalue must be ber_len_t *. See also
263 LDAP_OPT_X_SASL_SECPROPS.
264 LDAP_OPT_X_SASL_SSF_MIN
266 Gets/sets SASL minimum SSF; invalue must be const ber_len_t *,
267 while outvalue must be ber_len_t *. See also
268 LDAP_OPT_X_SASL_SECPROPS.
269 LDAP_OPT_X_SASL_USERNAME
271 Gets the SASL username; outvalue must be a char **. Its content
272 needs to be freed by the caller using ldap_memfree(3).
273
275 The TCP options are OpenLDAP specific. Mainly intended for use with
276 Linux, they may not be portable.
277 LDAP_OPT_X_KEEPALIVE_IDLE
279 Sets/gets the number of seconds a connection needs to remain
280 idle before TCP starts sending keepalive probes. invalue must
281 be const int *; outvalue must be int *.
282 LDAP_OPT_X_KEEPALIVE_PROBES
284 Sets/gets the maximum number of keepalive probes TCP should send
285 before dropping the connection. invalue must be const int *;
286 outvalue must be int *.
287 LDAP_OPT_X_KEEPALIVE_INTERVAL
289 Sets/gets the interval in seconds between individual keepalive
290 probes. invalue must be const int *; outvalue must be int *.
291
293 The TLS options are OpenLDAP specific.
294 LDAP_OPT_X_TLS_CACERTDIR
296 Sets/gets the path of the directory containing CA certificates.
297 invalue must be const char *; outvalue must be char **, and its
298 contents need to be freed by the caller using ldap_memfree(3).
299 LDAP_OPT_X_TLS_CACERTFILE
301 Sets/gets the full-path of the CA certificate file. invalue
302 must be const char *; outvalue must be char **, and its contents
303 need to be freed by the caller using ldap_memfree(3).
304 LDAP_OPT_X_TLS_CERTFILE
306 Sets/gets the full-path of the certificate file. invalue must
307 be const char *; outvalue must be char **, and its contents need
308 to be freed by the caller using ldap_memfree(3).
309 LDAP_OPT_X_TLS_CIPHER_SUITE
311 Sets/gets the allowed cipher suite. invalue must be const char
312 *; outvalue must be char **, and its contents need to be freed
313 by the caller using ldap_memfree(3).
314 LDAP_OPT_X_TLS_CONNECT_ARG
316 Sets/gets the connection callback argument. invalue must be
317 const void *; outvalue must be void **.
318 LDAP_OPT_X_TLS_CONNECT_CB
320 Sets/gets the connection callback handle. invalue must be const
321 LDAP_TLS_CONNECT_CB *; outvalue must be LDAP_TLS_CONNECT_CB **.
322 LDAP_OPT_X_TLS_CRLCHECK
324 Sets/gets the CRL evaluation strategy, one of
325 LDAP_OPT_X_TLS_CRL_NONE, LDAP_OPT_X_TLS_CRL_PEER, or
326 LDAP_OPT_X_TLS_CRL_ALL. invalue must be const int *; outvalue
327 must be int *. Requires OpenSSL.
328 LDAP_OPT_X_TLS_CRLFILE
330 Sets/gets the full-path of the CRL file. invalue must be const
331 char *; outvalue must be char **, and its contents need to be
332 freed by the caller using ldap_memfree(3). This option is only
333 valid for GnuTLS.
334 LDAP_OPT_X_TLS_CTX
336 Sets/gets the TLS library context. New TLS sessions will inherit
337 their default settings from this library context. invalue must
338 be const void *; outvalue must be void **. When using the
339 OpenSSL library this is an SSL_CTX*. When using other crypto
340 libraries this is a pointer to an OpenLDAP private structure.
341 Applications generally should not use this option or attempt to
342 manipulate this structure.
343 LDAP_OPT_X_TLS_DHFILE
345 Gets/sets the full-path of the file containing the parameters
346 for Diffie-Hellman ephemeral key exchange. invalue must be
347 const char *; outvalue must be char **, and its contents need to
348 be freed by the caller using ldap_memfree(3). Ignored by GnuTLS
349 and Mozilla NSS.
350 LDAP_OPT_X_TLS_KEYFILE
352 Sets/gets the full-path of the certificate key file. invalue
353 must be const char *; outvalue must be char **, and its contents
354 need to be freed by the caller using ldap_memfree(3).
355 LDAP_OPT_X_TLS_NEWCTX
357 Instructs the library to create a new TLS library context.
358 invalue must be const int *. A non-zero value pointed to by
359 invalue tells the library to create a context for a server.
360 LDAP_OPT_X_TLS_PROTOCOL_MIN
362 Sets/gets the minimum protocol version. invalue must be const
363 int *; outvalue must be int *.
364 LDAP_OPT_X_TLS_RANDOM_FILE
366 Sets/gets the random file when /dev/random and /dev/urandom are
367 not available. invalue must be const char *; outvalue must be
368 char **, and its contents need to be freed by the caller using
369 ldap_memfree(3). Ignored by GnuTLS older than version 2.2.
370 Ignored by Mozilla NSS.
371 LDAP_OPT_X_TLS_REQUIRE_CERT
373 Sets/gets the peer certificate checking strategy, one of
374 LDAP_OPT_X_TLS_NEVER, LDAP_OPT_X_TLS_HARD,
375 LDAP_OPT_X_TLS_DEMAND, LDAP_OPT_X_TLS_ALLOW, LDAP_OPT_X_TLS_TRY.
376 LDAP_OPT_X_TLS_SSL_CTX
378 Gets the TLS session context associated with this handle. out‐
379 value must be void **. When using the OpenSSL library this is
380 an SSL*. When using other crypto libraries this is a pointer to
381 an OpenLDAP private structure. Applications generally should
382 not use this option.
383
385 On success, the functions return LDAP_OPT_SUCCESS, while they may
386 return LDAP_OPT_ERROR to indicate a generic option handling error.
387 Occasionally, more specific errors can be returned, like LDAP_NO_MEMORY
388 to indicate a failure in memory allocation.
389
391 The LDAP libraries with the LDAP_OPT_REFERRALS option set to
392 LDAP_OPT_ON (default value) automatically follow referrals using an
393 anonymous bind. Application developers are encouraged to either imple‐
394 ment consistent referral chasing features, or explicitly disable refer‐
395 ral chasing by setting that option to LDAP_OPT_OFF.
396 The protocol version used by the library defaults to LDAPv2 (now his‐
398 toric), which corresponds to the LDAP_VERSION2 macro. Application
399 developers are encouraged to explicitly set LDAP_OPT_PROTOCOL_VERSION
400 to LDAPv3, using the LDAP_VERSION3 macro, or to allow users to select
401 the protocol version.
402
404 ldap(3), ldap_error(3), RFC 4422 (http://www.rfc-editor.org),
405
407 OpenLDAP Software is developed and maintained by The OpenLDAP Project
408 <http://www.openldap.org/>. OpenLDAP Software is derived from Univer‐
409 sity of Michigan LDAP 3.3 Release.
410OpenLDAP 2.4.40 2014/09/20 LDAP_GET_OPTION(3)