Tribblix: manual page: scf_value

SCF_VALUE_CREATE(3SCF) Service Configuration Facility Library Functions

NAME

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

SYNOPSIS

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);

DESCRIPTION

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.

RETURN VALUES

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.

ERRORS

The scf_value_create() function will fail if:

SCF_ERROR_HANDLE_DESTROYED
The handle associated with h has been
destroyed.

SCF_ERROR_INVALID_ARGUMENT
The handle is NULL.

SCF_ERROR_NO_MEMORY
There is not enough memory to allocate
an scf_value_t.

The scf_value_handle() function will fail if:

SCF_ERROR_HANDLE_DESTROYED
The handle associated with v has been
destroyed.

The scf_value_set_time() function will fail if:

SCF_ERROR_INVALID_ARGUMENT
The nanoseconds field is not in the
range 0 <= ns < 1,000,000,000.

The scf_type_base_type() function will fail if:

SCF_ERROR_INVALID_ARGUMENT
The type argument is not a valid type.

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 in argument is not a valid value
for the specified type or is longer
than the maximum supported value
length.

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 type argument is not a valid type.

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(), and scf_value_get_as_string_typed()
functions will fail if:

SCF_ERROR_NOT_SET
The v argument has not been set to a value.

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 requested type is not the same as the
value's type and is not in the base-type
chain.

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