path: root/usr/src/man/man9f/ldi_prop_lookup_int_array.9f

'\" te
.\" Copyright (c) 2003, Sun Microsystems, Inc.,  All Rights Reserved
.\" 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.
.\" 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.
.\" 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]
.TH LDI_PROP_LOOKUP_INT_ARRAY 9F "Jun 3, 2003"
.SH NAME
ldi_prop_lookup_int_array, ldi_prop_lookup_int64_array,
ldi_prop_lookup_string_array, ldi_prop_lookup_string,
ldi_prop_lookup_byte_array \- Lookup property information
.SH SYNOPSIS
.nf
#include <sys/sunldi.h>

\fBint\fR \fBldi_prop_lookup_int_array\fR(\fBldi_handle_t\fR \fIlh\fR, \fBuint_t\fR  \fIflags\fR, \fBchar *\fR\fIname\fR,
     \fBint **\fR\fIdatap\fR, \fBuint_t *\fR\fInelementsp\fR);
.fi

.LP
.nf
\fBint\fR \fBldi_prop_lookup_int64_array\fR(\fBldi_handle_t\fR \fIlh\fR, \fBuint_t\fR  \fIflags\fR, \fBchar *\fR\fIname\fR,
     \fBint64_t  **\fR\fIdatap\fR, \fBuint_t *\fR\fInelementsp\fR);
.fi

.LP
.nf
\fBint\fR \fBldi_prop_lookup_string_array\fR(\fBldi_handle_t\fR \fIlh\fR, \fBuint_t\fR  \fIflags\fR,
     \fBchar *\fR\fIname\fR, \fBchar ***\fR\fIdatap\fR, \fBuint_t *\fR\fInelementsp\fR);
.fi

.LP
.nf
\fBint\fR \fBldi_prop_lookup_string\fR(\fBldi_handle_t\fR \fIlh\fR, \fBuint_t\fR  \fIflags\fR, \fBchar *\fR\fIname\fR,
     \fBchar  **\fR\fIdatap\fR);
.fi

.LP
.nf
\fBint\fR \fBldi_prop_lookup_byte_array\fR(\fBldi_handle_t\fR \fIlh\fR, \fBuint_t\fR  \fIflags\fR, \fBchar *\fR\fIname\fR,
     \fBuchar_t **\fR\fIdatap\fR, \fBuint_t *\fR\fInelements\fR);
.fi

.SH PARAMETERS
.ne 2
.na
\fB\fIlh\fR\fR
.ad
.RS 9n
Layered handle.
.RE

.sp
.ne 2
.na
\fB\fIflags\fR\fR
.ad
.RS 9n
Possible flag values are some combination of:
.sp
.ne 2
.na
\fBLDI_DEV_T_ANY\fR
.ad
.RS 21n
Match the lookup request independent of the actual \fBdev_t\fR value that was
used when the property was created. The flag indicates any \fBdev_t\fR value
(including DDI_DEV_T_NONE) associated with a possible property match will
satisfy the matching criteria.
.RE

.sp
.ne 2
.na
\fBDDI_PROP_DONTPASS\fR
.ad
.RS 21n
Do not pass request to parent device information node if the property is not
found.
.RE

.sp
.ne 2
.na
\fBDDI_PROP_NOTPROM\fR
.ad
.RS 21n
Do not look at PROM properties (ignored on platforms that do not support PROM
properties).
.RE

.RE

.sp
.ne 2
.na
\fBname\fR
.ad
.RS 13n
String containing the property name.
.RE

.sp
.ne 2
.na
\fBnelements\fR
.ad
.RS 13n
The address of an unsigned integer which, upon successful return, contains the
number of elements accounted for in the memory pointed at by datap. Depending
on the interface you use, the elements are either integers, strings or bytes.
.RE

.sp
.LP
datap
.sp
.ne 2
.na
\fBldi_prop_lookup_int_array()\fR
.ad
.sp .6
.RS 4n
Pointer address to an array of integers which, upon successful return, point to
memory containing the integer array property value.
.RE

.sp
.ne 2
.na
\fBldi_prop_lookup_int64_array()\fR
.ad
.sp .6
.RS 4n
Pointer address to an array of 64-bit integers which, upon successful return,
point to memory containing the integer array property value.
.RE

