ldap_set_option

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 in-
       terface,  where  the type of the value either retrieved by ldap_get_op-
       tion(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  re-
              sponsible  for freeing the elements of the ldapai_extensions ar-
              ray 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 re-
              placements  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_DE-
              BUG_CONNS,   LDAP_DEBUG_NONE,    LDAP_DEBUG_PACKETS,    LDAP_DE-
              BUG_PARSE,  and  LDAP_DEBUG_TRACE.  This option is OpenLDAP spe-
              cific.

       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 li-
              brary 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_ER-
              ROR_STRING.   outvalue  must be a char **, and the caller is re-
              sponsible of freeing the returned string  by  calling  ldap_mem-
              free(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  re-
              sponsible  of  freeing  the returned string by calling ldap_mem-
              free(3), while invalue must be a const char *; the  library  du-
              plicates the corresponding string.

       LDAP_OPT_NETWORK_TIMEOUT
              Sets/gets  the  network  timeout  value  after which poll(2)/se-
              lect(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 re-
              placements  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 in-
              finite 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, no-
              dict,  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 li-
              braries this is a pointer to an OpenLDAP private structure.  Ap-
              plications 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.  in-
              value must be const int *.  A non-zero value pointed to  by  in-
              value 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.  Ig-
              nored 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_DE-
              MAND, 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  re-
       turn 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.

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  de-
       velopers  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 the Uni-
       versity of Michigan LDAP 3.3 Release.

OpenLDAP                          2020/01/30                LDAP_GET_OPTION(3)
Man Pages Copyright Respective Owners. Site Copyright (C) 1994 - 2024 Hurricane Electric. All Rights Reserved.