1ldap_search(3LDAP) LDAP Library Functions ldap_search(3LDAP)
2
6 ldap_search, ldap_search_s, ldap_search_ext, ldap_search_ext_s,
7 ldap_search_st - LDAP search operations
8
10 cc [ flag... ] file... -lldap[ library...]
11 #include <sys/time.h> /* for struct timeval definition */
12 #include <lber.h>
13 #include <ldap.h>
14 int ldap_search(LDAP *ld, char *base, int scope, char *filter,
16 char *attrs[], int attrsonly);
17 int ldap_search_s(LDAP *ld, char *base, int scope, char *filter,
20 char *attrs[],int attrsonly, LDAPMessage **res);
21 int ldap_search_st(LDAP *ld, char *base, int scope, char *filter,
24 char *attrs[], int attrsonly, struct timeval *timeout,
25 LDAPMessage **res);
26 int ldap_search_ext(LDAP *ld, char *base, int scope, char
29 *filter, char **attrs, int attrsonly, LDAPControl **serverctrls,
30 LDAPControl **clientctrls, struct timeval *timeoutp,
31 int sizelimit, int *msgidp);
32 int ldap_search_ext_s(LDAP *ld,char *base, int scope, char *filter,
35 char **attrs, int attrsonly, LDAPControl **serverctrls,
36 LDAPControl **clientctrls, struct timeval *timeoutp,
37 int sizelimit, LDAPMessage **res);
38
41 These functions are used to perform LDAP search operations. The
42 ldap_search_s() function does the search synchronously (that is, not
43 returning until the operation completes). The ldap_search_st() function
44 does the same, but allows a timeout to be specified. The ldap_search()
45 function is the asynchronous version, initiating the search and return‐
46 ing the message ID of the operation it initiated.
47 The base is the DN of the entry at which to start the search. The scope
50 is the scope of the search and should be one of LDAP_SCOPE_BASE, to
51 search the object itself, LDAP_SCOPE_ONELEVEL, to search the object's
52 immediate children, or LDAP_SCOPE_SUBTREE, to search the object and all
53 its descendents.
54 The filter is a string representation of the filter to apply in the
57 search. Simple filters can be specified as attributetype=attribute‐
58 value. More complex filters are specified using a prefix notation
59 according to the following BNF:
60 <filter> ::= '(' <filtercomp> ')'
62 <filtercomp> ::= <and> | <or> | <not> | <simple>
63 <and> ::= '&' <filterlist>
64 <or> ::= '|' <filterlist>
65 <not> ::= '!' <filter>
66 <filterlist> ::= <filter> | <filter> <filterlist>
67 <simple> ::= <attributetype> <filtertype> <attributevalue>
68 <filtertype> ::= '=' | '~=' | '<=' | '>='
69 The '~=' construct is used to specify approximate matching. The repre‐
73 sentation for <attributetype> and <attributevalue> are as described in
74 RFC 1778. In addition, <attributevalue> can be a single * to achieve an
75 attribute existence test, or can contain text and *'s interspersed to
76 achieve substring matching.
77 For example, the filter mail=* finds entries that have a mail
80 attribute. The filter mail=*@terminator.rs.itd.umich.edu finds entries
81 that have a mail attribute ending in the specified string. Use a back‐
82 slash (\fR) to escape parentheses characters in a filter. See RFC 1588
83 for a more complete description of the filters that are allowed. See
84 ldap_getfilter(3LDAP) for functions to help construct search filters
85 automatically.
86 The attrs is a null-terminated array of attribute types to return from
89 entries that match filter. If NULL is specified, all attributes are
90 returned. The attrsonly is set to 1 when attribute types only are
91 wanted. The attrsonly is set to 0 when both attributes types and
92 attribute values are wanted.
93 The sizelimit argument returns the number of matched entries specified
96 for a search operation. When sizelimit is set to 50, for example, no
97 more than 50 entries are returned. When sizelimit is set to 0, all
98 matched entries are returned. The LDAP server can be configured to send
99 a maximum number of entries, different from the size limit specified.
100 If 5000 entries are matched in the database of a server configured to
101 send a maximum number of 500 entries, no more than 500 entries are
102 returned even when sizelimit is set to 0.
103 The ldap_search_ext() function initiates an asynchronous search opera‐
106 tion and returns LDAP_SUCCESS when the request is successfully sent to
107 the server. Otherwise, ldap_search_ext() returns an LDAP error code.
108 See ldap_error(3LDAP). If successful, ldap_search_ext() places the mes‐
109 sage ID of the request in *msgidp. A subsequent call to
110 ldap_result(3LDAP) can be used to obtain the result of the add request.
111 The ldap_search_ext_s() function initiates a synchronous search opera‐
114 tion and returns the result of the operation itself.
115
117 The ldap_search_s() and ldap_search_st() functions return the LDAP
118 error code that results from a search operation. See ldap_error(3LDAP)
119 for details.
120 The ldap_search() function returns −1 when the operation terminates
123 unsuccessfully.
124
126 See attributes(5) for a description of the following attributes:
127 ┌─────────────────────────────┬─────────────────────────────┐
132 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
133 │Interface Stability │Evolving │
134 └─────────────────────────────┴─────────────────────────────┘
135
137 ldap(3LDAP), ldap_result(3LDAP), ldap_getfilter(3LDAP),
138 ldap_error(3LDAP) , attributes(5)
139 Howes, T., Kille, S., Yeong, W., Robbins, C., Wenn, J. RFC 1778, The
142 String Representation of Standard Attribute Syntaxes. Network Working
143 Group. March 1995.
144 Postel, J., Anderson, C. RFC 1588, White Pages Meeting Report. Network
147 Working Group. February 1994.
148
150 The read and list functionality are subsumed by ldap_search() func‐
151 tions, when a filter such as objectclass=* is used with the scope
152 LDAP_SCOPE_BASE to emulate read or the scope LDAP_SCOPE_ONELEVEL to
153 emulate list.
154 The ldap_search() functions may allocate memory which must be freed by
157 the calling application. Return values are contained in <ldap.h>.
158SunOS 5.11 05 Dec 2003 ldap_search(3LDAP)