Provided by: libldap2-dev_2.4.47+dfsg-3ubuntu2_amd64 bug

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 LDAPAPIFeatureInfo *, pointing to
              an  already allocated struct.  The ldapaif_info_version field of the struct must be
              initialized to LDAP_FEATURE_INFO_VERSION before making the call.  The  ldapaif_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 *, pointing 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 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
              ldap_search_ext(3), ldap_add_ext(3), ldap_modify_ext(3) and so on.   outvalue  must
              be LDAPControl ***, and the caller is responsible 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 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  LDAP_OPT_NETWORK_TIMEOUT).  This option is OpenLDAP
              specific.

       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  callback  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 OpenLDAP 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 deprecated 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_memfree(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 connections (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 operations.  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 responsible 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 cannot be NULL.

       LDAP_OPT_TIMEOUT
              Sets/gets a timeout value for the synchronous API calls.  outvalue must be a struct
              timeval ** (the caller has to free *outvalue), 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 contacted 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_memfree(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_memfree(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  canonicalized.   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.  outvalue 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 implement consistent referral chasing features, or explicitly disable
       referral chasing by setting that option to LDAP_OPT_OFF.

       The  protocol  version  used  by  the  library  defaults  to  LDAPv2 (now historic), 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 the University of Michigan
       LDAP 3.3 Release.