Service Configuration Facility Library Functions
scfpgcreate(3SCF)
NAME
scfpgcreate, scfpghandle, scfpgdestroy,
scfpggetparentservice, scfpggetparentinstance,
scfpggetparentsnaplevel, scfpggetname,
scfpggettype, scfpggetflags, scfpgupdate,
scfservicegetpg, scfserviceaddpg, scfinstancegetpg,
scfinstancegetpgcomposed, scfinstanceaddpg,
scfsnaplevelgetpg, scfpgdelete,
scfpggetunderlyingpg - create and manipulate property
group handles and property groups in the Service Configura-
tion Facility
SYNOPSIS
cc [ flag... ] file... -lscf [ library... ]
#include
scfpropertygroupt *scfpgcreate(scfhandlet *handle);
scfhandlet *scfpghandle(scfpropertygroupt *pg);
void scfpgdestroy(scfpropertygroupt *pg);
int scfpggetparentservice(const scfpropertygroupt *pg,
scfservicet *svc);
int scfpggetparentinstance(const scfpropertygroupt *pg,
scfinstancet *inst);
int scfpggetparentsnaplevel(const scfpropertygroupt *pg,
scfsnaplevelt *level);
ssizet scfpggetname(const scfpropertygroupt *pg, char *buf,
sizet size);
ssizet scfpggettype(const scfpropertygroupt *pg, char *buf,
sizet size);
int scfpggetflags(const scfpropertygroupt *pg, uint32t *out);
int scfpgupdate(const scfpropertygroupt *pg);
SunOS 5.11 Last change: 7 Jan 2008 1
Service Configuration Facility Library Functions
scfpgcreate(3SCF)
int scfservicegetpg(const scfservicet *svc, const char *name,
scfpropertygroupt *pg);
int scfserviceaddpg(const scfservicet *svc,
const char *name, const char *grouptype,
uint32t flags, scfpropertygroupt *pg);
int scfinstancegetpg(const scfinstancet *inst,
const char *name, scfpropertygroupt *pg);
int scfinstancegetpgcomposed(const scfinstancet *inst,
const scfsnapshott *snapshot, const char *name,
scfpropertygroupt *pg);
int scfinstanceaddpg(const scfinstancet *inst,
const char *name, const char *grouptype, uint32t flags,
scfpropertygroupt *pg);
int scfsnaplevelgetpg(const scfsnaplevelt *level,
const char *name, const char *name, scfpropertygroupt *pg);
int scfpgdelete(scfpropertygroupt *pg);
int scfpggetunderlyingpg(const scfpropertygroupt *pg,
scfpropertygroupt *out);
DESCRIPTION
Property groups are an atomically-updated group of typed
properties. Property groups of services (see
scfservicecreate(3SCF)) or instances (see
scfinstancecreate(3SCF)) are modifiable. Property groups
of snaplevels (see scfsnaplevelcreate(3SCF)) are not
modifiable.
An scfpropertygroupt is an opaque handle that can be set
to a single property group at any given time. When an
scfpropertygroupt is set, it references a frozen-in-time
version of the property group to which it is set. Updates to
the property group will not be visible until either
scfpgupdate() is called or the property group is set
again.
SunOS 5.11 Last change: 7 Jan 2008 2
Service Configuration Facility Library Functions
scfpgcreate(3SCF)
This static view is propagated to the scfpropertyts set to
children of the property group. They will not see updates,
even if the scfpropertygroupt is updated.
The scfpgcreate() function allocates and initializes a new
scfpropertygroupt bound to handle. The scfpgdestroy()
function destroys and frees pg.
The scfpghandle() function retrieves the handle to which
pg is bound.
The scfpggetparentservice(),
scfpggetparentinstance(), and
scfpggetparentsnaplevel() functions retrieve the pro-
perty group's parent, if it is of the requested type.
The scfpggetname() and scfpggettype() functions
retrieve the name and type, respectively, of the property
group to which pg is set.
The scfpggetflags() function retrieves the flags for the
property group to which pg is set. If
SCFPGFLAGNONPERSISTENT is set, the property group is not
included in snapshots and will lose its contents upon system
shutdown or reboot. Non-persistent property groups are
mainly used for smf-internal state. See smf(5).
The scfpgupdate() function ensures that pg is attached to
the most recent version of the pg to which it is set.
The scfservicegetpg(), scfinstancegetpg(), and
scfsnaplevelgetpg() functions set pg to the property
group specified by name in the service specified by svc, the
instance specified by inst, or the snaplevel specified by
level, respectively.
The scfinstancegetpgcomposed() function sets pg to the
property group specified by name in the composed view of
inst at the time snapshot was taken. If snapshot is NUL,
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
SunOS 5.11 Last change: 7 Jan 2008 3
Service Configuration Facility Library Functions
scfpgcreate(3SCF)
(including the property group name). After a successful call
to scfinstancegetpgcomposed(), the parent of pg might
not be inst, and the parents of properties obtained from pg
might not be pg. If inst 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 scfserviceaddpg() and scfinstanceaddpg() functions
create a new property group specified by name whose type is
grouptype, and attach the pg handle (if non-null) to the
new object. The flags argument must be either 0 or
SCFPGFLAGNONPERSISTENT.
The scfpgdelete() function deletes the property group.
Versions of the property group in snapshots are not
affected.
The scfpggetunderlyingpg() function gets the first
existing underlying property group. If the property group
specified by pg is an instance property group, out is set to
the property group of the same name in the instance's
parent.
Applications can use a transaction to modify a property
group. See scftransactioncreate(3SCF).
RETURN VALUES
Upon successful completion, scfpgcreate() returns a new
scfpropertygroupt. Otherwise, it returns NUL.
Upon successful completion, scfpghandle() returns a
pointer to the handle to which pg is bound. Otherwise, it
returns NUL.
Upon successful completion, scfinstancehandle() returns
the handle instance with which it is associated. Otherwise,
it returns NUL.
Upon successful completion, scfpggetname() and
scfpggettype() return the length of the string written,
not including the terminating null byte. Otherwise, they
return -1.
SunOS 5.11 Last change: 7 Jan 2008 4
Service Configuration Facility Library Functions
scfpgcreate(3SCF)
The scfpgupdate() function returns 1 if the object was
updated, 0 if the object was already up to date, and -1 on
failure.
Upon successful completion, scfpggetparentservice(),
scfpggetparentsnaplevel(), scfpggetflags(),
scfservicegetpg(), scfserviceaddpg(),
scfpggetparentinstance(), scfinstancegetpg(),
scfinstancegetpgcomposed(), scfinstanceaddpg(),
scfsnaplevelgetpg(), scfpgdelete(), and
scfpggetunderlyingpg() return 0. Otherwise, they return
-1.
ERORS
The scfpgcreate() function will fail if:
SCFERORINVALIDARGUMENT
The handle argument is NUL.
SCFERORNOMEMORY
There is not enough memory to allocate an
scfpropertygroupt.
SCFERORNORESOURCES
The server does not have adequate resources for a new
property group handle.
The scfpghandle() function will fail if:
SCFERORHANDLEDESTROYED
The handle associated with pg has been destroyed.
The scfpgupdate() function will fail if:
SCFERORCONECTIONBROKEN
The connection to the repository was lost.
SunOS 5.11 Last change: 7 Jan 2008 5
Service Configuration Facility Library Functions
scfpgcreate(3SCF)
SCFERORDELETED
An ancestor of the property group specified by pg has
been deleted.
SCFERORINTERNAL
An internal error occurred. This can happen if pg has
been corrupted.
SCFERORINVALIDARGUMENT
The pg argument refers to an invalid
scfpropertygroupt.
SCFERORNOTBOUND
The handle is not bound.
SCFERORNOTSET
The property group specified by pg is not set.
The scfservicegetpg(), scfinstancegetpg(),
scfinstancegetpgcomposed(), scfsnaplevelgetpg(), and
scfpggetunderlyingpg() functions will fail if:
SCFERORBACKENDACES
The storage mechanism that the repository server
(svc.configd(1M)) chose for the operation denied access.
SCFERORINTERNAL
An internal error occurred.
SCFERORNORESOURCES
The server does not have the resources to complete the
request.
SunOS 5.11 Last change: 7 Jan 2008 6
Service Configuration Facility Library Functions
scfpgcreate(3SCF)
The scfpggetname(), scfpggettype(),
scfpggetflags(), scfpggetparentservice(),
scfpggetparentsnaplevel(), and
scfpggetparentinstance() functions will fail if:
SCFERORDELETED
The property group specified by pg has been deleted.
SCFERORNOTSET
The property group specified by pg is not set.
SCFERORNOTBOUND
The handle is not bound.
SCFERORCONECTIONBROKEN
The connection to the repository was lost.
The scfpggetparentservice(),
scfpggetparentsnaplevel(), and
scfpggetparentinstance() functions will fail if:
SCFERORCONSTRAINTVIOLATED
The requested parent type does not match the actual type
of the parent of the property group specified by pg.
SCFERORHANDLEMISMATCH
The property group and either the instance, the service,
or the snaplevel are not derived from the same handle.
The scfinstancegetpg(), scfinstancegetpgcomposed(),
scfservicegetpg(), scfpggetunderlyingpg(), and
scfsnaplevelgetpg() functions will fail if:
SCFERORNOTFOUND
The property group specified by name was not found.
SunOS 5.11 Last change: 7 Jan 2008 7
Service Configuration Facility Library Functions
scfpgcreate(3SCF)
The scfserviceaddpg(), scfservicegetpg(),
scfinstanceaddpg(), scfinstancegetpg(),
scfinstancegetpgcomposed(), and scfsnaplevelgetpg()
functions will fail if:
SCFERORDELETED
The service or instance has been deleted.
SCFERORNOTSET
The instance is not set.
SCFERORINVALIDARGUMENT
The value of the name argument is not a valid property
group name.
SCFERORHANDLEMISMATCH
The property group and either the instance, the service,
or the level are not derived from the same handle.
SCFERORNOTBOUND
The handle is not bound.
SCFERORCONECTIONBROKEN
The connection to the repository was lost.
The scfserviceaddpg() and scfinstanceaddpg() functions
will fail if:
SCFERORPERMISIONDENIED
The caller does not have permission to create the
requested property group.
SCFERORBACKENDREADONLY
The repository backend is read-only.
SunOS 5.11 Last change: 7 Jan 2008 8
Service Configuration Facility Library Functions
scfpgcreate(3SCF)
SCFERORBACKENDACES
The repository backend refused the modification.
SCFEROREXISTS
A {service,instance,property group} named name already
exists.
SCFERORNORESOURCES
The server does not have the resources to complete the
request.
The scfpgdelete() function will fail if:
SCFERORBACKENDACES
The repository backend refused the modification.
SCFERORBACKENDREADONLY
The repository backend is read-only.
SCFERORCONECTIONBROKEN
The connection to the repository was lost.
SCFERORDELETED
The property group has been deleted by someone else.
SCFERORNORESOURCES
The server does not have adequate resources for a new
property group handle.
SCFERORNOTSET
The property group has not been set.
SunOS 5.11 Last change: 7 Jan 2008 9
Service Configuration Facility Library Functions
scfpgcreate(3SCF)
SCFERORPERMISIONDENIED
The caller does not have permission to delete this pro-
perty group.
The scfpggetunderlyingpg() function will fail if:
SCFERORCONECTIONBROKEN
The connection to the repository was lost.
SCFERORCONSTRAINTVIOLATED
A required constraint was not met.
SCFERORDELETED
The property group has been deleted.
SCFERORHANDLEMISMATCH
The property group and out are not derived from the same
handle.
SCFERORINVALIDARGUMENT
An argument is invalid.
SCFERORNOTBOUND
The handle is not bound.
SCFERORNOTSET
The property group has not been set.
The scferror(3SCF) function can be used to retrieve the
error value.
EXAMPLES
SunOS 5.11 Last change: 7 Jan 2008 10
Service Configuration Facility Library Functions
scfpgcreate(3SCF)
Example 1 Perform a layered lookup of name in pg.
int layeredlookup(scfpropertygroupt *pg, const char *name,
scfpropertyt *out) {
scfhandlet *handle = scfpghandle(out);
scfpropertygroupt *newpg;
scfpropertygroupt *cur, *other;
int state = 0;
if (handle == NUL) {
return (-1);
}
newpg = scfpgcreate(handle);
if (newpg == NUL) {
return (-1);
}
for (;;) {
cur = state ? pg : newpg;
other = state ? newpg : pg;
state = !state;
if (scfpggetproperty(cur, name, out) != -1) {
scfpgdestroy(newpg);
return (SUCES);
}
if (scfpggetunderlyingpg(cur, other) == -1)
break;
}
scfpgdestroy(newpg);
return (NOTFOUND);
}
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Committed
MT-Level Safe
SEE ALSO
libscf(3LIB), scferror(3SCF), scfhandledecodefmri(3SCF),
scfinstancecreate(3SCF), scfpgtofmri(3SCF),
SunOS 5.11 Last change: 7 Jan 2008 11
Service Configuration Facility Library Functions
scfpgcreate(3SCF)
scfservicecreate(3SCF), scfsnaplevelcreate(3SCF),
scftransactioncreate(3SCF), attributes(5), smf(5)
SunOS 5.11 Last change: 7 Jan 2008 12
Service Configuration Facility Library Functions
scfpgcreate(3SCF)
SunOS 5.11 Last change: 7 Jan 2008 13
|
