share/man/man3devinfo/di_prop_bytes.3devinfo

   1 '\" te
   2 .\" Copyright (c) 2001, Sun Microsystems, Inc.  All Rights Reserved
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH DI_PROP_BYTES 3DEVINFO "Mar 27, 2001"
   7 .SH NAME
   8 di_prop_bytes, di_prop_devt, di_prop_ints, di_prop_name, di_prop_strings,
   9 di_prop_type, di_prop_int64 \- access property values and attributes
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-ldevinfo\fR [ \fIlibrary\fR... ]
  14 #include <libdevinfo.h>
  15
  16 \fBint\fR \fBdi_prop_bytes\fR(\fBdi_prop_t\fR \fIprop\fR, \fBuchar_t **\fR\fIprop_data\fR);
  17 .fi
  18
  19 .LP
  20 .nf
  21 \fBdev_t\fR \fBdi_prop_devt\fR(\fBdi_prop_t\fR \fIprop\fR);
  22 .fi
  23
  24 .LP
  25 .nf
  26 \fBint\fR \fBdi_prop_ints\fR(\fBdi_prop_t\fR \fIprop\fR, \fBint **\fR\fIprop_data\fR);
  27 .fi
  28
  29 .LP
  30 .nf
  31 \fBint\fR \fBdi_prop_int64\fR(\fBdi_prop_t\fR \fIprop\fR, \fBint64_t **\fR\fIprop_data\fR);
  32 .fi
  33
  34 .LP
  35 .nf
  36 \fBchar *\fR\fBdi_prop_name\fR(\fBdi_prop_t\fR \fIprop\fR);
  37 .fi
  38
  39 .LP
  40 .nf
  41 \fBint\fR \fBdi_prop_strings\fR(\fBdi_prop_t\fR \fIprop\fR, \fBchar **\fR\fIprop_data\fR);
  42 .fi
  43
  44 .LP
  45 .nf
  46 \fBint\fR \fBdi_prop_type\fR(\fBdi_prop_t\fR \fIprop\fR);
  47 .fi
  48
  49 .SH PARAMETERS
  50 .sp
  51 .ne 2
  52 .na
  53 \fB\fIprop\fR\fR
  54 .ad
  55 .RS 13n
  56 Handle to a property returned by \fBdi_prop_next\fR(3DEVINFO).
  57 .RE
  58
  59 .sp
  60 .ne 2
  61 .na
  62 \fB\fIprop_data\fR\fR
  63 .ad
  64 .RS 13n
  65 For \fBdi_prop_bytes()\fR, the address of a pointer to an unsigned character.
  66 .sp
  67 For \fBdi_prop_ints()\fR, the address of a pointer to an integer.
  68 .sp
  69 For \fBdi_prop_int64()\fR, the address of a pointer to a 64-bit integer.
  70 .sp
  71 For \fBdi_prop_strings()\fR, the address of pointer to a character.
  72 .RE
  73
  74 .SH DESCRIPTION
  75 .sp
  76 .LP
  77 These functions access information associated with property values and
  78 attributes. All memory allocated by these functions is managed by the library
  79 and must not be freed by the caller.
  80 .sp
  81 .LP
  82 The \fBdi_prop_bytes()\fR function returns the property data as a series of
  83 unsigned characters.
  84 .sp
  85 .LP
  86 The \fBdi_prop_devt()\fR function returns the \fBdev_t\fR with which this
  87 property is associated. If the value is \fBDDI_DEV_T_NONE\fR, the property is
  88 not associated with any specific minor node.
  89 .sp
  90 .LP
  91 The \fBdi_prop_ints()\fR function returns the property data as a series of
  92 integers.
  93 .sp
  94 .LP
  95 The \fBdi_prop_int64()\fR function returns the property data as a series of
  96 64-bit integers.
  97 .sp
  98 .LP
  99 The \fBdi_prop_name()\fR function returns the name of the property.
 100 .sp
 101 .LP
 102 The \fBdi_prop_strings()\fR function returns the property data as a
 103 concatenation of null-terminated strings.
 104 .sp
 105 .LP
 106 The \fBdi_prop_type()\fR function returns the type of the property. The type
 107 determines the appropriate interface to access property values. The following
 108 is a list of possible types:
 109 .sp
 110 .ne 2
 111 .na
 112 \fB\fBDI_PROP_TYPE_BOOLEAN\fR\fR
 113 .ad
 114 .RS 25n
 115 There is no interface to call since there is no property data associated with
 116 boolean properties. The existence of the property defines a \fBTRUE\fR value.
 117 .RE
 118
 119 .sp
 120 .ne 2
 121 .na
 122 \fB\fBDI_PROP_TYPE_INT\fR\fR
 123 .ad
 124 .RS 25n
 125 Use \fBdi_prop_ints()\fR to access property data.
 126 .RE
 127
 128 .sp
 129 .ne 2
 130 .na
 131 \fB\fBDI_PROP_TYPE_INT64\fR\fR
 132 .ad
 133 .RS 25n
 134 Use \fBdi_prop_int64()\fR to access property data.
 135 .RE
 136
 137 .sp
 138 .ne 2
 139 .na
 140 \fB\fBDI_PROP_TYPE_STRING\fR\fR
 141 .ad
 142 .RS 25n
 143 Use \fBdi_prop_strings()\fR to access property data.
 144 .RE
 145
 146 .sp
 147 .ne 2
 148 .na
 149 \fB\fBDI_PROP_TYPE_BYTE\fR\fR
 150 .ad
 151 .RS 25n
 152 Use \fBdi_prop_bytes()\fR to access property data.
 153 .RE
 154
 155 .sp
 156 .ne 2
 157 .na
 158 \fB\fBDI_PROP_TYPE_UNKNOWN\fR\fR
 159 .ad
 160 .RS 25n
 161 Use \fBdi_prop_bytes()\fR to access property data. Since the type of property
 162 is unknown, the caller is responsible for interpreting the contents of the
 163 data.
 164 .RE
 165
 166 .sp
 167 .ne 2
 168 .na
 169 \fB\fBDI_PROP_TYPE_UNDEF_IT\fR\fR
 170 .ad
 171 .RS 25n
 172 The property has been undefined by the driver. No property data is available.
 173 .RE
 174
 175 .SH RETURN VALUES
 176 .sp
 177 .LP
 178 Upon successful completion, \fBdi_prop_bytes()\fR, \fBdi_prop_ints()\fR,
 179 \fBdi_prop_int64()\fR, and \fBdi_prop_strings()\fR return a non-negative value,
 180 indicating the number of entries in the property value buffer. See
 181 \fBdi_prom_prop_lookup_bytes\fR(3DEVINFO) for a description of the return
 182 values. Otherwise, -1 is returned and \fIerrno\fR is set to indicate the error.
 183 .sp
 184 .LP
 185 The \fBdi_prop_devt()\fR function returns the \fBdev_t\fR value associated with
 186 the property.
 187 .sp
 188 .LP
 189 The \fBdi_prop_name()\fR function returns a pointer to a string containing the
 190 name of the property.
 191 .sp
 192 .LP
 193 The \fBdi_prop_type()\fR function can return one of types described in the
 194 DESCRIPTION section.
 195 .SH ERRORS
 196 .sp
 197 .LP
 198 These functions will fail if:
 199 .sp
 200 .ne 2
 201 .na
 202 \fB\fBEINVAL\fR\fR
 203 .ad
 204 .RS 10n
 205 Invalid argument. For example, the property type does not match the interface.
 206 .RE
 207
 208 .SH ATTRIBUTES
 209 .sp
 210 .LP
 211 See \fBattributes\fR(5) for descriptions of the following attributes:
 212 .sp
 213
 214 .sp
 215 .TS
 216 box;
 217 c | c
 218 l | l .
 219 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 220 _
 221 Interface Stability     Evolving
 222 _
 223 MT-Level        Safe
 224 .TE
 225
 226 .SH SEE ALSO
 227 .sp
 228 .LP
 229 \fBdi_prom_prop_lookup_bytes\fR(3DEVINFO), \fBdi_prop_next\fR(3DEVINFO),
 230 \fBlibdevinfo\fR(3LIB), \fBattributes\fR(5)
 231 .sp
 232 .LP
 233 \fIWriting Device Drivers\fR