scf_decoration_create

, scf_decoration_handle

, scf_decoration_destroy

, scf_service_get_decoration

, scf_instance_get_decoration

, scf_pg_get_decoration

, scf_property_get_decoration

, scf_property_get_value_at_layer

, scf_iter_service_decorations

, scf_iter_instance_decorations

, scf_iter_pg_decorations

, scf_iter_property_decorations

, scf_iter_decoration_values

, scf_iter_next_decoration

, scf_decoration_get_bundle

, scf_decoration_get_layer

, scf_decoration_layer_to_string

, scf_decoration_layer_from_string

, scf_decoration_is_type

, scf_decoration_type

, scf_decoration_get_value

- get decoration and layer information in the Service Configuration Facility

Synopsis

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

scf_decoration_t *scf_decoration_create(scf_handle_t **handle));

scf_handle_t *scf_decoration_handle(const scf_decoration_t *dec);

void scf_decoration_destroy(scf_decoration_t *dec);

int scf_service_get_decoration(const scf_service_t *,
     scf_decoration_layer_t , scf_decoration_t *dec);

int scf_instance_get_decoration(const scf_instance_t *inst,
     scf_decoration_layer_t layer, scf_decoration_t *dec);

int scf_pg_get_decoration(const scf_propertygroup_t *pg,
     scf_decoration_layer_t layer, scf_decoration_t *dec);

int scf_property_get_decoration(const scf_property_t *prop,
     scf_decoration_layer_t layer layer, scf_decoration_t *dec);

int scf_property_get_value_at_layer(const scf_property_t *prop,
     scf_decoration_layer_t layer layer, scf_value_t *v);

int scf_iter_service_decorations(scf_iter_t *iter,
     const scf_service_t *svc, int flags);

int scf_iter_instance_decorations(scf_iter_t *iter,
     const scf_instance_t *inst, int flags);

int scf_iter_pg_decorations(scf_iter_t *iter,
     const scf_propertygroup_t *pg, int flags);

int scf_iter_property_decorations(scf_iter_t *iter,
     const scf_property_t *);

int scf_iter_decoration_values(scf_iter_t *,
     const scf_decoration_t *dec);

int scf_iter_next_decoration(scf_iter_t *iter, scf_decoration_t *out);

ssize_t scf_decoration_get_bundle(const scf_decoration_t *dec,
     char *out, size_t len);

int scf_decoration_get_layer(const scf_decoration_t *dec,
     scf_decoration_layer_t *out);

const char *scf_decoration_layer_to_string(scf_decoration_layer_t layer);

scf_decoration_layer_t scf_decoration_layer_from_string(const char *layer);

int scf_decoration_is_type(const scf_decoration_t *dec, scf_type_t base_arg);

int scf_decoration_type(const scf_decoration_t *dec, scf_type_t *out);

int scf_decoration_get_value(const scf_decoration_t *dec,
     scf_value_t *v);

Description

The scf_decoration_*() functions allow libscf(3LIB) consumers to explore decorations of each type of libscf entity. Basic _get interfaces are provided, along with iterators for all decorations on an entity.

Decorations are metadata about entities within libscf. A single entity may have multiple decorations in the repository to describe metadata about what files or actions contributed to that entity. These decorations are disambiguated by their layer. Only four layers are used, though more may be added later: admin, site-profile, system-profile, and manifest.

These layers are ordered, with the admin layer overriding the site-profile layer, and down to the manifest layer as the lowest layer.

All property reading libscf interfaces will get the value of properties contributed only by the highest layer. All property writing libscf interfaces will change values in only the administrative layer. The interfaces documented here allow access to layers explicitly.

Additionally, decorations are completely general, and in the future non-layer decorations may be added to capture other metadata.

An scf_decoration_t is an opaque handle that can be set to a single decoration at any given time. The scf_decoration_create() function allocates and initializes a new scf_decoration_t bound to a handle. The scf_decoration_destroy() function destroys and frees the decoration. The scf_decoration_handle() function retrieves the handle to which the decoration is bound.

The scf_decoration_layer_t describes specific layers:

• SCF_DECORATION_ADMIN is the admin layer.

• SCF_DECORATION_SITE_PROFILE is the site-profile layer.

• SCF_DECORATION_SYSTEM_PROFILE is the system-profile layer.

• SCF_DECORATION_MANIFEST is the manifest layer.

The scf_service_get_decoration(), scf_instance_get_decoration(), scf_pg_get_decoration(), and scf_property_get_decoration() functions take an entity and an scf_decoration_layer_t in order to retrieve the decoration at the requested layer. The layer may also be defined as SCF_DECORATION_TOP to get the topmost layer.

The scf_property_get_value_at_layer() function retrieves the scf_value_t at the defined layer.

The scf_iter_service_decorations(), scf_iter_instance_decorations(), scf_iter_pg_decorations(), scf_iter_property_decorations(), and scf_iter_decoration_values() functions take an iterator created by scf_iter_create(3SCF) and start the iteration over all decorations on the supplied entity. The scf_iter_next_decoration() function gets the next decoration.

