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

   1 .TH LDAP_FIRST_ENTRY 3 "23 July 2001" "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_first_entry, ldap_next_entry, ldap_count_entries \- LDAP result entry parsing and counting routines
   7 .SH SYNOPSIS
   8 .nf
   9 .ft B
  10 #include <ldap.h>
  11 .LP
  12 .ft B
  13 int ldap_count_entries( LDAP *ld, LDAPMessage *result )
  14 .LP
  15 .ft B
  16 LDAPMessage *ldap_first_entry( LDAP *ld, LDAPMessage *result )
  17 .LP
  18 .ft B
  19 LDAPMessage *ldap_next_entry( LDAP *ld, LDAPMessage *entry )
  20 .SH DESCRIPTION
  21 .LP
  22 These routines are used to parse results received from
  23 .BR ldap_result (3)
  24 or the synchronous LDAP search operation routines
  25 .BR ldap_search_s (3)
  26 and
  27 .BR ldap_search_st (3).
  28 .LP
  29 The
  30 .B ldap_first_entry()
  31 routine is used to retrieve the first entry in a chain
  32 of search results.  It takes the \fIresult\fP as returned by a call to
  33 .BR ldap_result (3)
  34 or
  35 .BR ldap_search_s (3)
  36 or
  37 .BR ldap_search_st (3)
  38 and returns a pointer to the first entry in the result.
  39 .LP
  40 This pointer should be supplied on a subsequent call to
  41 .B ldap_next_entry()
  42 to get the next entry, the result of which should be
  43 supplied to the next call to
  44 .BR ldap_next_entry() ,
  45 etc.
  46 .B ldap_next_entry()
  47 will return NULL when there are no more entries.  The entries returned
  48 from these calls are used in calls to the routines described in
  49 .BR ldap_get_dn (3),
  50 .BR ldap_first_attribute (3),
  51 .BR ldap_get_values (3),
  52 etc.
  53 .LP
  54 A count of the number of entries in the search result can be obtained
  55 by calling
  56 .BR ldap_count_entries() .
  57 .SH ERRORS
  58 If an error occurs in
  59 .B ldap_first_entry()
  60 or
  61 .BR ldap_next_entry() ,
  62 NULL is returned and the ld_errno field in the \fIld\fP parameter
  63 is set to indicate the error.  If an error occurs in
  64 .BR ldap_count_entries() ,
  65 -1 is returned, and
  66 .B ld_errno
  67 is set appropriately.  See
  68 .BR ldap_error (3)
  69 for a description of possible error codes.
  70 .SH SEE ALSO
  71 .BR ldap(3),
  72 .BR ldap_result(3),
  73 .BR ldap_search(3),
  74 .BR ldap_first_attribute(3),
  75 .BR ldap_get_values(3),
  76 .BR ldap_get_dn(3)
  77 .SH ACKNOWLEDGEMENTS
  78 .B      OpenLDAP
  79 is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
  80 .B      OpenLDAP
  81 is derived from University of Michigan LDAP 3.3 Release.