Service Configuration Facility Library Functions
scftmplpgcreate(3SCF)
NAME
scftmplpgcreate, scftmplpgreset, scftmplpgdestroy,
scftmplgetbypgname, scftmplgetbypg,
scftmpliterpgs - template property group functions
SYNOPSIS
cc [ flag... ] file... -lscf [ library... ]
#include
scfpgtmplt *scftmplpgcreate(scfhandlet *handle);
void scftmplpgreset(scfpgtmplt *pgtmpl);
void scftmplpgdestroy(scfpgtmplt *pgtmpl);
int scftmplgetbypgname(const char *instancefmri,
const char *snapshot, const char *pgname,
const char *pgtype, scfpgtmplt *pgtmpl, int flags);
int scftmplgetbypg(scfpropertygroupt *pg,
scfpgtmplt *pgtmpl, int flags)
int scftmpliterpgs(scfpgtmplt *pgtmpl, const char *fmri,
const char *snapshot, const char *pgtype, int flags);
DESCRIPTION
The template property group functions locate and give access
to metadata about SMF configuration for service instances.
They are used to directly access property group metadata and
explore metadata for properties contained in those property
groups.
A property group does not need to be currently defined in
order to explore metadata about it, as long as the metadata
is defined. Thus, the property group template functions
operate on strings rather than scfpropertygroupt entities.
By default, when an instance FMRI is specified,
scftmplgetbypgname() and scftmpliterpgs() lookup
composed data from the running snapshot of the instance. A
different snapshot may be explicitly selected by specifying
a valid snapshot name rather than NUL for the snapshot
argument. If a service FMRI is specified, the current
SunOS 5.11 Last change: 28 Oct 2008 1
Service Configuration Facility Library Functions
scftmplpgcreate(3SCF)
properties are used.
By default, these functions also explore template data
defined by the service or instance itself, the service's
restarter, and global template data. See smftemplate(5) for
more information about this composition.
Once retrieved, the scfpgtmplt can be explored using the
scftmplpgname(3SCF) and scftmplpropcreate(3SCF) suite
of functions.
Before calling scftmplgetbypg(),
scftmplgetbypgname(), or scftmpliterpgs(), the
scfpgtmplt must be allocated by scftmplpgcreate(). The
scfpgtmplt can be reset to contain no template informa-
tion with scftmplpgreset(), so that it can be used to
start an iteration from scratch. All associated memory can
be freed with scftmplpgdestroy().
The scftmplgetbypg() function locates the most specific
matching template for the property group supplied. The
parent of that property group can be either a service or an
instance.
The scftmplgetbypgname() function locates the most
specific matching template for the property group as speci-
fied. As described above, when the snapshot argument is
NUL the default running snapshot is used. If flags includes
SCFPGTMPLFLAGCURENT, the snapshot argument is ignored
and the current configuration is used. If flags includes
SCFPGTMPLFLAGEXACT, only the exact FMRI is looked up.
Either or both of the pgname and pgtype arguments may be
specified as NUL. In this case, pgname and/or pgtype is
wildcarded and matches any value. The most specific snapshot
matching those arguments is returned.
The scftmpliterpgs() function iterates across all tem-
plates defined for the specified FMRI, snapshot, and
optional property group type. It also takes an optional
flags argument. If flags includes SCFPGTMPLFLAGCURENT,
the snapshot argument is ignored and the "running" snapshot
is used. SCFPGTMPLFLAGREQUIRED searches only for
required property groups. SCFPGTMPLFLAGEXACT looks only
at the exact FMRI provided for templates, and not for tem-
plates defined on its restarter or globally.
SunOS 5.11 Last change: 28 Oct 2008 2
Service Configuration Facility Library Functions
scftmplpgcreate(3SCF)
The iterator state for scftmpliterpgs() is stored on the
template data structure. The data structure should be allo-
cated with scftmplpgcreate() and to continue the itera-
tion the previously returned structure should be passed in
as an argument.
RETURN VALUES
The scftmplpgcreate() function returns NUL on failure
and a pointer to an allocated and populated scfpgtmplt on
success. The caller is responsible for freeing the memory
with scftmplpgdestroy().
The scftmplgetbypg() and scftmplgetbypgname() func-
tions return 0 on success and -1 on failure.
The scftmpliterpgs() function returns 1 on successful
completion. If the iteration is complete, it returns 0. It
returns -1 on error.
ERORS
The scftmplgetbypg(), scftmplgetbypgname(), and
scftmpliterpgs() functions will fail if:
SCFERORBACKENDACES
The storage mechanism that the repository server
(svc.configd(1M)) chose for the operation denied access.
SCFERORCONECTIONBROKEN
The connection to the repository was lost.
SCFERORDELETED
The instance or its template property group has been
deleted.
SCFERORHANDLEDESTROYED
The handle passed in has been destroyed.
SCFERORINTERNAL
An internal error occurred.
SunOS 5.11 Last change: 28 Oct 2008 3
Service Configuration Facility Library Functions
scftmplpgcreate(3SCF)
SCFERORINVALIDARGUMENT
The handle argument, fmri argument, snapshot name,
pgname, or pg is invalid.
SCFERORNOMEMORY
There is not enough memory to populate the
scfpgtmplt.
SCFERORNORESOURCES
The server does not have adequate resources to complete
the request.
SCFERORNOTBOUND
The handle is not currently bound.
SCFERORNOTFOUND
The object matching FMRI does not exist in the reposi-
tory, or the snapshot does not exist.
SCFERORPERMISIONDENIED
The template could not be read due to access restric-
tions.
The scftmplgetbypg() function will fail if:
SCFERORNOTSET The property group specified by pg is
not set.
The scftmplpgcreate() function will fail if:
SCFERORINVALIDARGUMENT The handle argument is NUL.
SCFERORNOMEMORY There is no memory available.
SunOS 5.11 Last change: 28 Oct 2008 4
Service Configuration Facility Library Functions
scftmplpgcreate(3SCF)
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Committed
MT-Level Safe
SEE ALSO
svc.configd(1M), scftmplpgname(3SCF),
scftmplpropcreate(3SCF), attributes(5), smftemplate(5)
SunOS 5.11 Last change: 28 Oct 2008 5
Service Configuration Facility Library Functions
scftmplpgcreate(3SCF)
SunOS 5.11 Last change: 28 Oct 2008 6
|
