argument.
Global options are set/retrieved by passing a NULL LDAP handle.
.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_API_INFO
Fills-in a
.BR "struct ldapapiinfo" ;
pointing to an already allocated struct.
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 **" ;
+the library duplicates the controls passed via
+.BR invalue .
+.TP
+.B LDAP_OPT_CONNECT_ASYNC
+Sets/gets the status of the asynchronous connect flag.
+The value should either be
+.BR LDAP_OPT_OFF
+or
+.BR LDAP_OPT_ON .
+When set, the library will call
+.BR connect (2)
+and return, without waiting for response.
+This leaves the handler 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.
+The
+.B invalue
+must be a pointer to a
+.IR "struct ldap_conncb" .
+Callbacks are executed in last in-first served order.
+Hanlder-specific callbacks are executed first, followed by global ones.
+Right before freeing the callback structure, the
+.I lc_del
+callback handler is passed a
+.B NULL
+.IR 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.
+Both
+.BR outvalue
+and
+.BR invalue
+must be a
+.BR "int *" .
+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 "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 outvalue
+and
+.BR invalue
+must be
+.BR "int *" ,
+and 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 "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 ;
+.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 "Sockbuf **" .
-This is a read-only, handler-specific option.
+.BR "char *" ;
+the library duplicates the corresponding string.
.TP
-.B LDAP_OPT_TIMEOUT
-Sets/gets a timeout value for the synchronous API calls.
-.B outvalue
+.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 "struct timeval **"
-(the caller has to free
-.BR *outvalue ) ,
-and
-.B invalue
+.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 "struct timeval *" ,
-and they cannot be NULL. Using a struct with seconds set to \-1 results
-in an infinite timeout, which is the default.
+.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_NETWORK_TIMEOUT
Sets/gets the network timeout value after which
.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_DEREF
-Sets/gets the value that defines when alias dereferencing 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
+.B LDAP_OPT_PROTOCOL_VERSION
+Sets/gets the protocol version.
+.BR outvalue
+and
.BR invalue
-must be
-.BR "int *" ,
-and they cannot be NULL.
+must be
+.BR "int *" .
.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
+.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
-.BR "int *" ,
-and they cannot be NULL.
+must be a NULL-terminated
+.BR "char **" ;
+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.
or
.BR LDAP_OPT_ON .
.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 outvalue
or
.BR LDAP_OPT_ON .
.TP
-.B LDAP_OPT_PROTOCOL_VERSION
-Sets/gets the protocol version.
+.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
+must be a
.BR "int *" .
.TP
.B LDAP_OPT_SERVER_CONTROLS
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
+.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 "LDAPControl **" ;
-the library duplicates the controls passed via
-.BR invalue .
+must be
+.BR "int *" ,
+and they cannot be NULL.
.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 .
+.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 "char **" ,
-and the caller is responsible of freeing the resulting string by calling
-.BR ldap_memfree (3),
-while
+.BR "Sockbuf **" .
+This is a read-only, handler-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 outvalue
+and
.BR invalue
+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 "char *" ;
-the library duplicates the corresponding string.
+.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 space-separated list of URIs to be contacted by the library
+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
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 TLS OPTIONS
+The TLS options are 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 "char *" ;
-the library duplicates the corresponding string.
+.B LDAP_OPT_X_TLS
+Sets/gets the TLS mode, 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_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 *" .
+.B LDAP_OPT_X_TLS_CTX
+Sets/gets the OpenSSL CTX.
.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.
+.B LDAP_OPT_X_TLS_CACERTFILE
+Sets/gets the full-path CA certificate file.
.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.
+.B LDAP_OPT_X_TLS_CACERTDIR
+Sets/gets the path of the directory containing CA certificates.
.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.
+.B LDAP_OPT_X_TLS_CERTFILE
+Sets/gets the full-path certificate file.
.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.
+.B LDAP_OPT_X_TLS_KEYFILE
+Sets/gets the full-path certificate key file.
.TP
-.B LDAP_OPT_DEBUG_LEVEL
-Sets/gets the debug level of the client library.
-Both
-.BR outvalue
+.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_PROTOCOL_MIN
+Sets/gets the minimum protocol version.
+.TP
+.B LDAP_OPT_X_TLS_CIPHER_SUITE
+Sets/gets the allowed cipher suite.
+.TP
+.B LDAP_OPT_X_TLS_RANDOM_FILE
+Sets/gets the random file when
+.I /dev/random
and
+.I /dev/urandom
+are not available.
+Ignored by GNUtls.
+.TP
+.B LDAP_OPT_X_TLS_SSL_CTX
+Sets/gets the OpenSSL SSL CTX.
+.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 .
+Requires OpenSSL.
+.TP
+.B LDAP_OPT_X_TLS_CONNECT_CB
+Sets/gets the connection callback.
+Currently not implemented.
+.TP
+.B LDAP_OPT_X_TLS_CONNECT_ARG
+Sets/gets the connection callback argument.
+Currently not implemented.
+.TP
+.B LDAP_OPT_X_TLS_DHFILE
+Gets/sets the full-path of the file containing the parameters
+for Diffie-Hellman ephemeral key exchange.
+Ignored by GNUtls.
+.TP
+.B LDAP_OPT_X_TLS_NEWCTX
+Instructs the library to create a new TLS CTX.
+A non-zero
.BR invalue
-must be a
-.BR "int *" .
+tells the library to create a CTX for a server.
+.TP
+.B LDAP_OPT_X_TLS_CRLFILE
+Sets/gets the full-path of the CRL file.
+This option is only valid for GNUtls.
+.SH SASL OPTIONS
+.TP
+.B LDAP_OPT_X_SASL_MECH
+.TP
+.B LDAP_OPT_X_SASL_REALM
+.TP
+.B LDAP_OPT_X_SASL_AUTHCID
+.TP
+.B LDAP_OPT_X_SASL_AUTHZID
+.TP
+.B LDAP_OPT_X_SASL_SSF
+read-only
+.TP
+.B LDAP_OPT_X_SASL_SSF_EXTERNAL
+write-only
+.TP
+.B LDAP_OPT_X_SASL_SECPROPS
+write-only
+.TP
+.B LDAP_OPT_X_SASL_SSF_MIN
+.TP
+.B LDAP_OPT_X_SASL_SSF_MAX
+.TP
+.B LDAP_OPT_X_SASL_MAXBUFSIZE
+.TP
+.B LDAP_OPT_X_SASL_MECHLIST
+read-only
+.TP
+.B LDAP_OPT_X_SASL_NOCANON
+.TP
+.B LDAP_OPT_X_SASL_USERNAME
+read-only
.SH ERRORS
On success, the functions return
.BR LDAP_OPT_SUCCESS ,
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),
projects / openldap / commitdiff