diff options
Diffstat (limited to 'doc/man/man3/ldap_get_option.3')
| -rw-r--r-- | doc/man/man3/ldap_get_option.3 | 810 |
1 files changed, 810 insertions, 0 deletions
diff --git a/doc/man/man3/ldap_get_option.3 b/doc/man/man3/ldap_get_option.3 new file mode 100644 index 0000000..af5ede1 --- /dev/null +++ b/doc/man/man3/ldap_get_option.3 @@ -0,0 +1,810 @@ +.TH LDAP_GET_OPTION 3 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" $OpenLDAP$ +.\" Copyright 1998-2018 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. LDAP handles +inherit their default settings from the global options in effect at the time +the handle is created. +.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. +The +.B ldapaif_info_version +field of the struct must be initialized to +.B LDAP_FEATURE_INFO_VERSION +before making the call. The +.B ldapaif_name +field must be set to the name of a feature to query. +This is a read-only option. +.TP +.B LDAP_OPT_API_INFO +Fills-in a +.BR "LDAPAPIInfo" ; +.BR outvalue +must be a +.BR "LDAPAPIInfo *" , +pointing to an already allocated struct. The +.B ldapai_info_version +field of the struct must be initialized to +.B LDAP_API_INFO_VERSION +before making the call. +If the version passed in does not match the current library +version, the expected version number will be stored in the +struct and the call will fail. +The caller is responsible for freeing the elements of the +.B ldapai_extensions +array and the array itself using +.BR ldap_memfree (3). +The caller must also free the +.BR ldapi_vendor_name . +This is a read-only option. +.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 *const *" ; +the library duplicates the controls passed via +.BR invalue . +.TP +.B LDAP_OPT_CONNECT_ASYNC +Sets/gets the status of the asynchronous connect flag. +.BR invalue +should either be +.BR LDAP_OPT_OFF +or +.BR LDAP_OPT_ON ; +.BR outvalue +must be +.BR "int *" . +When set, the library will call +.BR connect (2) +and return, without waiting for response. +This leaves the handle in a connecting state. +Subsequent calls to library routines will poll for completion +of the connect before performing further operations. +As a consequence, library calls that need to establish a connection +with a DSA do not block even for the network timeout +(option +.BR LDAP_OPT_NETWORK_TIMEOUT ). +This option is OpenLDAP specific. +.TP +.B LDAP_OPT_CONNECT_CB +This option allows to set a connect callback. +.B invalue +must be a +.BR "const struct ldap_conncb *" . +Callbacks are executed in last in-first served order. +Handle-specific callbacks are executed first, followed by global ones. +Right before freeing the callback structure, the +.B lc_del +callback handler is passed a +.B NULL +.BR Sockbuf . +Calling +.BR ldap_get_option (3) +for this option removes the callback whose pointer matches +.BR outvalue . +This option is OpenLDAP specific. +.TP +.B LDAP_OPT_DEBUG_LEVEL +Sets/gets the debug level of the client library. +.BR invalue +must be a +.BR "const int *" ; +.BR outvalue +must be a +.BR "int *" . +Valid debug levels are +.BR LDAP_DEBUG_ANY , +.BR LDAP_DEBUG_ARGS , +.BR LDAP_DEBUG_BER , +.BR LDAP_DEBUG_CONNS , +.BR LDAP_DEBUG_NONE , +.BR LDAP_DEBUG_PACKETS , +.BR LDAP_DEBUG_PARSE , +and +.BR LDAP_DEBUG_TRACE . +This option is OpenLDAP specific. +.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 "const char *" ; +the library duplicates the corresponding string. +This option is OpenLDAP specific. +.TP +.B LDAP_OPT_DEREF +Sets/gets the value that defines when alias dereferencing must occur. +.BR invalue +must be +.BR "const int *" ; +.BR outvalue +must be +.BR "int *" . +They cannot be NULL. +The value of +.BR *invalue +should be one of +.BR LDAP_DEREF_NEVER +(the default), +.BR LDAP_DEREF_SEARCHING , +.BR LDAP_DEREF_FINDING , +or +.BR LDAP_DEREF_ALWAYS . +Note that this has ever been the only means to determine alias dereferencing +within search operations. +.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, handle-specific option. +.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_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 "const 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 "const char *" ; +the library duplicates the corresponding string. +.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 "const struct timeval *" . +They cannot be NULL. Using a struct with seconds set to \-1 results +in an infinite timeout, which is the default. +This option is OpenLDAP specific. +.TP +.B LDAP_OPT_PROTOCOL_VERSION +Sets/gets the protocol version. +.BR outvalue +and +.BR invalue +must be +.BR "int *" . +.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 ldap_memvfree (3), +while +.BR invalue +must be a NULL-terminated +.BR "char *const *" ; +the library duplicates the corresponding string. +This option is OpenLDAP specific. +.TP +.B LDAP_OPT_REFERRALS +Determines whether the library should implicitly chase referrals or not. +.BR invalue +must be +.BR "const int *" ; +its value should either be +.BR LDAP_OPT_OFF +or +.BR LDAP_OPT_ON . +.BR outvalue +must be +.BR "int *" . +.\".TP +.\".B LDAP_OPT_REFHOPLIMIT +.\"This option is OpenLDAP specific. +.\"It is not currently implemented. +.TP +.B LDAP_OPT_RESTART +Determines whether the library should implicitly restart connections (FIXME). +.BR invalue +must be +.BR "const int *" ; +its value should either be +.BR LDAP_OPT_OFF +or +.BR LDAP_OPT_ON . +.BR outvalue +must be +.BR "int *" . +.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 . +.BR invalue +must be a +.BR "const int *" . +.BR outvalue +must be a +.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 *const *" ; +the library duplicates the controls passed via +.BR invalue . +.TP +.B LDAP_OPT_SESSION_REFCNT +Returns the reference count associated with the LDAP handle passed in as +.BR ld ; +.BR outvalue +must be a +.BR "int *" . +This is a read-only, handle-specific option. +This option is OpenLDAP specific. +.TP +.B LDAP_OPT_SIZELIMIT +Sets/gets the value that defines the maximum number of entries +to be returned by a search operation. +.BR invalue +must be +.BR "const int *" , +while +.BR outvalue +must be +.BR "int *" ; +They cannot be NULL. +.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, handle-specific option. +This option is OpenLDAP specific. +.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 invalue +must be +.BR "const int *" , +while +.BR outvalue +must be +.BR "int *" , +and they cannot be NULL. +.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. +This option is OpenLDAP specific. +.TP +.B LDAP_OPT_URI +Sets/gets a comma- or 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 "const 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. +URIs may only contain the +.BR schema , +the +.BR host , +and the +.BR port +fields. +This option is OpenLDAP specific. +.SH SASL OPTIONS +The SASL options are OpenLDAP specific. +.TP +.B LDAP_OPT_X_SASL_AUTHCID +Gets the SASL authentication identity; +.BR outvalue +must be a +.BR "char **" , +its content needs to be freed by the caller using +.BR ldap_memfree (3). +.TP +.B LDAP_OPT_X_SASL_AUTHZID +Gets the SASL authorization identity; +.BR outvalue +must be a +.BR "char **" , +its content needs to be freed by the caller using +.BR ldap_memfree (3). +.TP +.B LDAP_OPT_X_SASL_MAXBUFSIZE +Gets/sets SASL maximum buffer size; +.BR invalue +must be +.BR "const ber_len_t *" , +while +.BR outvalue +must be +.BR "ber_len_t *" . +See also +.BR LDAP_OPT_X_SASL_SECPROPS . +.TP +.B LDAP_OPT_X_SASL_MECH +Gets the SASL mechanism; +.BR outvalue +must be a +.BR "char **" , +its content needs to be freed by the caller using +.BR ldap_memfree (3). +.TP +.B LDAP_OPT_X_SASL_MECHLIST +Gets the list of the available mechanisms, +in form of a NULL-terminated array of strings; +.BR outvalue +must be +.BR "char ***" . +The caller must not free or otherwise muck with it. +.TP +.B LDAP_OPT_X_SASL_NOCANON +Sets/gets the NOCANON flag. +When unset, the hostname is canonicalized. +.BR invalue +must be +.BR "const int *" ; +its value should either be +.BR LDAP_OPT_OFF +or +.BR LDAP_OPT_ON . +.BR outvalue +must be +.BR "int *" . +.TP +.B LDAP_OPT_X_SASL_REALM +Gets the SASL realm; +.BR outvalue +must be a +.BR "char **" , +its content needs to be freed by the caller using +.BR ldap_memfree (3). +.TP +.B LDAP_OPT_X_SASL_SECPROPS +Sets the SASL secprops; +.BR invalue +must be a +.BR "char *" , +containing a comma-separated list of properties. +Legal values are: +.BR none , +.BR nodict , +.BR noplain , +.BR noactive , +.BR passcred , +.BR forwardsec , +.BR noanonymous , +.BR minssf=<minssf> , +.BR maxssf=<maxssf> , +.BR maxbufsize=<maxbufsize> . +.TP +.B LDAP_OPT_X_SASL_SSF +Gets the SASL SSF; +.BR outvalue +must be a +.BR "ber_len_t *" . +.TP +.B LDAP_OPT_X_SASL_SSF_EXTERNAL +Sets the SASL SSF value related to an authentication +performed using an EXTERNAL mechanism; +.BR invalue +must be a +.BR "const ber_len_t *" . +.TP +.B LDAP_OPT_X_SASL_SSF_MAX +Gets/sets SASL maximum SSF; +.BR invalue +must be +.BR "const ber_len_t *" , +while +.BR outvalue +must be +.BR "ber_len_t *" . +See also +.BR LDAP_OPT_X_SASL_SECPROPS . +.TP +.B LDAP_OPT_X_SASL_SSF_MIN +Gets/sets SASL minimum SSF; +.BR invalue +must be +.BR "const ber_len_t *" , +while +.BR outvalue +must be +.BR "ber_len_t *" . +See also +.BR LDAP_OPT_X_SASL_SECPROPS . +.TP +.B LDAP_OPT_X_SASL_USERNAME +Gets the SASL username; +.BR outvalue +must be a +.BR "char **" . +Its content needs to be freed by the caller using +.BR ldap_memfree (3). +.SH TCP OPTIONS +The TCP options are OpenLDAP specific. +Mainly intended for use with Linux, they may not be portable. +.TP +.B LDAP_OPT_X_KEEPALIVE_IDLE +Sets/gets the number of seconds a connection needs to remain idle +before TCP starts sending keepalive probes. +.BR invalue +must be +.BR "const int *" ; +.BR outvalue +must be +.BR "int *" . +.TP +.B LDAP_OPT_X_KEEPALIVE_PROBES +Sets/gets the maximum number of keepalive probes TCP should send +before dropping the connection. +.BR invalue +must be +.BR "const int *" ; +.BR outvalue +must be +.BR "int *" . +.TP +.B LDAP_OPT_X_KEEPALIVE_INTERVAL +Sets/gets the interval in seconds between individual keepalive probes. +.BR invalue +must be +.BR "const int *" ; +.BR outvalue +must be +.BR "int *" . +.SH TLS OPTIONS +The TLS options are OpenLDAP specific. +.\".TP +.\".B LDAP_OPT_X_TLS +.\"Sets/gets the TLS mode. +.TP +.B LDAP_OPT_X_TLS_CACERTDIR +Sets/gets the path of the directory containing CA certificates. +.BR invalue +must be +.BR "const char *" ; +.BR outvalue +must be +.BR "char **" , +and its contents need to be freed by the caller using +.BR ldap_memfree (3). +.TP +.B LDAP_OPT_X_TLS_CACERTFILE +Sets/gets the full-path of the CA certificate file. +.BR invalue +must be +.BR "const char *" ; +.BR outvalue +must be +.BR "char **" , +and its contents need to be freed by the caller using +.BR ldap_memfree (3). +.TP +.B LDAP_OPT_X_TLS_CERTFILE +Sets/gets the full-path of the certificate file. +.BR invalue +must be +.BR "const char *" ; +.BR outvalue +must be +.BR "char **" , +and its contents need to be freed by the caller using +.BR ldap_memfree (3). +.TP +.B LDAP_OPT_X_TLS_CIPHER_SUITE +Sets/gets the allowed cipher suite. +.BR invalue +must be +.BR "const char *" ; +.BR outvalue +must be +.BR "char **" , +and its contents need to be freed by the caller using +.BR ldap_memfree (3). +.TP +.B LDAP_OPT_X_TLS_CONNECT_ARG +Sets/gets the connection callback argument. +.BR invalue +must be +.BR "const void *" ; +.BR outvalue +must be +.BR "void **" . +.TP +.B LDAP_OPT_X_TLS_CONNECT_CB +Sets/gets the connection callback handle. +.BR invalue +must be +.BR "const LDAP_TLS_CONNECT_CB *" ; +.BR outvalue +must be +.BR "LDAP_TLS_CONNECT_CB **" . +.TP +.B LDAP_OPT_X_TLS_CRLCHECK +Sets/gets the CRL evaluation strategy, one of +.BR LDAP_OPT_X_TLS_CRL_NONE , +.BR LDAP_OPT_X_TLS_CRL_PEER , +or +.BR LDAP_OPT_X_TLS_CRL_ALL . +.BR invalue +must be +.BR "const int *" ; +.BR outvalue +must be +.BR "int *" . +Requires OpenSSL. +.TP +.B LDAP_OPT_X_TLS_CRLFILE +Sets/gets the full-path of the CRL file. +.BR invalue +must be +.BR "const char *" ; +.BR outvalue +must be +.BR "char **" , +and its contents need to be freed by the caller using +.BR ldap_memfree (3). +This option is only valid for GnuTLS. +.TP +.B LDAP_OPT_X_TLS_CTX +Sets/gets the TLS library context. New TLS sessions will inherit their +default settings from this library context. +.BR invalue +must be +.BR "const void *" ; +.BR outvalue +must be +.BR "void **" . +When using the OpenSSL library this is an SSL_CTX*. When using other +crypto libraries this is a pointer to an OpenLDAP private structure. +Applications generally should not use this option or attempt to +manipulate this structure. +.TP +.B LDAP_OPT_X_TLS_DHFILE +Gets/sets the full-path of the file containing the parameters +for Diffie-Hellman ephemeral key exchange. +.BR invalue +must be +.BR "const char *" ; +.BR outvalue +must be +.BR "char **" , +and its contents need to be freed by the caller using +.BR ldap_memfree (3). +Ignored by GnuTLS and Mozilla NSS. +.TP +.B LDAP_OPT_X_TLS_KEYFILE +Sets/gets the full-path of the certificate key file. +.BR invalue +must be +.BR "const char *" ; +.BR outvalue +must be +.BR "char **" , +and its contents need to be freed by the caller using +.BR ldap_memfree (3). +.TP +.B LDAP_OPT_X_TLS_NEWCTX +Instructs the library to create a new TLS library context. +.BR invalue +must be +.BR "const int *" . +A non-zero value pointed to by +.BR invalue +tells the library to create a context for a server. +.TP +.B LDAP_OPT_X_TLS_PROTOCOL_MIN +Sets/gets the minimum protocol version. +.BR invalue +must be +.BR "const int *" ; +.BR outvalue +must be +.BR "int *" . +.TP +.B LDAP_OPT_X_TLS_RANDOM_FILE +Sets/gets the random file when +.B /dev/random +and +.B /dev/urandom +are not available. +.BR invalue +must be +.BR "const char *" ; +.BR outvalue +must be +.BR "char **" , +and its contents need to be freed by the caller using +.BR ldap_memfree (3). +Ignored by GnuTLS older than version 2.2. Ignored by Mozilla NSS. +.TP +.B LDAP_OPT_X_TLS_REQUIRE_CERT +Sets/gets the peer certificate checking strategy, +one of +.BR LDAP_OPT_X_TLS_NEVER , +.BR LDAP_OPT_X_TLS_HARD , +.BR LDAP_OPT_X_TLS_DEMAND , +.BR LDAP_OPT_X_TLS_ALLOW , +.BR LDAP_OPT_X_TLS_TRY . +.TP +.B LDAP_OPT_X_TLS_SSL_CTX +Gets the TLS session context associated with this handle. +.BR outvalue +must be +.BR "void **" . +When using the OpenSSL library this is an SSL*. When using other +crypto libraries this is a pointer to an OpenLDAP private structure. +Applications generally should not use this option. +.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 . +.P +The protocol version used by the library defaults to LDAPv2 (now historic), +which corresponds to the +.B LDAP_VERSION2 +macro. +Application developers are encouraged to explicitly set +.B LDAP_OPT_PROTOCOL_VERSION +to LDAPv3, using the +.B LDAP_VERSION3 +macro, or to allow users to select the protocol version. +.SH SEE ALSO +.BR ldap (3), +.BR ldap_error (3), +.B RFC 4422 +(http://www.rfc-editor.org), +.SH ACKNOWLEDGEMENTS +.so ../Project |