te
Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved.
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.
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
the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
scf_value_create, scf_value_handle, scf_value_reset, scf_value_destroy, scf_value_type, scf_value_base_type, scf_value_is_type, scf_type_base_type, scf_value_get_boolean, scf_value_get_count, scf_value_get_integer, scf_value_get_time, scf_value_get_astring, scf_value_get_ustring, scf_value_get_opaque, scf_value_get_as_string, scf_value_get_as_string_typed, scf_value_set_boolean, scf_value_set_count, scf_value_set_integer, scf_value_set_time, scf_value_set_from_string, scf_value_set_astring, scf_value_set_ustring, scf_value_set_opaque - manipulate values in the Service Configuration Facility

cc [ flag.\|.\|. ] file.\|.\|. -lscf [ library.\|.\|. ] 
#include <libscf.h>

scf_value_t *scf_value_create(scf_handle_t *h);

scf_handle_t *scf_value_handle(scf_value_t *v);

void scf_value_reset(scf_value_t *v);

void scf_value_destroy(scf_value_t *v);

int scf_value_type(scf_value_t *v);

int scf_value_base_type(scf_value_t *v);

int scf_value_is_type(scf_value_t *v, scf_type_t type);

int scf_type_base_type(scf_type_t type, scf_type_t *out);

int scf_value_get_boolean(scf_value_t *v, uint8_t *out);

int scf_value_get_count(scf_value_t *v, uint64_t *out);

int scf_value_get_integer(scf_value_t *v, int64_t *out);

int scf_value_get_time(scf_value_t *v, int64_t *seconds,
 int32_t *ns);

ssize_t scf_value_get_astring(scf_value_t *v, char *buf,
 size_t size);

ssize_t scf_value_get_ustring(scf_value_t *v, char *buf,
 size_t size);

ssize_t scf_value_get_opaque(scf_value_t *v, char *out,
 size_t len);

ssize_t scf_value_get_as_string(scf_value_t *v, char *buf,
 size_t size);

ssize_t scf_value_get_as_string_typed(scf_value_t *v,
 scf_type_t type, char *buf, size_t size);

void scf_value_set_boolean(scf_value_t *v, uint8_t in);

void scf_value_set_count(scf_value_t *v, uint64_t in);

void scf_value_set_integer(scf_value_t *v, int64_t in);

int scf_value_set_time(scf_value_t *v, int64_t seconds,
 int32_t ns);

int scf_value_set_from_string(scf_value_t *v, scf_type_t type,
 char *in);

int scf_value_set_astring(scf_value_t *v, const char *in);

int scf_value_set_ustring(scf_value_t *v, const char *in);

int scf_value_set_opaque(scf_value_t *v, void *in, size_t sz);

The scf_value_create() function creates a new, reset scf_value_t that holds a single typed value. The value can be used only with the handle specified by h and objects associated with h.

The scf_value_reset() function resets the value to the uninitialized state. The scf_value_destroy() function deallocates the object.

