Service Configuration Facility Library Functions
scfitercreate(3SCF)
NAME
scfitercreate, scfiterhandle, scfiterdestroy,
scfiterreset, scfiterhandlescopes,
scfiterscopeservices, scfiterserviceinstances,
scfiterservicepgs, scfiterservicepgstyped,
scfiterinstancesnapshots, scfitersnaplevelpgs,
scfitersnaplevelpgstyped, scfiterinstancepgs,
scfiterinstancepgstyped, scfiterinstancepgscomposed,
scfiterinstancepgstypedcomposed,
scfiterpgproperties, scfiterpropertyvalues,
scfiternextscope, scfiternextservice,
scfiternextinstance, scfiternextsnapshot,
scfiternextpg, scfiternextproperty,
scfiternextvalue - iterate through the Service Configura-
tion Facility repository
SYNOPSIS
cc [ flag... ] file... -lscf [ library... ]
#include
scfitert *scfitercreate(scfhandlet *handle);
scfhandlet *scfiterhandle(scfitert *iter);
void scfiterdestroy(scfitert *iter);
void scfiterreset(scfitert *iter);
int scfiterhandlescopes(scfitert *iter, const scfhandlet *h);
int scfiterscopeservices(scfitert *iter, const scfscopet *parent);
int scfiterserviceinstances(scfitert *iter,
const scfservicet *parent);
int scfiterservicepgs(scfitert *iter, const scfservicet *parent);
int scfiterservicepgstyped(scfitert *iter,
const scfservicet *parent, const char *pgtype);
int scfiterinstancesnapshots(scfitert *iter,
const scfinstancet *parent);
SunOS 5.11 Last change: 4 Dec 2008 1
Service Configuration Facility Library Functions
scfitercreate(3SCF)
int scfitersnaplevelpgs(scfitert *iter,
const scfsnaplevelt *parent);
int scfitersnaplevelpgstyped(scfitert *iter,
const scfsnaplevelt *parent, const char *pgtype);
int scfiterinstancepgs(scfitert *iter, scfinstancet *parent);
int scfiterinstancepgstyped(scfitert *iter,
scfinstancet *parent, const char *pgtype);
int scfiterinstancepgscomposed(scfitert *iter,
const scfinstancet *instance, const scfsnapshott *snapshot);
int scfiterinstancepgstypedcomposed(scfitert *iter,
const scfinstancet *instance, const scfsnapshott *snapshot,
const char *pgtype);
int scfiterpgproperties(scfitert *iter,
const scfpropertygroupt *parent);
int scfiterpropertyvalues(scfitert *iter,
const scfpropertyt *parent);
int scfiternextscope(scfitert *iter, scfscopet *out);
int scfiternextservice(scfitert *iter, scfservicet *out);
int scfiternextinstance(scfitert *iter, scfinstancet *out);
int scfiternextsnapshot(scfitert *iter, scfsnapshott *out);
int scfiternextpg(scfitert *iter, scfpropertygroupt *out);
int scfiternextproperty(scfitert *iter, scfpropertyt *out);
SunOS 5.11 Last change: 4 Dec 2008 2
Service Configuration Facility Library Functions
scfitercreate(3SCF)
int scfiternextvalue(scfitert *iter, scfvaluet *out);
DESCRIPTION
The scfitercreate() function creates a new iterator asso-
ciated with handle. The scfiterdestroy() function destroys
an iteration.
The scfiterreset() function releases any resources
involved with an active iteration and returns the iterator
to its initial state.
The scfiterhandlescopes(), scfiterscopeservices(),
scfiterserviceinstances(), scfiterinstancesnapshots(),
scfiterservicepgs(), scfiterinstancepgs(),
scfitersnaplevelpgs(), scfiterpgproperties(), and
scfiterpropertyvalues() functions set up a new iteration
of all the children parent of a particular type. The
scfiterpropertyvalues() function will iterate over values
in the order in which they were specified with
scfentryaddvalue(3SCF).
The scfiterservicepgstyped(),
scfiterinstancepgstyped(), and
scfitersnaplevelpgstyped() functions iterate over the
child property groups of parent, but restrict them to a par-
ticular property group type.
The scfiterinstancepgscomposed() function sets up a new
iteration of the composed view of instance's children at the
time snapshot was taken. If snapshot is NUL, the current
properties 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 this
iterator 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 and
its parent have property groups with the same name but dif-
ferent types, the properties in the property group of the
parent are excluded. The
scfiterinstancepgstypedcomposed() function behaves as
scfiterinstancepgscomposed(), except the property groups
of the type pgtype are returned.
SunOS 5.11 Last change: 4 Dec 2008 3
Service Configuration Facility Library Functions
scfitercreate(3SCF)
The scfiternextscope(), scfiternextservice(),
scfiternextinstance(), scfiternextsnapshot(),
scfiternextpg(), scfiternextproperty(), and
scfiternextvalue() functions retrieve the next element of
the iteration.
RETURN VALUES
Upon successful completion, scfitercreate() returns a
pointer to a new iterator. Otherwise, it returns NUL.
Upon successful completion, scfiterhandle() returns the
handle associated with iter. Otherwise it returns NUL.
Upon successful completion, scfiterhandlescopes(),
scfiterscopeservices(), scfiterserviceinstances(),
scfiterinstancesnapshots(), scfiterservicepgs(),
scfiterinstancepgs(), scfitersnaplevelpgs(),
scfiterpgproperties(), scfiterpropertyvalues(),
scfiterservicepgstyped(),
scfiterinstancepgscomposed(),
scfiterinstancepgstyped(),
scfiterinstancepgstypedcomposed(), and
scfitersnaplevelpgstyped() return 0. Otherwise, they
return -1.
Upon successful completion, scfiternextscope(),
scfiternextservice(), scfiternextinstance(),
scfiternextsnapshot(), scfiternextpg(),
scfiternextproperty(), and scfiternextvalue() return
1. If the iterator is complete, they return 0. Otherwise,
they return -1.
ERORS
The scfitercreate() function will fail if:
SCFERORINVALIDARGUMENT The handle argument is NUL.
SCFERORNOMEMORY There is no memory available.
SCFERORNORESOURCES 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 Functions
scfitercreate(3SCF)
The scfiterhandle() function will fail if:
SCFERORHANDLEDESTROYED The handle associated with
iter has been destroyed.
The scfiternextvalue() function will fail if:
SCFERORPERMISIONDENIED
The value could not be read due to access restrictions.
The scfiterhandlescopes(), scfiterscopeservices(),
scfiterserviceinstances(), scfiterinstancesnapshots(),
scfiterservicepgs(), scfiterinstancepgs(),
scfiterinstancepgscomposed(), scfitersnaplevelpgs(),
scfiterpgproperties(), scfiterpropertyvalues(),
scfiterservicepgstyped(), scfiterinstancepgstyped(),
scfiterinstancepgstypedcomposed(), and
scfitersnaplevelpgstyped() functions will fail if:
SCFERORDELETED
The parent has been deleted.
SCFERORNOTSET
The parent is not set.
SCFERORNOTBOUND
The handle is not bound.
SCFERORCONECTIONBROKEN
The connection to the repository was lost.
SCFERORHANDLEMISMATCH
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 Functions
scfitercreate(3SCF)
The scfiterservicepgstyped(),
scfiterinstancepgstyped(),
scfiterinstancepgstypedcomposed(), and
scfitersnaplevelpgstyped() functions will fail if:
SCFERORINVALIDARGUMENT The pgtype argument is not a
valid property group type.
The scfiternextservice(), scfiternextinstance(),
scfiternextsnapshot(), scfiternextpg(),
scfiternextproperty(), and scfiternextvalue() func-
tions will fail if:
SCFERORDELETED The parent the iterator is attached to
has been deleted.
The scfiternextscope(), scfiternextservice(),
scfiternextinstance(), scfiternextsnapshot(),
scfiternextpg(),scfiternextproperty(), and
scfiternextvalue() functions will fail if:
SCFERORNOTSET
The iterator is not set.
SCFERORINVALIDARGUMENT
The requested object type does not match the type the
iterator is walking.
SCFERORNOTBOUND
The handle is not bound.
SCFERORHANDLEMISMATCH
The iter and parent arguments are not derived from the
same handle.
SCFERORCONECTIONBROKEN
The connection to the repository was lost.
SunOS 5.11 Last change: 4 Dec 2008 6
Service Configuration Facility Library Functions
scfitercreate(3SCF)
The scfiterscopeservices(), scfiterserviceinstances(),
scfiterservicepgs(), scfiterinstancesnapshots(),
scfiterinstancepgs(), scfiterinstancepgscomposed(),
scfitersnaplevelpgs(), scfiterpgproperties(),
scfiterpropertyvalues(), scfiterservicepgstyped(),
scfiterinstancepgstyped(),
scfiterinstancepgstypedcomposed(),
scfitersnaplevelpgstyped(), scfiternextservice(),
scfiternextinstance(), scfiternextsnapshot(),
scfiternextpg(), and scfiternextproperty() functions
will fail if:
SCFERORNORESOURCES The server does not have the
resources to complete the request.
The scferror(3SCF) function can be used to retrieve the
error value.
EXAMPLES
Example 1 Iterate over all instances under a service.
scfitert *iter = scfitercreate(handle);
if (iter == NUL scfiterserviceinstances(iter, parent) == -1) {
/* failure */
}
while ((r = scfiternextinstance(iter, child)) > 0) {
/* process child */
}
if (r < 0) {
/* failure */
}
scfiterdestroy(iter);
Example 2 Connect to the repository, walk all services and
instances and print their FMRIs.
scfhandlet *handle = scfhandlecreate(SCFVERSION);
scfscopet *scope = scfscopecreate(handle);
scfservicet *svc = scfservicecreate(handle);
scfinstancet *inst = scfinstancecreate(handle);
scfitert *svciter = scfitercreate(handle);
scfitert *institer = scfitercreate(handle);
sizet sz = scflimit(SCFLIMITMAXFMRILENGTH) ] 1;
char *fmri = malloc(sz ] 1);
int r;
SunOS 5.11 Last change: 4 Dec 2008 7
Service Configuration Facility Library Functions
scfitercreate(3SCF)
if (handle == NUL scope == NUL svc == NUL
inst == NUL svciter == NUL institer == NUL
fmri == NUL) {
/* failure */
}
if (scfhandlebind(handle) == -1
scfhandlegetscope(handle, SCFSCOPELOCAL, scope) == -1
scfiterscopeservices(svciter, scope) == -1) {
/* failure */
}
while ((r = scfiternextservice(svciter, svc)) > 0) {
if (scfservicetofmri(svc, fmri, sz) < 0) {
/* failure */
}
puts(fmri);
if (scfiterserviceinstances(institer, svc) < 0) {
/* failure */
}
while ((r = scfiternextinstance(institer, inst)) > 0) {
if (scfinstancetofmri(inst, fmri, sz) < 0) {
/* failure */
}
puts(fmri);
}
if (r < 0)
break;
}
if (r < 0) {
/* failure */
}
scfhandledestroy(handle);
scfscopedestroy(scope);
scfservicedestroy(svc);
scfinstancedestroy(inst);
scfiterdestroy(svciter);
scfiterdestroy(institer);
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
SunOS 5.11 Last change: 4 Dec 2008 8
Service Configuration Facility Library Functions
scfitercreate(3SCF)
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Committed
MT-Level Safe
SEE ALSO
libscf(3LIB), scfentryaddvalue(3SCF), scferror(3SCF),
scfhandlecreate(3SCF), attributes(5)
SunOS 5.11 Last change: 4 Dec 2008 9
Service Configuration Facility Library Functions
scfitercreate(3SCF)
SunOS 5.11 Last change: 4 Dec 2008 10
|
