ldap_search(3)

LDAP_SEARCH(3)         C LIBRARY FUNCTIONS         LDAP_SEARCH(3)

NAME

     ldap_search, ldap_search_s, ldap_search_st - Perform an LDAP
     search operation

LIBRARY

     OpenLDAP LDAP (libldap, -lldap)

SYNOPSIS

     #include <sys/time.h> /* for struct timeval definition */
     #include <ldap.h>

     int ldap_search(ld, base, scope, filter, attrs, attrsonly)
     LDAP *ld;
     char *base;
     int scope;
     char *filter, *attrs[];
     int attrsonly;

     int ldap_search_s(ld, base, scope, filter, attrs, attrsonly, res)
     LDAP *ld;
     char *base;
     int scope;
     char *filter, *attrs[]
     int attrsonly;
     LDAPMessage **res;

     int ldap_search_st(ld, base, scope, filter, attrs, attrsonly, timeout, res)
     LDAP *ld;
     char *base;
     int scope;
     char *filter, *attrs[]
     int attrsonly;
     struct timeval *timeout;
     LDAPMessage **res;

DESCRIPTION

     These routines are used to perform LDAP  search  operations.
     ldap_search_s()  does  the  search  synchronously (i.e., not
     returning until the operation completes).   ldap_search_st()
     does  the  same,  but  allows  a  timeout  to  be specified.
     ldap_search() is the asynchronous  version,  initiating  the
     search and returning the message id of the operation it ini-
     tiated.  Base is the DN of the entry at which to  start  the
     search.   Scope 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 chil-
     dren, or LDAP_SCOPE_SUBTREE, to search the  object  and  all
     its descendents.

     Filter is a string representation of the filter to apply  in
     the   search.    Simple   filters   can   be   specified  as
     (attributetype=attributevalue).  More  complex  filters  are

OpenLDAP LDVERSION  Last change: RELEASEDATE                    1

LDAP_SEARCH(3)         C LIBRARY FUNCTIONS         LDAP_SEARCH(3)

     specified using a prefix notation according to the following
     BNF:

             <filter> ::= '(' <filtercomp> ')'
             <filtercomp> ::= <and> | <or> | <not> | <simple>
             <and> ::= '&' <filterlist>
             <or> ::= '|' <filterlist>
             <not> ::= '!' <filter>
             <filterlist> ::= <filter> | <filter> <filterlist>
             <simple> ::= <attributetype> <filtertype> <attributevalue>
             <filtertype> ::= '=' | '~=' | '<=' | '>='

     The '~=' construct is used to specify approximate  matching.
     The  representation for <attributetype> and <attributevalue>
     are as described in RFC 2254.  In addition, <attributevalue>
     can be a single * to achieve an attribute existence test, or
     can contain text and *'s interspersed to  achieve  substring
     matching.

     For example, the filter "(mail=*)"  will  find  any  entries
     that     have     a     mail    attribute.     The    filter
     "(mail=*@terminator.rs.itd.umich.edu)" will find any entries
     that  have  a mail attribute ending in the specified string.
     To put parentheses in a filter, escape them with a backslash
     '\' character.  See RFC 2254 for a more complete description
     of allowable filters.

     Attrs is a  null-terminated  array  of  attribute  types  to
     return  from  entries  that match filter.  If NULL is speci-
     fied, the return of all user attributes is  requested.   The
     type  "*"  (LDAP_ALL_USER_ATTRIBUTES) may be used to request
     all   user   attributes   to   be   returned.    The    type
     "+"(LDAP_ALL_OPERATIONAL_ATTRIBUTES)  may be used to request
     all operational attributes to be returned.   To  request  no
     attributes,  the type "1.1" (LDAP_NO_ATTRS) should be listed
     by itself.

     Attrsonly should be set to 1 if  only  attribute  types  are
     wanted.   It should be set to 0 if both attributes types and
     attribute values are wanted.

ERRORS

     ldap_search_s() and ldap_search_st() will  return  the  LDAP
     error   code  resulting  from  the  search  operation.   See
     ldap_error(3) for details.  ldap_search() returns -1 in case
     of trouble.

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

OpenLDAP LDVERSION  Last change: RELEASEDATE                    2

LDAP_SEARCH(3)         C LIBRARY FUNCTIONS         LDAP_SEARCH(3)

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

SEE ALSO

     ldap(3), ldap_result(3), ldap_getfilter(3), ldap_error(3)

ACKNOWLEDGEMENTS

     OpenLDAP is developed and maintained by The OpenLDAP Project
     (http://www.openldap.org/).    OpenLDAP   is   derived  from
     University of Michigan LDAP 3.3 Release.

OpenLDAP LDVERSION  Last change: RELEASEDATE                    3