te
Copyright (c) 2008, 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_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 Configuration Facility repository

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

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

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

int scf_iter_next_value(scf_iter_t *iter, scf_value_t *out);

The scf_iter_create() function creates a new iterator associated 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. The scf_iter_property_values() function will iterate over values in the order in which they were specified with scf_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 particular 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 current properties are used. The composed view of an instance's properties 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 this iterator might not have instance as their parent and properties retrieved from such property groups might not have the indicated property group as their parent. If instance and its parent have property groups with the same name but different types, the properties in the property group of the parent are excluded. The scf_iter_instance_pgs_typed_composed() function behaves as scf_iter_instance_pgs_composed(), except the property groups of the type pgtype are returned.

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.

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.

The scf_iter_create() function will fail if:

SCF_ERROR_INVALID_ARGUMENT

SCF_ERROR_NO_MEMORY

SCF_ERROR_NO_RESOURCES

The scf_iter_handle() function will fail if:

SCF_ERROR_HANDLE_DESTROYED

The scf_iter_next_value() function will fail if:

SCF_ERROR_PERMISSION_DENIED

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

SCF_ERROR_NOT_SET

SCF_ERROR_NOT_BOUND

SCF_ERROR_CONNECTION_BROKEN

SCF_ERROR_HANDLE_MISMATCH

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 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_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

SCF_ERROR_INVALID_ARGUMENT

SCF_ERROR_NOT_BOUND

SCF_ERROR_HANDLE_MISMATCH

SCF_ERROR_CONNECTION_BROKEN

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 scf_error(3SCF) function can be used to retrieve the error value.

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;

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

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), scf_handle_create(3SCF), attributes(5)