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

   1 .TH LDAP_FIRST_ENTRY 3 "RELEASEDATE" "OpenLDAP LDVERSION"
   2 .\" $OpenLDAP$
   3 .\" Copyright 1998-2014 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 .so ../Project