# ldap_search

## 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_ **);**
    
           **#include <openldap.h>**
    
           **int ldap_pvt_put_filter( BerElement ***_ber_**, const char ***_str_ **);**
    


## 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.
    
           **ldap_pvt_put_filter()** parses a string filter provided in _str_ ,
           performs structural validation and serializes it into the
           BerElement passed in _ber_ as a side-effect. On error, the encoding
           state of _ber_ is not specified in any way. There is currently no
           way to learn what part of the string caused the validation to
           fail.
    


## 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.
    


## 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.
    


* * *