git.sur5r.net Git - openldap/blob - doc/man/man3/ldap_get_values.3

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