ddi_prop_update_string(9f)

1ddi_prop_update(9F)      Kernel Functions for Drivers      ddi_prop_update(9F)
2
3
4

NAME

6       ddi_prop_update,     ddi_prop_update_int_array,    ddi_prop_update_int,
7       ddi_prop_update_string_array,                    ddi_prop_update_int64,
8       ddi_prop_update_int64_array,                    ddi_prop_update_string,
9       ddi_prop_update_byte_array - update properties
10

SYNOPSIS

12       #include <sys/ddi.h>
13       #include <sys/sunddi.h>
14
15
16
17       int ddi_prop_update_int_array(dev_t dev, dev_info_t *dip,
18            char *name, int *data, uint_t nelements);
19
20
21       int ddi_prop_update_int(dev_t dev, dev_info_t *dip, char *name,
22            int data);
23
24
25       int ddi_prop_update_int64_array(dev_t dev, dev_info_t *dip, char *name,
26            int64_t *data, uint_t nelements);
27
28
29       int ddi_prop_update_int64(dev_t dev, dev_info_t *dip, char *name,
30            int64_t data);
31
32
33       int ddi_prop_update_string_array(dev_t dev, dev_info_t *dip, char *name,
34            char **data, uint_t nelements);
35
36
37       int ddi_prop_update_string(dev_t dev, dev_info_t *dip, char *name,
38            char *data);
39
40
41       int ddi_prop_update_byte_array(dev_t dev, dev_info_t *dip, char *name,
42            uchar_t *data, uint_t nelements);
43
44

PARAMETERS

46       dev           Device number associated with the device.
47
48
49       dip           Pointer to the device info node of device whose  property
50                     list should be updated.
51
52
53       name          String containing the name of the property to be updated.
54
55
56       nelements     The number of elements contained in the memory pointed at
57                     by data.
58
59
60
61       ddi_prop_update_int_array()
62
63       data     A pointer an integer array with which to update the property.
64
65
66
67       ddi_prop_update_int()
68
69       data     An integer value with which to update the property.
70
71
72
73       ddi_prop_update_int64_array()
74
75       data     An pointer to a 64-bit integer array with which to update  the
76                property.
77
78
79
80       ddi_prop_update_int64()
81
82       data     A 64-bit integer value with which to update the property.
83
84
85
86       ddi_prop_update_string_array()
87
88       data     A pointer to a string array with which to update the property.
89                The array of strings is formatted as an array of  pointers  to
90                NULL  terminated  strings,  much  like  the  argv  argument to
91                execve(2).
92
93
94
95       ddi_prop_update_string()
96
97       data     A pointer to a string value with which to update the property.
98
99
100
101       ddi_prop_update_byte_array()
102
103       data     A pointer to a byte array with which to update the property.
104
105

INTERFACE LEVEL

107       Solaris DDI specific (Solaris DDI).
108

DESCRIPTION

