git.sur5r.net Git - openldap/blob - doc/man/man3/ldap_search.3

   1 .TH LDAP_SEARCH 3 "RELEASEDATE" "OpenLDAP LDVERSION"
   2 .\" $OpenLDAP$
   3 .\" Copyright 1998-2006 The OpenLDAP Foundation All Rights Reserved.
   4 .\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
   5 .SH NAME
   6 ldap_search, ldap_search_s, ldap_search_st, ldap_search_ext, ldap_search_ext_s \- Perform an LDAP search operation
   7 .SH LIBRARY
   8 OpenLDAP LDAP (libldap, -lldap)
   9 .SH SYNOPSIS
  10 .nf
  11 .ft B
  12 #include <sys/time.h> /* for struct timeval definition */
  13 #include <ldap.h>
  14 .LP
  15 .ft B
  16 int ldap_search(ld, base, scope, filter, attrs, attrsonly)
  17 .ft
  18 LDAP *ld;
  19 char *base;
  20 int scope;
  21 char *filter, *attrs[];
  22 int attrsonly;
  23 .LP
  24 .ft B
  25 int ldap_search_s(ld, base, scope, filter, attrs, attrsonly, res)
  26 .ft
  27 LDAP *ld;
  28 char *base;
  29 int scope;
  30 char *filter, *attrs[]
  31 int attrsonly;
  32 LDAPMessage **res;
  33 .LP
  34 .ft B
  35 int ldap_search_st(ld, base, scope, filter, attrs, attrsonly, timeout, res)
  36 .ft
  37 LDAP *ld;
  38 char *base;
  39 int scope;
  40 char *filter, *attrs[]
  41 int attrsonly;
  42 struct timeval *timeout;
  43 LDAPMessage **res;
  44 .LP
  45 .ft B
  46 int ldap_search_ext(ld, base, scope, filter, attrs, attrsonly, serverctrls,
  47 .ft
  48 clientctrls, timeout, sizelimit, msgidp)
  49 .ft
  50 LDAP *ld;
  51 char *base;
  52 int scope;
  53 char *filter, *attrs[]
  54 int attrsonly;
  55 LDAPControl **serverctrls, **clientctrls;
  56 struct timeval *timeout;
  57 int sizelimit, *msgidp;
  58 .LP
  59 .ft B
  60 int ldap_search_ext_s(ld, base, scope, filter, attrs, attrsonly, serverctrls,
  61 .ft
  62 clientctrls, timeout, sizelimit, res)
  63 .ft
  64 LDAP *ld;
  65 char *base;
  66 int scope;
  67 char *filter, *attrs[]
  68 int attrsonly;
  69 LDAPControl **serverctrls, **clientctrls;
  70 struct timeval *timeout;
  71 int sizelimit;
  72 LDAPMessage **res;
  73 .SH DESCRIPTION
  74 These routines are used to perform LDAP search operations.
  75 .B ldap_search_s()
  76 does the search synchronously (i.e., not
  77 returning until the operation completes).
  78 .B ldap_search_st()
  79 does
  80 the same, but allows a \fItimeout\fP to be specified.
  81 .B ldap_search()
  82 is the asynchronous version, initiating the search and returning
  83 the message id of the operation it initiated.
  84 \fIBase\fP is the DN of the entry at which to start the search.
  85 \fIScope\fP is the scope of the search and should be one of LDAP_SCOPE_BASE,
  86 to search the object itself,
  87 LDAP_SCOPE_ONELEVEL, to search the object's immediate children,
  88 or LDAP_SCOPE_SUBTREE, to search the object and all its descendants.
  89 .LP
  90 \fIFilter\fP is a string
  91
  92 representation of the filter to apply in the search.  Simple filters
  93 can be specified as \fI(attributetype=attributevalue)\fP.  More complex
  94 filters are specified using a prefix notation according to the following
  95 BNF:
  96 .LP
  97 .nf
  98         <filter> ::= '(' <filtercomp> ')'
  99         <filtercomp> ::= <and> | <or> | <not> | <simple>
 100         <and> ::= '&' <filterlist>
 101         <or> ::= '|' <filterlist>
 102         <not> ::= '!' <filter>
 103         <filterlist> ::= <filter> | <filter> <filterlist>
 104         <simple> ::= <attributetype> <filtertype> <attributevalue>
 105         <filtertype> ::= '=' | '~=' | '<=' | '>='
 106 .fi
 107 .LP
 108 The '~=' construct is used to specify approximate matching.  The
 109 representation for <attributetype> and <attributevalue> are as
 110 described in RFC 2254.  In addition, <attributevalue> can be a single *
 111 to achieve an attribute existence test, or can contain text and *'s
 112 interspersed to achieve substring matching.
 113 .LP
 114 For example, the filter "(mail=*)" will find any entries that have a mail
 115 attribute.  The filter "(mail=*@terminator.rs.itd.umich.edu)" will find
 116 any entries that have a mail attribute ending in the specified string.
 117 To put parentheses in a filter, escape them with a backslash '\\'
 118 character.  See RFC 2254 for a more complete description of allowable
 119 filters.
 120 .LP
 121 \fIAttrs\fP is a null-terminated array of attribute types to return
 122 from entries that match \fIfilter\fP.
 123 If NULL is specified, the return of all user attributes is requested.
 124 The type "*" (LDAP_ALL_USER_ATTRIBUTES) may be used to request
 125 all user attributes to be returned.
 126 The type "+"(LDAP_ALL_OPERATIONAL_ATTRIBUTES) may be used to request
 127 all operational attributes to be returned.
 128 To request no attributes, the type "1.1" (LDAP_NO_ATTRS)
 129 should be listed by itself.
 130 .LP
 131 \fIAttrsonly\fP should be set to 1 if
 132 only attribute types are wanted. It should be set to 0 if both
 133 attributes types and attribute values are wanted.
 134 .LP
 135 .B ldap_search_ext()
 136 routine allows server and client controls to be specified to extend
 137 the search request. This routine is asynchronous like
 138 .BR ldap_search() ,
 139 but its return value is an LDAP error code. It stores the message id
 140 of the request in the integer pointed to
 141 by
 142 .IR msgidp .
 143 .LP
 144 The
 145 .B ldap_search_ext_s()
 146 routine is the synchronous version of
 147 .BR ldap_search_ext().
 148 It also returns an LDAP error code indicating success or failure
 149 of the operation.
 150 .SH ERRORS
 151 .B ldap_search_s()
 152 and
 153 .B ldap_search_st()
 154 will return the LDAP error code resulting from the search operation.
 155 See
 156 .BR ldap_error (3)
 157 for details.
 158 .B ldap_search()
 159 returns -1 in case of trouble.
 160 .LP
 161 .B ldap_search_s(),
 162 .B ldap_search_ext_s
 163 and
 164 .B ldap_search_st()
 165 will return the LDAP error code resulting from the search operation.
 166 See
 167 .BR  ldap_error (3)
 168 for  details.
 169 .B ldap_search()
 170 and
 171 .B ldap_search_ext
 172 returns -1 in case of trouble.
 173 .SH NOTES
 174 Note that both read
 175 and list functionality are subsumed by these routines,
 176 by using a filter like "(objectclass=*)" and a scope of LDAP_SCOPE_BASE (to
 177 emulate read) or LDAP_SCOPE_ONELEVEL (to emulate list).
 178 .LP
 179 These routines may dynamically allocate memory. The caller is
 180 responsible for freeing such memory using supplied deallocation
 181 routines. Return values are contained in <ldap.h>.
 182 .SH SEE ALSO
 183 .BR ldap (3),
 184 .BR ldap_result (3),
 185 .BR ldap_error (3)
 186 .SH ACKNOWLEDGEMENTS
 187 .B OpenLDAP
 188 is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
 189 .B OpenLDAP
 190 is derived from University of Michigan LDAP 3.3 Release.