ldi_prop_lookup_string_array(9f)

1ldi_prop_lookup_int_array(K9eFr)nel Functions for Drivledris_prop_lookup_int_array(9F)
2
3
4

NAME

6       ldi_prop_lookup_int_array,                 ldi_prop_lookup_int64_array,
7       ldi_prop_lookup_string_array,                   ldi_prop_lookup_string,
8       ldi_prop_lookup_byte_array - Lookup property information
9

SYNOPSIS

11       #include <sys/sunldi.h>
12
13       int ldi_prop_lookup_int_array(ldi_handle_t lh, uint_t  flags, char *name,
14            int **datap, uint_t *nelementsp);
15
16
17       int ldi_prop_lookup_int64_array(ldi_handle_t lh, uint_t  flags, char *name,
18            int64_t  **datap, uint_t *nelementsp);
19
20
21       int ldi_prop_lookup_string_array(ldi_handle_t lh, uint_t  flags,
22            char *name, char ***datap, uint_t *nelementsp);
23
24
25       int ldi_prop_lookup_string(ldi_handle_t lh, uint_t  flags, char *name,
26            char  **datap);
27
28
29       int ldi_prop_lookup_byte_array(ldi_handle_t lh, uint_t  flags, char *name,
30            uchar_t **datap, uint_t *nelements);
31
32

PARAMETERS

34       lh       Layered handle.
35
36
37       flags    Possible flag values are some combination of:
38
39                LDI_DEV_T_ANY        Match  the  lookup request independent of
40                                     the actual dev_t value that was used when
41                                     the  property was created. The flag indi‐
42                                     cates   any   dev_t   value    (including
43                                     DDI_DEV_T_NONE)  associated with a possi‐
44                                     ble  property  match  will  satisfy   the
45                                     matching criteria.
46
47
48                DDI_PROP_DONTPASS    Do  not  pass  request  to  parent device
49                                     information node if the property  is  not
50                                     found.
51
52
53                DDI_PROP_NOTPROM     Do  not  look at PROM properties (ignored
54                                     on platforms that  do  not  support  PROM
55                                     properties).
56
57
58
59       name         String containing the property name.
60
61
62       nelements    The  address of an unsigned integer which, upon successful
63                    return, contains the number of elements accounted  for  in
64                    the memory pointed at by datap. Depending on the interface
65                    you use, the elements  are  either  integers,  strings  or
66                    bytes.
67
68
69
70       datap
71
72       ldi_prop_lookup_int_array()
73
74           Pointer  address  to  an  array  of integers which, upon successful
75           return, point to  memory  containing  the  integer  array  property
76           value.
77
78
79       ldi_prop_lookup_int64_array()
80
81           Pointer address to an array of 64-bit integers which, upon success‐
82           ful return, point to memory containing the integer  array  property
83           value.
84
85
86       ldi_prop_lookup_string_array()
87
88           Pointer  address  to  an  array  of  strings which, upon successful
89           return, point to memory containing the array of strings. The string
90           array  is  formatted  as  an  array  of pointers to NULL terminated
91           strings, much like the argv argument to execve(2).
92
93
94       ldi_prop_lookup_string()
95
96           Pointer address to a string which, upon successful  return,  points
97           to  memory containing the NULL terminated string value of the prop‐
98           erty.
99
100
101       ldi_prop_lookup_byte_array()
102
103           Pointer address to an array of bytes which, upon successful return,
104           point to memory containing the property byte array value.
105
106

INTERFACE LEVEL

108       Solaris DDI specific (Solaris DDI).
109

DESCRIPTION

