'\" te
.\" Copyright (c) 1990, Regents of the University of Michigan.  All Rights Reserved.
.\" Portions Copyright (c) 2002, 2011, Oracle and/or its affiliates. All rights reserved.
.TH ldap_get_values 3LDAP "23 Aug 2011" "SunOS 5.11" "LDAP Library Functions"
.SH NAME
ldap_get_values, ldap_get_values_len, ldap_count_values, ldap_count_values_len, ldap_value_free, ldap_value_free_len \- LDAP attribute value handling functions
.SH SYNOPSIS
.LP
.nf
cc [ \fIflag\fR... ] \fIfile\fR... -lldap [ \fIlibrary\fR... ]
#include <lber.h>
#include <ldap.h>

\fBchar **\fR\fBldap_get_values\fR(\fBLDAP *\fR\fIld\fR, \fBLDAPMessage *\fR\fIentry\fR, \fBchar *\fR\fIattr\fR);
.fi

.LP
.nf
\fBstruct berval **\fR\fBldap_get_values_len\fR(\fBLDAP *\fR \fIld\fR, \fBLDAPMessage *\fR\fIentry\fR,
     \fBchar *\fR\fIattr\fR);
.fi

.LP
.nf
\fBint\fR \fBldap_count_values\fR(\fBchar **\fR\fIvals\fR);
.fi

.LP
.nf
\fBint\fR \fBldap_count_values_len\fR(\fBstruct berval **\fR\fIvals\fR);
.fi

.LP
.nf
\fBvoid\fR \fBldap_value_free\fR(\fBchar **\fR\fIvals\fR);
.fi

.LP
.nf
\fBvoid\fR \fBldap_value_free_len\fR(\fBstruct berval\fR \fIvals\fR);
.fi

.SH DESCRIPTION
.sp
.LP
These functions are used to retrieve and manipulate attribute values from an LDAP entry as returned by \fBldap_first_entry\fR(3LDAP) or \fBldap_next_entry\fR(3LDAP). \fBldap_get_values()\fR takes the \fIentry\fR and the attribute \fIattr\fR whose values are desired and returns a null-terminated array of the attribute's values.  \fIattr\fR may be an attribute type as returned from \fBldap_first_attribute\fR(3LDAP) or \fBldap_next_attribute\fR(3LDAP), or if the attribute type is known it can simply be given.
.sp
.LP
The number of values in the array can be counted by calling \fBldap_count_values()\fR. The array of values returned can be freed by calling \fBldap_value_free()\fR. 
.sp
.LP
If the attribute values are binary in nature, and thus not suitable to be returned as an array of char *'s, the \fBldap_get_values_len()\fR function can be used instead.  It takes the same parameters as \fBldap_get_values()\fR, but returns a null-terminated array of pointers to berval structures, each containing the length of and a pointer to a value.
.sp
.LP
The number of values in the array can be counted by calling \fBldap_count_values_len()\fR. The array of values returned can be freed by calling \fBldap_value_free_len()\fR. 
.SH ERRORS
.sp
.LP
If an error occurs in \fBldap_get_values()\fR or \fBldap_get_values_len()\fR, \fINULL\fR returned and the \fBld_errno\fR field in the \fBld\fR parameter is set to indicate the error.  See \fBldap_error\fR(3LDAP) for a description of possible error codes.
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for a description of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Availabilitysystem/library
_
Interface StabilityCommitted
.TE

.SH SEE ALSO
.sp
.LP
\fBldap\fR(3LDAP), \fBldap_first_entry\fR(3LDAP), \fBldap_first_attribute\fR(3LDAP), \fBldap_error\fR(3LDAP), \fBattributes\fR(5)
.SH NOTES
.sp
.LP
These functions allocates memory that the caller must free.