path: root/usr/src/man/man3ldap/ldap_get_option.3ldap

'\" 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]
.TH LDAP_GET_OPTION 3LDAP "Jan 15, 2004"
.SH NAME
ldap_get_option, ldap_set_option \- get or set session preferences in the
\fBldap\fR structure.
.SH SYNOPSIS
.LP
.nf
\fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lldap\fR [ \fIlibrary\fR... ]
#include <lber.h>
#include <ldap.h>

\fBLDAP\fR \fBldap_set_option\fR(\fBLDAP\fR \fI*ld\fR, \fBint\fR \fIoption\fR, \fBvoid\fR \fI*optdata\fR[]);
.fi

.LP
.nf
\fBLDAP\fR \fBldap_get_option\fR(\fBLDAP\fR \fI*ld\fR, \fBint\fR \fIoption\fR, \fBvoid\fR \fIoptdata\fR[]);
.fi

.SH DESCRIPTION
.sp
.LP
These functions provide an \fBLDAP\fR structure with access to session
preferences. The \fBldap_get_option()\fR function gets session preferences from
the \fBLDAP\fR structure. The \fBldap_set_option()\fR function sets session
preferences in the \fBLDAP\fR structure.
.sp
.LP
The \fIld\fR parameter specifies the connection handle, a pointer to an
\fBLDAP\fR structure that contains information about the \fBLDAP\fR server
connection. The \fIoption\fR parameter specifies the name of the option to be
read or modified. The \fIoptdata\fR parameter serves as a pointer to the value
of the option that you set or get.
.SH PARAMETERS
.sp
.LP
The following values can be specified for the \fIoption\fR parameter:
.sp
.ne 2
.na
\fB\fBLDAP_OPT_API_INFO\fR\fR
.ad
.sp .6
.RS 4n
Retrieves basic information about the \fBLDAP\fR \fBAPI\fR implementation at
execution time. The data type for the \fIoptdata\fR parameter is
\fB(LDAPAPIInfo *)\fR. This option is READ-ONLY and cannot be set.
.RE

.sp
.ne 2
.na
\fB\fBLDAP_OPT_DEREF\fR\fR
.ad
.sp .6
.RS 4n
Determines how aliases are handled during a search. The data type for the
\fIoptdata\fR parameter is \fB(int *)\fR. The following values can be specified
for the \fIoptdata\fR parameter:
.sp
.ne 2
.na
\fB\fBLDAP_DEREF_NEVER\fR\fR
.ad
.RS 24n
Specifies that aliases are never dereferenced.
.RE

.sp
.ne 2
.na
\fB\fBLDAP_DEREF_SEARCHING\fR\fR
.ad
.RS 24n
Specifies that aliases are dereferenced when searching under the base object,
but not when finding the base object.
.RE

.sp
.ne 2
.na
\fB\fBLDAP_DEREF_FINDING\fR\fR
.ad
.RS 24n
Specifies that aliases are dereferenced when finding the base object, but not
when searching under the base object.
.RE

.sp
.ne 2
.na
\fB\fBLDAP_DEREF_ALWAYS\fR\fR
.ad
.RS 24n
Specifies that aliases are always dereferenced when finding the base object and
searching under the base object.
.RE

.RE

.sp
.ne 2
.na
\fB\fBLDAP_OPT_SIZELIMIT\fR\fR
.ad
.sp .6
.RS 4n
Specifies the maximum number of entries returned by the server in search
results. The data type for the \fIoptdata\fR parameter is \fB(int *)\fR.
Setting the \fIoptdata\fR parameter to \fBLDAP_NO_LIMIT\fR removes any size
limit enforced by the client.
.RE

.sp
.ne 2
.na
\fB\fBLDAP_OPT_TIMELIMIT\fR\fR
.ad
.sp .6
.RS 4n
Specifies the maximum number of seconds spent by the server when answering a
search request. The data type for the \fIoptdata\fR parameter is \fB(int *)\fR.
Setting the \fIoptdata\fR parameter to \fBLDAP_NO_LIMIT\fR removes any time
limit enforced by the client.
.RE

