ldi_prop_lookup_string_array man page on SmartOS

Man page or keyword search:  
man Server   16655 pages
apropos Keyword Search (all sections)
Output format
SmartOS logo
[printable version]

LDI_PROP_LOOKUP_INT_ARRAY(9F)			 LDI_PROP_LOOKUP_INT_ARRAY(9F)

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

SYNOPSIS
       #include <sys/sunldi.h>

       int ldi_prop_lookup_int_array(ldi_handle_t lh, uint_t  flags, char *name,
	    int **datap, uint_t *nelementsp);

       int ldi_prop_lookup_int64_array(ldi_handle_t lh, uint_t	flags, char *name,
	    int64_t  **datap, uint_t *nelementsp);

       int ldi_prop_lookup_string_array(ldi_handle_t lh, uint_t	 flags,
	    char *name, char ***datap, uint_t *nelementsp);

       int ldi_prop_lookup_string(ldi_handle_t lh, uint_t  flags, char *name,
	    char  **datap);

       int ldi_prop_lookup_byte_array(ldi_handle_t lh, uint_t  flags, char *name,
	    uchar_t **datap, uint_t *nelements);

PARAMETERS
       lh
		Layered handle.

       flags
		Possible flag values are some combination of:

		LDI_DEV_T_ANY
				     Match  the	 lookup request independent of
				     the actual dev_t value that was used when
				     the  property was created. The flag indi‐
				     cates   any   dev_t   value    (including
				     DDI_DEV_T_NONE)  associated with a possi‐
				     ble  property  match  will	 satisfy   the
				     matching criteria.

		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 platforms that	do  not	 support  PROM
				     properties).

       name
		    String containing the property name.

       nelements
		    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.

       datap

       ldi_prop_lookup_int_array()

	   Pointer  address  to	 an  array  of integers which, upon successful
	   return, point to  memory  containing	 the  integer  array  property
	   value.

       ldi_prop_lookup_int64_array()

	   Pointer address to an array of 64-bit integers which, upon success‐
	   ful return, point to memory containing the integer  array  property
	   value.

       ldi_prop_lookup_string_array()

	   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 execve(2).

       ldi_prop_lookup_string()

	   Pointer address to a string which, upon successful  return,	points
	   to  memory containing the NULL terminated string value of the prop‐
	   erty.

       ldi_prop_lookup_byte_array()

	   Pointer address to an array of bytes which, upon successful return,
	   point to memory containing the property byte array value.

INTERFACE LEVEL
       Solaris DDI specific (Solaris DDI).

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).

       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 of the device	represented by
		  the layered handle.

	   6.	  Return DDI_PROP_NOT_FOUND.

       Typically, the specific dev_t value associated with the	device	repre‐
       sented  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.

       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  cre‐
       ated  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.

       name must always be set to the name of the property being looked up.

       For   the  ldi_prop_lookup_int_array(),	ldi_prop_lookup_int64_array(),
       ldi_prop_lookup_string_array(),	    ldi_prop_lookup_string(),	   and
       ldi_prop_lookup_byte_array()  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.

       All of the property look up functions  may  block  to  allocate	memory
       needed to hold the value of the property.

       When  a driver has obtained a property with any look up function and is
       finished with that property, it must be freed by call  ddi_prop_free().
       ddi_prop_free()	must be called with the address of the allocated prop‐
       erty. For instance, if you call ldi_prop_lookup_int_array() with	 datap
       set to the address of a pointer to an integer, &my-int-ptr, the compan‐
       ion free call is ddi_prop_free(my-int-ptr).

       Property look up functions are described below:

       ldi_prop_lookup_int_array()

	   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.

       ldi_prop_lookup_int64_array()

	   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.

       ldi_prop_lookup_string_array()

	   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 mem‐
	   ory containing the array of strings.	 The array of strings is  for‐
	   matted  as  an  array  of pointers to null-terminated strings, much
	   like the argv argument to execve(2).

       ldi_prop_lookup_string()

	   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  con‐
	   taining the string value of the property.

       ldi_prop_lookup_byte_array()

	   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.

       ddi_prop_free()

	   Frees  the  resources  associated  with   a	 property   previously
	   allocated		 using		  ldi_prop_lookup_int_array(),
	   ldi_prop_lookup_int64_array(),      ldi_prop_lookup_string_array(),
	   ldi_prop_lookup_string(), and ldi_prop_lookup_byte_array().

RETURN VALUES
       The		  functions		  ldi_prop_lookup_int_array(),
       ldi_prop_lookup_int64_array(),	       ldi_prop_lookup_string_array(),
       ldi_prop_lookup_string(),  and  ldi_prop_lookup_byte_array() return the
       following values:

       DDI_PROP_SUCCESS
				 Property found and returned.

       DDI_PROP_INVAL_ARG
				 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.

       DDI_PROP_NOT_FOUND
				 Property not found.

       DDI_PROP_UNDEFINED
				 Prop explicitly undefined (see ddi_prop_unde‐
				 fine(9F)).

       DDI_PROP_CANNOT_DECODE
				 Property value cannot be decoded.

CONTEXT
       These functions may be called from user or kernel context.

EXAMPLE
	 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);
		}

SEE ALSO
       execve(2),  ddi_prop_free(9F), ddi_prop_lookup(9F), ldi_prop_exists(9F)
       .

       Writing Device Drivers

				  Jun 3, 2003	 LDI_PROP_LOOKUP_INT_ARRAY(9F)
[top]

List of man pages available for SmartOS

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