A set of functions offer access to information about a retrieved decoration. The scf_decoration_get_bundle() function retrieves the file, if any, that a decoration was created from.

The scf_decoration_get_layer() and scf_decoration_layer_from_string() functions retrieve the layer information. The scf_decoration_layer_to_string() function retrieves the layer information in string form.

Values within a decoration, if any, and their types can be retrieved with scf_decoration_is_type(), scf_decoration_type(), and scf_decoration_get_value().

Return Values

Upon successful completion, scf_decoration_create() returns a new scf_property_t. Upon successful completion, scf_decoration_handle() returns an scf_handle_t. Otherwise, they return NULL.

Upon successful completion, scf_service_get_decoration(), scf_instance_get_decoration(), scf_pg_get_decoration(), scf_property_get_decoration(), and scf_property_get_value_at_layer() return 0. Otherwise, they return -1.

Upon successful completion, scf_iter_service_decorations(), scf_iter_instance_decorations(), scf_iter_pg_decorations(), scf_iter_property_decorations(), and scf_iter_decoration_values() return 0. Otherwise, they return -1.

Upon successful completion, scf_iter_next_decoration() returns 1. If the iterator is complete, it returns 0. Otherwise, it returns -1.

Upon successful completion scf_decoration_get_bundle() returns the length of the string written, not including the terminating null byte. Otherwise, it returns -1.

Upon successful completion, scf_decoration_get_layer(), scf_decoration_type(), scf_decoration_get_value(), and scf_decoration_is_type() return 0. On error, they return -1.

Errors

The scf_decoration_create() function will fail if:

SCF_ERROR_INVALID_ARGUMENT

The value of the handle argument is NULL.

SCF_ERROR_NO_MEMORY

There is not enough memory to allocate an scf_decoration_t.

SCF_ERROR_NO_RESOURCES

The server does not have adequate resources for a new property handle.

The scf_decoration_handle() function will fail if:

SCF_ERROR_HANDLE_DESTROYED

The handle associated with prop has been destroyed.

The scf_service_get_decoration(), scf_instance_get_decoration(), scf_pg_get_decoration(), and scf_property_get_decoration() functions will fail if:

SCF_ERROR_CONSTRAINT_VIOLATED

Multiple decorations are available at the specified layer.

The scf_service_get_decoration(), scf_instance_get_decoration(), scf_pg_get_decoration(), scf_property_get_decoration(), scf_property_get_value_at_layer(), scf_decoration_get_bundle(), and scf_decoration_get_value() functions will fail if:

SCF_ERROR_BACKEND_ACCESS

The storage mechanism that the repository server (svc.configd(1M)) chose for the operation denied access.

SCF_ERROR_CONNECTION_BROKEN

The connection to the repository was lost.

SCF_ERROR_DELETED

The entity or an ancestor has been deleted.

SCF_ERROR_HANDLE_MISMATCH

The decoration and entity are not derived from the same handle.

SCF_ERROR_INTERNAL

An internal error occurred.

SCF_ERROR_INVALID_ARGUMENT

The entity is not the correct type.

SCF_ERROR_NO_RESOURCES

The server does not have the resources to complete the request.

SCF_ERROR_NOT_BOUND

The handle was never bound or has been unbound.

SCF_ERROR_NOT_SET

The entity is not set.

The scf_iter_service_decorations(), scf_iter_instance_decorations(), scf_iter_pg_decorations(), scf_iter_property_decorations(), scf_iter_decoration_values(), and scf_iter_next_decoration() functions will fail if:

SCF_ERROR_DELETED

The parent has been deleted.

SCF_ERROR_NOT_SET

The parent is not set.

SCF_ERROR_NOT_BOUND

The handle is not bound.

SCF_ERROR_NO_RESOURCES

The server does not have the resources to complete the request.

SCF_ERROR_CONNECTION_BROKEN

The connection to the repository was lost.

SCF_ERROR_HANDLE_MISMATCH

The iter and parent arguments are not derived from the same handle.

The scf_iter_next_decoration() function will fail if:

SCF_ERROR_INVALID_ARGUMENT

The requested object type does not match the type the iterator is walking.

The scf_decoration_get_layer(), scf_decoration_type(), and scf_decoration_is_type() functions will fail if:

SCF_ERROR_NOT_BOUND

The handle was never bound or has been unbound.

SCF_ERROR_DELETED

The parent has been deleted.

SCF_ERROR_NOT_SET

The parent is not set.

SCF_ERROR_INTERNAL

An internal error occurred.

SCF_ERROR_CONNECTION_BROKEN

The connection to the repository was lost.

The scf_decoration_is_type() function will fail if:

SCF_ERROR_INVALID_ARGUMENT

The type argument is not a valid type.

SCF_ERROR_TYPE_MISMATCH

The prop argument is not of a type compatible with type.

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

Attributes

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

See Also

svc.configd(1M), libscf(3LIB), scf_error(3SCF), scf_iter_create(3SCF), attributes(5)