share/man/man9f/ddi_prop_lookup.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_LOOKUP 9F "Apr 11, 2001"
   7 .SH NAME
   8 ddi_prop_lookup, ddi_prop_lookup_int_array, ddi_prop_lookup_int64_array,
   9 ddi_prop_lookup_string_array, ddi_prop_lookup_string,
  10 ddi_prop_lookup_byte_array, ddi_prop_free \- look up property information
  11 .SH SYNOPSIS
  12 .LP
  13 .nf
  14 #include <sys/ddi.h>
  15 #include <sys/sunddi.h>
  16
  17
  18
  19 \fBint\fR \fBddi_prop_lookup_int_array\fR(\fBdev_t\fR \fImatch_dev\fR, \fBdev_info_t *\fR\fIdip\fR,
  20      \fBuint_t\fR \fIflags\fR, \fBchar *\fR\fIname\fR, \fBint **\fR\fIdatap\fR, \fBuint_t *\fR\fInelementsp\fR);
  21 .fi
  22
  23 .LP
  24 .nf
  25 \fBint\fR \fBddi_prop_lookup_int64_array\fR(\fBdev_t\fR \fImatch_dev\fR, \fBdev_info_t *\fR\fIdip\fR,
  26      \fBuint_t\fR \fIflags\fR, \fBchar *\fR\fIname\fR, \fBint64_t **\fR\fIdatap\fR, \fBuint_t *\fR\fInelementsp\fR);
  27 .fi
  28
  29 .LP
  30 .nf
  31 \fBint\fR \fBddi_prop_lookup_string_array\fR(\fBdev_t\fR \fImatch_dev\fR, \fBdev_info_t *\fR\fIdip\fR,
  32      \fBuint_t\fR \fIflags\fR, \fBchar *\fR\fIname\fR, \fBchar ***\fR\fIdatap\fR, \fBuint_t *\fR\fInelementsp\fR);
  33 .fi
  34
  35 .LP
  36 .nf
  37 \fBint\fR \fBddi_prop_lookup_string\fR(\fBdev_t\fR \fImatch_dev\fR, \fBdev_info_t *\fR\fIdip\fR, \fBuint_t\fR \fIflags\fR,
  38      \fBchar *\fR\fIname\fR, \fBchar **\fR\fIdatap\fR);
  39 .fi
  40
  41 .LP
  42 .nf
  43 \fBint\fR \fBddi_prop_lookup_byte_array\fR(\fBdev_t\fR \fImatch_dev\fR, \fBdev_info_t *\fR\fIdip\fR,
  44      \fBuint_t\fR \fIflags\fR, \fBchar *\fR\fIname\fR, \fBuchar_t **\fR\fIdatap\fR, \fBuint_t *\fR\fInelementsp\fR);
  45 .fi
  46
  47 .LP
  48 .nf
  49 \fBvoid\fR \fBddi_prop_free\fR(\fBvoid *\fR\fIdata\fR);
  50 .fi
  51
  52 .SH PARAMETERS
  53 .sp
  54 .ne 2
  55 .na
  56 \fB\fImatch_dev\fR\fR
  57 .ad
  58 .RS 14n
  59 Device number associated with property or \fBDDI_DEV_T_ANY.\fR
  60 .RE
  61
  62 .sp
  63 .ne 2
  64 .na
  65 \fB\fIdip\fR\fR
  66 .ad
  67 .RS 14n
  68 Pointer to the device info node of device whose property list should be
  69 searched.
  70 .RE
  71
  72 .sp
  73 .ne 2
  74 .na
  75 \fB\fIflags\fR\fR
  76 .ad
  77 .RS 14n
  78 Possible flag values are some combination of:
  79 .sp
  80 .ne 2
  81 .na
  82 \fB\fBDDI_PROP_DONTPASS\fR\fR
  83 .ad
  84 .RS 21n
  85 Do not pass request to parent device information node if the property is not
  86 found.
  87 .RE
  88
  89 .sp
  90 .ne 2
  91 .na
  92 \fB\fBDDI_PROP_NOTPROM\fR\fR
  93 .ad
  94 .RS 21n
  95 Do not look at \fBPROM \fRproperties (ignored on platforms that do not support
  96 \fBPROM \fRproperties).
  97 .RE
  98
  99 .RE
 100
 101 .sp
 102 .ne 2
 103 .na
 104 \fB\fIname\fR\fR
 105 .ad
 106 .RS 14n
 107 String containing the name of the property.
 108 .RE
 109
 110 .sp
 111 .ne 2
 112 .na
 113 \fB\fInelementsp\fR\fR
 114 .ad
 115 .RS 14n
 116 The address of an unsigned integer which, upon successful return, will contain
 117 the number of elements accounted for in the memory pointed at by \fIdatap\fR.
 118 The elements are either integers, strings or bytes depending on the interface
 119 used.
 120 .RE
 121
 122 .sp
 123 .ne 2
 124 .na
 125 \fB\fIdatap\fR\fR
 126 .ad
 127 .RS 14n
 128 .sp
 129 .ne 2
 130 .na
 131 \fB\fBddi_prop_lookup_int_array()\fR\fR
 132 .ad
 133 .sp .6
 134 .RS 4n
 135 The address of a pointer to an array of integers which, upon successful return,
 136 will point to memory containing the integer array property value.
 137 .RE
 138
 139 .sp
 140 .ne 2
 141 .na
 142 \fB\fBddi_prop_lookup_int64_array()\fR\fR
 143 .ad
 144 .sp .6
 145 .RS 4n
 146 The address of a pointer to an array of 64-bit integers which, upon successful
 147 return, will point to memory containing the integer array property value.
 148 .RE
 149
 150 .sp
 151 .ne 2
 152 .na
 153 \fB\fBddi_prop_lookup_string_array()\fR\fR
 154 .ad
 155 .sp .6
 156 .RS 4n
 157 The address of a pointer to an array of strings which, upon successful return,
 158 will point to memory containing the array of strings. The array of strings is
 159 formatted as an array of pointers to \fBNULL \fRterminated strings, much like
 160 the \fIargv\fR argument to \fBexecve\fR(2).
 161 .RE
 162
 163 .sp
 164 .ne 2
 165 .na
 166 \fB\fBddi_prop_lookup_string()\fR\fR
 167 .ad
 168 .sp .6
 169 .RS 4n
 170 The address of a pointer to a string which, upon successful return, will point
 171 to memory containing the \fBNULL \fRterminated string value of the property.
 172 .RE
 173
 174 .sp
 175 .ne 2
 176 .na
 177 \fB\fBddi_prop_lookup_byte_array()\fR\fR
 178 .ad
 179 .sp .6
 180 .RS 4n
 181 The address of pointer to an array of bytes which, upon successful return, will
 182 point to memory containing the byte array value of the property.
 183 .RE
 184
 185 .RE
 186
 187 .SH INTERFACE LEVEL
 188 .sp
 189 .LP
 190 Solaris DDI specific (Solaris DDI).
 191 .SH DESCRIPTION
 192 .sp
 193 .LP
 194 The property look up routines search for and, if found, return the value of a
 195 given property. Properties are searched for based on the \fIdip\fR, \fIname\fR,
 196 \fImatch_dev\fR, and the type of the data (integer, string, or byte). The
 197 property search order is as follows:
 198 .RS +4
 199 .TP
 200 1.
 201 Search software properties created by the driver.
 202 .RE
 203 .RS +4
 204 .TP
 205 2.
 206 Search the software properties created by the system (or nexus nodes in the
 207 device info tree).
 208 .RE
 209 .RS +4
 210 .TP
 211 3.
 212 Search the driver global properties list.
 213 .RE
 214 .RS +4
 215 .TP
 216 4.
 217 If \fBDDI_PROP_NOTPROM\fR is not set, search the \fBPROM \fRproperties (if
 218 they exist).
 219 .RE
 220 .RS +4
 221 .TP
 222 5.
 223 If \fBDDI_PROP_DONTPASS\fR is not set, pass this request to the parent
 224 device information node.
 225 .RE
 226 .RS +4
 227 .TP
 228 6.
 229 Return \fBDDI_PROP_NOT_FOUND\fR.
 230 .RE
 231 .sp
 232 .LP
 233 Usually, the \fImatch_dev\fR argument should be set to the actual device number
 234 that this property is associated with. However, if the \fImatch_dev\fR argument
 235 is \fBDDI_DEV_T_ANY\fR, the property look up routines will match the request
 236 regardless of the actual \fImatch_dev\fR the property was created with. If a
 237 property was created with \fImatch_dev\fR set to \fBDDI_DEV_T_NONE\fR, then the
 238 only way to look up this property is with a \fImatch_dev\fR set to
 239 \fBDDI_DEV_T_ANY\fR. \fBPROM \fRproperties are always created with
 240 \fImatch_dev\fR set to \fBDDI_DEV_T_NONE\fR.
 241 .sp
 242 .LP
 243 \fIname\fR must always be set to the name of the property being looked up.
 244 .sp
 245 .LP
 246 For the routines \fBddi_prop_lookup_int_array()\fR,
 247 \fBddi_prop_lookup_int64_array()\fR, \fBddi_prop_lookup_string_array()\fR,
 248 \fBddi_prop_lookup_string()\fR, and \fBddi_prop_lookup_byte_array()\fR,
 249 \fIdatap\fR is the address of a pointer which, upon successful return, will
 250 point to memory containing the value of the property. In each case \fI*datap\fR
 251 points to a different type of property value. See the individual descriptions
 252 of the routines below for details on the different return values.
 253 \fInelementsp\fR is the address of an unsigned integer which, upon successful
 254 return, will contain the number of integer, string or byte elements accounted
 255 for in the memory pointed at by \fI*datap\fR.
 256 .sp
 257 .LP
 258 All of the property look up routines may block to allocate memory needed to
 259 hold the value of the property.
 260 .sp
 261 .LP
 262 When a driver has obtained a property with any look up routine and is finished
 263 with that property, it must be freed by calling \fBddi_prop_free()\fR.
 264 \fBddi_prop_free()\fR must be called with the address of the allocated
 265 property. For instance, if one called \fBddi_prop_lookup_int_array()\fR with
 266 \fIdatap\fR set to the address of a pointer to an integer, \fI&my_int_ptr\fR,
 267 then the companion free call would be
 268 \fBddi_prop_free(\fR\fImy_int_ptr\fR\fB)\fR.
 269 .sp
 270 .ne 2
 271 .na
 272 \fB\fBddi_prop_lookup_int_array()\fR\fR
 273 .ad
 274 .sp .6
 275 .RS 4n
 276 This routine searches for and returns an array of integer property values. An
 277 array of integers is defined to \fI*nelementsp\fR number of 4 byte long integer
 278 elements. \fIdatap\fR should be set to the address of a pointer to an array of
 279 integers which, upon successful return, will point to memory containing the
 280 integer array value of the property.
 281 .RE
 282
 283 .sp
 284 .ne 2
 285 .na
 286 \fB\fBddi_prop_lookup_int64_array()\fR\fR
 287 .ad
 288 .sp .6
 289 .RS 4n
 290 This routine searches for and returns an array of 64-bit integer property
 291 values. The array is defined to be *\fInelementsp\fR number of \fBint64_t\fR
 292 elements. \fIdatap\fR should be set to the address of a pointer to an array of
 293 \fBint64_t\fR's which, upon successful return, will point to memory containing
 294 the integer array value of the property. This routine will not search the PROM
 295 for 64-bit property values.
 296 .RE
 297
 298 .sp
 299 .ne 2
 300 .na
 301 \fB\fBddi_prop_lookup_string_array()\fR\fR
 302 .ad
 303 .sp .6
 304 .RS 4n
 305 This routine searches for and returns a property that is an array of strings.
 306 \fIdatap\fR should be set to address of a pointer to an array of strings which,
 307 upon successful return, will point to memory containing the array of strings.
 308 The array of strings is formatted as an array of pointers to null-terminated
 309 strings, much like the \fIargv\fR argument to \fBexecve\fR(2).
 310 .RE
 311
 312 .sp
 313 .ne 2
 314 .na
 315 \fB\fBddi_prop_lookup_string()\fR\fR
 316 .ad
 317 .sp .6
 318 .RS 4n
 319 This routine searches for and returns a property that is a null-terminated
 320 string. \fIdatap\fR should be set to the address of a pointer to string which,
 321 upon successful return, will point to memory containing the string value of the
 322 property.
 323 .RE
 324
 325 .sp
 326 .ne 2
 327 .na
 328 \fB\fBddi_prop_lookup_byte_array()\fR\fR
 329 .ad
 330 .sp .6
 331 .RS 4n
 332 This routine searches for and returns a property that is an array of bytes.
 333 \fIdatap\fR should be set to the address of a pointer to an array of bytes
 334 which, upon successful return, will point to memory containing the byte array
 335 value of the property.
 336 .RE
 337
 338 .sp
 339 .ne 2
 340 .na
 341 \fB\fBddi_prop_free()\fR\fR
 342 .ad
 343 .sp .6
 344 .RS 4n
 345 Frees the resources associated with a property previously allocated using
 346 \fBddi_prop_lookup_int_array()\fR, \fBddi_prop_lookup_int64_array()\fR,
 347 \fBddi_prop_lookup_string_array()\fR, \fBddi_prop_lookup_string()\fR, or
 348 \fBddi_prop_lookup_byte_array()\fR.
 349 .RE
 350
 351 .SH RETURN VALUES
 352 .sp
 353 .LP
 354 The functions \fBddi_prop_lookup_int_array()\fR,
 355 \fBddi_prop_lookup_int64_array()\fR, \fBddi_prop_lookup_string_array()\fR,
 356 \fBddi_prop_lookup_string()\fR, and \fBddi_prop_lookup_byte_array()\fR return
 357 the following values:
 358 .sp
 359 .ne 2
 360 .na
 361 \fB\fBDDI_PROP_SUCCESS\fR\fR
 362 .ad
 363 .RS 26n
 364 Upon success.
 365 .RE
 366
 367 .sp
 368 .ne 2
 369 .na
 370 \fB\fBDDI_PROP_INVAL_ARG\fR\fR
 371 .ad
 372 .RS 26n
 373 If an attempt is made to look up a property with \fImatch_dev\fR equal to
 374 \fBDDI_DEV_T_NONE\fR, \fIname\fR is \fBNULL \fRor \fIname\fR is the null
 375 string.
 376 .RE
 377
 378 .sp
 379 .ne 2
 380 .na
 381 \fB\fBDDI_PROP_NOT_FOUND\fR\fR
 382 .ad
 383 .RS 26n
 384 Property not found.
 385 .RE
 386
 387 .sp
 388 .ne 2
 389 .na
 390 \fB\fBDDI_PROP_UNDEFINED\fR\fR
 391 .ad
 392 .RS 26n
 393 Property explicitly not defined (see \fBddi_prop_undefine\fR(9F)).
 394 .RE
 395
 396 .sp
 397 .ne 2
 398 .na
 399 \fB\fBDDI_PROP_CANNOT_DECODE\fR\fR
 400 .ad
 401 .RS 26n
 402 The value of the property cannot be decoded.
 403 .RE
 404
 405 .SH CONTEXT
 406 .sp
 407 .LP
 408 These functions can be called from user or kernel context.
 409 .SH EXAMPLES
 410 .LP
 411 \fBExample 1 \fRUsing \fBddi_prop_lookup_int_array()\fR
 412 .sp
 413 .LP
 414 The following example demonstrates the use of
 415 \fBddi_prop_lookup_int_array()\fR.
 416
 417 .sp
 418 .in +2
 419 .nf
 420
 421 int     *options;
 422 int     noptions;
 423
 424 /*
 425  * Get the data associated with the integer "options" property
 426  * array, along with the number of option integers
 427  */
 428         if (ddi_prop_lookup_int_array(DDI_DEV_T_ANY, xx_dip, 0,
 429      "options", &options, &noptions) == DDI_PROP_SUCCESS) {
 430      /*
 431      * Do "our thing" with the options data from the property
 432      */
 433      xx_process_options(options, noptions);
 434
 435      /*
 436       * Free the memory allocated for the property data
 437       */
 438      ddi_prop_free(options);
 439 }
 440 .fi
 441 .in -2
 442
 443 .SH SEE ALSO
 444 .sp
 445 .LP
 446 \fBexecve\fR(2), \fBddi_prop_exists\fR(9F), \fBddi_prop_get_int\fR(9F),
 447 \fBddi_prop_remove\fR(9F), \fBddi_prop_undefine\fR(9F),
 448 \fBddi_prop_update\fR(9F)
 449 .sp
 450 .LP
 451 \fIWriting Device Drivers\fR