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-2002 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 \- 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 .SH DESCRIPTION
  45 These routines are used to perform LDAP search operations.
  46 .B ldap_search_s()
  47 does the search synchronously (i.e., not
  48 returning until the operation completes).
  49 .B ldap_search_st()
  50 does
  51 the same, but allows a \fItimeout\fP to be specified.
  52 .B ldap_search()
  53 is the asynchronous version, initiating the search and returning
  54 the message id of the operation it initiated.
  55 \fIBase\fP is the DN of the entry at which to start the search.
  56 \fIScope\fP is the scope of the search and should be one of LDAP_SCOPE_BASE,
  57 to search the object itself,
  58 LDAP_SCOPE_ONELEVEL, to search the object's immediate children,
  59 or LDAP_SCOPE_SUBTREE, to search the object and all its descendents.
  60 .LP
  61 \fIFilter\fP is a string
  62 representation of the filter to apply in the search.  Simple filters
  63 can be specified as \fIattributetype=attributevalue\fP.  More complex
  64 filters are specified using a prefix notation according to the following
  65 BNF:
  66 .LP
  67 .nf
  68         <filter> ::= '(' <filtercomp> ')'
  69         <filtercomp> ::= <and> | <or> | <not> | <simple>
  70         <and> ::= '&' <filterlist>
  71         <or> ::= '|' <filterlist>
  72         <not> ::= '!' <filter>
  73         <filterlist> ::= <filter> | <filter> <filterlist>
  74         <simple> ::= <attributetype> <filtertype> <attributevalue>
  75         <filtertype> ::= '=' | '~=' | '<=' | '>='
  76 .fi
  77 .LP
  78 The '~=' construct is used to specify approximate matching.  The
  79 representation for <attributetype> and <attributevalue> are as
  80 described in RFC 2254.  In addition, <attributevalue> can be a single *
  81 to achieve an attribute existence test, or can contain text and *'s
  82 interspersed to achieve substring matching.
  83 .LP
  84 For example, the filter "mail=*" will find any entries that have a mail
  85 attribute.  The filter "mail=*@terminator.rs.itd.umich.edu" will find
  86 any entries that have a mail attribute ending in the specified string.
  87 To put parentheses in a filter, escape them with a backslash '\\'
  88 character.  See RFC 2254 for a more complete description of allowable
  89 filters.  See
  90 .BR ldap_getfilter (3)
  91 for routines to help in constructing search filters automatically.
  92 .LP
  93 \fIAttrs\fP is a null-terminated array of attribute types to return
  94 from entries that match \fIfilter\fP.
  95 If NULL is specified, all attributes will be returned.
  96 The type "*" (LDAP_ALL_USER_ATTRIBUTES) may be used to request
  97 all user attributes to be returned.
  98 The type "+"(LDAP_ALL_OPERATIONAL_ATTRIBUTES) may be used to request
  99 all operational attributes to be returned.
 100 To request no attributes, the type "1.1" (LDAP_NO_ATTRS)
 101 should be listed by itself.
 102 .LP
 103 \fIAttrsonly\fP should be set to 1 if
 104 only attribute types are wanted.  It should be set to 0 if both
 105 attributes types and attribute values are wanted.
 106 .SH ERRORS
 107 .B ldap_search_s()
 108 and
 109 .B ldap_search_st()
 110 will return the LDAP error code resulting from the search operation.
 111 See
 112 .BR ldap_error (3)
 113 for details.
 114 .B ldap_search()
 115 returns -1 in case of trouble.
 116 .SH NOTES
 117 Note that both read
 118 and list functionality are subsumed by these routines,
 119 by using a filter like "objectclass=*" and a scope of LDAP_SCOPE_BASE (to
 120 emulate read) or LDAP_SCOPE_ONELEVEL (to emulate list).
 121 .LP
 122 These routines may dynamically allocate memory.  The caller is
 123 responsible for freeing such memory using supplied deallocation
 124 routines.  Return values are contained
 125 in <ldap.h>.
 126 .SH SEE ALSO
 127 .BR ldap (3),
 128 .BR ldap_result (3),
 129 .BR ldap_getfilter (3),
 130 .BR ldap_error (3)
 131 .SH ACKNOWLEDGEMENTS
 132 .B      OpenLDAP
 133 is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
 134 .B      OpenLDAP
 135 is derived from University of Michigan LDAP 3.3 Release.