111       The  property  look  up  functions search for and, if found, return the
112       value of a given property. Properties are searched for based on the dip
113       and dev_t values associated with the layered handle, the property name,
114       and type of the data (integer, string, or byte).
115
116
117       The property search order is as follows:
118
119           1.     Search software properties created by the driver.
120
121           2.     Search the software properties created  by  the  system  (or
122                  nexus nodes in the device info tree).
123
124           3.     Search the driver global properties list.
125
126           4.     If  DDI_PROP_NOTPROM  is not set, search the PROM properties
127                  (if they exist).
128
129           5.     If DDI_PROP_DONTPASS is not set, pass this  request  to  the
130                  parent device information node of the device  represented by
131                  the layered handle.
132
133           6.     Return DDI_PROP_NOT_FOUND.
134
135
136       Typically, the specific dev_t value associated with the  device  repre‐
137       sented  by  the  layered handle (ldi_handle_t) is used as a part of the
138       property match criteria. This association is  handled  by  the  layered
139       driver  infrastructure  on  behalf of the consumers of the ldi property
140       look up functions.
141
142
143       However, if the LDI_DEV_T_ANY flag is used,  the  ldi  property  lookup
144       functions  match  the  request regardless of the dev_t value associated
145       with the property at the time of its creation. If a property  was  cre‐
146       ated  with  a dev_t set to DDI_DEV_T_NONE, then the only way to look up
147       this property is with  the  LDI_DEV_T_ANY  flag.  PROM  properties  are
148       always created with a dev_t set to DDI_DEV_T_NONE.
149
150
151       name must always be set to the name of the property being looked up.
152
153
154       For   the  ldi_prop_lookup_int_array(),  ldi_prop_lookup_int64_array(),
155       ldi_prop_lookup_string_array(),      ldi_prop_lookup_string(),      and
156       ldi_prop_lookup_byte_array()  functions,  datap  is  the  address  of a
157       pointer which, upon successful return, points to memory containing  the
158       value  of  the property. In each case *datap points to a different type
159       of property value. See the individual  descriptions  of  the  functions
160       below  for  details  on  the different return values. nelementsp is the
161       address of an unsigned integer which, upon successful return,  contains
162       the  number  of  integer,  string or byte elements accounted for in the
163       memory pointed at by *datap.
164
165
166       All of the property look up functions  may  block  to  allocate  memory
167       needed to hold the value of the property.
168
169
170       When  a driver has obtained a property with any look up function and is
171       finished with that property, it must be freed by call  ddi_prop_free().
172       ddi_prop_free()  must be called with the address of the allocated prop‐
173       erty. For instance, if you call ldi_prop_lookup_int_array() with  datap
174       set to the address of a pointer to an integer, &my-int-ptr, the compan‐
175       ion free call is ddi_prop_free(my-int-ptr).
176
177
178       Property look up functions are described below:
179
180       ldi_prop_lookup_int_array()
181
182           This function searches for and returns an array of integer property
183           values.  An array of integers is defined to *nelementsp number of 4
184           byte long integer elements. datap should be set to the address of a
185           pointer to an array of integers which, upon successful return, will
186           point to memory containing the integer array value of the property.
187
188
189       ldi_prop_lookup_int64_array()
190
191           This function searches for and returns an array of integer property
192           values.  An array of integers is defined to *nelementsp number of 8
193           byte long integer        elements.  datap  should  be  set  to  the
194           address of a pointer to an array of integers which, upon successful
195           return, will point to memory containing the integer array value  of
196           the  property  This  function  does  not search the PROM for 64-bit
197           property values.
198
199
200       ldi_prop_lookup_string_array()
201
202           This function searches for and returns a property that is an  array
203           of  strings.   datap should be set to an address of a pointer to an
204           array of strings which, upon successful return, will point to  mem‐
205           ory  containing the array of strings.  The array of strings is for‐
206           matted as an array of pointers  to  null-terminated  strings,  much
207           like the argv argument to execve(2).
208
209
210       ldi_prop_lookup_string()
211
212           This  function  searches for and returns a property that is a null-
213           terminated string. datap should be set to the address of a  pointer
214           to  a  string  which, upon successful return, points to memory con‐
215           taining the string value of the property.
216
217
218       ldi_prop_lookup_byte_array()
219
220           This function searches for and returns a property that is an  array
221           of  bytes.   datap  should be set to the address of a pointer to an
222           array of bytes which, upon    successful return, points  to  memory
223           containing the byte array value of the property.
224
225
226       ddi_prop_free()
227
228           Frees   the   resources   associated  with  a  property  previously
229           allocated            using             ldi_prop_lookup_int_array(),
230           ldi_prop_lookup_int64_array(),      ldi_prop_lookup_string_array(),
231           ldi_prop_lookup_string(), and ldi_prop_lookup_byte_array().
232
233

RETURN VALUES

235       The               functions                ldi_prop_lookup_int_array(),
236       ldi_prop_lookup_int64_array(),          ldi_prop_lookup_string_array(),
237       ldi_prop_lookup_string(), and ldi_prop_lookup_byte_array()  return  the
238       following values:
239
240       DDI_PROP_SUCCESS          Property found and returned.
241
242
243       DDI_PROP_INVAL_ARG        If  an  attempt is made to look up a property
244                                 with a NULL ldi handle, name is NULL or  name
245                                 is a the null string.
246
247
248       DDI_PROP_NOT_FOUND        Property not found.
249
250
251       DDI_PROP_UNDEFINED        Prop explicitly undefined (see ddi_prop_unde‐
252                                 fine(9F)).
253
254
255       DDI_PROP_CANNOT_DECODE    Property value cannot be decoded.
256
257

CONTEXT

259       These functions may be called from user or kernel context.
260

EXAMPLE

262         Using ldi_prop_lookup_int64_array().
263
264                The following example demonstrates the use of
265                ldi_prop_lookup_int64_array().
266
267
268                int64_t *options;
269                uint_t  noptions;
270
271                /*
272                 * Get the data associated with the integer "options" property
273                 * array, along with the number of option integers
274                 */
275
276                if  (ldi_prop_lookup_int64_array(lh,
277                    LDI_DEV_T_ANY|DDI_PROP_NOTPROM, "options",
278                    &options, &noptions) == DDI_PROP_SUCCESS) {
279                       /*
280                          * Process the options data from the property
281                         * we just received. Let's do "our thing" with data.
282                         */
283                        xx_process_options(options, noptions);
284
285                        /*
286                         * Free the memory allocated for the property data
287                         */
288                        ddi_prop_free(options);
289                }
290
291