.sp
.ne 2
.na
\fBldi_prop_lookup_string_array()\fR
.ad
.sp .6
.RS 4n
Pointer address to an array of strings which, upon successful return, point to
memory containing the array of strings. The string array is formatted as an
array of pointers to NULL terminated strings, much like the argv argument to
\fBexecve(2)\fR.
.RE

.sp
.ne 2
.na
\fBldi_prop_lookup_string()\fR
.ad
.sp .6
.RS 4n
Pointer address to a string which, upon successful return, points to memory
containing the NULL terminated string value of the property.
.RE

.sp
.ne 2
.na
\fBldi_prop_lookup_byte_array()\fR
.ad
.sp .6
.RS 4n
Pointer address to an array of bytes which, upon successful return, point to
memory containing the property byte array value.
.RE

.SH INTERFACE LEVEL
illumos DDI specific (illumos DDI).
.SH DESCRIPTION
The property look up functions search for and, if found, return the value of a
given property. Properties are searched for based on the dip and dev_t values
associated with the layered handle, the property name, and type of the data
(integer, string, or byte).
.sp
.LP
The property search order is as follows:
.RS +4
.TP
1.
Search software properties created by the driver.
.RE
.RS +4
.TP
2.
Search the software properties created by the system (or nexus nodes in the
device info tree).
.RE
.RS +4
.TP
3.
Search the driver global properties list.
.RE
.RS +4
.TP
4.
If DDI_PROP_NOTPROM is not set, search the PROM properties (if they exist).
.RE
.RS +4
.TP
5.
If DDI_PROP_DONTPASS is not set, pass this request to the parent device
information node of the device  represented by the layered handle.
.RE
.RS +4
.TP
6.
Return \fBDDI_PROP_NOT_FOUND\fR.
.RE
.sp
.LP
Typically, the specific dev_t value associated with the device represented by
the layered handle (ldi_handle_t) is used as a part of the property match
criteria. This association is handled by the layered driver infrastructure on
behalf of the consumers of the ldi property look up functions.
.sp
.LP
However, if the LDI_DEV_T_ANY flag is used, the ldi property lookup functions
match the request regardless of the dev_t value associated with the property at
the time of its creation. If a property was created with a dev_t set to
DDI_DEV_T_NONE, then the only way to look up this property is with the
LDI_DEV_T_ANY flag. PROM properties are always created with a dev_t set to
DDI_DEV_T_NONE.
.sp
.LP
name must always be set to the name of the property being looked up.
.sp
.LP
For the l\fBdi_prop_lookup_int_array()\fR, \fBldi_prop_lookup_int64_array()\fR,
\fBldi_prop_lookup_string_array()\fR, \fBldi_prop_lookup_string()\fR, and
\fBldi_prop_lookup_byte_array()\fR functions, datap is the address of a pointer
which, upon successful return, points to memory containing the value of the
property. In each case *datap points to a different type of property value. See
the individual descriptions of the functions below for details on the different
return values. nelementsp is the address of an unsigned integer which, upon
successful return, contains the number of integer, string or byte elements
accounted for in the memory pointed at by *datap.
.sp
.LP
All of the property look up functions may block to allocate memory needed to
hold the value of the property.
.sp
.LP
When a driver has obtained a property with any look up function and is finished
with that property, it must be freed by call \fBddi_prop_free()\fR.
\fBddi_prop_free()\fR must be called with the address of the allocated
property. For instance, if you call \fBldi_prop_lookup_int_array()\fR with
datap set to the address of a pointer to an integer, &my-int-ptr, the companion
free call is ddi_prop_free(my-int-ptr).
.sp
.LP
Property look up functions are described below:
.sp
.ne 2
.na
\fB\fBldi_prop_lookup_int_array()\fR\fR
.ad
.sp .6
.RS 4n
This function searches for and returns an array of integer property values.  An
array of integers is defined to *nelementsp number of 4 byte long integer
elements. datap should be set to the address of a pointer to an array of
integers which, upon successful return, will point to memory containing the
integer array value of the property.
.RE

