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]
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

#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);

match_dev dip flags name nelementsp datap illumos DDI specific (illumos DDI). 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:

Usually, the match_dev argument should be set to the actual device number that this property is associated with. However, if the match_dev argument is DDI_DEV_T_ANY, the property 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 individual 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 routine 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()

ddi_prop_lookup_int64_array() ddi_prop_lookup_string_array() ddi_prop_lookup_string() ddi_prop_lookup_byte_array() ddi_prop_free() 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 DDI_PROP_INVAL_ARG DDI_PROP_NOT_FOUND DDI_PROP_UNDEFINED DDI_PROP_CANNOT_DECODE These functions can be called from user or kernel context. 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);
}

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