ddi_prop_lookup(9F)
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
SYNOPSIS
#include <sys/ddi.h>
#include <sys/sunddi.h>
int ddi_prop_lookup_int_array(dev_t match_dev, dev_info_t
*dip, uint_t flags, char *name, int **datap, uint_t
*nelementsp);
int ddi_prop_lookup_int64_array(dev_t match_dev, dev_info_t
*dip, uint_t flags, char *name, int64_t **datap, uint_t
*nelementsp);
int ddi_prop_lookup_string_array(dev_t match_dev, dev_info_t
*dip, uint_t flags, char *name, char ***datap, uint_t
*nelementsp);
int ddi_prop_lookup_string(dev_t match_dev, dev_info_t *dip,
uint_t flags, char *name, char **datap);
int ddi_prop_lookup_byte_array(dev_t match_dev, dev_info_t
*dip, uint_t flags, char *name, uchar_t **datap, uint_t
*nelementsp);
void ddi_prop_free(void *data);
PARAMETERS
match_dev
Device number associated with property or
DDI_DEV_T_ANY.
dip Pointer to the device info node of device whose pro-
perty list should be searched.
flags Possible flag values are some combination of:
DDI_PROP_DONTPASS
Do not pass request to parent device information
node if the property is not found.
DDI_PROP_NOTPROM
Do not look at PROM properties (ignored on plat-
forms that do not support PROM properties).
name String containing the name of the property.
nelementsp
The address of an unsigned integer which, upon suc-
cessful return, will contain the number of elements
accounted for in the memory pointed at by datap. The
elements are either integers, strings or bytes depend-
ing on the interface used.
datap
ddi_prop_lookup_int_array()
The address of a pointer to an array of integers
which, upon successful return, will point to
memory containing the integer array property
value.
ddi_prop_lookup_int64_array()
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.
ddi_prop_lookup_string_array()
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 NULL terminated strings, much like
the argv argument to execve(2).
ddi_prop_lookup_string()
The address of a pointer to a string which, upon
successful return, will point to memory contain-
ing the NULL terminated string value of the pro-
perty.
ddi_prop_lookup_byte_array()
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.
INTERFACE LEVEL
Solaris DDI specific (Solaris DDI).
DESCRIPTION
The property look up routines search for and, if found,
return the value of a given property. Properties are
searched for based on the dip, name, match_dev, and the type
of the data (integer, string, or byte). The property search
order is as follows:
1. Search software properties created by the driver.
2. Search the software properties created by the system (or
nexus nodes in the device info tree).
3. Search the driver global properties list.
4. If DDI_PROP_NOTPROM is not set, search the PROM proper-
ties (if they exist).
5. If DDI_PROP_DONTPASS is not set, pass this request to the
parent device information node.
6. Return DDI_PROP_NOT_FOUND.
Usually, the match_dev argument should be set to the actual
device number that this property is associated with. How-
ever, if the match_dev argument is DDI_DEV_T_ANY, the pro-
perty look up routines will match the request regardless of
the actual match_dev the property was created with. If a
property was created with match_dev set to DDI_DEV_T_NONE,
then the only way to look up this property is with a
match_dev set to DDI_DEV_T_ANY. PROM properties are always
created with match_dev set to DDI_DEV_T_NONE.
name must always be set to the name of the property being
looked up.
For the routines ddi_prop_lookup_int_array(),
ddi_prop_lookup_int64_array(),
ddi_prop_lookup_string_array(), ddi_prop_lookup_string(),
and ddi_prop_lookup_byte_array(), datap is the address of a
pointer which, upon successful return, will point to memory
containing the value of the property. In each case *datap
points to a different type of property value. See the indi-
vidual descriptions of the routines below for details on the
different return values. nelementsp 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 *datap.
All of the property look up routines may block to allocate
memory needed to hold the value of the property.
When a driver has obtained a property with any look up rou-
tine and is finished with that property, it must be freed by
calling ddi_prop_free(). ddi_prop_free() must be called with
the address of the allocated property. For instance, if one
called ddi_prop_lookup_int_array() with datap set to the
address of a pointer to an integer, &my_int_ptr, then the
companion free call would be ddi_prop_free(my_int_ptr).
ddi_prop_lookup_int_array()
This routine 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.
ddi_prop_lookup_int64_array()
This routine searches for and returns an array of 64-
bit integer property values. The array is defined to
be *nelementsp number of int64_t elements. datap
should be set to the address of a pointer to an array
of int64_t'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.
ddi_prop_lookup_string_array()
This routine searches for and returns a property that
is an array of strings. datap should be set to address
of a pointer to an array of strings which, upon suc-
cessful 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 execve(2).
ddi_prop_lookup_string()
This routine searches for and returns a property that
is a null-terminated string. datap should be set to
the address of a pointer to string which, upon suc-
cessful return, will point to memory containing the
string value of the property.
ddi_prop_lookup_byte_array()
This routine 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, will point to memory containing the
byte array value of the property.
ddi_prop_free()
Frees the resources associated with a property previ-
ously allocated using ddi_prop_lookup_int_array(),
ddi_prop_lookup_int64_array(),
ddi_prop_lookup_string_array(),
ddi_prop_lookup_string(), or
ddi_prop_lookup_byte_array().
RETURN VALUES
The functions ddi_prop_lookup_int_array(),
ddi_prop_lookup_int64_array(),
ddi_prop_lookup_string_array(), ddi_prop_lookup_string(),
and ddi_prop_lookup_byte_array() return the following
values:
DDI_PROP_SUCCESS
Upon success.
DDI_PROP_INVAL_ARG
If an attempt is made to look up a property with
match_dev equal to DDI_DEV_T_NONE, name is NULL
or name is the null string.
DDI_PROP_NOT_FOUND
Property not found.
DDI_PROP_UNDEFINED
Property explicitly not defined (see
ddi_prop_undefine(9F)).
DDI_PROP_CANNOT_DECODE
The value of the property cannot be decoded.
CONTEXT
These functions can be called from user or kernel context.
EXAMPLES
Example 1: Using ddi_prop_lookup_int_array()
The following example demonstrates the use of
ddi_prop_lookup_int_array().
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);
}
SEE ALSO
execve(2), ddi_prop_exists(9F), ddi_prop_get_int(9F),
ddi_prop_remove(9F), ddi_prop_undefine(9F),
ddi_prop_update(9F)
Writing Device Drivers
Man(1) output converted with
man2html