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

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