'\" te
.\" Copyright (c) 2001, 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 ddi_prop_lookup 9F "11 Apr 2001" "SunOS 5.11" "Kernel Functions for Drivers"
.SH NAME
ddi_prop_lookup, ddi_prop_lookup_int_array, ddi_prop_lookup_int64_array,
ddi_prop_lookup_string_array, ddi_prop_lookup_string,
ddi_prop_lookup_byte_array, ddi_prop_free \- look up property information
.SH SYNOPSIS
.LP
.nf
#include <sys/ddi.h>
#include <sys/sunddi.h>



\fBint\fR \fBddi_prop_lookup_int_array\fR(\fBdev_t\fR \fImatch_dev\fR, \fBdev_info_t *\fR\fIdip\fR, 
     \fBuint_t\fR \fIflags\fR, \fBchar *\fR\fIname\fR, \fBint **\fR\fIdatap\fR, \fBuint_t *\fR\fInelementsp\fR);
.fi

.LP
.nf
\fBint\fR \fBddi_prop_lookup_int64_array\fR(\fBdev_t\fR \fImatch_dev\fR, \fBdev_info_t *\fR\fIdip\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 \fBddi_prop_lookup_string_array\fR(\fBdev_t\fR \fImatch_dev\fR, \fBdev_info_t *\fR\fIdip\fR,
     \fBuint_t\fR \fIflags\fR, \fBchar *\fR\fIname\fR, \fBchar ***\fR\fIdatap\fR, \fBuint_t *\fR\fInelementsp\fR);
.fi

.LP
.nf
\fBint\fR \fBddi_prop_lookup_string\fR(\fBdev_t\fR \fImatch_dev\fR, \fBdev_info_t *\fR\fIdip\fR, \fBuint_t\fR \fIflags\fR,
     \fBchar *\fR\fIname\fR, \fBchar **\fR\fIdatap\fR);
.fi

.LP
.nf
\fBint\fR \fBddi_prop_lookup_byte_array\fR(\fBdev_t\fR \fImatch_dev\fR, \fBdev_info_t *\fR\fIdip\fR, 
     \fBuint_t\fR \fIflags\fR, \fBchar *\fR\fIname\fR, \fBuchar_t **\fR\fIdatap\fR, \fBuint_t *\fR\fInelementsp\fR);
.fi

.LP
.nf
\fBvoid\fR \fBddi_prop_free\fR(\fBvoid *\fR\fIdata\fR);
.fi

.SH PARAMETERS
.sp
.ne 2
.mk
.na
\fB\fImatch_dev\fR\fR
.ad
.RS 14n
.rt  
Device number associated with property or \fBDDI_DEV_T_ANY.\fR
.RE

.sp
.ne 2
.mk
.na
\fB\fIdip\fR\fR
.ad
.RS 14n
.rt  
Pointer to the device info node of device whose property list should be
searched.
.RE

.sp
.ne 2
.mk
.na
\fB\fIflags\fR\fR
.ad
.RS 14n
.rt  
Possible flag values are some combination of:
.sp
.ne 2
.mk
.na
\fB\fBDDI_PROP_DONTPASS\fR\fR
.ad
.RS 21n
.rt  
Do not pass request to parent device information node if the property is not
found.
.RE

.sp
.ne 2
.mk
.na
\fB\fBDDI_PROP_NOTPROM\fR\fR
.ad
.RS 21n
.rt  
Do not look at \fBPROM \fRproperties (ignored on platforms that do not support
\fBPROM \fRproperties).
.RE

.RE

.sp
.ne 2
.mk
.na
\fB\fIname\fR\fR
.ad
.RS 14n
.rt  
String containing the name of the property.
.RE

.sp
.ne 2
.mk
.na
\fB\fInelementsp\fR\fR
.ad
.RS 14n
.rt  
The address of an unsigned integer which, upon successful return, will contain
the number of elements accounted for in the memory pointed at by \fIdatap\fR.
The elements are either integers, strings or bytes depending on the interface
used.
.RE

.sp
.ne 2
.mk
.na
\fB\fIdatap\fR\fR
.ad
.RS 14n
.rt  
.sp
.ne 2
.mk
.na
\fB\fBddi_prop_lookup_int_array()\fR\fR
.ad
.sp .6
.RS 4n
The address of a pointer to an array of integers which, upon successful return,
will point to memory containing the integer array property value.
.RE

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

.sp
.ne 2
.mk
.na
\fB\fBddi_prop_lookup_string_array()\fR\fR
.ad
.sp .6
.RS 4n
The 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 \fBNULL \fRterminated strings, much like
the \fIargv\fR argument to \fBexecve\fR(2).
.RE

.sp
.ne 2
.mk
.na
\fB\fBddi_prop_lookup_string()\fR\fR
.ad
.sp .6
.RS 4n
The address of a pointer to a string which, upon successful return, will point
to memory containing the \fBNULL \fRterminated string value of the property.
.RE

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

.RE

.SH INTERFACE LEVEL
.sp
.LP
Solaris DDI specific (Solaris DDI).
.SH DESCRIPTION
.sp
.LP
The property look up routines search for and, if found, return the value of a
given property. Properties are searched for based on the \fIdip\fR, \fIname\fR,
\fImatch_dev\fR, and the type of the data (integer, string, or byte). 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 \fBDDI_PROP_NOTPROM\fR is not set, search the \fBPROM \fRproperties (if
they exist).
.RE
.RS +4
.TP
5.
If \fBDDI_PROP_DONTPASS\fR is not set, pass this request to the parent
device information node.
.RE
.RS +4
.TP
6.
Return \fBDDI_PROP_NOT_FOUND\fR.
.RE
.sp
.LP
Usually, the \fImatch_dev\fR argument should be set to the actual device number
that this property is associated with. However, if the \fImatch_dev\fR argument
is \fBDDI_DEV_T_ANY\fR, the property look up routines will match the request
regardless of the actual \fImatch_dev\fR the property was created with. If a
property was created with \fImatch_dev\fR set to \fBDDI_DEV_T_NONE\fR, then the
only way to look up this property is with a \fImatch_dev\fR set to
\fBDDI_DEV_T_ANY\fR. \fBPROM \fRproperties are always created with
\fImatch_dev\fR set to \fBDDI_DEV_T_NONE\fR.
.sp
.LP
\fIname\fR must always be set to the name of the property being looked up.
.sp
.LP
For the routines \fBddi_prop_lookup_int_array()\fR,
\fBddi_prop_lookup_int64_array()\fR, \fBddi_prop_lookup_string_array()\fR,
\fBddi_prop_lookup_string()\fR, and \fBddi_prop_lookup_byte_array()\fR,
\fIdatap\fR is the address of a pointer which, upon successful return, will
point to memory containing the value of the property. In each case \fI*datap\fR
points to a different type of property value. See the individual descriptions
of the routines below for details on the different return values.
\fInelementsp\fR is the address of an unsigned integer which, upon successful
return, will contain the number of integer, string or byte elements accounted
for in the memory pointed at by \fI*datap\fR.
.sp
.LP
All of the property look up routines 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 routine and is finished
with that property, it must be freed by calling \fBddi_prop_free()\fR.
\fBddi_prop_free()\fR must be called with the address of the allocated
property. For instance, if one called \fBddi_prop_lookup_int_array()\fR with
\fIdatap\fR set to the address of a pointer to an integer, \fI&my_int_ptr\fR,
then the companion free call would be
\fBddi_prop_free(\fR\fImy_int_ptr\fR\fB)\fR.
.sp
.ne 2
.mk
.na
\fB\fBddi_prop_lookup_int_array()\fR\fR
.ad
.sp .6
.RS 4n
This routine searches for and returns an array of integer property values. An
array of integers is defined to \fI*nelementsp\fR number of 4 byte long integer
elements. \fIdatap\fR 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
.mk
.na
\fB\fBddi_prop_lookup_int64_array()\fR\fR
.ad
.sp .6
.RS 4n
This routine searches for and returns an array of 64-bit integer property
values. The array is defined to be *\fInelementsp\fR number of \fBint64_t\fR
elements. \fIdatap\fR should be set to the address of a pointer to an array of
\fBint64_t\fR's which, upon successful return, will point to memory containing
the integer array value of the property. This routine will not search the PROM
for 64-bit property values.
.RE

.sp
.ne 2
.mk
.na
\fB\fBddi_prop_lookup_string_array()\fR\fR
.ad
.sp .6
.RS 4n
This routine searches for and returns a property that is an array of strings.
\fIdatap\fR should be set to 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 \fIargv\fR argument to \fBexecve\fR(2).
.RE

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

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

.sp
.ne 2
.mk
.na
\fB\fBddi_prop_free()\fR\fR
.ad
.sp .6
.RS 4n
Frees the resources associated with a property previously allocated using
\fBddi_prop_lookup_int_array()\fR, \fBddi_prop_lookup_int64_array()\fR,
\fBddi_prop_lookup_string_array()\fR, \fBddi_prop_lookup_string()\fR, or
\fBddi_prop_lookup_byte_array()\fR.
.RE

.SH RETURN VALUES
.sp
.LP
The functions \fBddi_prop_lookup_int_array()\fR,
\fBddi_prop_lookup_int64_array()\fR, \fBddi_prop_lookup_string_array()\fR,
\fBddi_prop_lookup_string()\fR, and \fBddi_prop_lookup_byte_array()\fR return
the following values:
.sp
.ne 2
.mk
.na
\fB\fBDDI_PROP_SUCCESS\fR\fR
.ad
.RS 26n
.rt  
Upon success.
.RE

.sp
.ne 2
.mk
.na
\fB\fBDDI_PROP_INVAL_ARG\fR\fR
.ad
.RS 26n
.rt  
If an attempt is made to look up a property with \fImatch_dev\fR equal to
\fBDDI_DEV_T_NONE\fR, \fIname\fR is \fBNULL \fRor \fIname\fR is the null
string.
.RE

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

.sp
.ne 2
.mk
.na
\fB\fBDDI_PROP_UNDEFINED\fR\fR
.ad
.RS 26n
.rt  
Property explicitly not defined (see \fBddi_prop_undefine\fR(9F)).
.RE

.sp
.ne 2
.mk
.na
\fB\fBDDI_PROP_CANNOT_DECODE\fR\fR
.ad
.RS 26n
.rt  
The value of the property cannot be decoded.
.RE

.SH CONTEXT
.sp
.LP
These functions can be called from user or kernel context.
.SH EXAMPLES
.LP
\fBExample 1 \fRUsing \fBddi_prop_lookup_int_array()\fR
.sp
.LP
The following example demonstrates the use of
\fBddi_prop_lookup_int_array()\fR.

.sp
.in +2
.nf
	
int	*options;
int	noptions;

/*
 * Get the data associated with the integer "options" property
 * array, along with the number of option integers
 */
	if (ddi_prop_lookup_int_array(DDI_DEV_T_ANY, xx_dip, 0,
     "options", &options, &noptions) == DDI_PROP_SUCCESS) {
     /*
     * Do "our thing" with the options data from the property
     */
     xx_process_options(options, noptions);

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

.SH SEE ALSO
.sp
.LP
\fBexecve\fR(2), \fBddi_prop_exists\fR(9F), \fBddi_prop_get_int\fR(9F),
\fBddi_prop_remove\fR(9F), \fBddi_prop_undefine\fR(9F),
\fBddi_prop_update\fR(9F)
.sp
.LP
\fIWriting Device Drivers\fR