Service Configuration Facility Library Functions
scf_iter_create(3SCF)
NAME
scf_iter_create, scf_iter_handle, scf_iter_destroy,
scf_iter_reset, scf_iter_handle_scopes,
scf_iter_scope_services, scf_iter_service_instances,
scf_iter_service_pgs, scf_iter_service_pgs_typed,
scf_iter_instance_snapshots, scf_iter_snaplevel_pgs,
scf_iter_snaplevel_pgs_typed, scf_iter_instance_pgs,
scf_iter_instance_pgs_typed, scf_iter_instance_pgs_composed,
scf_iter_instance_pgs_typed_composed,
scf_iter_pg_properties, scf_iter_property_values,
scf_iter_next_scope, scf_iter_next_service,
scf_iter_next_instance, scf_iter_next_snapshot,
scf_iter_next_pg, scf_iter_next_property,
scf_iter_next_value - iterate through the Service Configura-
tion Facility repositorySYNOPSIS
cc [ flag... ] file... -lscf [ library... ]
#include
scf_iter_t *scf_iter_create(scf_handle_t *handle);
scf_handle_t *scf_iter_handle(scf_iter_t *iter);
void scf_iter_destroy(scf_iter_t *iter);
void scf_iter_reset(scf_iter_t *iter);
int scf_iter_handle_scopes(scf_iter_t *iter, const scf_handle_t *h);
int scf_iter_scope_services(scf_iter_t *iter, const scf_scope_t *parent);
int scf_iter_service_instances(scf_iter_t *iter,
const scf_service_t *parent);
int scf_iter_service_pgs(scf_iter_t *iter, const scf_service_t *parent);
int scf_iter_service_pgs_typed(scf_iter_t *iter,
const scf_service_t *parent, const char *pgtype);
int scf_iter_instance_snapshots(scf_iter_t *iter,
const scf_instance_t *parent);
SunOS 5.11 Last change: 4 Dec 2008 1
Service Configuration Facility Library Functionsscf_iter_create(3SCF)
int scf_iter_snaplevel_pgs(scf_iter_t *iter,
const scf_snaplevel_t *parent);
int scf_iter_snaplevel_pgs_typed(scf_iter_t *iter,
const scf_snaplevel_t *parent, const char *pgtype);
int scf_iter_instance_pgs(scf_iter_t *iter, scf_instance_t *parent);
int scf_iter_instance_pgs_typed(scf_iter_t *iter,
scf_instance_t *parent, const char *pgtype);
int scf_iter_instance_pgs_composed(scf_iter_t *iter,
const scf_instance_t *instance, const scf_snapshot_t *snapshot);
int scf_iter_instance_pgs_typed_composed(scf_iter_t *iter,
const scf_instance_t *instance, const scf_snapshot_t *snapshot,
const char *pgtype);int scf_iter_pg_properties(scf_iter_t *iter,
const scf_propertygroup_t *parent);
int scf_iter_property_values(scf_iter_t *iter,
const scf_property_t *parent);
int scf_iter_next_scope(scf_iter_t *iter, scf_scope_t *out);
int scf_iter_next_service(scf_iter_t *iter, scf_service_t *out);
int scf_iter_next_instance(scf_iter_t *iter, scf_instance_t *out);
int scf_iter_next_snapshot(scf_iter_t *iter, scf_snapshot_t *out);
int scf_iter_next_pg(scf_iter_t *iter, scf_propertygroup_t *out);
int scf_iter_next_property(scf_iter_t *iter, scf_property_t *out);
SunOS 5.11 Last change: 4 Dec 2008 2
Service Configuration Facility Library Functionsscf_iter_create(3SCF)
int scf_iter_next_value(scf_iter_t *iter, scf_value_t *out);
DESCRIPTION
The scf_iter_create() function creates a new iterator asso-
ciated with handle. The scf_iter_destroy() function destroys
an iteration.The scf_iter_reset() function releases any resources
involved with an active iteration and returns the iterator to its initial state.The scf_iter_handle_scopes(), scf_iter_scope_services(),
scf_iter_service_instances(), scf_iter_instance_snapshots(),
scf_iter_service_pgs(), scf_iter_instance_pgs(),
scf_iter_snaplevel_pgs(), scf_iter_pg_properties(), and
scf_iter_property_values() functions set up a new iteration
of all the children parent of a particular type. Thescf_iter_property_values() function will iterate over values
in the order in which they were specified withscf_entry_add_value(3SCF).
The scf_iter_service_pgs_typed(),
scf_iter_instance_pgs_typed(), and
scf_iter_snaplevel_pgs_typed() functions iterate over the
child property groups of parent, but restrict them to a par-
ticular property group type.The scf_iter_instance_pgs_composed() function sets up a new
iteration of the composed view of instance's children at the time snapshot was taken. If snapshot is NULL, the currentproperties are used. The composed view of an instance's pro-
perties is the union of the properties of the instance and its ancestors. Properties of the instance take precedence over properties of the service with the same name, including property group name. Property groups retrieved with thisiterator might not have instance as their parent and proper-
ties retrieved from such property groups might not have the indicated property group as their parent. If instance andits parent have property groups with the same name but dif-
ferent types, the properties in the property group of the parent are excluded. Thescf_iter_instance_pgs_typed_composed() function behaves as
scf_iter_instance_pgs_composed(), except the property groups
of the type pgtype are returned.SunOS 5.11 Last change: 4 Dec 2008 3
Service Configuration Facility Library Functionsscf_iter_create(3SCF)
The scf_iter_next_scope(), scf_iter_next_service(),
scf_iter_next_instance(), scf_iter_next_snapshot(),
scf_iter_next_pg(), scf_iter_next_property(), and
scf_iter_next_value() functions retrieve the next element of
the iteration.RETURN VALUES
Upon successful completion, scf_iter_create() returns a
pointer to a new iterator. Otherwise, it returns NULL.Upon successful completion, scf_iter_handle() returns the
handle associated with iter. Otherwise it returns NULL.Upon successful completion, scf_iter_handle_scopes(),
scf_iter_scope_services(), scf_iter_service_instances(),
scf_iter_instance_snapshots(), scf_iter_service_pgs(),
scf_iter_instance_pgs(), scf_iter_snaplevel_pgs(),
scf_iter_pg_properties(), scf_iter_property_values(),
scf_iter_service_pgs_typed(),
scf_iter_instance_pgs_composed(),
scf_iter_instance_pgs_typed(),
scf_iter_instance_pgs_typed_composed(), and
scf_iter_snaplevel_pgs_typed() return 0. Otherwise, they
return -1.
Upon successful completion, scf_iter_next_scope(),
scf_iter_next_service(), scf_iter_next_instance(),
scf_iter_next_snapshot(), scf_iter_next_pg(),
scf_iter_next_property(), and scf_iter_next_value() return
1. If the iterator is complete, they return 0. Otherwise,they return -1.
ERRORS
The scf_iter_create() function will fail if:
SCF_ERROR_INVALID_ARGUMENT The handle argument is NULL.
SCF_ERROR_NO_MEMORY There is no memory available.
SCF_ERROR_NO_RESOURCES The server does not have ade-
quate resources for a new iteration.SunOS 5.11 Last change: 4 Dec 2008 4
Service Configuration Facility Library Functionsscf_iter_create(3SCF)
The scf_iter_handle() function will fail if:
SCF_ERROR_HANDLE_DESTROYED The handle associated with
iter has been destroyed.The scf_iter_next_value() function will fail if:
SCF_ERROR_PERMISSION_DENIED
The value could not be read due to access restrictions.The scf_iter_handle_scopes(), scf_iter_scope_services(),
scf_iter_service_instances(), scf_iter_instance_snapshots(),
scf_iter_service_pgs(), scf_iter_instance_pgs(),
scf_iter_instance_pgs_composed(), scf_iter_snaplevel_pgs(),
scf_iter_pg_properties(), scf_iter_property_values(),
scf_iter_service_pgs_typed(), scf_iter_instance_pgs_typed(),
scf_iter_instance_pgs_typed_composed(), and
scf_iter_snaplevel_pgs_typed() 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_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.SunOS 5.11 Last change: 4 Dec 2008 5
Service Configuration Facility Library Functionsscf_iter_create(3SCF)
The scf_iter_service_pgs_typed(),
scf_iter_instance_pgs_typed(),
scf_iter_instance_pgs_typed_composed(), and
scf_iter_snaplevel_pgs_typed() functions will fail if:
SCF_ERROR_INVALID_ARGUMENT The pgtype argument is not a
valid property group type.The scf_iter_next_service(), scf_iter_next_instance(),
scf_iter_next_snapshot(), scf_iter_next_pg(),
scf_iter_next_property(), and scf_iter_next_value() func-
tions will fail if:SCF_ERROR_DELETED The parent the iterator is attached to
has been deleted.The scf_iter_next_scope(), scf_iter_next_service(),
scf_iter_next_instance(), scf_iter_next_snapshot(),
scf_iter_next_pg(),scf_iter_next_property(), and
scf_iter_next_value() functions will fail if:
SCF_ERROR_NOT_SET
The iterator is not set.SCF_ERROR_INVALID_ARGUMENT
The requested object type does not match the type the iterator is walking.SCF_ERROR_NOT_BOUND
The handle is not bound.SCF_ERROR_HANDLE_MISMATCH
The iter and parent arguments are not derived from the same handle.SCF_ERROR_CONNECTION_BROKEN
The connection to the repository was lost.SunOS 5.11 Last change: 4 Dec 2008 6
Service Configuration Facility Library Functionsscf_iter_create(3SCF)
The scf_iter_scope_services(), scf_iter_service_instances(),
scf_iter_service_pgs(), scf_iter_instance_snapshots(),
scf_iter_instance_pgs(), scf_iter_instance_pgs_composed(),
scf_iter_snaplevel_pgs(), scf_iter_pg_properties(),
scf_iter_property_values(), scf_iter_service_pgs_typed(),
scf_iter_instance_pgs_typed(),
scf_iter_instance_pgs_typed_composed(),
scf_iter_snaplevel_pgs_typed(), scf_iter_next_service(),
scf_iter_next_instance(), scf_iter_next_snapshot(),
scf_iter_next_pg(), and scf_iter_next_property() functions
will fail if:SCF_ERROR_NO_RESOURCES The server does not have the
resources to complete the request.The scf_error(3SCF) function can be used to retrieve the
error value.EXAMPLES
Example 1 Iterate over all instances under a service.scf_iter_t *iter = scf_iter_create(handle);
if (iter == NULL || scf_iter_service_instances(iter, parent) == -1) {
/* failure */ }while ((r = scf_iter_next_instance(iter, child)) > 0) {
/* process child */ } if (r < 0) { /* failure */ }scf_iter_destroy(iter);
Example 2 Connect to the repository, walk all services and instances and print their FMRIs.scf_handle_t *handle = scf_handle_create(SCF_VERSION);
scf_scope_t *scope = scf_scope_create(handle);
scf_service_t *svc = scf_service_create(handle);
scf_instance_t *inst = scf_instance_create(handle);
scf_iter_t *svc_iter = scf_iter_create(handle);
scf_iter_t *inst_iter = scf_iter_create(handle);
size_t sz = scf_limit(SCF_LIMIT_MAX_FMRI_LENGTH) + 1;
char *fmri = malloc(sz + 1); int r;SunOS 5.11 Last change: 4 Dec 2008 7
Service Configuration Facility Library Functionsscf_iter_create(3SCF)
if (handle == NULL || scope == NULL || svc == NULL ||inst == NULL || svc_iter == NULL || inst_iter == NULL ||
fmri == NULL) { /* failure */ }if (scf_handle_bind(handle) == -1 ||
scf_handle_get_scope(handle, SCF_SCOPE_LOCAL, scope) == -1 ||
scf_iter_scope_services(svc_iter, scope) == -1) {
/* failure */ }while ((r = scf_iter_next_service(svc_iter, svc)) > 0) {
if (scf_service_to_fmri(svc, fmri, sz) < 0) {
/* failure */ } puts(fmri);if (scf_iter_service_instances(inst_iter, svc) < 0) {
/* failure */ }while ((r = scf_iter_next_instance(inst_iter, inst)) > 0) {
if (scf_instance_to_fmri(inst, fmri, sz) < 0) {
/* failure */ } puts(fmri); } if (r < 0) break; } if (r < 0) { /* failure */ }scf_handle_destroy(handle);
scf_scope_destroy(scope);
scf_service_destroy(svc);
scf_instance_destroy(inst);
scf_iter_destroy(svc_iter);
scf_iter_destroy(inst_iter);
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:SunOS 5.11 Last change: 4 Dec 2008 8
Service Configuration Facility Library Functionsscf_iter_create(3SCF)
______________________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Interface Stability | Committed ||_____________________________|_____________________________|
| MT-Level | Safe |
|_____________________________|_____________________________|
SEE ALSO
libscf(3LIB), scf_entry_add_value(3SCF), scf_error(3SCF),
scf_handle_create(3SCF), attributes(5)
SunOS 5.11 Last change: 4 Dec 2008 9
Service Configuration Facility Library Functionsscf_iter_create(3SCF)
SunOS 5.11 Last change: 4 Dec 2008 10