.sp
.ne 2
.na
\fB\fBLDAP_OPT_REFERRALS\fR\fR
.ad
.sp .6
.RS 4n
Determines whether the client should follow referrals. The data type for the
\fIoptdata\fR parameter is \fB(int *)\fR. The following values can be specified
for the \fIoptdata\fR parameter:
.sp
.ne 2
.na
\fB\fBLDAP_OPT_ON\fR\fR
.ad
.RS 16n
Specifies that the client should follow referrals.
.RE

.sp
.ne 2
.na
\fB\fBLDAP_OPT_OFF\fR\fR
.ad
.RS 16n
Specifies that the client should not follow referrals.
.RE

By default, the client follows referrals.
.RE

.sp
.ne 2
.na
\fB\fBLDAP_OPT_RESTART\fR\fR
.ad
.sp .6
.RS 4n
Determines whether \fBLDAP\fR I/O operations are automatically restarted if
aborted prematurely. It can be set to one of the constants \fBLDAP_OPT_ON\fR or
\fBLDAP_OPT_OFF\fR.
.RE

.sp
.ne 2
.na
\fB\fBLDAP_OPT_PROTOCOL_VERSION\fR\fR
.ad
.sp .6
.RS 4n
Specifies the version of the protocol supported by the client. The data type
for the \fIoptdata\fR parameter is \fB(int *)\fR. The version
\fBLDAP_VERSION2\fR or \fBLDAP_VERSION3\fR can be specified. If no version is
set, the default version \fBLDAP_VERSION2\fR is set. To use \fBLDAP\fR v3
features, set the protocol version to \fBLDAP_VERSION3\fR.
.RE

.sp
.ne 2
.na
\fB\fBLDAP_OPT_SERVER_CONTROLS\fR\fR
.ad
.sp .6
.RS 4n
Specifies a pointer to an array of \fBLDAPControl\fR structures that represent
the \fBLDAP\fR v3 server controls sent by default with every request. The data
type for the \fIoptdata\fR parameter for \fBldap_set_option()\fR is
\fB(LDAPControl **)\fR. For \fBldap_get_option()\fR, the data type is
\fB(LDAPControl ***)\fR.
.RE

.sp
.ne 2
.na
\fB\fBLDAP_OPT_CLIENT_CONTROLS\fR\fR
.ad
.sp .6
.RS 4n
Specifies a pointer to an array of \fBLDAPControl\fR structures that represent
the \fBLDAP\fR v3 client controls sent by default with every request. The data
type for the \fIoptdata\fR parameter for \fBldap_set_option()\fR is
\fB(LDAPControl **)\fR. For \fBldap_get_option()\fR, the data type is
\fB(LDAPControl ***)\fR.
.RE

.sp
.ne 2
.na
\fB\fBLDAP_OPT_API_FEATURE_INFO\fR\fR
.ad
.sp .6
.RS 4n
Retrieves version information at execution time about extended features of the
\fBLDAP\fR \fBAPI\fR. The data type for the \fIoptdata\fR parameter is
\fB(LDAPAPIFeatureInfo *)\fR. This option is READ-ONLY and cannot be set.
.RE

.sp
.ne 2
.na
\fB\fBLDAP_OPT_HOST_NAME\fR\fR
.ad
.sp .6
.RS 4n
Sets the host name or a list of hosts for the primary \fBLDAP\fR server. The
data type for the \fIoptdata\fR parameter for \fBldap_set_option()\fR is
\fB(char *)\fR. For \fBldap_get_option()\fR, the data type is \fB(char **)\fR.
.RE

.sp
.ne 2
.na
\fB\fBLDAP_OPT_ERROR_NUMBER\fR\fR
.ad
.sp .6
.RS 4n
Specifies the code of the most recent \fBLDAP\fR error that occurred for this
session. The data type for the \fIoptdata\fR parameter is \fB(int *)\fR.
.RE

.sp
.ne 2
.na
\fB\fBLDAP_OPT_ERROR_STRING\fR\fR
.ad
.sp .6
.RS 4n
Specifies the message returned with the most recent \fBLDAP\fR error that
occurred for this session. The data type for the \fIoptdata\fR parameter for
\fBldap_set_option()\fR is \fB(char *)\fR and for \fBldap_get_option()\fR is
\fB(char **)\fR.
.RE

