ldi_prop_lookup_int_array man page on SunOS

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

ldi_prop_lookup_int_arrayKernel Functions for Drildi_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  indicates
				   any	dev_t value (including DDI_DEV_T_NONE)
				   associated with a possible  property	 match
				   will satisfy the matching criteria.

			       DDI_PROP_DONTPASS

				   Do not pass request to parent device infor‐
				   mation node if the property is not found.

			       DDI_PROP_NOTPROM

				   Do not look at PROM properties (ignored  on
				   platforms  that do not support PROM proper‐
				   ties).

       name	       String containing the property name.

       nelements       The address of an unsigned integer which, upon success‐
		       ful  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

SunOS 5.10			  3 June 2003	 ldi_prop_lookup_int_array(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