Man Pages

ldap_set_option(3) - phpMan ldap_set_option(3) - phpMan

Command: man perldoc info search(apropos)  


LDAP_GET_OPTION(3)                                          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 argu-
       ment.  Global options are set/retrieved by passing a NULL LDAP handle. LDAP handles inherit their default  set-
       tings 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.  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.  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 argu-
              ments; 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  rou-
              tines  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  out-
              value.  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 *; out-
              value 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 con-
              nection.   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 argu-
              ments; 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  estab-
              lish  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  spe-
              cific.

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 pri-
              vate 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 refer-
       ral 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_VER-
       SION2 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 University of Michigan LDAP 3.3 Release.



OpenLDAP 2.4.40                   2014/09/20                LDAP_GET_OPTION(3)