From 607c80df81596e1bdfe39cf0ded31ea1d90ea6d2 Mon Sep 17 00:00:00 2001 From: Pierangelo Masarati Date: Mon, 9 Oct 2006 21:17:43 +0000 Subject: [PATCH] document ldap_[sg]et_option(3) --- doc/man/man3/ldap_get_option.3 | 331 +++++++++++++++++++++++++++ doc/man/man3/ldap_get_option.3.links | 1 + 2 files changed, 332 insertions(+) create mode 100644 doc/man/man3/ldap_get_option.3 create mode 100644 doc/man/man3/ldap_get_option.3.links diff --git a/doc/man/man3/ldap_get_option.3 b/doc/man/man3/ldap_get_option.3 new file mode 100644 index 0000000000..07580d7d01 --- /dev/null +++ b/doc/man/man3/ldap_get_option.3 @@ -0,0 +1,331 @@ +.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 +.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. diff --git a/doc/man/man3/ldap_get_option.3.links b/doc/man/man3/ldap_get_option.3.links new file mode 100644 index 0000000000..9105ef0272 --- /dev/null +++ b/doc/man/man3/ldap_get_option.3.links @@ -0,0 +1 @@ +ldap_set_option.3 -- 2.39.5