This document is a Mac OS X manual page. Manual pages are a command-line technology for providing documentation. You can view these manual pages locally using the man(1) command. These manual pages come from many different sources, and thus, have a variety of writing styles.

For more information about the manual page format, see the manual page for manpages(5).

LDAP_SEARCH(3)                                                                                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 syn-chronously synchronously
       chronously (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_SUB-TREE, LDAP_SCOPE_SUBTREE,
       TREE, to search the object and all its descendants.

       Filter is a string representation of the filter to apply in the search.  Simple filters can be speci-fied specified
       fied 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 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  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  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 opera-tion. operation.
       tion.  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).

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

SEE ALSO
       ldap(3), ldap_result(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.3.27                                  2006/08/19                                   LDAP_SEARCH(3)