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