/usr/man2/cat.3/ldap_search_ext.3.Z(/usr/man2/cat.3/ldap_search_ext.3.Z)

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 initiated.  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  children,  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 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 repre-
       sentation  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  allow-
       able filters.

       Attrs  is  a  null-terminated  array  of attribute types to return from
       entries that match filter.  If NULL is specified,  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 opera-
       tional 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 rou-
       tines, 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  respon-
       sible  for  freeing  such  memory using supplied deallocation 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 2.2.30                   2005/11/18                    LDAP_SEARCH(3)