From: Ondřej Kuzník <ondra@mistotebe.net>
Date: Thu, 13 May 2021 11:53:05 +0000 (+0100)
Subject: ITS#8820 Document ldap_get_attribute_ber()
X-Git-Tag: OPENLDAP_REL_ENG_2_6_0~212
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=363f10560f7283e6dcebdcd38dfd2074a94f62f7;p=thirdparty%2Fopenldap.git

ITS#8820 Document ldap_get_attribute_ber()
---

diff --git a/doc/man/man3/ldap_first_attribute.3 b/doc/man/man3/ldap_first_attribute.3
index abc5fc3afe..fa77df82a1 100644
--- a/doc/man/man3/ldap_first_attribute.3
+++ b/doc/man/man3/ldap_first_attribute.3
@@ -18,11 +18,17 @@ char *ldap_first_attribute(
 .ft B
 char *ldap_next_attribute(
 	LDAP *ld, LDAPMessage *entry, BerElement *ber )
+.LP
+.ft B
+int ldap_get_attribute_ber(
+	LDAP *ld, LDAPMessage *entry, BerElement *ber,
+	BerValue *attr, BerVarray *vals )
 .SH DESCRIPTION
 The
-.B ldap_first_attribute()
-and
+.BR ldap_first_attribute() ,
 .B ldap_next_attribute()
+and
+.B ldap_get_attribute_ber()
 routines are used
 to step through the attributes in an LDAP entry.
 .B ldap_first_attribute()
@@ -52,6 +58,19 @@ The attribute names returned are suitable for inclusion in a call
 to
 .BR ldap_get_values (3)
 to retrieve the attribute's values.
+.LP
+The
+.B ldap_get_attribute_ber()
+routine allows one to iterate over all attributes in-place, without
+allocating memory to hold text for the attribute name or its values,
+if requested. The use case is similar to
+.B ldap_next_attribute()
+except that the attribute name is returned into \fIattr\fP and, if
+\fIvals\fP is non-NULL, the list of values is stored there. Both point
+into the LDAP message and remain valid only while the entry is valid.
+The caller is still responsible for freeing \fIvals\fP with
+.BR ldap_memfree (3),
+if used.
 .SH ERRORS
 If an error occurs, NULL is returned and the ld_errno field in the
 \fIld\fP parameter is set to indicate the error.  See
@@ -63,7 +82,12 @@ The
 and
 .B ldap_next_attribute()
 return dynamically allocated memory that must be freed by the caller via
-.BR ldap_memfree (3).   
+.BR ldap_memfree (3).
+For
+.BR ldap_get_attribute_ber() ,
+only the actual \fIvals\fP pointer needs to be freed with
+.BR ldap_memfree (3),
+other data is accounted for as part of \fIber\fP.
 .SH SEE ALSO
 .BR ldap (3),
 .BR ldap_first_entry (3),
diff --git a/doc/man/man3/ldap_first_attribute.3.links b/doc/man/man3/ldap_first_attribute.3.links
index 739fe3a6c5..ce3981c687 100644
--- a/doc/man/man3/ldap_first_attribute.3.links
+++ b/doc/man/man3/ldap_first_attribute.3.links
@@ -1 +1,2 @@
 ldap_next_attribute.3
+ldap_get_attribute_ber.3