.sp
.ne 2
.na
\fB\fBLDAP_OPT_MATCHED_DN\fR\fR
.ad
.sp .6
.RS 4n
Specifies the matched \fBDN\fR value returned with the most recent \fBLDAP\fR
error that occurred for this session. The data type for the \fIoptdata\fR
parameter for \fBldap_set_option()\fR is \fB(char *)\fR and for
\fBldap_get_option()\fR is \fB(char **)\fR.
.RE

.sp
.ne 2
.na
\fB\fBLDAP_OPT_REBIND_ARG\fR\fR
.ad
.sp .6
.RS 4n
Sets the last argument passed to the routine specified by
\fBLDAP_OPT_REBIND_FN\fR. This option can also be set by calling the
\fBldap_set_rebind_proc()\fR function. The data type for the \fIoptdata\fR
parameter is \fB(void * )\fR.
.RE

.sp
.ne 2
.na
\fB\fBLDAP_OPT_REBIND_FN\fR\fR
.ad
.sp .6
.RS 4n
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
\fBldap_set_rebind_proc()\fR function. The data type for the \fIoptdata\fR
parameter is \fB(\fR\fBLDAP_REBINDPROC_CALLBACK\fR\fB *)\fR.
.RE

.sp
.ne 2
.na
\fB\fBLDAP_OPT_X_SASL_MECH\fR\fR
.ad
.sp .6
.RS 4n
Sets the default SASL mechanism to call \fBldap_interactive_bind_s()\fR. The
data type for the \fIoptdata\fR parameter is \fB(char * )\fR.
.RE

.sp
.ne 2
.na
\fB\fBLDAP_OPT_X_SASL_REALM\fR\fR
.ad
.sp .6
.RS 4n
Sets the default \fBSASL_REALM\fR. The default \fBSASL_REALM\fR should be used
during a SASL challenge in response to a \fBSASL_CB_GETREALM\fR request when
using the \fBldap_interactive_bind_s()\fR function. The data type for the
\fIoptdata\fR parameter is \fB(char * )\fR.
.RE

.sp
.ne 2
.na
\fB\fBLDAP_OPT_X_SASL_AUTHCID\fR\fR
.ad
.sp .6
.RS 4n
Sets the default \fBSASL_AUTHNAME\fR used during a SASL challenge in response
to a \fBSASL_CB_AUTHNAME\fR request when using the
\fBldap_interactive_bind_s()\fR function. The data type for the \fIoptdata\fR
parameter is \fB(char * )\fR.
.RE

.sp
.ne 2
.na
\fB\fBLDAP_OPT_X_SASL_AUTHZID\fR\fR
.ad
.sp .6
.RS 4n
Sets the default \fBSASL_USER\fR that should be used during a SASL challenge in
response to a \fBSASL_CB_USER\fR request when using the
\fBldap_interactive_bind_s\fR function. The data type for the \fIoptdata\fR
parameter is \fB(char * )\fR.
.RE

.sp
.ne 2
.na
\fB\fBLDAP_OPT_X_SASL_SSF\fR\fR
.ad
.sp .6
.RS 4n
A read-only option used exclusively with the \fBldap_get_option()\fR function.
The \fBldap_get_option()\fR function performs a \fBsasl_getprop()\fR operation
that gets the \fBSASL_SSF\fR value for the current connection. The data type
for the \fIoptdata\fR parameter is \fB(sasl_ssf_t * )\fR.
.RE

.sp
.ne 2
.na
\fB\fBLDAP_OPT_X_SASL_SSF_EXTERNAL\fR\fR
.ad
.sp .6
.RS 4n
A write-only option used exclusively with the \fBldap_set_option()\fR function.
The \fBldap_set_option()\fR function performs a \fBsasl_setprop()\fR operation
to set the \fBSASL_SSF_EXTERNAL\fR value for the current connection. The data
type for the \fIoptdata\fR parameter is \fB(sasl_ssf_t * )\fR.
.RE

