Query: ldap_set_option
OS: mojave
Section: 3
Format: Original Unix Latex Style Formatted with HTML and a Horizontal Scroll Bar
LDAP_GET_OPTION(3) Library Functions Manual LDAP_GET_OPTION(3)NAMEldap_get_option, ldap_set_option - LDAP option handling routinesLIBRARYOpenLDAP LDAP (libldap, -lldap)SYNOPSIS#include <ldap.h> int ldap_get_option(LDAP *ld, int option, void *outvalue); int ldap_set_option(LDAP *ld, int option, const void *invalue);DESCRIPTIONThese 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 ldap_get_option(3) or set by ldap_set_option(3) is cast to void *. The actual type is determined based on the value of the option argument. Global options are set/retrieved by passing a NULL LDAP handle. LDAP_OPT_API_FEATURE_INFO Fills-in a LDAPAPIFeatureInfo; outvalue must be a LDAPAPIFeatureInfo *, pointing to an already allocated struct. This is a read- only option. LDAP_OPT_API_INFO Fills-in a LDAPAPIInfo; outvalue must be a LDAPAPIInfo *, pointing to an already allocated struct. This is a read-only option. 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 ldap_search_ext(3), ldap_add_ext(3), ldap_modify_ext(3) and so on. outvalue must be LDAPControl ***, and the caller is responsible of freeing the returned controls, if any, by calling ldap_controls_free(3), while invalue must be LDAPControl *const *; the library duplicates the controls passed via invalue. LDAP_OPT_CONNECT_ASYNC Sets/gets the status of the asynchronous connect flag. invalue should either be LDAP_OPT_OFF or LDAP_OPT_ON; outvalue must be int *. When set, the library will call 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 LDAP_OPT_NETWORK_TIMEOUT). This option is OpenLDAP specific. LDAP_OPT_CONNECT_CB This option allows to set a connect callback. invalue must be a 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 lc_del callback handler is passed a NULL Sockbuf. Calling ldap_get_option(3) for this option removes the callback whose pointer matches outvalue. This option is OpenLDAP specific. LDAP_OPT_DEBUG_LEVEL Sets/gets the debug level of the client library. invalue must be a const int *; outvalue must be a int *. Valid debug levels are LDAP_DEBUG_ANY, LDAP_DEBUG_ARGS, LDAP_DEBUG_BER, LDAP_DEBUG_CONNS, LDAP_DEBUG_NONE, LDAP_DEBUG_PACKETS, LDAP_DEBUG_PARSE, and LDAP_DEBUG_TRACE. This option is OpenLDAP specific. LDAP_OPT_DEFBASE Sets/gets a string containing the DN to be used as default base for search operations. outvalue must be a char **, and the caller is responsible of freeing the returned string by calling ldap_memfree(3), while invalue must be a const char *; the library dupli- cates the corresponding string. This option is OpenLDAP specific. LDAP_OPT_DEREF Sets/gets the value that defines when alias dereferencing must occur. invalue must be const int *; outvalue must be int *. They cannot be NULL. The value of *invalue should be one of LDAP_DEREF_NEVER (the default), LDAP_DEREF_SEARCHING, LDAP_DEREF_FINDING, or LDAP_DEREF_ALWAYS. Note that this has ever been the only means to determine alias dereferencing within search operations. LDAP_OPT_DESC Returns the file descriptor associated to the socket buffer of the LDAP handle passed in as ld; outvalue must be a int *. This is a read-only, handle-specific option. LDAP_OPT_DIAGNOSTIC_MESSAGE Sets/gets a string containing the error string associated to the LDAP handle. This option was formerly known as LDAP_OPT_ERROR_STRING. outvalue must be a char **, and the caller is responsible of freeing the returned string by calling ldap_memfree(3), while invalue must be a char *; the library duplicates the corresponding string. 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 depre- cated in favor of LDAP_OPT_URI. outvalue must be a char **, and the caller is responsible of freeing the resulting string by call- ing ldap_memfree(3), while invalue must be a const char *; the library duplicates the corresponding string. LDAP_OPT_MATCHED_DN Sets/gets a string containing the matched DN associated to the LDAP handle. outvalue must be a char **, and the caller is responsi- ble of freeing the returned string by calling ldap_memfree(3), while invalue must be a const char *; the library duplicates the cor- responding string. LDAP_OPT_NETWORK_TIMEOUT Sets/gets the network timeout value after which poll(2)/select(2) following a connect(2) returns in case of no activity. outvalue must be a struct timeval ** (the caller has to free *outvalue), and invalue must be a 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. LDAP_OPT_PROTOCOL_VERSION Sets/gets the protocol version. outvalue and invalue must be int *. LDAP_OPT_REFERRAL_URLS Sets/gets an array containing the referral URIs associated to the LDAP handle. outvalue must be a char ***, and the caller is responsible of freeing the returned string by calling ldap_memvfree(3), while invalue must be a NULL-terminated char *const *; the library duplicates the corresponding string. This option is OpenLDAP specific. LDAP_OPT_REFERRALS Determines whether the library should implicitly chase referrals or not. invalue must be const int *; its value should either be LDAP_OPT_OFF or LDAP_OPT_ON. outvalue must be int *. LDAP_OPT_RESTART Determines whether the library should implicitly restart connections (FIXME). invalue must be const int *; its value should either be LDAP_OPT_OFF or LDAP_OPT_ON. outvalue must be int *. LDAP_OPT_RESULT_CODE Sets/gets the LDAP result code associated to the handle. This option was formerly known as LDAP_OPT_ERROR_NUMBER. invalue must be a const int *. outvalue must be a int *. 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 ldap_search_ext(3), ldap_add_ext(3), ldap_modify_ext(3) and so on. outvalue must be LDAPControl ***, and the caller is responsible of freeing the returned controls, if any, by calling ldap_controls_free(3), while invalue must be LDAPControl *const *; the library duplicates the controls passed via invalue. LDAP_OPT_SESSION_REFCNT Returns the reference count associated with the LDAP handle passed in as ld; outvalue must be a int *. This is a read-only, handle- specific option. This option is OpenLDAP specific. LDAP_OPT_SIZELIMIT Sets/gets the value that defines the maximum number of entries to be returned by a search operation. invalue must be const int *, while outvalue must be int *; They cannot be NULL. LDAP_OPT_SOCKBUF Returns a pointer to the socket buffer of the LDAP handle passed in as ld; outvalue must be a Sockbuf **. This is a read-only, han- dle-specific option. This option is OpenLDAP specific. LDAP_OPT_TIMELIMIT Sets/gets the value that defines the time limit after which a search operation should be terminated by the server. invalue must be const int *, while outvalue must be int *, and they cannot be NULL. LDAP_OPT_TIMEOUT Sets/gets a timeout value for the synchronous API calls. outvalue must be a struct timeval ** (the caller has to free *outvalue), and invalue must be a struct timeval *, and they cannot be NULL. Using a struct with seconds set to -1 results in an infinite time- out, which is the default. This option is OpenLDAP specific. 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. outvalue must be a char **, and the caller is responsible of freeing the resulting string by calling ldap_memfree(3), while invalue must be a const char *; the library parses the string into a list of LDAPURLDesc structures, so the invocation of ldap_set_option(3) may fail if URL parsing fails. URIs may only contain the schema, the host, and the port fields. This option is OpenLDAP specific.SASL OPTIONSThe SASL options are OpenLDAP specific. LDAP_OPT_X_SASL_AUTHCID Gets the SASL authentication identity; outvalue must be a char **, its content needs to be freed by the caller using ldap_mem- free(3). LDAP_OPT_X_SASL_AUTHZID Gets the SASL authorization identity; outvalue must be a char **, its content needs to be freed by the caller using ldap_memfree(3). LDAP_OPT_X_SASL_MAXBUFSIZE Gets/sets SASL maximum buffer size; invalue must be const ber_len_t *, while outvalue must be ber_len_t *. See also LDAP_OPT_X_SASL_SECPROPS. LDAP_OPT_X_SASL_MECH Gets the SASL mechanism; outvalue must be a char **, its content needs to be freed by the caller using ldap_memfree(3). LDAP_OPT_X_SASL_MECHLIST Gets the list of the available mechanisms, in form of a NULL-terminated array of strings; outvalue must be char ***. The caller must not free or otherwise muck with it. LDAP_OPT_X_SASL_NOCANON Sets/gets the NOCANON flag. When unset, the hostname is canonicalized. invalue must be const int *; its value should either be LDAP_OPT_OFF or LDAP_OPT_ON. outvalue must be int *. LDAP_OPT_X_SASL_REALM Gets the SASL realm; outvalue must be a char **, its content needs to be freed by the caller using ldap_memfree(3). LDAP_OPT_X_SASL_SECPROPS Sets the SASL secprops; invalue must be a char *, containing a comma-separated list of properties. Legal values are: none, nodict, noplain, noactive, passcred, forwardsec, noanonymous, minssf=<minssf>, maxssf=<maxssf>, maxbufsize=<maxbufsize>. LDAP_OPT_X_SASL_SSF Gets the SASL SSF; outvalue must be a ber_len_t *. LDAP_OPT_X_SASL_SSF_EXTERNAL Sets the SASL SSF value related to an authentication performed using an EXTERNAL mechanism; invalue must be a const ber_len_t *. LDAP_OPT_X_SASL_SSF_MAX Gets/sets SASL maximum SSF; invalue must be const ber_len_t *, while outvalue must be ber_len_t *. See also LDAP_OPT_X_SASL_SECPROPS. LDAP_OPT_X_SASL_SSF_MIN Gets/sets SASL minimum SSF; invalue must be const ber_len_t *, while outvalue must be ber_len_t *. See also LDAP_OPT_X_SASL_SECPROPS. LDAP_OPT_X_SASL_USERNAME Gets the SASL username; outvalue must be a char **. Its content needs to be freed by the caller using ldap_memfree(3).TCP OPTIONSThe TCP options are OpenLDAP specific. Mainly intended for use with Linux, they may not be portable. LDAP_OPT_X_KEEPALIVE_IDLE Sets/gets the number of seconds a connection needs to remain idle before TCP starts sending keepalive probes. invalue must be const int *; outvalue must be int *. LDAP_OPT_X_KEEPALIVE_PROBES Sets/gets the maximum number of keepalive probes TCP should send before dropping the connection. invalue must be const int *; out- value must be int *. LDAP_OPT_X_KEEPALIVE_INTERVAL Sets/gets the interval in seconds between individual keepalive probes. invalue must be const int *; outvalue must be int *.TLS OPTIONSThe TLS options are OpenLDAP specific. LDAP_OPT_X_TLS_CACERTDIR Sets/gets the path of the directory containing CA certificates. invalue must be const char *; outvalue must be char **, and its contents need to be freed by the caller using ldap_memfree(3). When using SecureTransport this option is not valid. Instead use the LDAP_OPT_X_TLS_TRUSTED_CERTS option. LDAP_OPT_X_TLS_CACERTFILE Sets/gets the full-path of the CA certificate file. invalue must be const char *; outvalue must be char **, and its contents need to be freed by the caller using ldap_memfree(3). When using SecureTransport this option is not valid. Instead use the LDAP_OPT_X_TLS_TRUSTED_CERTS option. LDAP_OPT_X_TLS_CERTFILE Sets/gets the full-path of the certificate file. invalue must be const char *; outvalue must be char **, and its contents need to be freed by the caller using ldap_memfree(3). When using SecureTransport this option is not valid. Instead use the LDAP_OPT_X_TLS_IDENTITY option. LDAP_OPT_X_TLS_CIPHER_SUITE Sets/gets the allowed cipher suite. invalue must be const char *; outvalue must be char **, and its contents need to be freed by the caller using ldap_memfree(3). LDAP_OPT_X_TLS_CONNECT_ARG Sets/gets the connection callback argument. invalue must be const void *; outvalue must be void **. LDAP_OPT_X_TLS_CONNECT_CB Sets/gets the connection callback handle. invalue must be const LDAP_TLS_CONNECT_CB *; outvalue must be LDAP_TLS_CONNECT_CB **. LDAP_OPT_X_TLS_CRLCHECK Sets/gets the CRL evaluation strategy, one of LDAP_OPT_X_TLS_CRL_NONE, LDAP_OPT_X_TLS_CRL_PEER, or LDAP_OPT_X_TLS_CRL_ALL. invalue must be const int *; outvalue must be int *. Requires SecureTransport or OpenSSL. LDAP_OPT_X_TLS_CRLFILE Sets/gets the full-path of the CRL file. invalue must be const char *; outvalue must be char **, and its contents need to be freed by the caller using ldap_memfree(3). This option is only valid for GnuTLS. LDAP_OPT_X_TLS_CTX Sets/gets the TLS library context. New TLS sessions will inherit their default settings from this library context. invalue must be const void *; outvalue must be 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. LDAP_OPT_X_TLS_DHFILE Gets/sets the full-path of the file containing the parameters for Diffie-Hellman ephemeral key exchange. invalue must be const char *; outvalue must be char **, and its contents need to be freed by the caller using ldap_memfree(3). Ignored by GnuTLS and Mozilla NSS. LDAP_OPT_X_TLS_IDENTITY Gets/sets the name of the identity in the system keychain. An identity is a certificate paired with a private key. invalue must be const char *; outvalue must be char **, and its contents need to be freed by the caller using ldap_memfree(3). Used by SecureTrans- port. Ignored by OpenSSL, GnuTLS and Mozilla NSS. LDAP_OPT_X_TLS_KEYFILE Sets/gets the full-path of the certificate key file. invalue must be const char *; outvalue must be char **, and its contents need to be freed by the caller using ldap_memfree(3). When using SecureTransport this option is not valid. Instead use the LDAP_OPT_X_TLS_IDENTITY option. LDAP_OPT_X_TLS_NEWCTX Instructs the library to create a new TLS library context. invalue must be const int *. A non-zero value pointed to by invalue tells the library to create a context for a server. LDAP_OPT_X_TLS_PROTOCOL_MIN Sets/gets the minimum protocol version. invalue must be const int *; outvalue must be int *. LDAP_OPT_X_TLS_RANDOM_FILE Sets/gets the random file when /dev/random and /dev/urandom are not available. invalue must be const char *; outvalue must be char **, and its contents need to be freed by the caller using ldap_memfree(3). Ignored by GnuTLS older than version 2.2. Ignored by SecureTransport and Mozilla NSS. LDAP_OPT_X_TLS_REQUIRE_CERT Sets/gets the peer certificate checking strategy, one of LDAP_OPT_X_TLS_NEVER, LDAP_OPT_X_TLS_HARD, LDAP_OPT_X_TLS_DEMAND, LDAP_OPT_X_TLS_ALLOW, LDAP_OPT_X_TLS_TRY. LDAP_OPT_X_TLS_SSL_CTX Gets the TLS session context associated with this handle. outvalue must be 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. LDAP_OPT_X_TLS_TRUSTED_CERTS Gets/sets the list of the trusted certificates in the system keychain. invalue must be const char *; outvalue must be char **, and its contents need to be freed by the caller using ldap_memfree(3). Used by SecureTransport. Ignored by OpenSSL, GnuTLS and Mozilla NSS.ERRORSOn success, the functions return LDAP_OPT_SUCCESS, while they may return LDAP_OPT_ERROR to indicate a generic option handling error. Occa- sionally, more specific errors can be returned, like LDAP_NO_MEMORY to indicate a failure in memory allocation.NOTESThe LDAP libraries with the LDAP_OPT_REFERRALS option set to 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 chas- ing by setting that option to LDAP_OPT_OFF. The protocol version used by the library defaults to LDAPv2 (now historic), which corresponds to the LDAP_VERSION2 macro. Application developers are encouraged to explicitly set LDAP_OPT_PROTOCOL_VERSION to LDAPv3, using the LDAP_VERSION3 macro, or to allow users to select the protocol version.SEE ALSOldap(3), ldap_error(3), RFC 4422 (http://www.rfc-editor.org),ACKNOWLEDGEMENTSOpenLDAP Software is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. OpenLDAP Software is derived from Uni- versity of Michigan LDAP 3.3 Release. OpenLDAP 2.4.28 2011/11/24 LDAP_GET_OPTION(3)