1 .TH LDAP_SEARCH 3 "25 July 1999" "OpenLDAP LDVERSION"
3 ldap_search, ldap_search_s, ldap_search_st \- Perform an LDAP search operation
7 #include <sys/time.h> /* for struct timeval definition */
12 int ldap_search(ld, base, scope, filter, attrs, attrsonly)
17 char *filter, *attrs[];
21 int ldap_search_s(ld, base, scope, filter, attrs, attrsonly, res)
26 char *filter, *attrs[]
31 int ldap_search_st(ld, base, scope, filter, attrs, attrsonly, timeout, res)
36 char *filter, *attrs[]
38 struct timeval *timeout;
41 These routines are used to perform LDAP search operations.
43 does the search synchronously (i.e., not
44 returning until the operation completes).
47 the same, but allows a \fItimeout\fP to be specified.
49 is the asynchronous version, initiating the search and returning
50 the message id of the operation it initiated.
51 \fIBase\fP is the DN of the entry at which to start the search.
52 \fIScope\fP is the scope of the search and should be one of LDAP_SCOPE_BASE,
53 to search the object itself,
54 LDAP_SCOPE_ONELEVEL, to search the object's immediate children,
55 or LDAP_SCOPE_SUBTREE, to search the object and all its descendents.
57 \fIFilter\fP is a string
58 representation of the filter to apply in the search. Simple filters
59 can be specified as \fIattributetype=attributevalue\fP. More complex
60 filters are specified using a prefix notation according to the following
64 <filter> ::= '(' <filtercomp> ')'
65 <filtercomp> ::= <and> | <or> | <not> | <simple>
66 <and> ::= '&' <filterlist>
67 <or> ::= '|' <filterlist>
68 <not> ::= '!' <filter>
69 <filterlist> ::= <filter> | <filter> <filterlist>
70 <simple> ::= <attributetype> <filtertype> <attributevalue>
71 <filtertype> ::= '=' | '~=' | '<=' | '>='
74 The '~=' construct is used to specify approximate matching. The
75 representation for <attributetype> and <attributevalue> are as
76 described in RFC 1778. In addition, <attributevalue> can be a single *
77 to achieve an attribute existence test, or can contain text and *'s
78 interspersed to achieve substring matching.
80 For example, the filter "mail=*" will find any entries that have a mail
81 attribute. The filter "mail=*@terminator.rs.itd.umich.edu" will find
82 any entries that have a mail attribute ending in the specified string.
83 To put parentheses in a filter, escape them with a backslash '\\'
84 character. See RFC 1588 for a more complete description of allowable
86 .BR ldap_getfilter (3)
87 for routines to help in constructing search filters automatically.
89 \fIAttrs\fP is a null-terminated array of attribute types to return
90 from entries that match \fIfilter\fP.
91 If NULL is specified, all attributes will be returned.
92 The type "*" (LDAP_ALL_USER_ATTRIBUTES) may be used to request
93 all user attributes to be returned.
94 The type "+"(LDAP_ALL_OPERATIONAL_ATTRIBUTES) may be used to request
95 all operational attributes to be returned.
96 To request no attributes, the type "1.1" (LDAP_NO_ATTRS)
97 should be listed by itself.
99 \fIAttrsonly\fP should be set to 1 if
100 only attribute types are wanted. It should be set to 0 if both
101 attributes types and attribute values are wanted.
106 will return the LDAP error code resulting from the search operation.
111 returns -1 in case of trouble.
114 and list functionality are subsumed by these routines,
115 by using a filter like "objectclass=*" and a scope of LDAP_SCOPE_BASE (to
116 emulate read) or LDAP_SCOPE_ONELEVEL (to emulate list).
118 These routines may dynamically allocate memory. The caller is
119 responsible for freeing such memory using supplied deallocation
120 routines. Return values are contained
125 .BR ldap_getfilter (3),
129 is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
131 is derived from University of Michigan LDAP 3.3 Release.