.sp
.ne 2
.na
\fB\fBLDAP_OPT_X_SASL_SECPROPS\fR\fR
.ad
.sp .6
.RS 4n
A write-only option used exclusively with the \fBldap_set_option()\fR. This
function performs a \fBsasl_setprop\fR(3SASL) operation for the
\fBSASL_SEC_PROPS\fR value for the current connection during an
\fBldap_interactive_bind_s()\fR operation. The data type for the \fIoptdata\fR
parameter is \fB(char * )\fR, a comma delimited string containing text values
for any of the \fBSASL_SEC_PROPS\fR that should be set. The text values are:
.sp
.ne 2
.na
\fB\fBnoanonymous\fR\fR
.ad
.RS 16n
Sets the \fBSASL_SEC_NOANONYMOUS\fR flag
.RE

.sp
.ne 2
.na
\fB\fBnodict\fR\fR
.ad
.RS 16n
Sets the \fBSASL_SEC_NODICTIONARY\fR flag
.RE

.sp
.ne 2
.na
\fB\fBnoplain\fR\fR
.ad
.RS 16n
Sets the \fBSASL_SEC_NOPLAINTEXT\fR flag
.RE

.sp
.ne 2
.na
\fB\fBforwardsec\fR\fR
.ad
.RS 16n
Sets the \fBSASL_SEC_FORWARD_SECRECY\fR flag
.RE

.sp
.ne 2
.na
\fB\fBpasscred\fR\fR
.ad
.RS 16n
Sets the \fBSASL_SEC_PASS_CREDENTIALS\fR flag
.RE

.sp
.ne 2
.na
\fB\fBminssf=N\fR\fR
.ad
.RS 16n
Sets \fBminssf\fR to the integer value \fBN\fR
.RE

.sp
.ne 2
.na
\fB\fBmaxssf=N\fR\fR
.ad
.RS 16n
Sets \fBmaxssf\fR to the integer value \fBN\fR
.RE

.sp
.ne 2
.na
\fB\fBmaxbufsize=N\fR\fR
.ad
.RS 16n
Sets \fBmaxbufsize\fR to the integer value \fBN\fR
.RE

.RE

.sp
.ne 2
.na
\fB\fBLDAP_OPT_X_SASL_SSF_MIN\fR\fR
.ad
.sp .6
.RS 4n
Sets the default \fBSSF_MIN\fR value used during a
\fBldap_interactive_bind_s()\fR operation. The data type for the \fIoptdata\fR
parameter is \fB(char * )\fR numeric string.
.RE

.sp
.ne 2
.na
\fB\fBLDAP_OPT_X_SASL_SSF_MAX\fR\fR
.ad
.sp .6
.RS 4n
Sets the default \fBSSF_MAX\fR value used during a
\fBldap_interactive_bind_s()\fR operation. The data type for the \fIoptdata\fR
parameter is \fB(char * )\fR numeric string.
.RE

.sp
.ne 2
.na
\fB\fBLDAP_OPT_X_SASL_MAXBUFSIZE\fR\fR
.ad
.sp .6
.RS 4n
Sets the default \fBSSF_MAXBUFSIZE\fR value used during a
\fBldap_interactive_bind_s()\fR operation. The data type for the \fIoptdata\fR
parameter is \fB(char * )\fR numeric string.
.RE

.SH RETURN VALUES
.sp
.LP
The \fBldap_set_option()\fR and \fBldap_get_option()\fR functions return:
.sp
.ne 2
.na
\fB\fBLDAP_SUCCESS\fR\fR
.ad
.RS 16n
If successful
.RE

.sp
.ne 2
.na
\fB\fB-1\fR\fR
.ad
.RS 16n
If unsuccessful
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Evolving
_
MT-Level	Safe
.TE

.SH SEE ALSO
.sp
.LP
\fBldap_init\fR(3LDAP), \fBsasl_setprop\fR(3SASL), \fBattributes\fR(5)
.SH NOTES
.sp
.LP
There are other elements in the \fBLDAP\fR structure that should not be
changed. No assumptions should be made about the order of elements in the
\fBLDAP\fR structure.