--- /dev/null
+.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.
projects / openldap / commitdiff