external/bsd/openldap/man/ldap_first_entry.3

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