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