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

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