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-2018 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/types.h>
  13 #include <ldap.h>
  14 .LP
  15 .ft B
  16 int ldap_search_ext(
  17 .RS
  18 LDAP *\fIld\fB,
  19 char *\fIbase\fB,
  20 int \fIscope\fB,
  21 char *\fIfilter\fB,
  22 char *\fIattrs\fB[],
  23 int \fIattrsonly\fB,
  24 LDAPControl **\fIserverctrls\fB,
  25 LDAPControl **\fIclientctrls\fB,
  26 struct timeval *\fItimeout\fB,
  27 int \fIsizelimit\fB,
  28 int *\fImsgidp\fB );
  29 .RE
  30 .LP
  31 .ft B
  32 int ldap_search_ext_s(
  33 .RS
  34 LDAP *\fIld\fB,
  35 char *\fIbase\fB,
  36 int \fIscope\fB,
  37 char *\fIfilter\fB,
  38 char *\fIattrs\fB[],
  39 int \fIattrsonly\fB,
  40 LDAPControl **\fIserverctrls\fB,
  41 LDAPControl **\fIclientctrls\fB,
  42 struct timeval *\fItimeout\fB,
  43 int \fIsizelimit\fB,
  44 LDAPMessage **\fIres\fB );
  45 .RE
  46 .SH DESCRIPTION
  47 These routines are used to perform LDAP search operations.
  48 The
  49 .B ldap_search_ext_s()
  50 routine
  51 does the search synchronously (i.e., not
  52 returning until the operation completes), providing a pointer
  53 to the resulting LDAP messages at the location pointed to by
  54 the \fIres\fP parameter.
  55 .LP
  56 The
  57 .B ldap_search_ext()
  58 routine is the asynchronous version, initiating the search and returning
  59 the message id of the operation it initiated in the integer
  60 pointed to by the \fImsgidp\fP parameter.
  61 .LP
  62 The \fIbase\fP parameter is the DN of the entry at which to start the search.
  63 .LP
  64 The \fIscope\fP parameter is the scope of the search and should be one
  65 of LDAP_SCOPE_BASE, to search the object itself, LDAP_SCOPE_ONELEVEL,
  66 to search the object's immediate children, LDAP_SCOPE_SUBTREE, to
  67 search the object and all its descendants, or LDAP_SCOPE_CHILDREN,
  68 to search all of the descendants.   Note that the latter requires
  69 the server support the LDAP Subordinates Search Scope extension.
  70 .LP
  71 The \fIfilter\fP is a string representation of the filter to
  72 apply in the search.  The string should conform to the format
  73 specified in RFC 4515 as extended by RFC 4526.  For instance,
  74 "(cn=Jane Doe)".  Note that use of the extension requires the
  75 server to support the LDAP Absolute True/False Filter extension.
  76 NULL may be specified to indicate the library should send the
  77 filter (objectClass=*).
  78 .LP
  79 The \fIattrs\fP parameter is a null-terminated array of attribute
  80 descriptions to return from matching entries.
  81 If NULL is specified, the return of all user attributes is requested.
  82 The description "*" (LDAP_ALL_USER_ATTRIBUTES) may be used to request
  83 all user attributes to be returned.
  84 The description "+"(LDAP_ALL_OPERATIONAL_ATTRIBUTES) may be used to
  85 request all operational attributes to be returned.  Note that this
  86 requires the server to support the LDAP All Operational Attribute
  87 extension.
  88 To request no attributes, the description "1.1" (LDAP_NO_ATTRS)
  89 should be listed by itself.
  90 .LP
  91 The \fIattrsonly\fP parameter should be set to a non-zero value
  92 if only attribute descriptions are wanted.  It should be set to zero (0)
  93 if both attributes descriptions and attribute values are wanted.
  94 .LP
  95 The \fIserverctrls\fP and \fIclientctrls\fP parameters may be used
  96 to specify server and client controls, respectively.
  97 .LP
  98 The
  99 .B ldap_search_ext_s()
 100 routine is the synchronous version of
 101 .BR ldap_search_ext().
 102 .LP
 103 It also returns a code indicating success or, in the
 104 case of failure, indicating the nature of the failure
 105 of the operation.  See
 106 .BR ldap_error (3)
 107 for details.
 108 .SH NOTES
 109 Note that both read
 110 and list functionality are subsumed by these routines,
 111 by using a filter like "(objectclass=*)" and a scope of LDAP_SCOPE_BASE (to
 112 emulate read) or LDAP_SCOPE_ONELEVEL (to emulate list).
 113 .LP
 114 These routines may dynamically allocate memory. The caller is
 115 responsible for freeing such memory using supplied deallocation
 116 routines. Return values are contained in <ldap.h>.
 117 .LP
 118 Note that \fIres\fR parameter of
 119 .B ldap_search_ext_s()
 120 and
 121 .B ldap_search_s()
 122 should be freed with
 123 .B ldap_msgfree()
 124 regardless of return value of these functions.
 125 .SH DEPRECATED INTERFACES
 126 The
 127 .B ldap_search()
 128 routine is deprecated in favor of the
 129 .B ldap_search_ext()
 130 routine.  The
 131 .B ldap_search_s()
 132 and
 133 .B ldap_search_st()
 134 routines are deprecated in favor of the
 135 .B ldap_search_ext_s()
 136 routine.
 137 .LP
 138 .so Deprecated
 139 .SH SEE ALSO
 140 .BR ldap (3),
 141 .BR ldap_result (3),
 142 .BR ldap_error (3)
 143 .SH ACKNOWLEDGEMENTS
 144 .so ../Project