share/man/man3devinfo/di_path_prop_bytes.3devinfo

   1 '\" te
   2 .\" Copyright (c) 2008, 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_PATH_PROP_BYTES 3DEVINFO "May 15, 2008"
   7 .SH NAME
   8 di_path_prop_bytes, di_path_prop_ints, di_path_prop_int64s, di_path_prop_name,
   9 di_path_prop_strings, di_path_prop_type \- access path property information
  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 \fBchar *\fR\fBdi_path_prop_bytes\fR(\fBdi_path_prop_t\fR \fIprop\fR);
  17 .fi
  18
  19 .LP
  20 .nf
  21 \fBint\fR \fB\fR(\fBdi_path_prop_t\fR \fIprop\fR);
  22 .fi
  23
  24 .LP
  25 .nf
  26 \fBint\fR \fB\fR(\fBdi_path_prop_t\fR \fIprop\fR, \fBuchar_t **\fR\fIprop_data\fR);
  27 .fi
  28
  29 .LP
  30 .nf
  31 \fBint\fR \fB\fR(\fBdi_path_prop_t\fR \fIprop\fR, \fBint **\fR\fIprop_data\fR);
  32 .fi
  33
  34 .LP
  35 .nf
  36 \fBint\fR \fB\fR(\fBdi_path_prop_t\fR \fIprop\fR, \fBint64_t **\fR\fIprop_data\fR);
  37 .fi
  38
  39 .LP
  40 .nf
  41 \fBint\fR \fBdi_path_prop_type\fR(\fBdi_path_prop_t\fR \fIprop\fR, \fBchar **\fR\fIprop_data\fR);
  42 .fi
  43
  44 .SH PARAMETERS
  45 .sp
  46 .ne 2
  47 .na
  48 \fB\fIprop\fR\fR
  49 .ad
  50 .RS 13n
  51 A handle to a property returned by \fBdi_path_prop_next\fR(3DEVINFO).
  52 .RE
  53
  54 .sp
  55 .ne 2
  56 .na
  57 \fB\fIprop_data\fR\fR
  58 .ad
  59 .RS 13n
  60 For \fBdi_path_prop_bytes()\fR, the address of a pointer to an unsigned
  61 character.
  62 .sp
  63 For \fBdi_path_prop_ints()\fR, the address of a pointer to an integer.
  64 .sp
  65 For \fBdi_path_prop_int64()\fR, the address of a pointer to a 64-bit integer.
  66 .sp
  67 For \fBdi_path_prop_strings()\fR, the address of pointer to a character.
  68 .RE
  69
  70 .SH DESCRIPTION
  71 .sp
  72 .LP
  73 These functions access information associated with path property values and
  74 attributes such as the property name or data type.
  75 .sp
  76 .LP
  77 The \fBdi_path_prop_name()\fR function returns a pointer to a string containing
  78 the name of the property.
  79 .sp
  80 .LP
  81 The \fBdi_path_prop_type()\fR function returns the type of the path property.
  82 The type determines the appropriate interface to access property values.
  83 Possible property types are the same as for \fBdi_prop_type\fR(3DEVINFO),
  84 excluding \fBDI_PROP_TYPE_UNKNOWN\fR and \fBDI_PROP_UNDEFINED\fR. Thus,
  85 \fBdi_path_prop_type()\fR can return one of the following constants:
  86 .sp
  87 .ne 2
  88 .na
  89 \fB\fBDI_PROP_TYPE_INT\fR\fR
  90 .ad
  91 .RS 23n
  92 Use \fBdi_path_prop_ints()\fR to access property data.
  93 .RE
  94
  95 .sp
  96 .ne 2
  97 .na
  98 \fB\fBDI_PROP_TYPE_INT64\fR\fR
  99 .ad
 100 .RS 23n
 101 Use \fBdi_path_prop_int64s()\fR to access property data.
 102 .RE
 103
 104 .sp
 105 .ne 2
 106 .na
 107 \fB\fBDI_PROP_TYPE_STRING\fR\fR
 108 .ad
 109 .RS 23n
 110 Use \fBdi_path_prop_strings()\fR to access property data.
 111 .RE
 112
 113 .sp
 114 .ne 2
 115 .na
 116 \fB\fBDI_PROP_TYPE_BYTE\fR\fR
 117 .ad
 118 .RS 23n
 119 Use \fBdi_path_prop_bytes()\fR to access property data.
 120 .RE
 121
 122 .sp
 123 .LP
 124 The \fBdi_path_prop_bytes()\fR function returns the property data as a series
 125 of unsigned characters.
 126 .sp
 127 .LP
 128 The \fBdi_path_prop_ints()\fR function returns the property data as a series of
 129 integers.
 130 .sp
 131 .LP
 132 The \fBdi_path_prop_int64s()\fR function returns the property data as a series
 133 of integers.
 134 .sp
 135 .LP
 136 The \fBdi_path_prop_strings()\fR function returns the property data as a
 137 concatenation of null-terminated strings.
 138 .SH RETURN VALUES
 139 .sp
 140 .LP
 141 Upon successful completion,  \fBdi_path_prop_bytes()\fR,
 142 \fBdi_path_prop_ints()\fR, \fBdi_path_prop_int64s()\fR, and
 143 \fBdi_path_prop_strings()\fR return a non-negative value, indicating the number
 144 of entries in the property value buffer. If the property is found, the number
 145 of entries in \fIprop_data\fR is returned. Otherwise, -1 is returned and
 146 \fBerrno\fR is set to indicate the error.
 147 .sp
 148 .LP
 149 For \fBdi_path_prop_bytes()\fR, the number of entries is the number of unsigned
 150 characters contained in the buffer pointed to by \fIprop_data\fR.
 151 .sp
 152 .LP
 153 For \fBdi_path_prop_ints()\fR, the number of entries is the number of integers
 154 contained in the buffer pointed to by \fIprop_data\fR.
 155 .sp
 156 .LP
 157 For \fBdi_path_prop_ints()\fR, the number of entries is the number of 64-bit
 158 integers contained in the buffer pointed to by \fIprop_data\fR.
 159 .sp
 160 .LP
 161 For \fBdi_path_prop_strings()\fR, the number of entries is the number of
 162 null-terminated strings contained in the buffer. The strings are stored in a
 163 concatenated format in the buffer.
 164 .sp
 165 .LP
 166 The \fBdi_path_prop_name()\fR function returns the name of the property.
 167 .sp
 168 .LP
 169 The \fBdi_path_prop_type()\fR function can return one of types described in the
 170 Description.
 171 .SH ERRORS
 172 .sp
 173 .LP
 174 These functions will fail if:
 175 .sp
 176 .ne 2
 177 .na
 178 \fB\fBEINVAL\fR\fR
 179 .ad
 180 .RS 11n
 181 One of the arguments is invalid. For example, the property type does not match
 182 the interface.
 183 .RE
 184
 185 .sp
 186 .ne 2
 187 .na
 188 \fB\fBENOTSUP\fR\fR
 189 .ad
 190 .RS 11n
 191 The snapshot contains no property information.
 192 .RE
 193
 194 .sp
 195 .ne 2
 196 .na
 197 \fB\fBENXIO\fR\fR
 198 .ad
 199 .RS 11n
 200 The path property does not exist.
 201 .RE
 202
 203 .SH ATTRIBUTES
 204 .sp
 205 .LP
 206 See \fBattributes\fR(5)  for descriptions of the following attributes:
 207 .sp
 208
 209 .sp
 210 .TS
 211 box;
 212 c | c
 213 l | l .
 214 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 215 _
 216 Interface Stability     Committed
 217 _
 218 MT-Level        Safe
 219 .TE
 220
 221 .SH SEE ALSO
 222 .sp
 223 .LP
 224 \fBdi_path_prop_next\fR(3DEVINFO), \fBdi_prop_type\fR(3DEVINFO),
 225 \fBlibdevinfo\fR(3LIB), \fBattributes\fR(5)
 226 .sp
 227 .LP
 228 \fIWriting Device Drivers\fR