30
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.
32
41
.B LDAP_OPT_API_INFO
34
.BR "struct ldapapiinfo" ;
37
.BR "struct ldapapiinfo *" ,
38
47
pointing to an already allocated struct.
39
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.
42
169
Returns the file descriptor associated to the socket buffer
43
170
of the LDAP handle passed in as
86
.BR "struct timeval *" ,
87
and they cannot be NULL. Using a struct with seconds set to \-1 results
235
.BR "const struct timeval *" .
236
They cannot be NULL. Using a struct with seconds set to \-1 results
88
237
in an infinite timeout, which is the default.
91
Sets/gets the value that defines when alias dereferencing must occur.
97
and they cannot be NULL.
100
Sets/gets the value that defines the maximum number of entries
101
to be returned by a search operation.
107
and they cannot be NULL.
109
.B LDAP_OPT_TIMELIMIT
110
Sets/gets the value that defines the time limit after which
111
a search operation should be terminated by the server.
117
and they cannot be NULL.
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.
119
262
.B LDAP_OPT_REFERRALS
120
263
Determines whether the library should implicitly chase referrals or not.
126
their value should either be
267
its value should either be
129
270
.BR LDAP_OPT_ON .
275
.\".B LDAP_OPT_REFHOPLIMIT
276
.\"This option is OpenLDAP specific.
277
.\"It is not currently implemented.
131
279
.B LDAP_OPT_RESTART
132
280
Determines whether the library should implicitly restart connections (FIXME).
138
their value should either be
284
its value should either be
141
287
.BR LDAP_OPT_ON .
143
.B LDAP_OPT_PROTOCOL_VERSION
144
Sets/gets the protocol version.
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 .
151
303
.B LDAP_OPT_SERVER_CONTROLS
169
.BR "LDAPControl **" ;
170
the library duplicates the controls passed via
173
.B LDAP_OPT_CLIENT_CONTROLS
174
Sets/gets the client-side controls to be used for all operations.
175
This is now deprecated as modern LDAP C API provides replacements
176
for all main operations which accepts client-side controls as
177
explicit arguments; see for example
178
.BR ldap_search_ext (3),
179
.BR ldap_add_ext (3),
180
.BR ldap_modify_ext (3)
184
.BR "LDAPControl ***" ,
185
and the caller is responsible of freeing the returned controls, if any,
187
.BR ldap_controls_free (3),
191
.BR "LDAPControl **" ;
192
the library duplicates the controls passed via
195
.B LDAP_OPT_HOST_NAME
196
Sets/gets a space-separated list of hosts to be contacted by the library
197
when trying to establish a connection.
198
This is now deprecated in favor of
203
and the caller is responsible of freeing the resulting string by calling
204
.BR ldap_memfree (3),
209
the library duplicates the corresponding string.
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.
212
Sets/gets a space-separated list of URIs to be contacted by the library
374
Sets/gets a comma- or space-separated list of URIs to be contacted by the library
213
375
when trying to establish a connection.
223
385
the library parses the string into a list of
225
387
structures, so the invocation of
226
388
.BR ldap_set_option (3)
227
389
may fail if URL parsing fails.
230
Sets/gets a string containing the DN to be used as default base
231
for search operations.
235
and the caller is responsible of freeing the returned string by calling
236
.BR ldap_memfree (3),
241
the library duplicates the corresponding string.
243
.B LDAP_OPT_RESULT_CODE
244
Sets/gets the LDAP result code associated to the handle.
245
This option was formerly known as
246
.BR LDAP_OPT_ERROR_NUMBER .
254
.B LDAP_OPT_DIAGNOSTIC_MESSAGE
255
Sets/gets a string containing the error string associated to the LDAP handle.
256
This option was formerly known as
257
.BR LDAP_OPT_ERROR_STRING .
261
and the caller is responsible of freeing the returned string by calling
262
.BR ldap_memfree (3),
267
the library duplicates the corresponding string.
269
.B LDAP_OPT_MATCHED_DN
270
Sets/gets a string containing the matched DN associated to the LDAP handle.
274
and the caller is responsible of freeing the returned string by calling
275
.BR ldap_memfree (3),
280
the library duplicates the corresponding string.
282
.B LDAP_OPT_REFERRAL_URLS
283
Sets/gets an array containing the referral URIs associated to the LDAP handle.
287
and the caller is responsible of freeing the returned string by calling
288
.BR ber_memvfree (3),
291
must be a NULL-terminated
293
the library duplicates the corresponding string.
295
.B LDAP_OPT_API_FEATURE_INFO
297
.BR "LDAPAPIFeatureInfo" ;
300
.BR "LDAPAPIFeatureInfo *" ,
301
pointing to an already allocated struct.
302
This is a read-only option.
304
.B LDAP_OPT_DEBUG_LEVEL
305
Sets/gets the debug level of the client library.
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.
313
745
On success, the functions return
314
746
.BR LDAP_OPT_SUCCESS ,
added
removed
doc/man/man3/ldap_get_option.3
