external/bsd/openldap/man/ldap_get_values.3

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