.sp
.ne 2
.na
\fB\fBldi_prop_lookup_int64_array()\fR\fR
.ad
.sp .6
.RS 4n
This function searches for and returns an array of integer property values. An
array of integers is defined to *nelementsp number of 8 byte long integer
elements. datap should be set to the address of a pointer to an array of
integers which, upon successful return, will point to memory containing the
integer array value of the property This function does not search the PROM for
64-bit property values.
.RE

.sp
.ne 2
.na
\fB\fBldi_prop_lookup_string_array()\fR\fR
.ad
.sp .6
.RS 4n
This function searches for and returns a property that is an array of strings.
datap should be set to an address of a pointer to an array of strings which,
upon successful return, will point to memory containing the array of strings.
The array of strings is formatted as an array of pointers to null-terminated
strings, much like the argv argument to \fBexecve\fR(2).
.RE

.sp
.ne 2
.na
\fB\fBldi_prop_lookup_string()\fR\fR
.ad
.sp .6
.RS 4n
This function searches for and returns a property that is a null-terminated
string. datap should be set to the address of a pointer to a string which, upon
successful return, points to memory containing the string value of the
property.
.RE

.sp
.ne 2
.na
\fB\fBldi_prop_lookup_byte_array()\fR\fR
.ad
.sp .6
.RS 4n
This function searches for and returns a property that is an array of bytes.
datap should be set to the address of a pointer to an array of bytes which,
upon    successful return, points to memory containing the byte array value of
the property.
.RE

.sp
.ne 2
.na
\fB\fBddi_prop_free()\fR\fR
.ad
.sp .6
.RS 4n
Frees the resources associated with a property previously      allocated using
\fBldi_prop_lookup_int_array()\fR, \fBldi_prop_lookup_int64_array()\fR,
\fBldi_prop_lookup_string_array()\fR, \fBldi_prop_lookup_string()\fR, and
\fBldi_prop_lookup_byte_array()\fR.
.RE

.SH RETURN VALUES
The functions \fBldi_prop_lookup_int_array()\fR,
\fBldi_prop_lookup_int64_array()\fR, \fBldi_prop_lookup_string_array()\fR,
\fBldi_prop_lookup_string()\fR, and \fBldi_prop_lookup_byte_array()\fR return
the following values:
.sp
.ne 2
.na
\fBDDI_PROP_SUCCESS\fR
.ad
.RS 26n
Property found and returned.
.RE

.sp
.ne 2
.na
\fBDDI_PROP_INVAL_ARG\fR
.ad
.RS 26n
If an attempt is made to look up a property with a NULL ldi handle, name is
NULL or name is a the null string.
.RE

.sp
.ne 2
.na
\fBDDI_PROP_NOT_FOUND\fR
.ad
.RS 26n
Property not found.
.RE

.sp
.ne 2
.na
\fBDDI_PROP_UNDEFINED\fR
.ad
.RS 26n
Prop explicitly undefined (see \fBddi_prop_undefine(9F\fR)).
.RE

.sp
.ne 2
.na
\fBDDI_PROP_CANNOT_DECODE\fR
.ad
.RS 26n
Property value cannot be decoded.
.RE

.SH CONTEXT
These functions may be called from user or kernel context.
.SH EXAMPLE
.in +2
.nf
Using ldi_prop_lookup_int64_array().

       The following example demonstrates the use of
       ldi_prop_lookup_int64_array().


       int64_t *options;
       uint_t  noptions;

       /*
        * Get the data associated with the integer "options" property
        * array, along with the number of option integers
        */

       if  (ldi_prop_lookup_int64_array(lh,
           LDI_DEV_T_ANY|DDI_PROP_NOTPROM, "options",
           &options, &noptions) == DDI_PROP_SUCCESS) {
              /*
                 * Process the options data from the property
                * we just received. Let's do "our thing" with data.
                */
               xx_process_options(options, noptions);

               /*
                * Free the memory allocated for the property data
                */
               ddi_prop_free(options);
       }
.fi
.in -2

.SH SEE ALSO
\fBexecve\fR(2), \fBddi_prop_free\fR(9F), \fBddi_prop_lookup\fR(9F),
\fBldi_prop_exists\fR(9F) .
.sp
.LP
\fIWriting Device Drivers\fR