1 .TH LDAP_GET_OPTION 3 "RELEASEDATE" "OpenLDAP LDVERSION"
3 .\" Copyright 1998-2007 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.
34 .BR "struct ldapapiinfo" ;
37 .BR "struct ldapapiinfo *" ,
38 pointing to an already allocated struct.
39 This is a read-only option.
42 Returns the file descriptor associated to the socket buffer
43 of the LDAP handle passed in as
48 This is a read-only, handler-specific option.
51 Returns a pointer to the socket buffer of the LDAP handle passed in as
56 This is a read-only, handler-specific option.
59 Sets/gets a timeout value for the synchronous API calls.
64 .BR "struct timeval *" ,
65 and they cannot be NULL. Using a struct with seconds set to -1 results
66 in an infinite timeout, which is the default.
68 .B LDAP_OPT_NETWORK_TIMEOUT
69 Sets/gets the network timeout value after which
70 .BR poll (2)/ select (2)
73 returns in case of no activity.
78 .BR "struct timeval *" ,
79 and they cannot be NULL. Using a struct with seconds set to -1 results
80 in an infinite timeout, which is the default.
83 Sets/gets the value that defines when alias deferencing must occur.
89 and they cannot be NULL.
92 Sets/gets the value that defines the maximum number of entries
93 to be returned by a search operation.
99 and they cannot be NULL.
101 .B LDAP_OPT_TIMELIMIT
102 Sets/gets the value that defines the time limit after which
103 a search operation should be terminated by the server.
109 and they cannot be NULL.
111 .B LDAP_OPT_REFERRALS
112 Determines whether the library should implicitly chase referrals or not.
118 their value should either be
124 Determines whether the library should implicitly restart connections (FIXME).
130 their value should either be
135 .B LDAP_OPT_PROTOCOL_VERSION
136 Sets/gets the protocol version.
143 .B LDAP_OPT_SERVER_CONTROLS
144 Sets/gets the server-side controls to be used for all operations.
145 This is now deprecated as modern LDAP C API provides replacements
146 for all main operations which accepts server-side controls as
147 explicit arguments; see for example
148 .BR ldap_search_ext (3),
149 .BR ldap_add_ext (3),
150 .BR ldap_modify_ext (3)
154 .BR "LDAPControl ***" ,
155 and the caller is responsible of freeing the returned controls, if any,
157 .BR ldap_controls_free (3),
161 .BR "LDAPControl **" ;
162 the library duplicates the controls passed via
165 .B LDAP_OPT_CLIENT_CONTROLS
166 Sets/gets the client-side controls to be used for all operations.
167 This is now deprecated as modern LDAP C API provides replacements
168 for all main operations which accepts client-side controls as
169 explicit arguments; see for example
170 .BR ldap_search_ext (3),
171 .BR ldap_add_ext (3),
172 .BR ldap_modify_ext (3)
176 .BR "LDAPControl ***" ,
177 and the caller is responsible of freeing the returned controls, if any,
179 .BR ldap_controls_free (3),
183 .BR "LDAPControl **" ;
184 the library duplicates the controls passed via
187 .B LDAP_OPT_HOST_NAME
188 Sets/gets a space-separated list of hosts to be contacted by the library
189 when trying to establish a connection.
190 This is now deprecated in favour of
195 and the caller is responsible of freeing the resulting string by calling
196 .BR ldap_memfree (3),
201 the library duplicates the corresponding string.
204 Sets/gets a space-separated list of URIs to be contacted by the library
205 when trying to establish a connection.
209 and the caller is responsible of freeing the resulting string by calling
210 .BR ldap_memfree (3),
215 the library parses the string into a list of
217 structures, so the invocation of
218 .BR ldap_set_option (3)
219 may fail if URL parsing fails.
222 Sets/gets a string containing the DN to be used as default base
223 for search operations.
227 and the caller is responsible of freeing the returned string by calling
228 .BR ldap_memfree (3),
233 the library duplicates the corresponding string.
235 .B LDAP_OPT_RESULT_CODE
236 Sets/gets the LDAP result code associated to the handle.
237 This option was formerly known as
238 .BR LDAP_OPT_ERROR_NUMBER .
246 .B LDAP_OPT_DIAGNOSTIC_MESSAGE
247 Sets/gets a string containing the error string associated to the LDAP handle.
248 This option was formerly known as
249 .BR LDAP_OPT_ERROR_STRING .
253 and the caller is responsible of freeing the returned string by calling
254 .BR ldap_memfree (3),
259 the library duplicates the corresponding string.
261 .B LDAP_OPT_MATCHED_DN
262 Sets/gets a string containing the matched DN associated to the LDAP handle.
266 and the caller is responsible of freeing the returned string by calling
267 .BR ldap_memfree (3),
272 the library duplicates the corresponding string.
274 .B LDAP_OPT_REFERRAL_URLS
275 Sets/gets an array containing the referral URIs associated to the LDAP handle.
279 and the caller is responsible of freeing the returned string by calling
280 .BR ber_memvfree (3),
283 must be a NULL-terminated
285 the library duplicates the corresponding string.
287 .B LDAP_OPT_API_FEATURE_INFO
289 .BR "LDAPAPIFeatureInfo" ;
292 .BR "LDAPAPIFeatureInfo *" ,
293 pointing to an already allocated struct.
294 This is a read-only option.
296 .B LDAP_OPT_DEBUG_LEVEL
297 Sets/gets the debug level of the client library.
305 On success, the functions return
306 .BR LDAP_OPT_SUCCESS ,
307 while they may return
309 to indicate a generic option handling error.
310 Occasionally, more specific errors can be returned, like
312 to indicate a failure in memory allocation.
314 The LDAP libraries with the
315 .B LDAP_OPT_REFERRALS
318 (default value) automatically follow referrals using an anonymous bind.
319 Application developers are encouraged to either implement consistent
320 referral chasing features, or explicitly disable referral chasing
321 by setting that option to
327 (http://www.rfc-editor.org),