1scf_value_createS(e3rSvCiFc)e Configuration Facility Library Funscctfi_ovnaslue_create(3SCF)
2
3
4

NAME

6       scf_value_create, scf_value_handle, scf_value_reset, scf_value_destroy,
7       scf_value_type,         scf_value_base_type,         scf_value_is_type,
8       scf_type_base_type,     scf_value_get_boolean,     scf_value_get_count,
9       scf_value_get_integer,    scf_value_get_time,    scf_value_get_astring,
10       scf_value_get_ustring,  scf_value_get_opaque,  scf_value_get_as_string,
11       scf_value_get_as_string_typed,                   scf_value_set_boolean,
12       scf_value_set_count,     scf_value_set_integer,     scf_value_set_time,
13       scf_value_set_from_string,                       scf_value_set_astring,
14       scf_value_set_ustring,  scf_value_set_opaque - manipulate values in the
15       Service Configuration Facility
16

SYNOPSIS

18       cc [ flag... ] file... -lscf [ library... ]
19       #include <libscf.h>
20
21       scf_value_t *scf_value_create(scf_handle_t *h);
22
23
24       scf_handle_t *scf_value_handle(scf_value_t *v);
25
26
27       void scf_value_reset(scf_value_t *v);
28
29
30       void scf_value_destroy(scf_value_t *v);
31
32
33       int scf_value_type(scf_value_t *v);
34
35
36       int scf_value_base_type(scf_value_t *v);
37
38
39       int scf_value_is_type(scf_value_t *v, scf_type_t type);
40
41
42       int scf_type_base_type(scf_type_t type, scf_type_t *out);
43
44
45       int scf_value_get_boolean(scf_value_t *v, uint8_t *out);
46
47
48       int scf_value_get_count(scf_value_t *v, uint64_t *out);
49
50
51       int scf_value_get_integer(scf_value_t *v, int64_t *out);
52
53
54       int scf_value_get_time(scf_value_t *v, int64_t *seconds,
55            int32_t *ns);
56
57
58       ssize_t scf_value_get_astring(scf_value_t *v, char *buf,
59            size_t size);
60
61
62       ssize_t scf_value_get_ustring(scf_value_t *v, char *buf,
63            size_t size);
64
65
66       ssize_t scf_value_get_opaque(scf_value_t *v, char *out,
67            size_t len);
68
69
70       ssize_t scf_value_get_as_string(scf_value_t *v, char *buf,
71            size_t size);
72
73
74       ssize_t scf_value_get_as_string_typed(scf_value_t *v,
75            scf_type_t type, char *buf, size_t size);
76
77
78       void scf_value_set_boolean(scf_value_t *v, uint8_t in);
79
80
81       void scf_value_set_count(scf_value_t *v, uint64_t in);
82
83
84       void scf_value_set_integer(scf_value_t *v, int64_t in);
85
86
87       int scf_value_set_time(scf_value_t *v, int64_t seconds,
88            int32_t ns);
89
90
91       int scf_value_set_from_string(scf_value_t *v, scf_type_t type,
92            char *in);
93
94
95       int scf_value_set_astring(scf_value_t *v, const char *in);
96
97
98       int scf_value_set_ustring(scf_value_t *v, const char *in);
99
100
101       int scf_value_set_opaque(scf_value_t *v, void *in, size_t sz);
102
103

DESCRIPTION