The scf_value_type() function retrieves the type of the contents of v. The scf_value_is_type() function determines if a value is of a particular type or any of its subtypes. The scf_type_base_type() function returns the base type of type. The scf_value_base_type() function returns the true base type of the value (the highest type reachable from the value's type).

Type Identifier	Base Type	Type Description
SCF_TYPE_INVALID		reserved invalid type
SCF_TYPE_BOOLEAN		single bit
SCF_TYPE_COUNT		unsigned 64-bit quantity
SCF_TYPE_INTEGER		signed 64-bit quantity
SCF_TYPE_TIME
signed 64-bit seconds, signed 32-bit nanoseconds in the range 0 <= ns < 1,000,000,000
SCF_TYPE_ASTRING		8-bit NUL-terminated string
SCF_TYPE_OPAQUE		opaque 8-bit data
SCF_TYPE_USTRING	ASTRING	8-bit UTF-8 string
SCF_TYPE_URI	USTRING	a URI string
SCF_TYPE_FMRI	URI	a Fault Management Resource Identifier
SCF_TYPE_HOST	USTRING
either a hostname, IPv4 address, or IPv6 address
SCF_TYPE_HOSTNAME	HOST	a fully-qualified domain name
SCF_TYPE_NET_ADDR_V4	HOST
a dotted-quad IPv4 address with optional network portion
SCF_TYPE_NET_ADDR_V6	HOST	legal IPv6 address

The scf_value_get_boolean(), scf_value_get_count(), scf_value_get_integer(), scf_value_get_time(), scf_value_get_astring(), scf_value_get_ustring(), and scf_value_get_opaque() functions read a particular type of value from v.

The scf_value_get_as_string() and scf_value_get_as_string_typed() functions convert the value to a string form. For scf_value_get_as_string_typed(), the value must be a reachable subtype of type.

The scf_value_set_boolean(), scf_value_set_count(), scf_value_set_integer(), scf_value_set_time(), scf_value_set_astring(), scf_value_set_ustring(), and scf_value_set_opaque() functions set v to a particular value of a particular type.

The scf_value_set_from_string() function is the inverse of scf_value_get_as_string(). It sets v to the value encoded in buf of type type.

The scf_value_set_*() functions will succeed on scf_value_t objects that have already been set.

Upon successful completion, scf_value_create() returns a new, reset scf_value_t. Otherwise, it returns NULL.

Upon successful completion, scf_value_handle() returns the handle associated with v. Otherwise, it returns NULL.

The scf_value_base_type() function returns the base type of the value, or SCF_TYPE_INVALID on failure.

Upon successful completion, scf_value_type() returns the type of the value. Otherwise, it returns SCF_TYPE_INVALID.

Upon successful completion, scf_value_is_type(), scf_value_get_boolean(), scf_value_get_count(), scf_value_get_integer(), scf_value_get_time(), scf_value_set_time(), scf_value_set_from_string(), scf_value_set_astring(), scf_value_set_ustring(), and scf_value_set_opaque() return 0. Otherwise, they return -1.

Upon successful completion, scf_value_get_astring(), scf_value_get_ustring(), scf_value_get_as_string(), and scf_value_get_as_string_typed() return the length of the source string, not including the terminating null byte. Otherwise, they return -1.

Upon successful completion, scf_value_get_opaque() returns the number of bytes written. Otherwise, it returns -1.

The scf_value_create() function will fail if:

SCF_ERROR_HANDLE_DESTROYED

SCF_ERROR_INVALID_ARGUMENT

SCF_ERROR_NO_MEMORY

The scf_value_handle() function will fail if:

SCF_ERROR_HANDLE_DESTROYED

The scf_value_set_time() function will fail if:

SCF_ERROR_INVALID_ARGUMENT

The scf_type_base_type() function will fail if:

SCF_ERROR_INVALID_ARGUMENT

The scf_value_set_astring(), scf_value_set_ustring(), scf_value_set_opaque(), and scf_value_set_from_string() functions will fail if:

SCF_ERROR_INVALID_ARGUMENT

The scf_type_base_type(), scf_value_is_type(), and scf_value_get_as_string_typed() functions will fail if:

SCF_ERROR_INVALID_ARGUMENT

The scf_value_type(), scf_value_base_type(), scf_value_get_boolean(), scf_value_get_count(), scf_value_get_integer(), scf_value_get_time(), scf_value_get_astring(), scf_value_get_ustring(), scf_value_get_as_string(), andscf_value_get_as_string_typed() functions will fail if:

SCF_ERROR_NOT_SET

The scf_value_get_boolean(), scf_value_get_count(), scf_value_get_integer(), scf_value_get_time(), scf_value_get_astring(), scf_value_get_ustring(), and scf_value_get_as_string_typed() functions will fail if:

SCF_ERROR_TYPE_MISMATCH

The scf_error(3SCF) function can be used to retrieve the error value.

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Committed
MT-Level	Safe

libscf(3LIB), scf_entry_add_value(3SCF), scf_error(3SCF), attributes(5)