ldap_get_option, ldap_set_option — LDAP option handling routines
#include <ldap.h>
int ldap_get_option( |
LDAP *ld, |
| int option, | |
void *outvalue); |
int ldap_set_option( |
LDAP *ld, |
| int option, | |
const void *invalue); |
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_FEATURE_INFOFills-in a LDAPAPIFeatureInfo; outvalue must be a
LDAPAPIFeatureInfo *,
pointing to an already allocated struct. This is a
read-only option.
LDAP_OPT_API_INFOFills-in a LDAPAPIInfo;
outvalue must
be a LDAPAPIInfo *, pointing
to an already allocated struct. This is a read-only
option.
LDAP_OPT_CLIENT_CONTROLSSets/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 *const
*; the library duplicates the controls
passed via invalue.
LDAP_OPT_CONNECT_ASYNCSets/gets the status of the asynchronous connect
flag. invalue
should either be LDAP_OPT_OFF or LDAP_OPT_ON; outvalue must be
int *. When set,
the library will call connect(2) and
return, without waiting for response. This leaves the
handle in a connecting state. Subsequent calls to
library routines will poll for completion of the
connect before performing further operations. As a
consequence, library calls that need to establish a
connection with a DSA do not block even for the network
timeout (option LDAP_OPT_NETWORK_TIMEOUT). This
option is OpenLDAP specific.
LDAP_OPT_CONNECT_CBThis option allows to set a connect callback.
invalue must be
a const struct ldap_conncb *.
Callbacks are executed in last in-first served order.
Handle-specific callbacks are executed first, followed
by global ones. Right before freeing the callback
structure, the lc_del
callback handler is passed a NULL Sockbuf. Calling ldap_get_option(3)
for this option removes the callback whose pointer
matches outvalue. This option is
OpenLDAP specific.
LDAP_OPT_DEBUG_LEVELSets/gets the debug level of the client library.
invalue must be
a const int *; outvalue must be a
int *. Valid
debug levels are LDAP_DEBUG_ANY, LDAP_DEBUG_ARGS, LDAP_DEBUG_BER, LDAP_DEBUG_CONNS, LDAP_DEBUG_NONE, LDAP_DEBUG_PACKETS, LDAP_DEBUG_PARSE, and LDAP_DEBUG_TRACE. This option is
OpenLDAP specific.
LDAP_OPT_DEFBASESets/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 const char *; the
library duplicates the corresponding string. This
option is OpenLDAP specific.
LDAP_OPT_DEREFSets/gets the value that defines when alias
dereferencing must occur. invalue must be
const int *; outvalue must be
int *. They
cannot be NULL. The value of *invalue should be one of
LDAP_DEREF_NEVER (the
default), LDAP_DEREF_SEARCHING, LDAP_DEREF_FINDING, or LDAP_DEREF_ALWAYS. Note that this has
ever been the only means to determine alias
dereferencing within search operations.
LDAP_OPT_DESCReturns 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, handle-specific option.
LDAP_OPT_DIAGNOSTIC_MESSAGESets/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_HOST_NAMESets/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 const char *; the
library duplicates the corresponding string.
LDAP_OPT_MATCHED_DNSets/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 const char *; the
library duplicates the corresponding string.
LDAP_OPT_NETWORK_TIMEOUTSets/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
const struct timeval *. They
cannot be NULL. Using a struct with seconds set to
−1 results in an infinite timeout, which is the
default. This option is OpenLDAP specific.
LDAP_OPT_PROTOCOL_VERSIONSets/gets the protocol version. outvalue and invalue must be
int *.
LDAP_OPT_REFERRAL_URLSSets/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 ldap_memvfree(3),
while invalue
must be a NULL-terminated char *const *; the library
duplicates the corresponding string. This option is
OpenLDAP specific.
LDAP_OPT_REFERRALSDetermines whether the library should implicitly
chase referrals or not. invalue must be
const int *; its value should
either be LDAP_OPT_OFF or
LDAP_OPT_ON. outvalue must be
int *.
LDAP_OPT_RESTARTDetermines whether the library should implicitly
restart connections (FIXME). invalue must be
const int *; its value should
either be LDAP_OPT_OFF or
LDAP_OPT_ON. outvalue must be
int *.
LDAP_OPT_RESULT_CODESets/gets the LDAP result code associated to the
handle. This option was formerly known as LDAP_OPT_ERROR_NUMBER. invalue must be a
const int *. outvalue must be a
int *.
LDAP_OPT_SERVER_CONTROLSSets/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 *const
*; the library duplicates the controls
passed via invalue.
LDAP_OPT_SIZELIMITSets/gets the value that defines the maximum number
of entries to be returned by a search operation.
invalue must be
const int *, while outvalue must be
int *; They
cannot be NULL.
LDAP_OPT_SOCKBUFReturns a pointer to the socket buffer of the LDAP
handle passed in as ld; outvalue must be a
Sockbuf **. This
is a read-only, handle-specific option. This option is
OpenLDAP specific.
LDAP_OPT_TIMELIMITSets/gets the value that defines the time limit
after which a search operation should be terminated by
the server. invalue must be
const int *, while outvalue must be
int *, and they
cannot be NULL.
LDAP_OPT_TIMEOUTSets/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. This option is OpenLDAP specific.
LDAP_OPT_URISets/gets a comma- or 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 const 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. URIs may only contain
the schema, the
host, and the
port fields. This option
is OpenLDAP specific.
The SASL options are OpenLDAP specific.
LDAP_OPT_X_SASL_AUTHCIDGets the SASL authentication identity; outvalue must be a
char **, its
content needs to be freed by the caller using ldap_memfree(3).
LDAP_OPT_X_SASL_AUTHZIDGets the SASL authorization identity; outvalue must be a
char **, its
content needs to be freed by the caller using ldap_memfree(3).
LDAP_OPT_X_SASL_MAXBUFSIZEGets/sets SASL maximum buffer size; invalue must be
const ber_len_t *, while
outvalue must
be ber_len_t *.
See also LDAP_OPT_X_SASL_SECPROPS.
LDAP_OPT_X_SASL_MECHGets the SASL mechanism; outvalue must be a
char **, its
content needs to be freed by the caller using ldap_memfree(3).
LDAP_OPT_X_SASL_MECHLISTGets the list of the available mechanisms, in form
of a NULL-terminated array of strings; outvalue must be
char ***. The
caller must not free or otherwise muck with it.
LDAP_OPT_X_SASL_NOCANONSets/gets the NOCANON flag. When unset, the hostname
is canonicalized. invalue must be
const int *; its value should
either be LDAP_OPT_OFF or
LDAP_OPT_ON. outvalue must be
int *.
LDAP_OPT_X_SASL_REALMGets the SASL realm; outvalue must be a
char **, its
content needs to be freed by the caller using ldap_memfree(3).
LDAP_OPT_X_SASL_SECPROPSSets the SASL secprops; invalue must be a
char *,
containing a comma-separated list of properties. Legal
values are: none,
nodict, noplain, noactive, passcred, forwardsec, noanonymous, minssf=<minssf>,
maxssf=<maxssf>,
maxbufsize=<maxbufsize>.
LDAP_OPT_X_SASL_SSFGets the SASL SSF; outvalue must be a
ber_len_t *.
LDAP_OPT_X_SASL_SSF_EXTERNALSets the SASL SSF value related to an authentication
performed using an EXTERNAL mechanism; invalue must be a
const ber_len_t *.
LDAP_OPT_X_SASL_SSF_MAXGets/sets SASL maximum SSF; invalue must be
const ber_len_t *, while
outvalue must
be ber_len_t *.
See also LDAP_OPT_X_SASL_SECPROPS.
LDAP_OPT_X_SASL_SSF_MINGets/sets SASL minimum SSF; invalue must be
const ber_len_t *, while
outvalue must
be ber_len_t *.
See also LDAP_OPT_X_SASL_SECPROPS.
LDAP_OPT_X_SASL_USERNAMEGets the SASL username; outvalue must be a
char **. Its
content needs to be freed by the caller using ldap_memfree(3).
The TCP options are OpenLDAP specific. Mainly intended for use with Linux, they may not be portable.
LDAP_OPT_X_KEEPALIVE_IDLESets/gets the number of seconds a connection needs
to remain idle before TCP starts sending keepalive
probes. invalue
must be const int *;
outvalue must
be int *.
LDAP_OPT_X_KEEPALIVE_PROBESSets/gets the maximum number of keepalive probes TCP
should send before dropping the connection. invalue must be
const int *; outvalue must be
int *.
LDAP_OPT_X_KEEPALIVE_INTERVALSets/gets the interval in seconds between individual
keepalive probes. invalue must be
const int *; outvalue must be
int *.
The TLS options are OpenLDAP specific.
LDAP_OPT_X_TLS_CACERTDIRSets/gets the path of the directory containing CA
certificates. invalue must be
const char *; outvalue must be
char **, and its
contents need to be freed by the caller using ldap_memfree(3).
LDAP_OPT_X_TLS_CACERTFILESets/gets the full-path of the CA certificate file.
invalue must be
const char *; outvalue must be
char **, and its
contents need to be freed by the caller using ldap_memfree(3).
LDAP_OPT_X_TLS_CERTFILESets/gets the full-path of the certificate file.
invalue must be
const char *; outvalue must be
char **, and its
contents need to be freed by the caller using ldap_memfree(3).
LDAP_OPT_X_TLS_CIPHER_SUITESets/gets the allowed cipher suite. invalue must be
const char *; outvalue must be
char **, and its
contents need to be freed by the caller using ldap_memfree(3).
LDAP_OPT_X_TLS_CONNECT_ARGSets/gets the connection callback argument.
invalue must be
const void *; outvalue must be
void **.
LDAP_OPT_X_TLS_CONNECT_CBSets/gets the connection callback handle. invalue must be
const LDAP_TLS_CONNECT_CB *;
outvalue must
be LDAP_TLS_CONNECT_CB
**.
LDAP_OPT_X_TLS_CRLCHECKSets/gets the CRL evaluation strategy, one of
LDAP_OPT_X_TLS_CRL_NONE,
LDAP_OPT_X_TLS_CRL_PEER,
or LDAP_OPT_X_TLS_CRL_ALL. invalue must be
const int *; outvalue must be
int *. Requires
OpenSSL.
LDAP_OPT_X_TLS_CRLFILESets/gets the full-path of the CRL file. invalue must be
const char *; outvalue must be
char **, and its
contents need to be freed by the caller using ldap_memfree(3). This
option is only valid for GnuTLS.
LDAP_OPT_X_TLS_CTXSets/gets the TLS library context. New TLS sessions
will inherit their default settings from this library
context. invalue must be
const void *; outvalue must be
void **. When
using the OpenSSL library this is an SSL_CTX*. When
using other crypto libraries this is a pointer to an
OpenLDAP private structure. Applications generally
should not use this option or attempt to manipulate
this structure.
LDAP_OPT_X_TLS_DHFILEGets/sets the full-path of the file containing the
parameters for Diffie-Hellman ephemeral key exchange.
invalue must be
const char *; outvalue must be
char **, and its
contents need to be freed by the caller using ldap_memfree(3).
Ignored by GnuTLS.
LDAP_OPT_X_TLS_KEYFILESets/gets the full-path of the certificate key file.
invalue must be
const char *; outvalue must be
char **, and its
contents need to be freed by the caller using ldap_memfree(3).
LDAP_OPT_X_TLS_NEWCTXInstructs the library to create a new TLS library
context. invalue must be
const int *. A non-zero value
pointed to by invalue tells the library
to create a context for a server.
LDAP_OPT_X_TLS_PROTOCOL_MINSets/gets the minimum protocol version. invalue must be
const int *; outvalue must be
int *.
LDAP_OPT_X_TLS_RANDOM_FILESets/gets the random file when /dev/random and /dev/urandom are not available.
invalue must be
const char *; outvalue must be
char **, and its
contents need to be freed by the caller using ldap_memfree(3).
Ignored by GnuTLS older than version 2.2.
LDAP_OPT_X_TLS_REQUIRE_CERTSets/gets the peer certificate checking strategy,
one of LDAP_OPT_X_TLS_NEVER, LDAP_OPT_X_TLS_HARD, LDAP_OPT_X_TLS_DEMAND, LDAP_OPT_X_TLS_ALLOW, LDAP_OPT_X_TLS_TRY.
LDAP_OPT_X_TLS_SSL_CTXGets the TLS session context associated with this
handle. outvalue must be
void **. When
using the OpenSSL library this is an SSL*. When using
other crypto libraries this is a pointer to an OpenLDAP
private structure. Applications generally should not
use this option.
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.
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.
The protocol version used by the library defaults to
LDAPv2 (now historic), which corresponds to the LDAP_VERSION2 macro. Application developers
are encouraged to explicitly set LDAP_OPT_PROTOCOL_VERSION to LDAPv3, using
the LDAP_VERSION3 macro, or to
allow users to select the protocol version.
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.