mirror of
https://git.openldap.org/openldap/openldap.git
synced 2024-12-21 03:10:25 +08:00
338 lines
8.1 KiB
Groff
338 lines
8.1 KiB
Groff
.TH LDAP_GET_OPTION 3 "RELEASEDATE" "OpenLDAP LDVERSION"
|
|
.\" $OpenLDAP$
|
|
.\" Copyright 1998-2008 The OpenLDAP Foundation All Rights Reserved.
|
|
.\" Copying restrictions apply. See COPYRIGHT/LICENSE.
|
|
.SH NAME
|
|
ldap_get_option, ldap_set_option \- LDAP option handling routines
|
|
.SH LIBRARY
|
|
OpenLDAP LDAP (libldap, -lldap)
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B #include <ldap.h>
|
|
.LP
|
|
.BI "int ldap_get_option(LDAP *" ld ", int " option ", void *" outvalue ");"
|
|
.LP
|
|
.BI "int ldap_set_option(LDAP *" ld ", int " option ", const void *" invalue ");"
|
|
.SH DESCRIPTION
|
|
.LP
|
|
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
|
|
.BR ldap_get_option (3)
|
|
or set by
|
|
.BR ldap_set_option (3)
|
|
is cast to
|
|
.BR "void *" .
|
|
The actual type is determined based on the value of the
|
|
.B option
|
|
argument.
|
|
Global options are set/retrieved by passing a NULL LDAP handle.
|
|
.TP
|
|
.B LDAP_OPT_API_INFO
|
|
Fills-in a
|
|
.BR "struct ldapapiinfo" ;
|
|
.BR outvalue
|
|
must be a
|
|
.BR "struct ldapapiinfo *" ,
|
|
pointing to an already allocated struct.
|
|
This is a read-only option.
|
|
.TP
|
|
.B LDAP_OPT_DESC
|
|
Returns the file descriptor associated to the socket buffer
|
|
of the LDAP handle passed in as
|
|
.BR ld ;
|
|
.BR outvalue
|
|
must be a
|
|
.BR "int *" .
|
|
This is a read-only, handler-specific option.
|
|
.TP
|
|
.B LDAP_OPT_SOCKBUF
|
|
Returns a pointer to the socket buffer of the LDAP handle passed in as
|
|
.BR ld ;
|
|
.BR outvalue
|
|
must be a
|
|
.BR "Sockbuf **" .
|
|
This is a read-only, handler-specific option.
|
|
.TP
|
|
.B LDAP_OPT_TIMEOUT
|
|
Sets/gets a timeout value for the synchronous API calls.
|
|
.B outvalue
|
|
must be a
|
|
.BR "struct timeval **"
|
|
(the caller has to free
|
|
.BR *outvalue ) ,
|
|
and
|
|
.B invalue
|
|
must be a
|
|
.BR "struct timeval *" ,
|
|
and they cannot be NULL. Using a struct with seconds set to -1 results
|
|
in an infinite timeout, which is the default.
|
|
.TP
|
|
.B LDAP_OPT_NETWORK_TIMEOUT
|
|
Sets/gets the network timeout value after which
|
|
.BR poll (2)/ select (2)
|
|
following a
|
|
.BR connect (2)
|
|
returns in case of no activity.
|
|
.B outvalue
|
|
must be a
|
|
.BR "struct timeval **"
|
|
(the caller has to free
|
|
.BR *outvalue ) ,
|
|
and
|
|
.B invalue
|
|
must be a
|
|
.BR "struct timeval *" ,
|
|
and they cannot be NULL. Using a struct with seconds set to -1 results
|
|
in an infinite timeout, which is the default.
|
|
.TP
|
|
.B LDAP_OPT_DEREF
|
|
Sets/gets the value that defines when alias dereferencing must occur.
|
|
.BR outvalue
|
|
and
|
|
.BR invalue
|
|
must be
|
|
.BR "int *" ,
|
|
and they cannot be NULL.
|
|
.TP
|
|
.B LDAP_OPT_SIZELIMIT
|
|
Sets/gets the value that defines the maximum number of entries
|
|
to be returned by a search operation.
|
|
.BR outvalue
|
|
and
|
|
.BR invalue
|
|
must be
|
|
.BR "int *" ,
|
|
and they cannot be NULL.
|
|
.TP
|
|
.B LDAP_OPT_TIMELIMIT
|
|
Sets/gets the value that defines the time limit after which
|
|
a search operation should be terminated by the server.
|
|
.BR outvalue
|
|
and
|
|
.BR invalue
|
|
must be
|
|
.BR "int *" ,
|
|
and they cannot be NULL.
|
|
.TP
|
|
.B LDAP_OPT_REFERRALS
|
|
Determines whether the library should implicitly chase referrals or not.
|
|
.BR outvalue
|
|
and
|
|
.BR invalue
|
|
must be
|
|
.BR "int *" ;
|
|
their value should either be
|
|
.BR LDAP_OPT_OFF
|
|
or
|
|
.BR LDAP_OPT_ON .
|
|
.TP
|
|
.B LDAP_OPT_RESTART
|
|
Determines whether the library should implicitly restart connections (FIXME).
|
|
.BR outvalue
|
|
and
|
|
.BR invalue
|
|
must be
|
|
.BR "int *" ;
|
|
their value should either be
|
|
.BR LDAP_OPT_OFF
|
|
or
|
|
.BR LDAP_OPT_ON .
|
|
.TP
|
|
.B LDAP_OPT_PROTOCOL_VERSION
|
|
Sets/gets the protocol version.
|
|
.BR outvalue
|
|
and
|
|
.BR invalue
|
|
must be
|
|
.BR "int *" .
|
|
.TP
|
|
.B LDAP_OPT_SERVER_CONTROLS
|
|
Sets/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
|
|
.BR ldap_search_ext (3),
|
|
.BR ldap_add_ext (3),
|
|
.BR ldap_modify_ext (3)
|
|
and so on.
|
|
.BR outvalue
|
|
must be
|
|
.BR "LDAPControl ***" ,
|
|
and the caller is responsible of freeing the returned controls, if any,
|
|
by calling
|
|
.BR ldap_controls_free (3),
|
|
while
|
|
.BR invalue
|
|
must be
|
|
.BR "LDAPControl **" ;
|
|
the library duplicates the controls passed via
|
|
.BR invalue .
|
|
.TP
|
|
.B LDAP_OPT_CLIENT_CONTROLS
|
|
Sets/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
|
|
.BR ldap_search_ext (3),
|
|
.BR ldap_add_ext (3),
|
|
.BR ldap_modify_ext (3)
|
|
and so on.
|
|
.BR outvalue
|
|
must be
|
|
.BR "LDAPControl ***" ,
|
|
and the caller is responsible of freeing the returned controls, if any,
|
|
by calling
|
|
.BR ldap_controls_free (3),
|
|
while
|
|
.BR invalue
|
|
must be
|
|
.BR "LDAPControl **" ;
|
|
the library duplicates the controls passed via
|
|
.BR invalue .
|
|
.TP
|
|
.B LDAP_OPT_HOST_NAME
|
|
Sets/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
|
|
.BR LDAP_OPT_URI .
|
|
.BR outvalue
|
|
must be a
|
|
.BR "char **" ,
|
|
and the caller is responsible of freeing the resulting string by calling
|
|
.BR ldap_memfree (3),
|
|
while
|
|
.BR invalue
|
|
must be a
|
|
.BR "char *" ;
|
|
the library duplicates the corresponding string.
|
|
.TP
|
|
.B LDAP_OPT_URI
|
|
Sets/gets a space-separated list of URIs to be contacted by the library
|
|
when trying to establish a connection.
|
|
.BR outvalue
|
|
must be a
|
|
.BR "char **" ,
|
|
and the caller is responsible of freeing the resulting string by calling
|
|
.BR ldap_memfree (3),
|
|
while
|
|
.BR invalue
|
|
must be a
|
|
.BR "char *" ;
|
|
the library parses the string into a list of
|
|
.BR LDAPURLDesc
|
|
structures, so the invocation of
|
|
.BR ldap_set_option (3)
|
|
may fail if URL parsing fails.
|
|
.TP
|
|
.B LDAP_OPT_DEFBASE
|
|
Sets/gets a string containing the DN to be used as default base
|
|
for search operations.
|
|
.BR outvalue
|
|
must be a
|
|
.BR "char **" ,
|
|
and the caller is responsible of freeing the returned string by calling
|
|
.BR ldap_memfree (3),
|
|
while
|
|
.BR invalue
|
|
must be a
|
|
.BR "char *" ;
|
|
the library duplicates the corresponding string.
|
|
.TP
|
|
.B LDAP_OPT_RESULT_CODE
|
|
Sets/gets the LDAP result code associated to the handle.
|
|
This option was formerly known as
|
|
.BR LDAP_OPT_ERROR_NUMBER .
|
|
Both
|
|
.BR outvalue
|
|
and
|
|
.BR invalue
|
|
must be a
|
|
.BR "int *" .
|
|
.TP
|
|
.B LDAP_OPT_DIAGNOSTIC_MESSAGE
|
|
Sets/gets a string containing the error string associated to the LDAP handle.
|
|
This option was formerly known as
|
|
.BR LDAP_OPT_ERROR_STRING .
|
|
.BR outvalue
|
|
must be a
|
|
.BR "char **" ,
|
|
and the caller is responsible of freeing the returned string by calling
|
|
.BR ldap_memfree (3),
|
|
while
|
|
.BR invalue
|
|
must be a
|
|
.BR "char *" ;
|
|
the library duplicates the corresponding string.
|
|
.TP
|
|
.B LDAP_OPT_MATCHED_DN
|
|
Sets/gets a string containing the matched DN associated to the LDAP handle.
|
|
.BR outvalue
|
|
must be a
|
|
.BR "char **" ,
|
|
and the caller is responsible of freeing the returned string by calling
|
|
.BR ldap_memfree (3),
|
|
while
|
|
.BR invalue
|
|
must be a
|
|
.BR "char *" ;
|
|
the library duplicates the corresponding string.
|
|
.TP
|
|
.B LDAP_OPT_REFERRAL_URLS
|
|
Sets/gets an array containing the referral URIs associated to the LDAP handle.
|
|
.BR outvalue
|
|
must be a
|
|
.BR "char ***" ,
|
|
and the caller is responsible of freeing the returned string by calling
|
|
.BR ber_memvfree (3),
|
|
while
|
|
.BR invalue
|
|
must be a NULL-terminated
|
|
.BR "char **" ;
|
|
the library duplicates the corresponding string.
|
|
.TP
|
|
.B LDAP_OPT_API_FEATURE_INFO
|
|
Fills-in a
|
|
.BR "LDAPAPIFeatureInfo" ;
|
|
.BR outvalue
|
|
must be a
|
|
.BR "LDAPAPIFeatureInfo *" ,
|
|
pointing to an already allocated struct.
|
|
This is a read-only option.
|
|
.TP
|
|
.B LDAP_OPT_DEBUG_LEVEL
|
|
Sets/gets the debug level of the client library.
|
|
Both
|
|
.BR outvalue
|
|
and
|
|
.BR invalue
|
|
must be a
|
|
.BR "int *" .
|
|
.SH ERRORS
|
|
On success, the functions return
|
|
.BR LDAP_OPT_SUCCESS ,
|
|
while they may return
|
|
.B LDAP_OPT_ERROR
|
|
to indicate a generic option handling error.
|
|
Occasionally, more specific errors can be returned, like
|
|
.B LDAP_NO_MEMORY
|
|
to indicate a failure in memory allocation.
|
|
.SH NOTES
|
|
The LDAP libraries with the
|
|
.B LDAP_OPT_REFERRALS
|
|
option set to
|
|
.B 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
|
|
.BR LDAP_OPT_OFF .
|
|
.SH SEE ALSO
|
|
.BR ldap (3),
|
|
.BR ldap_error (3),
|
|
.B RFC 4422
|
|
(http://www.rfc-editor.org),
|
|
.SH ACKNOWLEDGEMENTS
|
|
.so ../Project
|