1ldap_search(3LDAP)          LDAP Library Functions          ldap_search(3LDAP)
2
3
4

NAME

6       ldap_search,    ldap_search_s,    ldap_search_ext,   ldap_search_ext_s,
7       ldap_search_st - LDAP search operations
8

SYNOPSIS

10       cc [ flag... ] file... -lldap[ library...]
11       #include <sys/time.h> /* for struct timeval definition */
12       #include <lber.h>
13       #include <ldap.h>
14
15       int ldap_search(LDAP *ld, char *base, int scope, char *filter,
16            char *attrs[], int attrsonly);
17
18
19       int ldap_search_s(LDAP *ld, char *base, int scope, char *filter,
20            char *attrs[],int attrsonly, LDAPMessage **res);
21
22
23       int ldap_search_st(LDAP *ld, char *base, int scope, char *filter,
24            char *attrs[], int attrsonly, struct timeval *timeout,
25            LDAPMessage **res);
26
27
28       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
33
34       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
39

DESCRIPTION

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
48
49       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
55
56       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
61                 <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
70
71
72       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
78
79       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
87
88       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
94
95       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
104
105       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
112
113       The ldap_search_ext_s() function initiates a synchronous search  opera‐
114       tion and returns the result of the operation itself.
115

ERRORS

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
121
122       The  ldap_search()  function  returns  −1 when the operation terminates
123       unsuccessfully.
124

ATTRIBUTES

126       See attributes(5) for a description of the following attributes:
127
128
129
130
131       ┌─────────────────────────────┬─────────────────────────────┐
132       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
133       │Interface Stability          │Evolving                     │
134       └─────────────────────────────┴─────────────────────────────┘
135

SEE ALSO

137       ldap(3LDAP),         ldap_result(3LDAP),         ldap_getfilter(3LDAP),
138       ldap_error(3LDAP) , attributes(5)
139
140
141       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
145
146       Postel,  J., Anderson, C. RFC 1588, White Pages Meeting Report. Network
147       Working Group. February 1994.
148

NOTES

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
155
156       The  ldap_search() functions may allocate memory which must be freed by
157       the calling application. Return values are contained in <ldap.h>.
158
159
160
161SunOS 5.11                        05 Dec 2003               ldap_search(3LDAP)
Impressum