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