ldap_set_option

       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.  The lda-
              paif_info_version field of the struct  must  be  initialized  to
              LDAP_FEATURE_INFO_VERSION  before  making  the  call.  The  lda-
              paif_name field must be set to the name of a feature  to  query.
              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.  The  ldapai_info_version
              field of the struct must be initialized to 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 ldapai_extensions
              array and the array itself using  ldap_memfree(3).   The  caller
              must  also  free  the  ldapi_vendor_name.   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,
              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
              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.
              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,
              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

       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

       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                          2015/08/14                LDAP_GET_OPTION(3)
Man Pages Copyright Respective Owners. Site Copyright (C) 1994 - 2019 Hurricane Electric. All Rights Reserved.