usr/src/man/man3ldap/ldap_get_values.3ldap

   1 '\" te
   2 .\" Copyright (C) 1990, Regents of the University of Michigan.  All Rights Reserved.
   3 .\" Portions Copyright (C) 2002, Sun Microsystems, Inc. All Rights Reserved.
   4 .\" 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.
   5 .\" 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.
   6 .\" 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]
   7 .TH LDAP_GET_VALUES 3LDAP "Jan 28, 2002"
   8 .SH NAME
   9 ldap_get_values, ldap_get_values_len, ldap_count_values, ldap_count_values_len,
  10 ldap_value_free, ldap_value_free_len \- LDAP attribute value handling functions
  11 .SH SYNOPSIS
  12 .LP
  13 .nf
  14 cc[ \fIflag\fR... ] \fIfile\fR... -lldap[ \fIlibrary\fR... ]
  15 #include <lber.h>
  16 #include <ldap.h>
  17
  18 \fBchar **\fR\fBldap_get_values\fR(\fBLDAP\fR \fI*ld\fR, \fBLDAPMessage\fR \fI*entry\fR, \fBchar\fR \fI*attr\fR);
  19 .fi
  20
  21 .LP
  22 .nf
  23 \fBstruct berval **\fR\fBldap_get_values_len\fR(\fBLDAP\fR \fI*ld\fR, \fBLDAPMessage\fR \fI*entry\fR,
  24      \fBchar\fR \fI*attr\fR);
  25 .fi
  26
  27 .LP
  28 .nf
  29 \fB\fR\fBldap_count_values\fR(\fBchar\fR \fI**vals\fR);
  30 .fi
  31
  32 .LP
  33 .nf
  34 \fB\fR\fBldap_count_values_len\fR(\fBstruct berval\fR \fI**vals\fR);
  35 .fi
  36
  37 .LP
  38 .nf
  39 \fB\fR\fBldap_value_free\fR(\fBchar\fR \fI**vals\fR);
  40 .fi
  41
  42 .LP
  43 .nf
  44 \fB\fR\fBldap_value_free_len\fR(\fBstruct berval\fR \fI**vals\fR);
  45 .fi
  46
  47 .SH DESCRIPTION
  48 .sp
  49 .LP
  50 These functions are used to retrieve and manipulate attribute values from an
  51 LDAP entry as returned by \fBldap_first_entry\fR(3LDAP) or
  52 \fBldap_next_entry\fR(3LDAP). \fBldap_get_values()\fR takes the \fIentry\fR and
  53 the attribute \fIattr\fR whose values are desired and returns a null-terminated
  54 array of the attribute's values.  \fIattr\fR may be an attribute type as
  55 returned from \fBldap_first_attribute\fR(3LDAP) or
  56 \fBldap_next_attribute\fR(3LDAP), or if the attribute type is known it can
  57 simply be given.
  58 .sp
  59 .LP
  60 The number of values in the array can be counted by calling
  61 \fBldap_count_values()\fR. The array of values returned can be freed by calling
  62 \fBldap_value_free()\fR.
  63 .sp
  64 .LP
  65 If the attribute values are binary in nature, and thus not suitable to be
  66 returned as an array of char *'s, the \fBldap_get_values_len()\fR function can
  67 be used instead.  It takes the same parameters as \fBldap_get_values()\fR, but
  68 returns a null-terminated array of pointers to berval structures, each
  69 containing the length of and a pointer to a value.
  70 .sp
  71 .LP
  72 The number of values in the array can be counted by calling
  73 \fBldap_count_values_len()\fR. The array of values returned can be freed by
  74 calling \fBldap_value_free_len()\fR.
  75 .SH ERRORS
  76 .sp
  77 .LP
  78 If an error occurs in \fBldap_get_values()\fR or \fBldap_get_values_len()\fR,
  79 \fINULL\fR returned and the \fBld_errno\fR field in the \fBld\fR parameter is
  80 set to indicate the error.  See \fBldap_error\fR(3LDAP) for a description of
  81 possible error codes.
  82 .SH ATTRIBUTES
  83 .sp
  84 .LP
  85 See \fBattributes\fR(5) for a description of the following attributes:
  86 .sp
  87
  88 .sp
  89 .TS
  90 box;
  91 c | c
  92 l | l .
  93 ATTRIBUTE TYPE  ATTRIBUTE VALUE
  94 Interface Stability     Evolving
  95 .TE
  96
  97 .SH SEE ALSO
  98 .sp
  99 .LP
 100 \fBldap\fR(3LDAP), \fBldap_first_entry\fR(3LDAP),
 101 \fBldap_first_attribute\fR(3LDAP), \fBldap_error\fR(3LDAP), \fBattributes\fR(5)
 102 .SH NOTES
 103 .sp
 104 .LP
 105 These functions allocates memory that the caller must free.