Unix/Linux Go Back    


CentOS 7.0 - man page for ldap_get_option (centos section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


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  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.  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 dep-
	      recated  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 comple-
	      tion 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-spe-
	      cific  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 opera-
	      tions.  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_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  try-
	      ing  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.   out-
	      value  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 con-
	      nect(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  time-
	      out, 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.   out-
	      value 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 dep-
	      recated 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; out-
	      value 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 LDA-
	      PURLDesc structures, so the invocation of ldap_set_option(3) may fail if URL  pars-
	      ing  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  out-
	      value 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.  out-
	      value 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,  for-
	      wardsec, 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_CON-
	      NECT_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_mem-
	      free(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 set-
	      tings  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  con-
	      text 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 gener-
	      ally 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 corre-
       sponds 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.openl-
       dap.org/>.  OpenLDAP Software is derived from University of Michigan LDAP 3.3 Release.

OpenLDAP 2.4.39 			    2014/01/26			       LDAP_GET_OPTION(3)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 03:03 AM.