usr/src/man/man3ldap/ldap_search.3ldap

   1 '\" te
   2 .\" Copyright (C) 1990, Regents of the University of Michigan.  All Rights Reserved.
   3 .\" Portions Copyright (C) 2003, Sun Microsystems, Inc. All Rights Reserved.
   4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH LDAP_SEARCH 3LDAP "Dec 05, 2003"
   8 .SH NAME
   9 ldap_search, ldap_search_s, ldap_search_ext, ldap_search_ext_s, ldap_search_st
  10 \- LDAP search operations
  11 .SH SYNOPSIS
  12 .LP
  13 .nf
  14 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... -lldap[ \fIlibrary\fR...]
  15 #include <sys/time.h> /* for struct timeval definition */
  16 #include <lber.h>
  17 #include <ldap.h>
  18
  19 \fBint\fR \fBldap_search\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*base\fR, \fBint\fR \fIscope\fR, \fBchar\fR \fI*filter\fR,
  20      \fBchar\fR \fI*attrs\fR[], \fBint\fR \fIattrsonly\fR);
  21 .fi
  22
  23 .LP
  24 .nf
  25 \fBint\fR \fBldap_search_s\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*base\fR, \fBint\fR \fIscope\fR, \fBchar\fR \fI*filter\fR,
  26      \fBchar\fR \fI*attrs\fR[],\fBint\fR \fIattrsonly\fR, \fBLDAPMessage\fR \fI**res\fR);
  27 .fi
  28
  29 .LP
  30 .nf
  31 \fBint\fR \fBldap_search_st\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*base\fR, \fBint\fR \fIscope\fR, \fBchar\fR \fI*filter\fR,
  32      \fBchar\fR \fI*attrs\fR[], \fBint\fR \fIattrsonly\fR, \fBstruct timeval\fR \fI*timeout\fR,
  33      \fBLDAPMessage\fR \fI**res\fR);
  34 .fi
  35
  36 .LP
  37 .nf
  38 \fBint\fR \fBldap_search_ext\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*base\fR, \fBint\fR \fIscope\fR, \fBchar\fR
  39      \fI*filter\fR, \fBchar\fR \fI**attrs\fR,\ \fBint\fR \fIattrsonly\fR, \fBLDAPControl\fR \fI**serverctrls\fR,
  40      \fBLDAPControl\fR \fI**clientctrls\fR, \fBstruct timeval\fR \fI*timeoutp\fR,
  41      \fBint\fR \fIsizelimit\fR, \fBint\fR \fI*msgidp\fR);
  42 .fi
  43
  44 .LP
  45 .nf
  46 \fBint\fR \fBldap_search_ext_s\fR(\fBLDAP\fR \fI*ld\fR,char \fI*base\fR, \fBint\fR \fIscope\fR, \fBchar\fR \fI*filter\fR,
  47      \fBchar\fR \fI**attrs\fR, \fBint\fR \fIattrsonly\fR, \fBLDAPControl\fR \fI**serverctrls\fR,
  48      \fBLDAPControl\fR \fI**clientctrls\fR, \fBstruct timeval\fR \fI*timeoutp\fR,
  49      \fBint\fR \fIsizelimit\fR, \fBLDAPMessage\fR \fI**res\fR);
  50 .fi
  51
  52 .SH DESCRIPTION
  53 .sp
  54 .LP
  55 These functions are used to perform LDAP search operations. The
  56 \fBldap_search_s()\fR function does the search synchronously (that is, not
  57 returning until the operation completes). The \fBldap_search_st()\fR function
  58 does the same, but allows a \fItimeout\fR to be specified. The
  59 \fBldap_search()\fR function is the asynchronous version, initiating the search
  60 and returning the message ID of the operation it initiated.
  61 .sp
  62 .LP
  63 The \fIbase\fR is the DN of the entry at which to start the search. The
  64 \fIscope\fR is the scope of the search and should be one of
  65 \fBLDAP_SCOPE_BASE\fR, to search the object itself, \fBLDAP_SCOPE_ONELEVEL\fR,
  66 to search the object's immediate children, or \fBLDAP_SCOPE_SUBTREE\fR, to
  67 search the object and all its descendents.
  68 .sp
  69 .LP
  70 The \fIfilter\fR is a string representation of the filter to apply in the
  71 search. Simple filters can be specified as \fIattributetype=attributevalue\fR.
  72 More complex filters are specified using a prefix notation according to the
  73 following BNF:
  74 .sp
  75 .in +2
  76 .nf
  77         <filter> ::= '(' <filtercomp> ')'
  78         <filtercomp> ::= <and> | <or> | <not> | <simple>
  79         <and> ::= '&' <filterlist>
  80         <or> ::= '|' <filterlist>
  81         <not> ::= '!' <filter>
  82         <filterlist> ::= <filter> | <filter> <filterlist>
  83         <simple> ::= <attributetype> <filtertype> <attributevalue>
  84         <filtertype> ::= '=' | '~=' | '<=' | '>='
  85 .fi
  86 .in -2
  87
  88 .sp
  89 .LP
  90 The '~=' construct is used to specify approximate matching. The representation
  91 for <attributetype> and <attributevalue> are as described in RFC 1778. In
  92 addition, <attributevalue> can be a single * to achieve an attribute existence
  93 test, or can contain text and *'s interspersed to achieve substring matching.
  94 .sp
  95 .LP
  96 For example, the filter \fBmail=*\fR finds entries that have a mail attribute.
  97 The filter \fBmail=*@terminator.rs.itd.umich.edu\fR finds entries that have a
  98 mail attribute ending in the specified string. Use a backslash (\fB\\fR) to
  99 escape parentheses characters in a filter. See RFC 1588 for a more complete
 100 description of the filters that are allowed. See \fBldap_getfilter\fR(3LDAP)
 101 for functions to help construct search filters automatically.
 102 .sp
 103 .LP
 104 The \fIattrs\fR is a null-terminated array of attribute types to return from
 105 entries that match \fIfilter\fR. If \fBNULL\fR is specified, all attributes are
 106 returned. The \fIattrsonly\fR is set to \fB1\fR when attribute types only are
 107 wanted. The \fIattrsonly\fR is set to \fB0\fR when both attributes types and
 108 attribute values are wanted.
 109 .sp
 110 .LP
 111 The \fIsizelimit\fR argument returns the number of matched entries specified
 112 for a search operation. When \fIsizelimit\fR is set to 50, for example, no more
 113 than 50 entries are returned. When \fIsizelimit\fR is set to 0, all matched
 114 entries are returned. The LDAP server can be configured to send a maximum
 115 number of entries, different from the size limit specified. If 5000 entries are
 116 matched in the database of a server configured to send a maximum number of 500
 117 entries, no more than 500 entries are returned even when \fIsizelimit\fR is set
 118 to 0.
 119 .sp
 120 .LP
 121 The \fBldap_search_ext()\fR function initiates an asynchronous search operation
 122 and returns \fBLDAP_SUCCESS\fR when the request is successfully sent to the
 123 server. Otherwise, \fBldap_search_ext()\fR returns an LDAP error code. See
 124 \fBldap_error\fR(3LDAP). If successful, \fBldap_search_ext()\fR places the
 125 message ID of the request in \fI*msgidp\fR. A subsequent call to
 126 \fBldap_result\fR(3LDAP) can be used to obtain the result of the add request.
 127 .sp
 128 .LP
 129 The \fBldap_search_ext_s()\fR function initiates a synchronous search operation
 130 and returns the result of the operation itself.
 131 .SH ERRORS
 132 .sp
 133 .LP
 134 The \fBldap_search_s()\fR and \fBldap_search_st()\fR functions return the LDAP
 135 error code that results from a search operation. See \fBldap_error\fR(3LDAP)
 136 for details.
 137 .sp
 138 .LP
 139 The \fBldap_search()\fR function returns \fB\(mi1\fR when the operation
 140 terminates unsuccessfully.
 141 .SH ATTRIBUTES
 142 .sp
 143 .LP
 144 See \fBattributes\fR(5) for a description of the following attributes:
 145 .sp
 146
 147 .sp
 148 .TS
 149 box;
 150 c | c
 151 l | l .
 152 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 153 Interface Stability     Evolving
 154 .TE
 155
 156 .SH SEE ALSO
 157 .sp
 158 .LP
 159 \fBldap\fR(3LDAP), \fBldap_result\fR(3LDAP), \fBldap_getfilter\fR(3LDAP),
 160 \fBldap_error\fR(3LDAP) , \fBattributes\fR(5)
 161 .sp
 162 .LP
 163 Howes, T., Kille, S., Yeong, W., Robbins, C., Wenn, J. \fIRFC 1778, The String
 164 Representation of Standard Attribute Syntaxes\fR. Network Working Group. March
 165 1995.
 166 .sp
 167 .LP
 168 Postel, J., Anderson, C. \fIRFC 1588, White Pages Meeting Report\fR. Network
 169 Working Group. February 1994.
 170 .SH NOTES
 171 .sp
 172 .LP
 173 The read and list functionality are subsumed by \fBldap_search()\fR functions,
 174 when a filter such as \fBobjectclass=*\fR is used with the scope
 175 \fBLDAP_SCOPE_BASE\fR to emulate read or the scope \fBLDAP_SCOPE_ONELEVEL\fR to
 176 emulate list.
 177 .sp
 178 .LP
 179 The \fBldap_search()\fR functions may allocate memory which must be freed by
 180 the calling application. Return values are contained in <\fBldap.h\fR>.