110       The property update routines search for and, if found, modify the value
111       of  a  given  property.  Properties  are searched for based on the dip,
112       name, dev, and the type of the data (integer,  string,  or  byte).  The
113       driver  software properties list is searched. If the property is found,
114       it is updated with the supplied value. If the property is not found  on
115       this list, a new property is created with the value supplied. For exam‐
116       ple, if a driver attempts to update  the  "foo"  property,  a  property
117       named  "foo" is searched for on the driver's software property list. If
118       "foo" is found, the value is updated. If "foo"  is  not  found,  a  new
119       property  named "foo" is created on the driver's software property list
120       with the supplied value even if a  "foo"  property  exists  on  another
121       property list (such as a PROM property list).
122
123
124       Every property value has a data type associated with it: byte, integer,
125       or string. A property should be updated using a function with the  same
126       corresponding  data type as the property value. For example, an integer
127       property must be updated using  either  ddi_prop_update_int_array()  or
128       ddi_prop_update_int().   For   a   64-bit   integer,   you   must   use
129       ddi_prop_update_int64_array() or ddi_prop_update_int64().  Attempts  to
130       update a property with a function that does not correspond to the prop‐
131       erty data type that was used to  create  it  results  in  an  undefined
132       state.
133
134
135       Usually,  the  dev  argument  should be set to the actual device number
136       that this property is associated with. If the property is  not  associ‐
137       ated  with  any  particular dev, then the argument dev should be set to
138       DDI_DEV_T_NONE. This property will then match a look  up  request  (see
139       ddi_prop_lookup(9F))  with the match_dev argument set to DDI_DEV_T_ANY.
140       If no dev is available for the device (for  example  during  attach(9E)
141       time),  one  can be created using makedevice(9F) with a major number of
142       DDI_MAJOR_T_UNKNOWN. The update routines will then generate the correct
143       dev when creating or updating the property.
144
145
146       name must always be set to the name of the property being updated.
147
148
149       For          the          routines         ddi_prop_update_int_array(),
150       ddi_prop_lookup_int64_array(),          ddi_prop_update_string_array(),
151       ddi_prop_update_string(),  and  ddi_prop_update_byte_array(), data is a
152       pointer which points to memory containing the value of the property. In
153       each  case  *data points to a different type of property value. See the
154       individual descriptions of the routines below  for  details  concerning
155       the  different  values. nelements is an unsigned integer which contains
156       the number of integer, string, or byte elements accounted  for  in  the
157       memory pointed at by *data.
158
159
160       For  the  routines  ddi_prop_update_int()  and ddi_prop_update_int64(),
161       data is the new value of the property.
162
163
164       ddi_prop_update_int_array()
165
166
167       Updates or creates an array of integer property  values.  An  array  of
168       integers  is  defined  to be nelements of 4 byte long integer elements.
169       data must be a pointer to an integer array with  which  to  update  the
170       property.
171
172
173       ddi_prop_update_int()
174
175
176       Update or creates a single integer value of a property. data must be an
177       integer value with which to update the property.
178
179
180       ddi_prop_update_int64_array()
181
182
183       Updates or creates an array of 64-bit integer property values. An array
184       of  integers  is  defined  to be nelements of int64_t integer elements.
185       data must be a pointer to a 64-bit integer array with which  to  update
186       the property.
187
188
189       ddi_prop_update_int64()
190
191
192       Updates  or  creates  a single 64-bit integer value of a property. data
193       must be an int64_t value with which to update the property.
194
195
196       ddi_prop_update_string_array()
197
198
199       Updates or creates a property that is an array of strings. data must be
200       a  pointer  to  a  string  array with which to update the property. The
201       array of strings is formatted as an array of pointers to NULLterminated
202       strings, much like the argv argument to execve(2).
203
204
205       ddi_prop_update_string()
206
207
208       Updates  or creates a property that is a single string value. data must
209       be a pointer to a string with which to update the property.
210
211
212       ddi_prop_update_byte_array()
213
214
215       Updates or creates a property that is an array of bytes. data should be
216       a pointer to a byte array with which to update the property.
217
218
219       The  property  update  routines  may block to allocate memory needed to
220       hold the value of the property.
221

RETURN VALUES

223       All of the property update routines return:
224
225       DDI_PROP_SUCCESS           On success.
226
227
228       DDI_PROP_INVAL_ARG         If an attempt is made to update  a  property
229                                  with  name  set  to  NULL or name set to the
230                                  null string.
231
232
233       DDI_PROP_CANNOT_ENCODE     If the  bytes  of  the  property  cannot  be
234                                  encoded.
235
236

CONTEXT

238       These functions can only be called from user or kernel context.
239

EXAMPLES

241       Example 1 Updating Properties
242
243
244       The      following      example     demonstrates     the     use     of
245       ddi_prop_update_int_array().
246
247
248         int  options[4];
249
250              /*
251               * Create the "options" integer array with
252               * our default values for these parameters
253               */
254              options[0] = XX_OPTIONS0;
255              options[1] = XX_OPTIONS1;
256              options[2] = XX_OPTIONS2;
257              options[3] = XX_OPTIONS3;
258              i = ddi_prop_update_int_array(xx_dev, xx_dip, "options",
259                   &options, sizeof (options) / sizeof (int));
260
261