usr/src/man/man9f/ddi_prop_update.9f

   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 DDI_PROP_UPDATE 9F "Aug 28, 2001"
   7 .SH NAME
   8 ddi_prop_update, ddi_prop_update_int_array, ddi_prop_update_int,
   9 ddi_prop_update_string_array, ddi_prop_update_int64,
  10 ddi_prop_update_int64_array, ddi_prop_update_string, ddi_prop_update_byte_array
  11 \- update properties
  12 .SH SYNOPSIS
  13 .LP
  14 .nf
  15 #include <sys/ddi.h>
  16 #include <sys/sunddi.h>
  17
  18
  19
  20 \fBint\fR \fBddi_prop_update_int_array\fR(\fBdev_t\fR \fIdev\fR, \fBdev_info_t *\fR\fIdip\fR,
  21      \fBchar *\fR\fIname\fR, \fBint *\fR\fIdata\fR, \fBuint_t\fR \fInelements\fR);
  22 .fi
  23
  24 .LP
  25 .nf
  26 \fBint\fR \fBddi_prop_update_int\fR(\fBdev_t\fR \fIdev\fR, \fBdev_info_t *\fR\fIdip\fR, \fBchar *\fR\fIname\fR,
  27      \fBint\fR \fIdata\fR);
  28 .fi
  29
  30 .LP
  31 .nf
  32 \fBint\fR \fBddi_prop_update_int64_array\fR(\fBdev_t\fR \fIdev\fR, \fBdev_info_t *\fR\fIdip\fR, \fBchar *\fR\fIname\fR,
  33      \fBint64_t *\fR\fIdata\fR, \fBuint_t\fR \fInelements\fR);
  34 .fi
  35
  36 .LP
  37 .nf
  38 \fBint\fR \fBddi_prop_update_int64\fR(\fBdev_t\fR \fIdev\fR, \fBdev_info_t *\fR\fIdip\fR, \fBchar *\fR\fIname\fR,
  39      \fBint64_t\fR \fIdata\fR);
  40 .fi
  41
  42 .LP
  43 .nf
  44 \fBint\fR \fBddi_prop_update_string_array\fR(\fBdev_t\fR \fIdev\fR, \fBdev_info_t *\fR\fIdip\fR, \fBchar *\fR\fIname\fR,
  45      \fBchar **\fR\fIdata\fR, \fBuint_t\fR \fInelements\fR);
  46 .fi
  47
  48 .LP
  49 .nf
  50 \fBint\fR \fBddi_prop_update_string\fR(\fBdev_t\fR \fIdev\fR, \fBdev_info_t *\fR\fIdip\fR, \fBchar *\fR\fIname\fR,
  51      \fBchar *\fR\fIdata\fR);
  52 .fi
  53
  54 .LP
  55 .nf
  56 \fBint\fR \fBddi_prop_update_byte_array\fR(\fBdev_t\fR \fIdev\fR, \fBdev_info_t *\fR\fIdip\fR, \fBchar *\fR\fIname\fR,
  57      \fBuchar_t *\fR\fIdata\fR, \fBuint_t\fR \fInelements\fR);
  58 .fi
  59
  60 .SH PARAMETERS
  61 .sp
  62 .ne 2
  63 .na
  64 \fB\fIdev\fR \fR
  65 .ad
  66 .RS 14n
  67 Device number associated with the device.
  68 .RE
  69
  70 .sp
  71 .ne 2
  72 .na
  73 \fB\fIdip\fR \fR
  74 .ad
  75 .RS 14n
  76 Pointer to the device info node of device whose property list should be
  77 updated.
  78 .RE
  79
  80 .sp
  81 .ne 2
  82 .na
  83 \fB\fIname\fR \fR
  84 .ad
  85 .RS 14n
  86 String containing the name of the property to be updated.
  87 .RE
  88
  89 .sp
  90 .ne 2
  91 .na
  92 \fB\fInelements\fR \fR
  93 .ad
  94 .RS 14n
  95 The number of elements contained in the memory pointed at by \fIdata\fR.
  96 .RE
  97
  98 .sp
  99 .LP
 100 \fBddi_prop_update_int_array()\fR
 101 .sp
 102 .ne 2
 103 .na
 104 \fB\fIdata\fR \fR
 105 .ad
 106 .RS 9n
 107 A pointer an integer array with which to update the property.
 108 .RE
 109
 110 .sp
 111 .LP
 112 \fBddi_prop_update_int()\fR
 113 .sp
 114 .ne 2
 115 .na
 116 \fB\fIdata\fR \fR
 117 .ad
 118 .RS 9n
 119 An integer value with which to update the property.
 120 .RE
 121
 122 .sp
 123 .LP
 124 \fBddi_prop_update_int64_array()\fR
 125 .sp
 126 .ne 2
 127 .na
 128 \fB\fIdata\fR \fR
 129 .ad
 130 .RS 9n
 131 An pointer to a 64-bit integer array with which to update the property.
 132 .RE
 133
 134 .sp
 135 .LP
 136 \fBddi_prop_update_int64()\fR
 137 .sp
 138 .ne 2
 139 .na
 140 \fB\fIdata\fR \fR
 141 .ad
 142 .RS 9n
 143 A 64-bit integer value with which to update the property.
 144 .RE
 145
 146 .sp
 147 .LP
 148 \fBddi_prop_update_string_array()\fR
 149 .sp
 150 .ne 2
 151 .na
 152 \fB\fIdata\fR \fR
 153 .ad
 154 .RS 9n
 155 A pointer to a string array with which to update the property. The array of
 156 strings is formatted as an array of pointers to \fBNULL \fRterminated strings,
 157 much like the \fIargv\fR argument to \fBexecve\fR(2).
 158 .RE
 159
 160 .sp
 161 .LP
 162 \fBddi_prop_update_string()\fR
 163 .sp
 164 .ne 2
 165 .na
 166 \fB\fIdata\fR \fR
 167 .ad
 168 .RS 9n
 169 A pointer to a string value with which to update the property.
 170 .RE
 171
 172 .sp
 173 .LP
 174 \fBddi_prop_update_byte_array()\fR
 175 .sp
 176 .ne 2
 177 .na
 178 \fB\fIdata\fR \fR
 179 .ad
 180 .RS 9n
 181 A pointer to a byte array with which to update the property.
 182 .RE
 183
 184 .SH INTERFACE LEVEL
 185 .sp
 186 .LP
 187 Solaris DDI specific (Solaris DDI).
 188 .SH DESCRIPTION
 189 .sp
 190 .LP
 191 The property update routines search for and, if found, modify the value of a
 192 given property. Properties are searched for based on the \fIdip\fR, \fIname\fR,
 193 \fIdev\fR, and the type of the data (integer, string, or byte). The driver
 194 software properties list is searched. If the property is found, it is updated
 195 with the supplied value. If the property is not found on this list, a new
 196 property is created with the value supplied. For example, if a driver attempts
 197 to update the "foo" property, a property named "foo" is searched for on the
 198 driver's software property list. If "foo" is found, the value is updated. If
 199 "foo" is not found, a new property named "foo" is created on the driver's
 200 software property list with the supplied value even if a "foo" property exists
 201 on another property list (such as a \fBPROM \fRproperty list).
 202 .sp
 203 .LP
 204 Every property value has a data type associated with it: byte, integer, or
 205 string. A property should be updated using a function with the same
 206 corresponding data type as the property value. For example, an integer property
 207 must be updated using either \fBddi_prop_update_int_array()\fR or
 208 \fBddi_prop_update_int()\fR. For a 64-bit integer, you must use
 209 \fBddi_prop_update_int64_array()\fR or \fBddi_prop_update_int64()\fR. Attempts
 210 to update a property with a function that does not correspond to the property
 211 data type that was used to create it results in an undefined state.
 212 .sp
 213 .LP
 214 Usually, the \fIdev\fR argument should be set to the actual device number that
 215 this property is associated with. If the property is not associated with any
 216 particular \fIdev\fR, then the argument \fIdev\fR should be set to
 217 \fBDDI_DEV_T_NONE.\fR This property will then match a look up request (see
 218 \fBddi_prop_lookup\fR(9F)) with the \fImatch_dev\fR argument set to
 219 \fBDDI_DEV_T_ANY.\fR If no \fIdev\fR is available for the device (for example
 220 during \fBattach\fR(9E) time), one can be created using \fBmakedevice\fR(9F)
 221 with a major number of \fBDDI_MAJOR_T_UNKNOWN.\fR The update routines will then
 222 generate the correct \fIdev\fR when creating or updating the property.
 223 .sp
 224 .LP
 225 \fIname\fR must always be set to the name of the property being updated.
 226 .sp
 227 .LP
 228 For the routines \fBddi_prop_update_int_array\fR(\|),
 229 \fBddi_prop_lookup_int64_array()\fR, \fBddi_prop_update_string_array\fR(\|),
 230 \fBddi_prop_update_string\fR(\|), and \fBddi_prop_update_byte_array\fR(\|),
 231 \fIdata\fR is a pointer which points to memory containing the value of the
 232 property. In each case \fI*data\fR points to a different type of property
 233 value. See the individual descriptions of the routines below for details
 234 concerning the different values. \fInelements\fR is an unsigned integer which
 235 contains the number of integer, string, or byte elements accounted for in the
 236 memory pointed at by \fI*data\fR.
 237 .sp
 238 .LP
 239 For the routines \fBddi_prop_update_int()\fR and \fBddi_prop_update_int64()\fR,
 240 \fIdata\fR is the new value of the property.
 241 .sp
 242 .LP
 243 \fBddi_prop_update_int_array()\fR
 244 .sp
 245 .LP
 246 Updates or creates an array of integer property values. An array of integers is
 247 defined to be \fInelements\fR of 4 byte long integer elements. \fIdata\fR must
 248 be a pointer to an integer array with which to update the property.
 249 .sp
 250 .LP
 251 \fBddi_prop_update_int()\fR
 252 .sp
 253 .LP
 254 Update or creates a single integer value of a property. \fIdata\fR must be an
 255 integer value with which to update the property.
 256 .sp
 257 .LP
 258 \fBddi_prop_update_int64_array()\fR
 259 .sp
 260 .LP
 261 Updates or creates an array of 64-bit integer property values. An array of
 262 integers is defined to be \fBnelements\fR of \fBint64_t\fR integer elements.
 263 \fIdata\fR must be a pointer to a 64-bit integer array with which to update the
 264 property.
 265 .sp
 266 .LP
 267 \fBddi_prop_update_int64()\fR
 268 .sp
 269 .LP
 270 Updates or creates a single 64-bit integer value of a property. \fIdata\fR must
 271 be an \fBint64_t\fR value with which to update the property.
 272 .sp
 273 .LP
 274 \fBddi_prop_update_string_array()\fR
 275 .sp
 276 .LP
 277 Updates or creates a property that is an array of strings. \fIdata\fR must be a
 278 pointer to a string array with which to update the property. The array of
 279 strings is formatted as an array of pointers to \fBNULL\fRterminated strings,
 280 much like the \fIargv\fR argument to \fBexecve\fR(2).
 281 .sp
 282 .LP
 283 \fBddi_prop_update_string()\fR
 284 .sp
 285 .LP
 286 Updates or creates a property that is a single string value. \fIdata\fR must be
 287 a pointer to a string with which to update the property.
 288 .sp
 289 .LP
 290 \fBddi_prop_update_byte_array()\fR
 291 .sp
 292 .LP
 293 Updates or creates a property that is an array of bytes. \fIdata\fR should be a
 294 pointer to a byte array with which to update the property.
 295 .sp
 296 .LP
 297 The property update routines may block to allocate memory needed to hold the
 298 value of the property.
 299 .SH RETURN VALUES
 300 .sp
 301 .LP
 302 All of the property update routines return:
 303 .sp
 304 .ne 2
 305 .na
 306 \fB\fBDDI_PROP_SUCCESS\fR \fR
 307 .ad
 308 .RS 27n
 309 On success.
 310 .RE
 311
 312 .sp
 313 .ne 2
 314 .na
 315 \fB\fBDDI_PROP_INVAL_ARG\fR \fR
 316 .ad
 317 .RS 27n
 318 If an attempt is made to update a property with \fIname\fR set to \fINULL\fR or
 319 \fIname\fR set to the null string.
 320 .RE
 321
 322 .sp
 323 .ne 2
 324 .na
 325 \fB\fBDDI_PROP_CANNOT_ENCODE\fR \fR
 326 .ad
 327 .RS 27n
 328 If the bytes of the property cannot be encoded.
 329 .RE
 330
 331 .SH CONTEXT
 332 .sp
 333 .LP
 334 These functions can only be called from user or kernel context.
 335 .SH EXAMPLES
 336 .LP
 337 \fBExample 1 \fRUpdating Properties
 338 .sp
 339 .LP
 340 The following example demonstrates the use of
 341 \fBddi_prop_update_int_array()\fR.
 342
 343 .sp
 344 .in +2
 345 .nf
 346 int     options[4];
 347
 348         /*
 349          * Create the "options" integer array with
 350          * our default values for these parameters
 351          */
 352         options[0] = XX_OPTIONS0;
 353         options[1] = XX_OPTIONS1;
 354         options[2] = XX_OPTIONS2;
 355         options[3] = XX_OPTIONS3;
 356         i = ddi_prop_update_int_array(xx_dev, xx_dip, "options",
 357                 &options, sizeof (options) / sizeof (int));
 358 .fi
 359 .in -2
 360
 361 .SH SEE ALSO
 362 .sp
 363 .LP
 364 \fBexecve\fR(2), \fBattach\fR(9E), \fBddi_prop_lookup\fR(9F),
 365 \fBddi_prop_remove\fR(9F), \fBmakedevice\fR(9F)
 366 .sp
 367 .LP
 368 \fIWriting Device Drivers\fR