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)