ddi_prop_lookup man page on SunOS

Printed from http://www.polarhome.com/service/man/?qf=ddi_prop_lookup&af=0&tf=2&of=SunOS

ddi_prop_lookup(9F)	 Kernel Functions for Drivers	   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	 prop‐
		       erty 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 success‐
		       ful  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	 argu‐
			   ment to execve(2).

		       ddi_prop_lookup_string()

			   The	address	 of  a pointer to a string which, upon
			   successful return, will point to memory  containing
			   the NULL terminated string value of the property.

		       ddi_prop_lookup_byte_array()

			   The	address of pointer to an array of bytes which,
			   upon successful return, will point to  memory  con‐
			   taining 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 properties (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 num‐
       ber 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. nele‐
       mentsp  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()

	   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 successful return, will point to memory con‐
	   taining 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 successful return, will point to memory  con‐
	   taining 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 previously 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

SunOS 5.10			  11 Apr 2001		   ddi_prop_lookup(9F)
[top]

List of man pages available for SunOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net