Страницы справочника OS X

Эта страница руководства является частью версии 5.0 Инструментов XCode

Читать страницы руководства

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_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 con-trols controls
              trols  as  explicit  arguments; see for example ldap_search_ext(3), ldap_add_ext(3), ldap_mod-ify_ext(3) ldap_modify_ext(3)
              ify_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.   Subse-quent Subsequent
              quent calls to library routines will poll for completion of the connect before performing fur-ther further
              ther 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 call-back callback
              back 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.  out-value outvalue
              value must be a char **, and the caller is responsible of freeing the returned string by call-ing calling
              ing  ldap_memfree(3),  while invalue must be a const char *; the library duplicates the corre-sponding corresponding
              sponding 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 dereferenc-ing dereferencing
              ing 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 estab-lish establish
              lish  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_mem-free(3), ldap_memfree(3),
              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 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  dupli-cates duplicates
              cates 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 con-trols controls
              trols as explicit arguments; see for example  ldap_search_ext(3),  ldap_add_ext(3),  ldap_mod-ify_ext(3) ldap_modify_ext(3)
              ify_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  ter-minated terminated
              minated  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 free-ing freeing
              ing 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; out-value outvalue
              value 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 proper-ties. properties.
              ties.  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 connec-tion. connection.
              tion.  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_mem-free(3). ldap_memfree(3).
              free(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 *; out-value outvalue
              value 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_MEM-ORY LDAP_NO_MEMORY
       ORY to indicate a failure in memory allocation.

NOTES
       The LDAP libraries with the LDAP_OPT_REFERRALS option set to LDAP_OPT_ON  (default  value)  automati-cally automatically
       cally  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_VER-SION LDAP_OPT_PROTOCOL_VERSION
       SION 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.28                                  2011/11/24                               LDAP_GET_OPTION(3)