ldap_set_option


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_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-
              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
              *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
              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

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

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                          2011/11/24                LDAP_GET_OPTION(3)
Man Pages Copyright Respective Owners. Site Copyright (C) 1994 - 2017 Hurricane Electric. All Rights Reserved.