From 363f10560f7283e6dcebdcd38dfd2074a94f62f7 Mon Sep 17 00:00:00 2001
From: =?utf8?q?Ond=C5=99ej=20Kuzn=C3=ADk?= <ondra@mistotebe.net>
Date: Thu, 13 May 2021 12:53:05 +0100
Subject: [PATCH] ITS#8820 Document ldap_get_attribute_ber()

---
 doc/man/man3/ldap_first_attribute.3       | 30 ++++++++++++++++++++---
 doc/man/man3/ldap_first_attribute.3.links |  1 +
 2 files changed, 28 insertions(+), 3 deletions(-)

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
-- 
2.47.3