te
Copyright (c) 2008, Sun Microsystems Inc. All Rights Reserved.
The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
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

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);

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(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 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.

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.

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

SCF_ERROR_CONNECTION_BROKEN

SCF_ERROR_DELETED

SCF_ERROR_HANDLE_DESTROYED

SCF_ERROR_INTERNAL

SCF_ERROR_INVALID_ARGUMENT

SCF_ERROR_NO_MEMORY

SCF_ERROR_NO_RESOURCES

SCF_ERROR_NOT_BOUND

SCF_ERROR_NOT_FOUND

SCF_ERROR_PERMISSION_DENIED

The scf_tmpl_get_by_pg() function will fail if:

SCF_ERROR_NOT_SET

The scf_tmpl_pg_create() function will fail if:

SCF_ERROR_INVALID_ARGUMENT

SCF_ERROR_NO_MEMORY

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Committed
MT-Level	Safe

svc.configd(1M), scf_tmpl_pg_name(3SCF), scf_tmpl_prop_create(3SCF), attributes(5), smf_template(5)