Tribblix: manual page: scf_tmpl_pg

SCF_TMPL_PG_CREATE(3SCF) Service Configuration Facility Library Functions

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 <libscf.h>

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 functions operate 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 current 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 smf_template(7) 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 information with scf_tmpl_pg_reset(), so that it can be used
to start an iteration from scratch. All associated memory can be
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 specified. As described
above, when the snapshot argument is NULL the default running
snapshot is used. If flags includes SCF_PG_TMPL_FLAG_CURRENT, the
snapshot argument is ignored and the current configuration is used.
If flags includes SCF_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 templates
defined for the specified FMRI, snapshot, and optional property group
type. It also takes an optional flags argument. If flags includes
SCF_PG_TMPL_FLAG_CURRENT, the snapshot argument is ignored and the
"running" snapshot is 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 templates defined
on its restarter or globally.

The iterator state for scf_tmpl_iter_pgs() is stored on the template
data structure. The data structure should be allocated with
scf_tmpl_pg_create() and to continue the iteration 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 memory with
scf_tmpl_pg_destroy().

The scf_tmpl_get_by_pg() and scf_tmpl_get_by_pg_name() functions
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. It returns -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(8))
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.

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 the scf_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 repository, or the
snapshot does not exist.

SCF_ERROR_PERMISSION_DENIED

The template could not be read due to access restrictions.

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.