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 (\fIFIXME: currently unused\fP).
62 .BR "struct timeval **" ,
63 and the resulting pointer must be freed by the caller using
67 .BR "struct timeval *" .
69 .B LDAP_OPT_NETWORK_TIMEOUT
70 Sets/gets the network timeout value after which
71 .BR poll (2)/ select (2)
74 returns in case of no activity.
77 .BR "struct timeval **" ,
78 and the resulting pointer must be freed by the caller using
82 .BR "struct timeval *" .
85 Sets/gets the value that defines when alias deferencing must occur.
91 and they cannot be NULL.
94 Sets/gets the value that defines the maximum number of entries
95 to be returned by a search operation.
101 and they cannot be NULL.
103 .B LDAP_OPT_TIMELIMIT
104 Sets/gets the value that defines the time limit after which
105 a search operation should be terminated by the server.
111 and they cannot be NULL.
113 .B LDAP_OPT_REFERRALS
114 Determines whether the library should implicitly chase referrals or not.
120 their value should either be
126 Determines whether the library should implicitly restart connections (FIXME).
132 their value should either be
137 .B LDAP_OPT_PROTOCOL_VERSION
138 Sets/gets the protocol version.
145 .B LDAP_OPT_SERVER_CONTROLS
146 Sets/gets the server-side controls to be used for all operations.
147 This is now deprecated as modern LDAP C API provides replacements
148 for all main operations which accepts server-side controls as
149 explicit arguments; see for example
150 .BR ldap_search_ext (3),
151 .BR ldap_add_ext (3),
152 .BR ldap_modify_ext (3)
156 .BR "LDAPControl ***" ,
157 and the caller is responsible of freeing the returned controls, if any,
159 .BR ldap_controls_free (3),
163 .BR "LDAPControl **" ;
164 the library duplicates the controls passed via
167 .B LDAP_OPT_CLIENT_CONTROLS
168 Sets/gets the client-side controls to be used for all operations.
169 This is now deprecated as modern LDAP C API provides replacements
170 for all main operations which accepts client-side controls as
171 explicit arguments; see for example
172 .BR ldap_search_ext (3),
173 .BR ldap_add_ext (3),
174 .BR ldap_modify_ext (3)
178 .BR "LDAPControl ***" ,
179 and the caller is responsible of freeing the returned controls, if any,
181 .BR ldap_controls_free (3),
185 .BR "LDAPControl **" ;
186 the library duplicates the controls passed via
189 .B LDAP_OPT_HOST_NAME
190 Sets/gets a space-separated list of hosts to be contacted by the library
191 when trying to establish a connection.
192 This is now deprecated in favour of
197 and the caller is responsible of freeing the resulting string by calling
198 .BR ldap_memfree (3),
203 the library duplicates the corresponding string.
206 Sets/gets a space-separated list of URIs to be contacted by the library
207 when trying to establish a connection.
211 and the caller is responsible of freeing the resulting string by calling
212 .BR ldap_memfree (3),
217 the library parses the string into a list of
219 structures, so the invocation of
220 .BR ldap_set_option (3)
221 may fail if URL parsing fails.
224 Sets/gets a string containing the DN to be used as default base
225 for search operations.
229 and the caller is responsible of freeing the returned string by calling
230 .BR ldap_memfree (3),
235 the library duplicates the corresponding string.
237 .B LDAP_OPT_RESULT_CODE
238 Sets/gets the LDAP result code associated to the handle.
239 This option was formerly known as
240 .BR LDAP_OPT_ERROR_NUMBER .
248 .B LDAP_OPT_DIAGNOSTIC_MESSAGE
249 Sets/gets a string containing the error string associated to the LDAP handle.
250 This option was formerly known as
251 .BR LDAP_OPT_ERROR_STRING .
255 and the caller is responsible of freeing the returned string by calling
256 .BR ldap_memfree (3),
261 the library duplicates the corresponding string.
263 .B LDAP_OPT_MATCHED_DN
264 Sets/gets a string containing the matched DN associated to the LDAP handle.
268 and the caller is responsible of freeing the returned string by calling
269 .BR ldap_memfree (3),
274 the library duplicates the corresponding string.
276 .B LDAP_OPT_REFERRAL_URLS
277 Sets/gets an array containing the referral URIs associated to the LDAP handle.
281 and the caller is responsible of freeing the returned string by calling
282 .BR ber_memvfree (3),
285 must be a NULL-terminated
287 the library duplicates the corresponding string.
289 .B LDAP_OPT_API_FEATURE_INFO
291 .BR "LDAPAPIFeatureInfo" ;
294 .BR "LDAPAPIFeatureInfo *" ,
295 pointing to an already allocated struct.
296 This is a read-only option.
298 .B LDAP_OPT_DEBUG_LEVEL
299 Sets/gets the debug level of the client library.
307 On success, the functions return
308 .BR LDAP_OPT_SUCCESS ,
309 while they may return
311 to indicate a generic option handling error.
312 Occasionally, more specific errors can be returned, like
314 to indicate a failure in memory allocation.
316 The LDAP libraries with the
317 .B LDAP_OPT_REFERRALS
320 (default value) automatically follow referrals using an anonymous bind.
321 Application developers are encouraged to either implement consistent
322 referral chasing features, or explicitly disable referral chasing
323 by setting that option to
329 (http://www.rfc-editor.org),
332 is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
334 is derived from University of Michigan LDAP 3.3 Release.