LDAP_GET_OPTION(3)	   Library Functions Manual	    LDAP_GET_OPTION(3)



NAME
       ldap_get_option, ldap_set_option - LDAP option handling routines

LIBRARY
       OpenLDAP 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);

DESCRIPTION
       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
       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
       handles	inherit	 their	default	 settings  from	 the global options in
       effect at the time the handle is created.

       LDAP_OPT_API_FEATURE_INFO
	      Fills-in a LDAPAPIFeatureInfo; outvalue must  be	a  LDAPAPIFea-
	      tureInfo	*, 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 *, point-
	      ing 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 opera-
	      tions.  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 respon-
	      sible  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  con-
	      necting  state.	Subsequent calls to library routines will poll
	      for completion of the connect before performing  further	opera-
	      tions.  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 spe-
	      cific.

       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 call-
	      back 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	OpenL-
	      DAP 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 duplicates 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 dep-
	      recated in favor of LDAP_OPT_URI.	 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 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
	      responsible  of freeing the returned string by calling ldap_mem-
	      free(3), while invalue must be  a	 const	char  *;  the  library
	      duplicates the corresponding 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 connec-
	      tions (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 opera-
	      tions.  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 respon-
	      sible  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,
	      handle-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 can-
	      not be NULL.

       LDAP_OPT_TIMEOUT
	      Sets/gets a timeout value for the synchronous API	 calls.	  out-
	      value  must be a struct timeval ** (the caller has to free *out-
	      value), and invalue must be a 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.

       LDAP_OPT_URI
	      Sets/gets	 a  comma-  or space-separated list of URIs to be con-
	      tacted 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 OPTIONS
       The 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_mem-
	      free(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 canoni-
	      calized.	 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 OPTIONS
       The  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 *;
	      outvalue 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 OPTIONS
       The 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).

       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).

       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).

       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 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_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).

       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 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.	  out-
	      value  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.

ERRORS
       On success, the	functions  return  LDAP_OPT_SUCCESS,  while  they  may
       return  LDAP_OPT_ERROR  to  indicate  a	generic option handling error.
       Occasionally, more specific errors can be returned, like LDAP_NO_MEMORY
       to indicate a failure in memory allocation.

NOTES
       The   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 imple-
       ment consistent referral chasing features, or explicitly disable refer-
       ral chasing by setting that option to LDAP_OPT_OFF.

       The  protocol  version used by the library defaults to LDAPv2 (now his-
       toric), 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 ALSO
       ldap(3), ldap_error(3), RFC 4422 (http://www.rfc-editor.org),

ACKNOWLEDGEMENTS
       OpenLDAP	 Software  is developed and maintained by The OpenLDAP Project
       <http://www.openldap.org/>.  OpenLDAP Software is derived from  Univer-
       sity of Michigan LDAP 3.3 Release.



OpenLDAP 2.4.40			  2014/09/20		    LDAP_GET_OPTION(3)