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

   1 .TH LDAP_SEARCH 3 "22 September 1998" "OpenLDAP LDVERSION"
   2 .SH NAME
   3 ldap_search, ldap_search_s, ldap_search_st \- Perform an LDAP search operation
   4 .SH SYNOPSIS
   5 .nf
   6 .ft B
   7 #include <sys/time.h> /* for struct timeval definition */
   8 #include <lber.h>
   9 #include <ldap.h>
  10 .LP
  11 .ft B
  12 int ldap_search(ld, base, scope, filter, attrs, attrsonly)
  13 .ft
  14 LDAP *ld;
  15 char *base;
  16 int scope;
  17 char *filter, *attrs[];
  18 int attrsonly;
  19 .LP
  20 .ft B
  21 int ldap_search_s(ld, base, scope, filter, attrs, attrsonly, res)
  22 .ft
  23 LDAP *ld;
  24 char *base;
  25 int scope;
  26 char *filter, *attrs[]
  27 int attrsonly;
  28 LDAPMessage **res;
  29 .LP
  30 .ft B
  31 int ldap_search_st(ld, base, scope, filter, attrs, attrsonly, timeout, res)
  32 .ft
  33 LDAP *ld;
  34 char *base;
  35 int scope;
  36 char *filter, *attrs[]
  37 int attrsonly;
  38 struct timeval *timeout;
  39 LDAPMessage **res;
  40 .SH DESCRIPTION
  41 These routines are used to perform LDAP search operations.
  42 .B ldap_search_s()
  43 does the search synchronously (i.e., not
  44 returning until the operation completes).
  45 .B ldap_search_st()
  46 does
  47 the same, but allows a \fItimeout\fP to be specified.
  48 .B ldap_search()
  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.
  56 .LP
  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
  61 BNF:
  62 .LP
  63 .nf
  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> ::= '=' | '~=' | '<=' | '>='
  72 .fi
  73 .LP
  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.
  79 .LP
  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
  85 filters.  See
  86 .BR ldap_getfilter (3)
  87 for routines to help in constructing search filters automatically.
  88 .LP
  89 \fIAttrs\fP is a null-terminated array of attribute types to return
  90 from entries that match \fIfilter\fP.  If NULL is specified, all
  91 attributes will be returned.  \fIAttrsonly\fP should be set to 1 if
  92 only attribute types are wanted.  It should be set to 0 if both
  93 attributes types and attribute values are wanted.
  94 .SH ERRORS
  95 .B ldap_search_s()
  96 and
  97 .B ldap_search_st()
  98 will return the LDAP error code resulting from the search operation.
  99 See
 100 .BR ldap_error (3)
 101 for details.
 102 .B ldap_search()
 103 returns -1 in case of trouble.
 104 .SH NOTES
 105 Note that both read
 106 and list functionality are subsumed by these routines,
 107 by using a filter like "objectclass=*" and a scope of LDAP_SCOPE_BASE (to
 108 emulate read) or LDAP_SCOPE_ONELEVEL (to emulate list).
 109 .LP
 110 These routines may dynamically allocate memory.  The caller is
 111 responsible for freeing such memory using supplied deallocation
 112 routines.  Return values are contained
 113 in <ldap.h>.
 114 .SH SEE ALSO
 115 .BR ldap (3),
 116 .BR ldap_result (3),
 117 .BR ldap_getfilter (3),
 118 .BR ldap_error (3)
 119 .SH ACKNOWLEDGEMENTS
 120 .B      OpenLDAP
 121 is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
 122 .B      OpenLDAP
 123 is derived from University of Michigan LDAP 3.3 Release.