'\" te
.\" Copyright (C) 1990, Regents of the University of Michigan.  All Rights Reserved.
.\" Portions Copyright (C) 2002, Sun Microsystems, Inc. All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH LDAP_GET_VALUES 3LDAP "Jan 28, 2002"
.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 \fI*ld\fR, \fBLDAPMessage\fR \fI*entry\fR, \fBchar\fR \fI*attr\fR);
.fi

.LP
.nf
\fBstruct berval **\fR\fBldap_get_values_len\fR(\fBLDAP\fR \fI*ld\fR, \fBLDAPMessage\fR \fI*entry\fR,
     \fBchar\fR \fI*attr\fR);
.fi

.LP
.nf
\fB\fR\fBldap_count_values\fR(\fBchar\fR \fI**vals\fR);
.fi

.LP
.nf
\fB\fR\fBldap_count_values_len\fR(\fBstruct berval\fR \fI**vals\fR);
.fi

.LP
.nf
\fB\fR\fBldap_value_free\fR(\fBchar\fR \fI**vals\fR);
.fi

.LP
.nf
\fB\fR\fBldap_value_free_len\fR(\fBstruct berval\fR \fI**vals\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
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Evolving
.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.