Updated: 2022/Sep/29

Please read Privacy Policy. It's for your privacy.

LDAP_SEARCH(3)             Library Functions Manual             LDAP_SEARCH(3)



NAME
       ldap_search, ldap_search_s, ldap_search_st, ldap_search_ext,
       ldap_search_ext_s - Perform an LDAP search operation

LIBRARY
       OpenLDAP LDAP (libldap, -lldap)

SYNOPSIS
       #include <sys/types.h>
       #include <ldap.h>

       int ldap_search_ext(
              LDAP *ld,
              char *base,
              int scope,
              char *filter,
              char *attrs[],
              int attrsonly,
              LDAPControl **serverctrls,
              LDAPControl **clientctrls,
              struct timeval *timeout,
              int sizelimit,
              int *msgidp );

       int ldap_search_ext_s(
              LDAP *ld,
              char *base,
              int scope,
              char *filter,
              char *attrs[],
              int attrsonly,
              LDAPControl **serverctrls,
              LDAPControl **clientctrls,
              struct timeval *timeout,
              int sizelimit,
              LDAPMessage **res );

DESCRIPTION
       These routines are used to perform LDAP search operations.  The
       ldap_search_ext_s() routine does the search synchronously (i.e., not
       returning until the operation completes), providing a pointer to the
       resulting LDAP messages at the location pointed to by the res
       parameter.

       The ldap_search_ext() routine is the asynchronous version, initiating
       the search and returning the message id of the operation it initiated
       in the integer pointed to by the msgidp parameter.

       The base parameter is the DN of the entry at which to start the search.

       The scope parameter is the scope of the search and should be one of
       LDAP_SCOPE_BASE, to search the object itself, LDAP_SCOPE_ONELEVEL, to
       search the object's immediate children, LDAP_SCOPE_SUBTREE, to search
       the object and all its descendants, or LDAP_SCOPE_CHILDREN, to search
       all of the descendants.   Note that the latter requires the server
       support the LDAP Subordinates Search Scope extension.

       The filter is a string representation of the filter to apply in the
       search.  The string should conform to the format specified in RFC 4515
       as extended by RFC 4526.  For instance, "(cn=Jane Doe)".  Note that use
       of the extension requires the server to support the LDAP Absolute
       True/False Filter extension.  NULL may be specified to indicate the
       library should send the filter (objectClass=*).

       The attrs parameter is a null-terminated array of attribute
       descriptions to return from matching entries.  If NULL is specified,
       the return of all user attributes is requested.  The description "*"
       (LDAP_ALL_USER_ATTRIBUTES) may be used to request all user attributes
       to be returned.  The description "+"(LDAP_ALL_OPERATIONAL_ATTRIBUTES)
       may be used to request all operational attributes to be returned.  Note
       that this requires the server to support the LDAP All Operational
       Attribute extension.  To request no attributes, the description "1.1"
       (LDAP_NO_ATTRS) should be listed by itself.

       The attrsonly parameter should be set to a non-zero value if only
       attribute descriptions are wanted.  It should be set to zero (0) if
       both attributes descriptions and attribute values are wanted.

       The serverctrls and clientctrls parameters may be used to specify
       server and client controls, respectively.

       The ldap_search_ext_s() routine is the synchronous version of
       ldap_search_ext().

       It also returns a code indicating success or, in the case of failure,
       indicating the nature of the failure of the operation.  See
       ldap_error(3) for details.

NOTES
       Note that both read and list functionality are subsumed by these
       routines, by using a filter like "(objectclass=*)" and a scope of
       LDAP_SCOPE_BASE (to emulate read) or LDAP_SCOPE_ONELEVEL (to emulate
       list).

       These routines may dynamically allocate memory. The caller is
       responsible for freeing such memory using supplied deallocation
       routines. Return values are contained in <ldap.h>.

       Note that res parameter of ldap_search_ext_s() and ldap_search_s()
       should be freed with ldap_msgfree() regardless of return value of these
       functions.

DEPRECATED INTERFACES
       The ldap_search() routine is deprecated in favor of the
       ldap_search_ext() routine.  The ldap_search_s() and ldap_search_st()
       routines are deprecated in favor of the ldap_search_ext_s() routine.

       Deprecated interfaces generally remain in the library.  The macro
       LDAP_DEPRECATED can be defined to a non-zero value (e.g.,
       -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated
       interfaces.  It is recommended that developers writing new programs, or
       updating old programs, avoid use of deprecated interfaces.  Over time,
       it is expected that documentation (and, eventually, support) for
       deprecated interfaces to be eliminated.

SEE ALSO
       ldap(3), ldap_result(3), ldap_error(3)

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.



OpenLDAP 2.4.50                   2020/04/28                    LDAP_SEARCH(3)