LDAP_GET_OPTION(3) Library Functions Manual LDAP_GET_OPTION(3)
NAME
ldap_get_option, ldap_set_option - LDAP option handling routines
LIBRARY
OpenLDAP LDAP (libldap, -lldap)
SYNOPSIS
#include <ldap.h>
int ldap_get_option(LDAP *ld, int option, void *outvalue);
int ldap_set_option(LDAP *ld, int option, const void *invalue);
DESCRIPTION
These routines provide access to options stored either in a LDAP handle or as global options, where applicable. They make use of a neutral
interface, where the type of the value either retrieved by ldap_get_option(3) or set by ldap_set_option(3) is cast to void *. The actual
type is determined based on the value of the option argument. Global options are set/retrieved by passing a NULL LDAP handle.
LDAP_OPT_API_INFO
Fills-in a struct ldapapiinfo; outvalue must be a struct ldapapiinfo *, pointing to an already allocated struct. This is a read-
only option.
LDAP_OPT_DESC
Returns the file descriptor associated to the socket buffer of the LDAP handle passed in as ld; outvalue must be a int *. This is a
read-only, handler-specific option.
LDAP_OPT_SOCKBUF
Returns a pointer to the socket buffer of the LDAP handle passed in as ld; outvalue must be a Sockbuf **. This is a read-only, han-
dler-specific option.
LDAP_OPT_TIMEOUT
Sets/gets a timeout value for the synchronous API calls. outvalue must be a struct timeval ** (the caller has to free *outvalue),
and invalue must be a struct timeval *, and they cannot be NULL. Using a struct with seconds set to -1 results in an infinite time-
out, which is the default.
LDAP_OPT_NETWORK_TIMEOUT
Sets/gets the network timeout value after which poll(2)/select(2) following a connect(2) returns in case of no activity. outvalue
must be a struct timeval ** (the caller has to free *outvalue), and invalue must be a struct timeval *, and they cannot be NULL.
Using a struct with seconds set to -1 results in an infinite timeout, which is the default.
LDAP_OPT_DEREF
Sets/gets the value that defines when alias dereferencing must occur. outvalue and invalue must be int *, and they cannot be NULL.
LDAP_OPT_SIZELIMIT
Sets/gets the value that defines the maximum number of entries to be returned by a search operation. outvalue and invalue must be
int *, and they cannot be NULL.
LDAP_OPT_TIMELIMIT
Sets/gets the value that defines the time limit after which a search operation should be terminated by the server. outvalue and
invalue must be int *, and they cannot be NULL.
LDAP_OPT_REFERRALS
Determines whether the library should implicitly chase referrals or not. outvalue and invalue must be int *; their value should
either be LDAP_OPT_OFF or LDAP_OPT_ON.
LDAP_OPT_RESTART
Determines whether the library should implicitly restart connections (FIXME). outvalue and invalue must be int *; their value
should either be LDAP_OPT_OFF or LDAP_OPT_ON.
LDAP_OPT_PROTOCOL_VERSION
Sets/gets the protocol version. outvalue and invalue must be int *.
LDAP_OPT_SERVER_CONTROLS
Sets/gets the server-side controls to be used for all operations. This is now deprecated as modern LDAP C API provides replacements
for all main operations which accepts server-side controls as explicit arguments; see for example ldap_search_ext(3),
ldap_add_ext(3), ldap_modify_ext(3) and so on. outvalue must be LDAPControl ***, and the caller is responsible of freeing the
returned controls, if any, by calling ldap_controls_free(3), while invalue must be LDAPControl **; the library duplicates the con-
trols passed via invalue.
LDAP_OPT_CLIENT_CONTROLS
Sets/gets the client-side controls to be used for all operations. This is now deprecated as modern LDAP C API provides replacements
for all main operations which accepts client-side controls as explicit arguments; see for example ldap_search_ext(3),
ldap_add_ext(3), ldap_modify_ext(3) and so on. outvalue must be LDAPControl ***, and the caller is responsible of freeing the
returned controls, if any, by calling ldap_controls_free(3), while invalue must be LDAPControl **; the library duplicates the con-
trols passed via invalue.
LDAP_OPT_HOST_NAME
Sets/gets a space-separated list of hosts to be contacted by the library when trying to establish a connection. This is now depre-
cated in favor of LDAP_OPT_URI. outvalue must be a char **, and the caller is responsible of freeing the resulting string by call-
ing ldap_memfree(3), while invalue must be a char *; the library duplicates the corresponding string.
LDAP_OPT_URI
Sets/gets a space-separated list of URIs to be contacted by the library when trying to establish a connection. outvalue must be a
char **, and the caller is responsible of freeing the resulting string by calling ldap_memfree(3), while invalue must be a char *;
the library parses the string into a list of LDAPURLDesc structures, so the invocation of ldap_set_option(3) may fail if URL parsing
fails.
LDAP_OPT_DEFBASE
Sets/gets a string containing the DN to be used as default base for search operations. outvalue must be a char **, and the caller
is responsible of freeing the returned string by calling ldap_memfree(3), while invalue must be a char *; the library duplicates the
corresponding string.
LDAP_OPT_RESULT_CODE
Sets/gets the LDAP result code associated to the handle. This option was formerly known as LDAP_OPT_ERROR_NUMBER. Both outvalue
and invalue must be a int *.
LDAP_OPT_DIAGNOSTIC_MESSAGE
Sets/gets a string containing the error string associated to the LDAP handle. This option was formerly known as
LDAP_OPT_ERROR_STRING. outvalue must be a char **, and the caller is responsible of freeing the returned string by calling
ldap_memfree(3), while invalue must be a char *; the library duplicates the corresponding string.
LDAP_OPT_MATCHED_DN
Sets/gets a string containing the matched DN associated to the LDAP handle. outvalue must be a char **, and the caller is responsi-
ble of freeing the returned string by calling ldap_memfree(3), while invalue must be a char *; the library duplicates the corre-
sponding string.
LDAP_OPT_REFERRAL_URLS
Sets/gets an array containing the referral URIs associated to the LDAP handle. outvalue must be a char ***, and the caller is
responsible of freeing the returned string by calling ber_memvfree(3), while invalue must be a NULL-terminated char **; the library
duplicates the corresponding string.
LDAP_OPT_API_FEATURE_INFO
Fills-in a LDAPAPIFeatureInfo; outvalue must be a LDAPAPIFeatureInfo *, pointing to an already allocated struct. This is a read-
only option.
LDAP_OPT_DEBUG_LEVEL
Sets/gets the debug level of the client library. Both outvalue and invalue must be a int *.
ERRORS
On success, the functions return LDAP_OPT_SUCCESS, while they may return LDAP_OPT_ERROR to indicate a generic option handling error. Occa-
sionally, more specific errors can be returned, like LDAP_NO_MEMORY to indicate a failure in memory allocation.
NOTES
The LDAP libraries with the LDAP_OPT_REFERRALS option set to LDAP_OPT_ON (default value) automatically follow referrals using an anonymous
bind. Application developers are encouraged to either implement consistent referral chasing features, or explicitly disable referral chas-
ing by setting that option to LDAP_OPT_OFF.
SEE ALSO
ldap(3), ldap_error(3), RFC 4422 (http://www.rfc-editor.org),
ACKNOWLEDGEMENTS
OpenLDAP Software is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. OpenLDAP Software is derived from Uni-
versity of Michigan LDAP 3.3 Release.
OpenLDAP 2.4.11 2008/07/16 LDAP_GET_OPTION(3)