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

   1 .TH LDAP_FIRST_ATTRIBUTE 3  "25 November 1994" "U-M LDAP LDVERSION"
   2 .SH NAME
   3 ldap_first_attribute, ldap_next_attribute \- step through LDAP entry attributes
   4 .SH SYNOPSIS
   5 .nf
   6 .ft B
   7 #include <lber.h>
   8 #include <ldap.h>
   9 .LP
  10 .ft B
  11 char *ldap_first_attribute(ld, entry, berptr)
  12 .ft
  13 LDAP *ld;
  14 LDAPMessage *entry;
  15 BerElement **berptr;
  16 .LP
  17 .ft B
  18 char *ldap_next_attribute(ld, entry, ber)
  19 .ft
  20 LDAP *ld;
  21 LDAPMessage *entry;
  22 BerElement *ber;
  23 .SH DESCRIPTION
  24 The
  25 .B ldap_first_attribute()
  26 and
  27 .B ldap_next_attribute()
  28 routines are used
  29 to step through the attributes in an LDAP entry.
  30 .B ldap_first_attribute()
  31 takes an \fIentry\fP as returned by
  32 .BR ldap_first_entry (3)
  33 or
  34 .BR ldap_next_entry (3)
  35 and returns a pointer to a per-connection buffer
  36 containing the first attribute type in the entry.  The return value
  37 should be treated as if it is a pointer to a static area (i.e.,
  38 .BR strdup (3)
  39 it if you want to save it).
  40 .LP
  41 It also returns, in \fIberptr\fP, a pointer to a BerElement it has
  42 allocated to keep track of its current position.  This pointer should
  43 be passed to subsequent calls to
  44 .B ldap_next_attribute()
  45 and is used used
  46 to effectively step through the entry's attributes.  This pointer
  47 is freed by
  48 .B ldap_next_attribute()
  49 when there are no more attributes (that
  50 is, when
  51 .B ldap_next_attribute()
  52 returns NULL).  Otherwise, the caller is
  53 responsible for freeing the BerElement pointed to by \fIberptr\fP when
  54 it is no longer needed by calling
  55 .BR ber_free (3).
  56 When calling
  57 .BR ber_free (3)
  58 in this instance, be sure the second argument is 0.
  59 .LP
  60 The attribute names returned are suitable for inclusion in a call
  61 to
  62 .BR ldap_get_values (3)
  63 to retrieve the attribute's values.
  64 .SH ERRORS
  65 If an error occurs, NULL is returned and the ld_errno field in the
  66 \fIld\fP parameter is set to indicate the error.  See
  67 .BR ldap_error (3)
  68 for a description of possible error codes.
  69 .SH NOTES
  70 The
  71 .B ldap_first_attribute()
  72 routine mallocs memory that may need to
  73 be freed by the caller via
  74 .BR ber_free (3).
  75 .SH SEE ALSO
  76 .BR ldap(3),
  77 .BR ldap_first_entry(3),
  78 .BR ldap_get_values(3),
  79 .BR ldap_error(3)