summaryrefslogtreecommitdiffstats
path: root/doc/man/man3/ldap_first_attribute.3
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 16:35:32 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 16:35:32 +0000
commit5ea77a75dd2d2158401331879f3c8f47940a732c (patch)
treed89dc06e9f4850a900f161e25f84e922c4f86cc8 /doc/man/man3/ldap_first_attribute.3
parentInitial commit. (diff)
downloadopenldap-5ea77a75dd2d2158401331879f3c8f47940a732c.tar.xz
openldap-5ea77a75dd2d2158401331879f3c8f47940a732c.zip
Adding upstream version 2.5.13+dfsg.upstream/2.5.13+dfsgupstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'doc/man/man3/ldap_first_attribute.3')
-rw-r--r--doc/man/man3/ldap_first_attribute.397
1 files changed, 97 insertions, 0 deletions
diff --git a/doc/man/man3/ldap_first_attribute.3 b/doc/man/man3/ldap_first_attribute.3
new file mode 100644
index 0000000..47e8b0c
--- /dev/null
+++ b/doc/man/man3/ldap_first_attribute.3
@@ -0,0 +1,97 @@
+.TH LDAP_FIRST_ATTRIBUTE 3 "RELEASEDATE" "OpenLDAP LDVERSION"
+.\" $OpenLDAP$
+.\" Copyright 1998-2022 The OpenLDAP Foundation All Rights Reserved.
+.\" Copying restrictions apply. See COPYRIGHT/LICENSE.
+.SH NAME
+ldap_first_attribute, ldap_next_attribute \- step through LDAP entry attributes
+.SH LIBRARY
+OpenLDAP LDAP (libldap, \-lldap)
+.SH SYNOPSIS
+.nf
+.ft B
+#include <ldap.h>
+.LP
+.ft B
+char *ldap_first_attribute(
+ LDAP *ld, LDAPMessage *entry, BerElement **berptr )
+.LP
+.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
+.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()
+takes an \fIentry\fP as returned by
+.BR ldap_first_entry (3)
+or
+.BR ldap_next_entry (3)
+and returns a pointer to character string
+containing the first attribute description in the entry.
+.B ldap_next_attribute()
+returns the next attribute description in the entry.
+.LP
+It also returns, in \fIberptr\fP, a pointer to a BerElement it has
+allocated to keep track of its current position. This pointer should
+be passed to subsequent calls to
+.B ldap_next_attribute()
+and is used
+to effectively step through the entry's attributes. The caller is
+solely responsible for freeing the BerElement pointed to by \fIberptr\fP
+when it is no longer needed by calling
+.BR ber_free (3).
+When calling
+.BR ber_free (3)
+in this instance, be sure the second argument is 0.
+.LP
+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
+.BR ldap_error (3)
+for a description of possible error codes.
+.SH NOTES
+The
+.B ldap_first_attribute()
+and
+.B ldap_next_attribute()
+return dynamically allocated memory that must be freed by the caller via
+.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),
+.BR ldap_get_values (3),
+.BR ldap_error (3)
+.SH ACKNOWLEDGEMENTS
+.so ../Project