Service Configuration Facility Library Functions
scf_tmpl_pg_create(3SCF)
NAME
scf_tmpl_pg_create, scf_tmpl_pg_reset, scf_tmpl_pg_destroy,
scf_tmpl_get_by_pg_name, scf_tmpl_get_by_pg,
scf_tmpl_iter_pgs - template property group functions
SYNOPSIS
cc [ flag... ] file... -lscf [ library... ]
#include
scf_pg_tmpl_t *scf_tmpl_pg_create(scf_handle_t *handle);
void scf_tmpl_pg_reset(scf_pg_tmpl_t *pg_tmpl);
void scf_tmpl_pg_destroy(scf_pg_tmpl_t *pg_tmpl);
int scf_tmpl_get_by_pg_name(const char *instance_fmri,
const char *snapshot, const char *pg_name,
const char *pg_type, scf_pg_tmpl_t *pg_tmpl, int flags);
int scf_tmpl_get_by_pg(scf_propertygroup_t *pg,
scf_pg_tmpl_t *pg_tmpl, int flags)
int scf_tmpl_iter_pgs(scf_pg_tmpl_t *pg_tmpl, const char *fmri,
const char *snapshot, const char *pg_type, 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 functionsoperate on strings rather than scf_propertygroup_t entities.
By default, when an instance FMRI is specified,scf_tmpl_get_by_pg_name() and scf_tmpl_iter_pgs() 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 NULL for the snapshot argument. If a service FMRI is specified, the currentSunOS 5.11 Last change: 28 Oct 2008 1
Service Configuration Facility Library Functionsscf_tmpl_pg_create(3SCF)
properties are used. By default, these functions also explore template data defined by the service or instance itself, the service'srestarter, and global template data. See smf_template(5) for
more information about this composition.Once retrieved, the scf_pg_tmpl_t can be explored using the
scf_tmpl_pg_name(3SCF) and scf_tmpl_prop_create(3SCF) suite
of functions.Before calling scf_tmpl_get_by_pg(),
scf_tmpl_get_by_pg_name(), or scf_tmpl_iter_pgs(), the
scf_pg_tmpl_t must be allocated by scf_tmpl_pg_create(). The
scf_pg_tmpl_t can be reset to contain no template informa-
tion with scf_tmpl_pg_reset(), so that it can be used to
start an iteration from scratch. All associated memory canbe freed with scf_tmpl_pg_destroy().
The scf_tmpl_get_by_pg() 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 scf_tmpl_get_by_pg_name() function locates the most
specific matching template for the property group as speci-
fied. As described above, when the snapshot argument is NULL the default running snapshot is used. If flags includesSCF_PG_TMPL_FLAG_CURRENT, the snapshot argument is ignored
and the current configuration is used. If flags includesSCF_PG_TMPL_FLAG_EXACT, only the exact FMRI is looked up.
Either or both of the pg_name and pg_type arguments may be
specified as NULL. In this case, pg_name and/or pg_type is
wildcarded and matches any value. The most specific snapshot matching those arguments is returned.The scf_tmpl_iter_pgs() function iterates across all tem-
plates defined for the specified FMRI, snapshot, and optional property group type. It also takes an optionalflags argument. If flags includes SCF_PG_TMPL_FLAG_CURRENT,
the snapshot argument is ignored and the "running" snapshotis used. SCF_PG_TMPL_FLAG_REQUIRED searches only for
required property groups. SCF_PG_TMPL_FLAG_EXACT 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 Functionsscf_tmpl_pg_create(3SCF)
The iterator state for scf_tmpl_iter_pgs() is stored on the
template data structure. The data structure should be allo-
cated with scf_tmpl_pg_create() and to continue the itera-
tion the previously returned structure should be passed in as an argument.RETURN VALUES
The scf_tmpl_pg_create() function returns NULL on failure
and a pointer to an allocated and populated scf_pg_tmpl_t on
success. The caller is responsible for freeing the memorywith scf_tmpl_pg_destroy().
The scf_tmpl_get_by_pg() and scf_tmpl_get_by_pg_name() func-
tions return 0 on success and -1 on failure.
The scf_tmpl_iter_pgs() function returns 1 on successful
completion. If the iteration is complete, it returns 0. Itreturns -1 on error.
ERRORS
The scf_tmpl_get_by_pg(), scf_tmpl_get_by_pg_name(), and
scf_tmpl_iter_pgs() functions will fail if:
SCF_ERROR_BACKEND_ACCESS
The storage mechanism that the repository server (svc.configd(1M)) chose for the operation denied access.SCF_ERROR_CONNECTION_BROKEN
The connection to the repository was lost.SCF_ERROR_DELETED
The instance or its template property group has been deleted.SCF_ERROR_HANDLE_DESTROYED
The handle passed in has been destroyed.SCF_ERROR_INTERNAL
An internal error occurred.SunOS 5.11 Last change: 28 Oct 2008 3
Service Configuration Facility Library Functionsscf_tmpl_pg_create(3SCF)
SCF_ERROR_INVALID_ARGUMENT
The handle argument, fmri argument, snapshot name,pg_name, or pg is invalid.
SCF_ERROR_NO_MEMORY
There is not enough memory to populate thescf_pg_tmpl_t.
SCF_ERROR_NO_RESOURCES
The server does not have adequate resources to complete the request.SCF_ERROR_NOT_BOUND
The handle is not currently bound.SCF_ERROR_NOT_FOUND
The object matching FMRI does not exist in the reposi-
tory, or the snapshot does not exist.SCF_ERROR_PERMISSION_DENIED
The template could not be read due to access restric-
tions.The scf_tmpl_get_by_pg() function will fail if:
SCF_ERROR_NOT_SET The property group specified by pg is
not set.The scf_tmpl_pg_create() function will fail if:
SCF_ERROR_INVALID_ARGUMENT The handle argument is NULL.
SCF_ERROR_NO_MEMORY There is no memory available.
SunOS 5.11 Last change: 28 Oct 2008 4
Service Configuration Facility Library Functionsscf_tmpl_pg_create(3SCF)
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Interface Stability | Committed ||_____________________________|_____________________________|
| MT-Level | Safe |
|_____________________________|_____________________________|
SEE ALSO
svc.configd(1M), scf_tmpl_pg_name(3SCF),
scf_tmpl_prop_create(3SCF), attributes(5), smf_template(5)
SunOS 5.11 Last change: 28 Oct 2008 5
Service Configuration Facility Library Functionsscf_tmpl_pg_create(3SCF)
SunOS 5.11 Last change: 28 Oct 2008 6