| blob | d1662df58a1f803889313d66d78be6ea25de23c1 |
1 '\" te
2 .\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved.
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
4 .\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with
5 .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH SCF_VALUE_CREATE 3SCF "May 28, 2009"
7 .SH NAME
8 scf_value_create, scf_value_handle, scf_value_reset, scf_value_destroy,
9 scf_value_type, scf_value_base_type, scf_value_is_type, scf_type_base_type,
10 scf_value_get_boolean, scf_value_get_count, scf_value_get_integer,
11 scf_value_get_time, scf_value_get_astring, scf_value_get_ustring,
12 scf_value_get_opaque, scf_value_get_as_string, scf_value_get_as_string_typed,
13 scf_value_set_boolean, scf_value_set_count, scf_value_set_integer,
14 scf_value_set_time, scf_value_set_from_string, scf_value_set_astring,
15 scf_value_set_ustring, scf_value_set_opaque \- manipulate values in the Service
16 Configuration Facility
17 .SH SYNOPSIS
18 .LP
19 .nf
20 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lscf\fR [ \fIlibrary\fR\&.\|.\|. ]
21 #include <libscf.h>
23 \fBscf_value_t *\fR\fBscf_value_create\fR(\fBscf_handle_t *\fR\fIh\fR);
24 .fi
26 .LP
27 .nf
28 \fBscf_handle_t *\fR\fBscf_value_handle\fR(\fBscf_value_t *\fR\fIv\fR);
29 .fi
31 .LP
32 .nf
33 \fBvoid\fR \fBscf_value_reset\fR(\fBscf_value_t *\fR\fIv\fR);
34 .fi
36 .LP
37 .nf
38 \fBvoid\fR \fBscf_value_destroy\fR(\fBscf_value_t *\fR\fIv\fR);
39 .fi
41 .LP
42 .nf
43 \fBint\fR \fBscf_value_type\fR(\fBscf_value_t *\fR\fIv\fR);
44 .fi
46 .LP
47 .nf
48 \fBint\fR \fBscf_value_base_type\fR(\fBscf_value_t *\fR\fIv\fR);
49 .fi
51 .LP
52 .nf
53 \fBint\fR \fBscf_value_is_type\fR(\fBscf_value_t *\fR\fIv\fR, \fBscf_type_t\fR \fItype\fR);
54 .fi
56 .LP
57 .nf
58 \fBint\fR \fBscf_type_base_type\fR(\fBscf_type_t\fR \fItype\fR, \fBscf_type_t *\fR\fIout\fR);
59 .fi
61 .LP
62 .nf
63 \fBint\fR \fBscf_value_get_boolean\fR(\fBscf_value_t *\fR\fIv\fR, \fBuint8_t *\fR\fIout\fR);
64 .fi
66 .LP
67 .nf
68 \fBint\fR \fBscf_value_get_count\fR(\fBscf_value_t *\fR\fIv\fR, \fBuint64_t *\fR\fIout\fR);
69 .fi
71 .LP
72 .nf
73 \fBint\fR \fBscf_value_get_integer\fR(\fBscf_value_t *\fR\fIv\fR, \fBint64_t *\fR\fIout\fR);
74 .fi
76 .LP
77 .nf
78 \fBint\fR \fBscf_value_get_time\fR(\fBscf_value_t *\fR\fIv\fR, \fBint64_t *\fR\fIseconds\fR,
79 \fBint32_t *\fR\fIns\fR);
80 .fi
82 .LP
83 .nf
84 \fBssize_t\fR \fBscf_value_get_astring\fR(\fBscf_value_t *\fR\fIv\fR, \fBchar *\fR\fIbuf\fR,
85 \fBsize_t\fR \fIsize\fR);
86 .fi
88 .LP
89 .nf
90 \fBssize_t\fR \fBscf_value_get_ustring\fR(\fBscf_value_t *\fR\fIv\fR, \fBchar *\fR\fIbuf\fR,
91 \fBsize_t\fR \fIsize\fR);
92 .fi
94 .LP
95 .nf
96 \fBssize_t\fR \fBscf_value_get_opaque\fR(\fBscf_value_t *\fR\fIv\fR, \fBchar *\fR\fIout\fR,
97 \fBsize_t\fR \fIlen\fR);
98 .fi
100 .LP
101 .nf
102 \fBssize_t\fR \fBscf_value_get_as_string\fR(\fBscf_value_t *\fR\fIv\fR, \fBchar *\fR\fIbuf\fR,
103 \fBsize_t\fR \fIsize\fR);
104 .fi
106 .LP
107 .nf
108 \fBssize_t\fR \fBscf_value_get_as_string_typed\fR(\fBscf_value_t *\fR\fIv\fR,
109 \fBscf_type_t\fR \fItype\fR, \fBchar *\fR\fIbuf\fR, \fBsize_t\fR \fIsize\fR);
110 .fi
112 .LP
113 .nf
114 \fBvoid\fR \fBscf_value_set_boolean\fR(\fBscf_value_t *\fR\fIv\fR, \fBuint8_t\fR \fIin\fR);
115 .fi
117 .LP
118 .nf
119 \fBvoid\fR \fBscf_value_set_count\fR(\fBscf_value_t *\fR\fIv\fR, \fBuint64_t\fR \fIin\fR);
120 .fi
122 .LP
123 .nf
124 \fBvoid\fR \fBscf_value_set_integer\fR(\fBscf_value_t *\fR\fIv\fR, \fBint64_t\fR \fIin\fR);
125 .fi
127 .LP
128 .nf
129 \fBint\fR \fBscf_value_set_time\fR(\fBscf_value_t *\fR\fIv\fR, \fBint64_t\fR \fIseconds\fR,
130 \fBint32_t\fR \fIns\fR);
131 .fi
133 .LP
134 .nf
135 \fBint\fR \fBscf_value_set_from_string\fR(\fBscf_value_t *\fR\fIv\fR, \fBscf_type_t\fR \fItype\fR,
136 \fBchar *\fR\fIin\fR);
137 .fi
139 .LP
140 .nf
141 \fBint\fR \fBscf_value_set_astring\fR(\fBscf_value_t *\fR\fIv\fR, \fBconst char *\fR\fIin\fR);
142 .fi
144 .LP
145 .nf
146 \fBint\fR \fBscf_value_set_ustring\fR(\fBscf_value_t *\fR\fIv\fR, \fBconst char *\fR\fIin\fR);
147 .fi
149 .LP
150 .nf
151 \fBint\fR \fBscf_value_set_opaque\fR(\fBscf_value_t *\fR\fIv\fR, \fBvoid *\fR\fIin\fR, \fBsize_t\fR \fIsz\fR);
152 .fi
154 .SH DESCRIPTION
155 .sp
156 .LP
157 The \fBscf_value_create()\fR function creates a new, reset \fBscf_value_t\fR
158 that holds a single typed value. The value can be used only with the handle
159 specified by \fIh\fR and objects associated with \fIh\fR.
160 .sp
161 .LP
162 The \fBscf_value_reset()\fR function resets the value to the uninitialized
163 state. The \fBscf_value_destroy()\fR function deallocates the object.
164 .sp
165 .LP
166 The \fBscf_value_type()\fR function retrieves the type of the contents of
167 \fIv\fR. The \fBscf_value_is_type()\fR function determines if a value is of a
168 particular type or any of its subtypes. The \fBscf_type_base_type()\fR function
169 returns the base type of \fItype\fR. The \fBscf_value_base_type()\fR function
170 returns the true base type of the value (the highest type reachable from the
171 value's type).
172 .sp
174 .sp
175 .TS
176 c c c
177 l l l .
178 Type Identifier Base Type Type Description
179 _
180 \fBSCF_TYPE_INVALID\fR reserved invalid type
181 \fBSCF_TYPE_BOOLEAN\fR single bit
182 \fBSCF_TYPE_COUNT\fR unsigned 64-bit quantity
183 \fBSCF_TYPE_INTEGER\fR signed 64-bit quantity
184 \fBSCF_TYPE_TIME\fR T{
185 signed 64-bit seconds, signed 32-bit nanoseconds in the range 0 <= \fIns\fR < 1,000,000,000
186 T}
187 \fBSCF_TYPE_ASTRING\fR 8-bit NUL-terminated string
188 \fBSCF_TYPE_OPAQUE\fR opaque 8-bit data
189 \fBSCF_TYPE_USTRING\fR \fBASTRING\fR 8-bit UTF-8 string
190 \fBSCF_TYPE_URI\fR \fBUSTRING\fR a URI string
191 \fBSCF_TYPE_FMRI\fR \fBURI\fR a Fault Management Resource Identifier
192 \fBSCF_TYPE_HOST\fR \fBUSTRING\fR T{
193 either a hostname, IPv4 address, or IPv6 address
194 T}
195 \fBSCF_TYPE_HOSTNAME\fR \fBHOST\fR a fully-qualified domain name
196 \fBSCF_TYPE_NET_ADDR_V4\fR \fBHOST\fR T{
197 a dotted-quad IPv4 address with optional network portion
198 T}
199 \fBSCF_TYPE_NET_ADDR_V6\fR \fBHOST\fR legal IPv6 address
200 .TE
202 .sp
203 .LP
204 The \fBscf_value_get_boolean()\fR, \fBscf_value_get_count()\fR,
205 \fBscf_value_get_integer()\fR, \fBscf_value_get_time()\fR,
206 \fBscf_value_get_astring()\fR, \fBscf_value_get_ustring()\fR, and
207 \fBscf_value_get_opaque()\fR functions read a particular type of value from
208 \fIv\fR.
209 .sp
210 .LP
211 The \fBscf_value_get_as_string()\fR and \fBscf_value_get_as_string_typed()\fR
212 functions convert the value to a string form. For
213 \fBscf_value_get_as_string_typed()\fR, the value must be a reachable subtype of
214 \fItype\fR.
215 .sp
216 .LP
217 The \fBscf_value_set_boolean()\fR, \fBscf_value_set_count()\fR,
218 \fBscf_value_set_integer()\fR, \fBscf_value_set_time()\fR,
219 \fBscf_value_set_astring()\fR, \fBscf_value_set_ustring()\fR, and
220 \fBscf_value_set_opaque()\fR functions set \fIv\fR to a particular value of a
221 particular type.
222 .sp
223 .LP
224 The \fBscf_value_set_from_string()\fR function is the inverse of
225 \fBscf_value_get_as_string()\fR. It sets \fIv\fR to the value encoded in
226 \fIbuf\fR of type \fItype\fR.
227 .sp
228 .LP
229 The \fBscf_value_set_*()\fR functions will succeed on \fBscf_value_t\fR objects
230 that have already been set.
231 .SH RETURN VALUES
232 .sp
233 .LP
234 Upon successful completion, \fBscf_value_create()\fR returns a new, reset
235 \fBscf_value_t\fR. Otherwise, it returns \fINULL\fR.
236 .sp
237 .LP
238 Upon successful completion, \fBscf_value_handle()\fR returns the handle
239 associated with \fIv\fR. Otherwise, it returns \fINULL\fR.
240 .sp
241 .LP
242 The \fBscf_value_base_type()\fR function returns the base type of the value, or
243 \fBSCF_TYPE_INVALID\fR on failure.
244 .sp
245 .LP
246 Upon successful completion, \fBscf_value_type()\fR returns the type of the
247 value. Otherwise, it returns \fBSCF_TYPE_INVALID\fR.
248 .sp
249 .LP
250 Upon successful completion, \fBscf_value_is_type()\fR,
251 \fBscf_value_get_boolean()\fR, \fBscf_value_get_count()\fR,
252 \fBscf_value_get_integer()\fR, \fBscf_value_get_time()\fR,
253 \fBscf_value_set_time()\fR, \fBscf_value_set_from_string()\fR,
254 \fBscf_value_set_astring()\fR, \fBscf_value_set_ustring()\fR, and
255 \fBscf_value_set_opaque()\fR return 0. Otherwise, they return -1.
256 .sp
257 .LP
258 Upon successful completion, \fBscf_value_get_astring()\fR,
259 \fBscf_value_get_ustring()\fR, \fBscf_value_get_as_string()\fR, and
260 \fBscf_value_get_as_string_typed()\fR return the length of the source string,
261 not including the terminating null byte. Otherwise, they return -1.
262 .sp
263 .LP
264 Upon successful completion, \fBscf_value_get_opaque()\fR returns the number of
265 bytes written. Otherwise, it returns -1.
266 .SH ERRORS
267 .sp
268 .LP
269 The \fBscf_value_create()\fR function will fail if:
270 .sp
271 .ne 2
272 .na
273 \fB\fBSCF_ERROR_HANDLE_DESTROYED\fR\fR
274 .ad
275 .RS 30n
276 The handle associated with \fIh\fR has been destroyed.
277 .RE
279 .sp
280 .ne 2
281 .na
282 \fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
283 .ad
284 .RS 30n
285 The handle is \fINULL\fR.
286 .RE
288 .sp
289 .ne 2
290 .na
291 \fB\fBSCF_ERROR_NO_MEMORY\fR\fR
292 .ad
293 .RS 30n
294 There is not enough memory to allocate an \fBscf_value_t\fR.
295 .RE
297 .sp
298 .LP
299 The \fBscf_value_handle()\fR function will fail if:
300 .sp
301 .ne 2
302 .na
303 \fB\fBSCF_ERROR_HANDLE_DESTROYED\fR\fR
304 .ad
305 .RS 30n
306 The handle associated with \fIv\fR has been destroyed.
307 .RE
309 .sp
310 .LP
311 The \fBscf_value_set_time()\fR function will fail if:
312 .sp
313 .ne 2
314 .na
315 \fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
316 .ad
317 .RS 30n
318 The nanoseconds field is not in the range 0 <= \fIns\fR < 1,000,000,000.
319 .RE
321 .sp
322 .LP
323 The \fBscf_type_base_type()\fR function will fail if:
324 .sp
325 .ne 2
326 .na
327 \fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
328 .ad
329 .RS 30n
330 The \fItype\fR argument is not a valid type.
331 .RE
333 .sp
334 .LP
335 The \fBscf_value_set_astring()\fR, \fBscf_value_set_ustring()\fR,
336 \fBscf_value_set_opaque()\fR, and \fBscf_value_set_from_string()\fR functions
337 will fail if:
338 .sp
339 .ne 2
340 .na
341 \fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
342 .ad
343 .RS 30n
344 The \fIin\fR argument is not a valid value for the specified type or is longer
345 than the maximum supported value length.
346 .RE
348 .sp
349 .LP
350 The \fBscf_type_base_type()\fR, \fBscf_value_is_type()\fR, and
351 \fBscf_value_get_as_string_typed()\fR functions will fail if:
352 .sp
353 .ne 2
354 .na
355 \fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
356 .ad
357 .RS 30n
358 The \fItype\fR argument is not a valid type.
359 .RE
361 .sp
362 .LP
363 The \fBscf_value_type()\fR, \fBscf_value_base_type()\fR,
364 \fBscf_value_get_boolean()\fR, \fBscf_value_get_count()\fR,
365 \fBscf_value_get_integer()\fR, \fBscf_value_get_time()\fR,
366 \fBscf_value_get_astring()\fR, \fBscf_value_get_ustring()\fR,
367 \fBscf_value_get_as_string()\fR, and\fBscf_value_get_as_string_typed()\fR
368 functions will fail if:
369 .sp
370 .ne 2
371 .na
372 \fB\fBSCF_ERROR_NOT_SET\fR\fR
373 .ad
374 .RS 21n
375 The \fIv\fR argument has not been set to a value.
376 .RE
378 .sp
379 .LP
380 The \fBscf_value_get_boolean()\fR, \fBscf_value_get_count()\fR,
381 \fBscf_value_get_integer()\fR, \fBscf_value_get_time()\fR,
382 \fBscf_value_get_astring()\fR, \fBscf_value_get_ustring()\fR, and
383 \fBscf_value_get_as_string_typed()\fR functions will fail if:
384 .sp
385 .ne 2
386 .na
387 \fB\fBSCF_ERROR_TYPE_MISMATCH\fR\fR
388 .ad
389 .RS 27n
390 The requested type is not the same as the value's type and is not in the
391 base-type chain.
392 .RE
394 .sp
395 .LP
396 The \fBscf_error\fR(3SCF) function can be used to retrieve the error value.
397 .SH ATTRIBUTES
398 .sp
399 .LP
400 See \fBattributes\fR(5) for descriptions of the following attributes:
401 .sp
403 .sp
404 .TS
405 box;
406 c | c
407 l | l .
408 ATTRIBUTE TYPE ATTRIBUTE VALUE
409 _
410 Interface Stability Committed
411 _
412 MT-Level Safe
413 .TE
415 .SH SEE ALSO
416 .sp
417 .LP
418 \fBlibscf\fR(3LIB), \fBscf_entry_add_value\fR(3SCF), \fBscf_error\fR(3SCF),
419 \fBattributes\fR(5)