ldap_get_option(3ldap)
ldap_get_option, ldap_set_option --
control aspects of an LDAP session
Synopsis
#include <ldap.h>
int ldap_get_option(LDAP
ld, int option, void
outvalue);
int ldap_set_option(LDAP
ld, int option, void
invalue);
Description
The LDAP session handle returned by
ldap_init(3ldap)
is a pointer to a data type representing an LDAP session. This
should be treated as an opaque type, in which case ldap_get_option
can be used to access the current value of various session-wide parameters,
and ldap_set_option can be used to set the value of these
parameters.
Note that in RFC 1823, the LDAP session handle was not
opaque, and certain fields were used for the communication of session options.
This alternative style may still be used, but it is deprecated, and may not
be supported in subsequent releases of the LDAP library. Users
are advised to use ldap_get_option and ldap_set_option
instead.
The ld parameter is the session handle. The option
parameter identifies the option being accessed or set, and should be one
of the following constants:
- LDAP_OPT_DESC
-
The underlying socket descriptor corresponding to the default LDAP
connection.
- LDAP_OPT_DEREF
-
Controls how aliases are handled during search. It can have one of the
following values:
- LDAP_DEREF_NEVER
-
aliases are never dereferenced
- LDAP_DEREF_SEARCHING
-
aliases are dereferenced during the search, but not when locating the base
object of the search
- LDAP_DEREF_FINDING
-
aliases are dereferenced when locating the base object but not during the
search
- LDAP_DEREF_ALWAYS
-
aliases are always dereferenced, both for locating the base object and for
the search under the base object
- LDAP_OPT_SIZELIMIT
-
A limit on the number of entries to return from a search. A value of 0
means no limit. The datatype for invalue and outvalue
is
int
optdata
. In addition to the limit requested by the
client, the server may impose its own limits.
- LDAP_OPT_TIMELIMIT
-
A limit on the number of seconds to spend on a search. A value of 0 means
no limit. The datatype for invalue and outvalue is
int
optdata
. In addition to the limit requested by the client,
the server may impose its own limits.
- LDAP_OPT_REFERRALS
-
Controls whether the LDAP library automatically follows referrals
returned by LDAP servers or not. It can be set to one of the
constants LDAP_OPT_ON or LDAP_OPT_OFF.
- LDAP_OPT_RESTART
-
Controls whether LDAP I/O operations should automatically
be restarted if they abort prematurely. It should be set to one of the
constants LDAP_OPT_ON or LDAP_OPT_OFF. This option is
useful if an LDAP I/O operation may be interrupted
prematurely, for example by a timer.
- LDAP_OPT_VERSION
-
Indicates the version of the default LDAP server. Currently, only
LDAP_VERSION2 is supported.
- LDAP_OPT_REBIND_FN
-
Controls the routine that will be called back to obtain bind credentials
used when a new server is contacted during the following of an
LDAP referral. The use of the following is the expected
LDAP version 3 alternative to
ldap_set_rebind_proc(3ldap):
ldap_set_option(LDAP_OPT_REBIND_FN ...);
The following of referrals will only take place if LDAP_OPT_REFERRALS
is set to LDAP_OPT_ON (this is the default). If
ldap_set_option is never called to set LDAP_OPT_REBIND_FN,
or if it is called with a null invalue parameter, an unauthenticated
simple LDAP bind will always be done when chasing referrals.
The data type for the invalue parameter is as follows:
int (
invalue)(LDAP
ld, char 
whop, char 
credp,
int
methodp, int freeit);
The LDAP library will first call this rebind procedure to obtain
the referral bind credentials, and the freeit parameter will be 0.
The whop, credp, and methodp parameters should
be set as appropriate. If the rebind procedure returns LDAP_SUCCESS,
referral processing continues, and the rebind procedure will be called a
second time with non-zero freeit to give the application a chance
to free any memory allocated in the previous call.
If anything but LDAP_SUCCESS is returned by the first call
to the rebind procedure, then referral processing is stopped and that error
code is returned for the original LDAP operation.
The outvalue parameter specifies the address of a place to put
the value of the option. The type of this parameter depends on the setting
of the option parameter. invalue is a pointer to the value
the option is to be given. The type of this parameter depends on the setting
of option. The constants LDAP_OPT_ON and
LDAP_OPT_OFF can be given for options that have on or off settings.
References
Intro(3ldap)
30 January 1998
© 1998 The Santa Cruz Operation, Inc. All rights reserved.