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