105       The scf_value_create() function creates a new, reset  scf_value_t  that
106       holds  a single typed value. The value can be used only with the handle
107       specified by h and objects associated with h.
108
109
110       The scf_value_reset() function resets the value  to  the  uninitialized
111       state. The scf_value_destroy() function deallocates the object.
112
113
114       The  scf_value_type() function retrieves the type of the contents of v.
115       The scf_value_is_type() function determines if a value is of a particu‐
116       lar  type  or  any  of  its subtypes. The scf_type_base_type() function
117       returns the base  type  of  type.  The  scf_value_base_type()  function
118       returns  the  true  base  type of the value (the highest type reachable
119       from the value's type).
120
121
122
123
124         Type Identifier      Base Type              Type Description
125       ──────────────────────────────────────────────────────────────────────────
126       SCF_TYPE_INVALID                   reserved invalid type
127       SCF_TYPE_BOOLEAN                   single bit
128       SCF_TYPE_COUNT                     unsigned 64-bit quantity
129       SCF_TYPE_INTEGER                   signed 64-bit quantity
130
131
132
133       SCF_TYPE_TIME                      signed 64-bit seconds,  signed  32-bit
134                                          nanoseconds  in  the  range  0 <= ns <
135                                          1,000,000,000
136       SCF_TYPE_ASTRING                   8-bit NUL-terminated string
137       SCF_TYPE_OPAQUE                    opaque 8-bit data
138       SCF_TYPE_USTRING       ASTRING     8-bit UTF-8 string
139       SCF_TYPE_URI           USTRING     a URI string
140       SCF_TYPE_FMRI          URI         a Fault Management Resource Identifier
141       SCF_TYPE_HOST          USTRING     either a hostname,  IPv4  address,  or
142                                          IPv6 address
143       SCF_TYPE_HOSTNAME      HOST        a fully-qualified domain name
144       SCF_TYPE_NET_ADDR_V4   HOST        a   dotted-quad   IPv4   address  with
145                                          optional network portion
146       SCF_TYPE_NET_ADDR_V6   HOST        legal IPv6 address
147
148
149
150       The scf_value_get_boolean(), scf_value_get_count(), scf_value_get_inte‐
151       ger(),          scf_value_get_time(),          scf_value_get_astring(),
152       scf_value_get_ustring(), and scf_value_get_opaque()  functions  read  a
153       particular type of value from v.
154
155
156       The scf_value_get_as_string() and scf_value_get_as_string_typed() func‐
157       tions    convert    the    value    to    a    string     form.     For
158       scf_value_get_as_string_typed(),  the value must be a reachable subtype
159       of type.
160
161
162       The scf_value_set_boolean(), scf_value_set_count(), scf_value_set_inte‐
163       ger(),          scf_value_set_time(),          scf_value_set_astring(),
164       scf_value_set_ustring(), and scf_value_set_opaque() functions set v  to
165       a particular value of a particular type.
166
167
168       The    scf_value_set_from_string()   function   is   the   inverse   of
169       scf_value_get_as_string(). It sets v to the value  encoded  in  buf  of
170       type type.
171
172
173       The  scf_value_set_*()  functions  will  succeed on scf_value_t objects
174       that have already been set.
175

RETURN VALUES

177       Upon successful completion, scf_value_create()  returns  a  new,  reset
178       scf_value_t. Otherwise, it returns NULL.
179
180
181       Upon successful completion, scf_value_handle() returns the handle asso‐
182       ciated with v. Otherwise, it returns NULL.
183
184
185       The scf_value_base_type() function returns the base type of the  value,
186       or SCF_TYPE_INVALID on failure.
187
188
189       Upon  successful  completion,  scf_value_type() returns the type of the
190       value. Otherwise, it returns SCF_TYPE_INVALID.
191
192
193       Upon successful  completion,  scf_value_is_type(),  scf_value_get_bool‐
194       ean(),          scf_value_get_count(),         scf_value_get_integer(),
195       scf_value_get_time(),                             scf_value_set_time(),
196       scf_value_set_from_string(),                   scf_value_set_astring(),
197       scf_value_set_ustring(), and scf_value_set_opaque()  return  0.  Other‐
198       wise, they return -1.
199
200
201       Upon        successful       completion,       scf_value_get_astring(),
202       scf_value_get_ustring(),         scf_value_get_as_string(),         and
203       scf_value_get_as_string_typed() return the length of the source string,
204       not including the terminating null byte. Otherwise, they return -1.
205
206
207       Upon successful completion, scf_value_get_opaque() returns  the  number
208       of bytes written. Otherwise, it returns -1.
209

ERRORS

211       The scf_value_create() function will fail if:
212
213       SCF_ERROR_HANDLE_DESTROYED    The  handle  associated  with  h has been
214                                     destroyed.
215
216
217       SCF_ERROR_INVALID_ARGUMENT    The handle is NULL.
218
219
220       SCF_ERROR_NO_MEMORY           There is not enough memory to allocate an
221                                     scf_value_t.
222
223
224
225       The scf_value_handle() function will fail if:
226
227       SCF_ERROR_HANDLE_DESTROYED    The  handle  associated  with  v has been
228                                     destroyed.
229
230
231
232       The scf_value_set_time() function will fail if:
233
234       SCF_ERROR_INVALID_ARGUMENT    The nanoseconds field is not in the range
235                                     0 <= ns < 1,000,000,000.
236
237
238
239       The scf_type_base_type() function will fail if:
240
241       SCF_ERROR_INVALID_ARGUMENT    The type argument is not a valid type.
242
243
244
245       The          scf_value_set_astring(),          scf_value_set_ustring(),
246       scf_value_set_opaque(), and scf_value_set_from_string() functions  will
247       fail if:
248
249       SCF_ERROR_INVALID_ARGUMENT    The  in argument is not a valid value for
250                                     the specified type or is longer than  the
251                                     maximum supported value length.
252
253
254
255       The        scf_type_base_type(),        scf_value_is_type(),        and
256       scf_value_get_as_string_typed() functions will fail if:
257
258       SCF_ERROR_INVALID_ARGUMENT    The type argument is not a valid type.
259
260
261
262       The scf_value_type(),  scf_value_base_type(),  scf_value_get_boolean(),
263       scf_value_get_count(),  scf_value_get_integer(),  scf_value_get_time(),
264       scf_value_get_astring(),                       scf_value_get_ustring(),
265       scf_value_get_as_string(), andscf_value_get_as_string_typed() functions
266       will fail if:
267
268       SCF_ERROR_NOT_SET    The v argument has not been set to a value.
269
270
271
272       The scf_value_get_boolean(), scf_value_get_count(), scf_value_get_inte‐
273       ger(),          scf_value_get_time(),          scf_value_get_astring(),
274       scf_value_get_ustring(), and scf_value_get_as_string_typed()  functions
275       will fail if:
276
277       SCF_ERROR_TYPE_MISMATCH    The  requested  type  is not the same as the
278                                  value's type and is  not  in  the  base-type
279                                  chain.
280
281
282
283       The scf_error(3SCF) function can be used to retrieve the error value.
284

ATTRIBUTES

286       See attributes(5) for descriptions of the following attributes:
287
288
289
290
291       ┌─────────────────────────────┬─────────────────────────────┐
292       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
293       ├─────────────────────────────┼─────────────────────────────┤
294       │Interface Stability          │Committed                    │
295       ├─────────────────────────────┼─────────────────────────────┤
296       │MT-Level                     │Safe                         │
297       └─────────────────────────────┴─────────────────────────────┘
298

SEE ALSO

300       libscf(3LIB), scf_entry_add_value(3SCF), scf_error(3SCF), attributes(5)
301
302
303
304SunOS 5.11                        28 May 2009           scf_value_create(3SCF)
Impressum