These functions provide access to session preferences to an LDAP structure. ldap_get_option() gets session preferences from the LDAP structure. ldap_set_option() sets session preferences in the LDAP structure.

ld is the connection handle, which is a pointer to an LDAP structure containing information about the connection to the LDAP server. option is the name of the option to be read or modified. optdata is a pointer to the value of the option that you want to set/get.

The option parameter can have one of the values listed in the following section.

The following are the values for the option parameter:

LDAP_OPT_API_INFO

Used to retrieve some basic information about the LDAP API implementation at execution time. The data type for the optdata parameter is (LDAPAPIInfo *). This option is READ-ONLY and cannot be set.

LDAP_OPT_DEREF

Determines how aliases are handled during a search . The data type for the optdata parameter is (int *). optdata can be one of the following values:

LDAP_DEREF_NEVER

Specifies that aliases are never dereferenced.

LDAP_DEREF_SEARCHING

Specifies that aliases are dereferenced when searching under the base object (but not when finding the base object).

LDAP_DEREF_FINDING

Specifies thataliases are dereferenced when finding the base object (but not when searching under the base object).

LDAP_DEREF_ALWAYS

Specifies that aliases are always dereferenced when finding the base object and searching under the base object.

LDAP_OPT_SIZELIMIT

Maximum number of entries that should be returned by the server in search results. The data type for the optdata parameter is (int *). Setting the optdata parameter to LDAP_NO_LIMIT removes any size limit enforced by the client.

LDAP_OPT_TIMELIMIT

Maximum number of seconds that should be spent by the server when answering a search request. The data type for the optdata parameter is (int *). Setting the optdata parameter to LDAP_NO_LIMIT removes any time limit enforced by the client.

LDAP_OPT_REFERRALS

Determines whether or not the client should follow referrals. The data type for the optdata parameter is (int *). optdata can be one of the following values:

LDAP_OPT_ON

Specifies that the client should follow referrals.

LDAP_OPT_OFF

Specifies that the client should not follow referrals.

By default, the client follows referrals.

LDAP_OPT_RESTART

Determines whether LDAP I/O operations are automatically restarted if they abort prematurely. It may be set to one of the constants LDAP_OPT_ON or LDAP_OPT_OFF.

LDAP_OPT_PROTOCOL_VERSION

Version of the protocol supported by your client. The data type for the optdata parameter is (int *). You can specify either LDAP_VERSION2 or LDAP_VERSION3. If no version is set, the default is LDAP_VERSION2. In order to use LDAP v3 features, you need to set the protocol version to LDAP_VERSION3.

LDAP_OPT_SERVER_CONTROLS

Pointer to an array of LDAPControl structures representing the LDAP v3 server controls you want sent with every request by default. The data type for the optdata parameter for ldap_set_option() is (LDAPControl **) and for ldap_get_option() is (LDAPControl ***).

LDAP_OPT_CLIENT_CONTROLS

Pointer to an array of LDAPControl structures representing the LDAP v3 client controls you want sent with every request by default. The data type for the optdata parameter for ldap_set_option() is (LDAPControl **) and for ldap_get_option() is (LDAPControl ***).

LDAP_OPT_API_FEATURE_INFO

Used to retrieve version information about LDAP API extended features at execution time. The data type for the optdata parameter is (LDAPAPIFeatureInfo *). This option is READ-ONLY and cannot be set.

LDAP_OPT_HOST_NAME

This option sets the host name (or list of hosts) for the primary LDAP server. The data type for the optdata parameter for ldap_set_option() is (char *), and for ldap_get_option() is (char **).

LDAP_OPT_ERROR_NUMBER

The code of the most recent LDAP error that occurred for this session. The data type for the optdata parameter is (int *).

LDAP_OPT_ERROR_STRING

The message returned with the most recent LDAP error that occurred for this session. The data type for the optdata parameter for ldap_set_option() is (char *) and for ldap_get_option() is (char **).

LDAP_OPT_MATCHED_DN

The matched DN value returned with the most recent LDAP error that occurred for this session. The data type for the optdata parameter for ldap_set_option() is (char *) and for ldap_get_option() is (char **).

LDAP_OPT_REBIND_ARG

Lets you set the last argument passed to the routine specified by LDAP_OPT_REBIND_FN. You can also set this option by calling the ldap_set_rebind_proc() function. The data type for the optdata parameter is (void * ).

LDAP_OPT_REBIND_FN

Lets you set the routine to be called when you need to authenticate a connection with another LDAP server (for example, during the course of a referral). You can also set this option by calling the ldap_set_rebind_proc() function. The data type for the optdata parameter is (LDAP_REBINDPROC_CALLBACK *).

The ldap_set_option() and ldap_get_option() functions return:

LDAP_SUCCESS

If successful

-1

If unsuccessful

Upon successful completion, both functions return LDAP_SUCCESS, otherwise -1 is returned.

See attributes(5) for a description of the following attributes:

ldap_init(3LDAP), attributes(5)

There are other elements in the LDAP structure that you should not change. You should not make any assumptions about the order of elements in the LDAP structure.