1LDAP_SEARCH(3)             Library Functions Manual             LDAP_SEARCH(3)
2
3
4

NAME

6       ldap_search,     ldap_search_s,     ldap_search_st,    ldap_search_ext,
7       ldap_search_ext_s - Perform an LDAP search operation
8

LIBRARY

10       OpenLDAP LDAP (libldap, -lldap)
11

SYNOPSIS

13       #include <sys/types.h>
14       #include <ldap.h>
15
16       int ldap_search_ext(
17              LDAP *ld,
18              char *base,
19              int scope,
20              char *filter,
21              char *attrs[],
22              int attrsonly,
23              LDAPControl **serverctrls,
24              LDAPControl **clientctrls,
25              struct timeval *timeout,
26              int sizelimit,
27              int *msgidp );
28
29       int ldap_search_ext_s(
30              LDAP *ld,
31              char *base,
32              int scope,
33              char *filter,
34              char *attrs[],
35              int attrsonly,
36              LDAPControl **serverctrls,
37              LDAPControl **clientctrls,
38              struct timeval *timeout,
39              int sizelimit,
40              LDAPMessage **res );
41

DESCRIPTION

43       These routines  are  used  to  perform  LDAP  search  operations.   The
44       ldap_search_ext_s()  routine  does  the search synchronously (i.e., not
45       returning until the operation completes), providing a  pointer  to  the
46       resulting  LDAP  messages at the location pointed to by the res parame‐
47       ter.
48
49       The ldap_search_ext() routine is the asynchronous  version,  initiating
50       the  search  and returning the message id of the operation it initiated
51       in the integer pointed to by the msgidp parameter.
52
53       The base parameter is the DN of the entry at which to start the search.
54
55       The scope parameter is the scope of the search and  should  be  one  of
56       LDAP_SCOPE_BASE,  to  search the object itself, LDAP_SCOPE_ONELEVEL, to
57       search the object's immediate children, LDAP_SCOPE_SUBTREE,  to  search
58       the  object  and all its descendants, or LDAP_SCOPE_CHILDREN, to search
59       all of the descendants.   Note that the latter requires the server sup‐
60       port the LDAP Subordinates Search Scope extension.
61
62       The  filter  is  a  string representation of the filter to apply in the
63       search.  The string should conform to the format specified in RFC  4515
64       as extended by RFC 4526.  For instance, "(cn=Jane Doe)".  Note that use
65       of the extension requires the  server  to  support  the  LDAP  Absolute
66       True/False  Filter  extension.   NULL  may be specified to indicate the
67       library should send the filter (objectClass=*).
68
69       The attrs parameter is a null-terminated array  of  attribute  descrip‐
70       tions  to  return  from  matching  entries.   If NULL is specified, the
71       return of all  user  attributes  is  requested.   The  description  "*"
72       (LDAP_ALL_USER_ATTRIBUTES)  may  be used to request all user attributes
73       to be returned.  The  description  "+"(LDAP_ALL_OPERATIONAL_ATTRIBUTES)
74       may be used to request all operational attributes to be returned.  Note
75       that this requires the server  to  support  the  LDAP  All  Operational
76       Attribute  extension.   To request no attributes, the description "1.1"
77       (LDAP_NO_ATTRS) should be listed by itself.
78
79       The attrsonly parameter should be set  to  a  non-zero  value  if  only
80       attribute  descriptions  are  wanted.   It should be set to zero (0) if
81       both attributes descriptions and attribute values are wanted.
82
83       The serverctrls and clientctrls  parameters  may  be  used  to  specify
84       server and client controls, respectively.
85
86       The   ldap_search_ext_s()   routine   is  the  synchronous  version  of
87       ldap_search_ext().
88
89       It also returns a code indicating success or, in the case  of  failure,
90       indicating   the   nature   of  the  failure  of  the  operation.   See
91       ldap_error(3) for details.
92

NOTES

94       Note that both read and list functionality are subsumed by  these  rou‐
95       tines,  by  using  a  filter  like  "(objectclass=*)"  and  a  scope of
96       LDAP_SCOPE_BASE (to emulate read) or  LDAP_SCOPE_ONELEVEL  (to  emulate
97       list).
98
99       These routines may dynamically allocate memory. The caller is responsi‐
100       ble for freeing  such  memory  using  supplied  deallocation  routines.
101       Return values are contained in <ldap.h>.
102
103       Note  that  res  parameter  of  ldap_search_ext_s() and ldap_search_s()
104       should be freed with ldap_msgfree() regardless of return value of these
105       functions.
106

DEPRECATED INTERFACES

108       The   ldap_search()   routine   is   deprecated   in   favor   of   the
109       ldap_search_ext() routine.  The  ldap_search_s()  and  ldap_search_st()
110       routines are deprecated in favor of the ldap_search_ext_s() routine.
111
112       Deprecated  interfaces  generally  remain  in  the  library.  The macro
113       LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRE‐
114       CATED=1)  when compiling program designed to use deprecated interfaces.
115       It is recommended that developers writing new programs, or updating old
116       programs,  avoid  use  of  deprecated  interfaces.   Over  time,  it is
117       expected that documentation (and, eventually, support)  for  deprecated
118       interfaces to be eliminated.
119

SEE ALSO

121       ldap(3), ldap_result(3), ldap_error(3)
122

ACKNOWLEDGEMENTS

124       OpenLDAP  Software  is developed and maintained by The OpenLDAP Project
125       <http://www.openldap.org/>.  OpenLDAP Software is derived from the Uni‐
126       versity of Michigan LDAP 3.3 Release.
127
128
129
130OpenLDAP 2.4.46                   2018/03/22                    LDAP_SEARCH(3)
Impressum