openldap/doc/man/man3/ldap_get_option.3

.TH LDAP_GET_OPTION 3 "RELEASEDATE" "OpenLDAP LDVERSION"
.\" $OpenLDAP$
.\" Copyright 1998-2006 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 (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 (\fIFIXME: currently unused\fP).
.BR outvalue
must be a 
.BR "struct timeval **" ,
and the resulting pointer must be freed by the caller using
.BR ldap_memfree (3).
.BR invalue
must be a
.BR "struct timeval *" .
.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.
.BR outvalue
must be a 
.BR "struct timeval **" ,
and the resulting pointer must be freed by the caller using
.BR ldap_memfree (3).
.BR invalue
must be a
.BR "struct timeval *" .
.TP
.B LDAP_OPT_DEREF
Sets/gets the value that defines when alias deferencing 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 favour 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_ERROR_STRING
Sets/gets a string containing the error string 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_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
.B OpenLDAP
is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
.B OpenLDAP
is derived from University of Michigan LDAP 3.3 Release.