1.lf 1 stdin
2.TH LDAP_GET_VALUES 3 "2020/04/28" "OpenLDAP 2.4.50"
3.\" $OpenLDAP$
4.\" Copyright 1998-2020 The OpenLDAP Foundation All Rights Reserved.
5.\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
6.SH NAME
7ldap_get_values, ldap_get_values_len, ldap_count_values \- LDAP attribute value handling routines
8.SH LIBRARY
9OpenLDAP LDAP (libldap, \-lldap)
10.SH SYNOPSIS
11.nf
12.ft B
13#include <ldap.h>
14
15.LP
16.ft B
17char **ldap_get_values(ld, entry, attr)
18.ft
19LDAP *ld;
20LDAPMessage *entry;
21char *attr;
22.LP
23.ft B
24struct berval **ldap_get_values_len(ld, entry, attr)
25.ft
26LDAP *ld;
27LDAPMessage *entry;
28char *attr;
29.LP
30.ft B
31int ldap_count_values(vals)
32.ft
33char **vals;
34.LP
35.ft B
36int ldap_count_values_len(vals)
37.ft
38struct berval **vals;
39.LP
40.ft B
41void ldap_value_free(vals)
42.ft
43char **vals;
44.LP
45.ft B
46void ldap_value_free_len(vals)
47.ft
48struct berval **vals;
49.SH DESCRIPTION
50These routines are used to retrieve and manipulate attribute values
51from an LDAP entry as returned by
52.BR ldap_first_entry (3)
53or
54.BR ldap_next_entry (3).
55.B ldap_get_values()
56takes the \fIentry\fP and the attribute \fIattr\fP
57whose values are desired and returns a NULL-terminated array of the
58attribute's values.  \fIattr\fP may be an attribute type as returned
59from
60.BR ldap_first_attribute (3)
61or
62.BR ldap_next_attribute (3),
63or if the attribute type is known it can simply be given.
64.LP
65The number of values in the array can be counted by calling
66.BR ldap_count_values() .
67The array of values returned can be freed by calling
68.BR ldap_value_free() .
69.LP
70If the attribute values are binary in nature, and thus not suitable
71to be returned as an array of char *'s, the
72.B ldap_get_values_len()
73routine can be used instead.  It takes the same parameters as
74.BR ldap_get_values() ,
75but returns a NULL-terminated array of pointers
76to berval structures, each containing the length of and a pointer
77to a value.
78.LP
79The number of values in the array can be counted by calling
80.BR ldap_count_values_len() .
81The array of values returned can be freed by calling
82.BR ldap_value_free_len() .
83.SH ERRORS
84If an error occurs in
85.B ldap_get_values()
86or
87.BR ldap_get_values_len() ,
88NULL is returned and the
89.B ld_errno
90field in the \fIld\fP parameter is set to
91indicate the error.  See
92.BR ldap_error (3)
93for a description of possible error codes.
94.SH NOTES
95These routines dynamically allocate memory which the caller must free
96using the supplied routines.
97.SH SEE ALSO
98.BR ldap (3),
99.BR ldap_first_entry (3),
100.BR ldap_first_attribute (3),
101.BR ldap_error (3)
102.SH ACKNOWLEDGEMENTS
103.lf 1 ./../Project
104.\" Shared Project Acknowledgement Text
105.B "OpenLDAP Software"
106is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>.
107.B "OpenLDAP Software"
108is derived from the University of Michigan LDAP 3.3 Release.  
109.lf 103 stdin
110