Content-type: text/html
Man page of LDAP_GET_OPTION
LDAP_GET_OPTION
Section: C Library Functions (3)
Updated: 2009/07/13
Index
Return to Main Contents
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, handler-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 timeout, 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 controls 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 controls 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 deprecated in favor of
LDAP_OPT_URI.
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 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 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_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.
Occasionally, 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 chasing
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 University of Michigan LDAP 3.3 Release.
Index
- NAME
-
- LIBRARY
-
- SYNOPSIS
-
- DESCRIPTION
-
- ERRORS
-
- NOTES
-
- SEE ALSO
-
- ACKNOWLEDGEMENTS
-
This document was created by
man2html,
using the manual pages.
Time: 04:14:16 GMT, September 24, 2010