xref: /titanic_50/usr/src/man/man3ldap/ldap_get_option.3ldap (revision c10c16dec587a0662068f6e2991c29ed3a9db943) 
 te
 Copyright (C) 1990, Regents of the University of Michigan. All Rights Reserved.
 Portions Copyright (C) 2004, Sun Microsystems, Inc. All Rights Reserved.
 The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
 You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
 When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
 ldap_get_option 3LDAP "15 Jan 2004" "SunOS 5.11" "LDAP Library Functions"
 NAME
ldap_get_option, ldap_set_option - get or set session preferences in the
ldap structure.

 SYNOPSIS


cc [ flag... ] file... -lldap [ library... ]
#include <lber.h>
#include <ldap.h>

LDAP ldap_set_option(LDAP *ld, int option, void *optdata[]);






LDAP ldap_get_option(LDAP *ld, int option, void optdata[]);




 DESCRIPTION

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


The ld parameter specifies the connection handle, a pointer to an
LDAP structure that contains information about the LDAP server
connection. The option parameter specifies the name of the option to be
read or modified. The optdata parameter serves as a pointer to the value
of the option that you set or get.

 PARAMETERS

The following values can be specified for the option parameter:


LDAP_OPT_API_INFO


Retrieves 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 *). The following values can be specified
for the optdata parameter:


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 that aliases 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


Specifies the maximum number of entries 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


Specifies the maximum number of seconds 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 the client should follow referrals. The data type for the
optdata parameter is (int *). The following values can be specified
for the optdata parameter:


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
aborted prematurely. It can be set to one of the constants LDAP_OPT_ON or
LDAP_OPT_OFF.





LDAP_OPT_PROTOCOL_VERSION


Specifies the version of the protocol supported by the client. The data type
for the optdata parameter is (int *). The version
LDAP_VERSION2 or LDAP_VERSION3 can be specified. If no version is
set, the default version LDAP_VERSION2 is set. To use LDAP v3
features, set the protocol version to LDAP_VERSION3.





LDAP_OPT_SERVER_CONTROLS


Specifies a pointer to an array of LDAPControl structures that represent
the LDAP v3 server controls sent by default with every request. The data
type for the optdata parameter for ldap_set_option() is
(LDAPControl **). For ldap_get_option(), the data type is
(LDAPControl ***).





LDAP_OPT_CLIENT_CONTROLS


Specifies a pointer to an array of LDAPControl structures that represent
the LDAP v3 client controls sent by default with every request. The data
type for the optdata parameter for ldap_set_option() is
(LDAPControl **). For ldap_get_option(), the data type is
(LDAPControl ***).





LDAP_OPT_API_FEATURE_INFO


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





LDAP_OPT_HOST_NAME


Sets the host name or a list of hosts for the primary LDAP server. The
data type for the optdata parameter for ldap_set_option() is
(char *). For ldap_get_option(), the data type is (char **).





LDAP_OPT_ERROR_NUMBER


Specifies 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


Specifies 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


Specifies 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


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





LDAP_OPT_REBIND_FN


Sets the routine to be called to authenticate a connection with another LDAP
server. For example, the option is used to set the routine called during the
course of a referral. This option can also be by calling the
ldap_set_rebind_proc() function. The data type for the optdata
parameter is (LDAP_REBINDPROC_CALLBACK *).





LDAP_OPT_X_SASL_MECH


Sets the default SASL mechanism to call ldap_interactive_bind_s(). The
data type for the optdata parameter is (char * ).





LDAP_OPT_X_SASL_REALM


Sets the default SASL_REALM. The default SASL_REALM should be used
during a SASL challenge in response to a SASL_CB_GETREALM request when
using the ldap_interactive_bind_s() function. The data type for the
optdata parameter is (char * ).





LDAP_OPT_X_SASL_AUTHCID


Sets the default SASL_AUTHNAME used during a SASL challenge in response
to a SASL_CB_AUTHNAME request when using the
ldap_interactive_bind_s() function. The data type for the optdata
parameter is (char * ).





LDAP_OPT_X_SASL_AUTHZID


Sets the default SASL_USER that should be used during a SASL challenge in
response to a SASL_CB_USER request when using the
ldap_interactive_bind_s function. The data type for the optdata
parameter is (char * ).





LDAP_OPT_X_SASL_SSF


A read-only option used exclusively with the ldap_get_option() function.
The ldap_get_option() function performs a sasl_getprop() operation
that gets the SASL_SSF value for the current connection. The data type
for the optdata parameter is (sasl_ssf_t * ).





LDAP_OPT_X_SASL_SSF_EXTERNAL


A write-only option used exclusively with the ldap_set_option() function.
The ldap_set_option() function performs a sasl_setprop() operation
to set the SASL_SSF_EXTERNAL value for the current connection. The data
type for the optdata parameter is (sasl_ssf_t * ).





LDAP_OPT_X_SASL_SECPROPS


A write-only option used exclusively with the ldap_set_option(). This
function performs a sasl_setprop(3SASL) operation for the
SASL_SEC_PROPS value for the current connection during an
ldap_interactive_bind_s() operation. The data type for the optdata
parameter is (char * ), a comma delimited string containing text values
for any of the SASL_SEC_PROPS that should be set. The text values are:


noanonymous


Sets the SASL_SEC_NOANONYMOUS flag





nodict


Sets the SASL_SEC_NODICTIONARY flag





noplain


Sets the SASL_SEC_NOPLAINTEXT flag





forwardsec


Sets the SASL_SEC_FORWARD_SECRECY flag





passcred


Sets the SASL_SEC_PASS_CREDENTIALS flag





minssf=N


Sets minssf to the integer value N





maxssf=N


Sets maxssf to the integer value N





maxbufsize=N


Sets maxbufsize to the integer value N








LDAP_OPT_X_SASL_SSF_MIN


Sets the default SSF_MIN value used during a
ldap_interactive_bind_s() operation. The data type for the optdata
parameter is (char * ) numeric string.





LDAP_OPT_X_SASL_SSF_MAX


Sets the default SSF_MAX value used during a
ldap_interactive_bind_s() operation. The data type for the optdata
parameter is (char * ) numeric string.





LDAP_OPT_X_SASL_MAXBUFSIZE


Sets the default SSF_MAXBUFSIZE value used during a
ldap_interactive_bind_s() operation. The data type for the optdata
parameter is (char * ) numeric string.




 RETURN VALUES

The ldap_set_option() and ldap_get_option() functions return:


LDAP_SUCCESS


If successful





-1


If unsuccessful




 ATTRIBUTES

See attributes(5) for descriptions of the following attributes:







ATTRIBUTE TYPEATTRIBUTE VALUE
Interface StabilityEvolving
MT-LevelSafe



 SEE ALSO

ldap_init(3LDAP), sasl_setprop(3SASL), attributes(5)

 NOTES

There are other elements in the LDAP structure that should not be
changed. No assumptions should be made about the order of elements in the
LDAP structure.