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_name, scf_tmpl_pg_type, scf_tmpl_pg_target, scf_tmpl_pg_required, scf_tmpl_pg_common_name, scf_tmpl_pg_description - retrieve the metadata about a specific property group

cc [ flag.\|.\|. ] file.\|.\|. -lscf [ library.\|.\|. ]
#include <libscf.h>

ssize_t scf_tmpl_pg_name(const scf_pg_tmpl_t *pg_tmpl,
 char **out);

ssize_t scf_tmpl_pg_type(const scf_pg_tmpl_t *pg_tmpl,
 char **out);

ssize_t scf_tmpl_pg_target(const scf_pg_tmpl_t *pg_tmpl,
 char **out);

int scf_tmpl_pg_required(const scf_pg_tmpl_t *pg_tmpl,
 uint8_t *out)

ssize_t scf_tmpl_pg_common_name(const scf_pg_tmpl_t *pg_tmpl,
 const char * locale, char **out);

ssize_t scf_tmpl_pg_description(const scf_pg_tmpl_t *pg_tmpl,
 const char * locale, char **out);

These functions retrieve the metadata about a specific property group. They require that the template for the property group has already been located by one of the scf_tmpl_pg_create(3SCF) suite of functions.

The scf_tmpl_pg_name() function retrieves the name of the property group template and place it in *out. If the property group name is implicitly wildcarded (see smf_template(7)) in the template, this function will return a string containing SCF_TMPL_WILDCARD ("*") in *out. The caller is responsible for freeing the *out buffer on success.

The scf_tmpl_pg_type() function will retrieve the type of the property group template and place it in *out. If the property group type is implicitly wildcarded (see smf_template(7)) in the template, this function will return a string containing SCF_TMPL_WILDCARD ("*") in *out. The caller is responsible for freeing the *out buffer on success.

The scf_tmpl_pg_target() function will retrieve the target of the property group template and place it in *out. The caller is responsible for freeing the *out buffer on success.

The scf_tmpl_pg_required() function will determine whether the property group is required and place the result of that check in *out. If required is unset, out will be the default value of 0. If the property is explicitly set to required, out will be 1.

The scf_tmpl_pg_common_name() function will retrieve the property group's localized common name as currently templated and place it in *out. A locale (as described in setlocale(3C)) may be specified, or if the supplied locale is NULL, the current locale will be used. If a common_name in the specified locale is not found, the function will also look for a common_name in the C locale. Some templates will not specify the property group common name. The caller is responsible for freeing the *out buffer on success.

The scf_tmpl_pg_description() function will retrieve the property group's localized description as currently templated and place it in *out. A locale (as described in setlocale(3C)) may be specified, or if the supplied locale is NULL, the current locale will be used. If a description in the specified locale is not found, the function will also look for a description in the C locale. Some templates will not specify the property group description. The caller is responsible for freeing the *out buffer on success.

Upon successful completion, scf_tmpl_pg_name(), scf_tmpl_pg_common_name(), scf_tmpl_pg_description(), scf_tmpl_pg_target(), and scf_tmpl_pg_type() return the length of the string written, not including the terminating null byte. Otherwise, they return -1.

Upon successful completion, scf_tmpl_pg_required() returns 0. Otherwise, it returns -1.

The scf_tmpl_pg_name(), scf_tmpl_pg_common_name(), scf_tmpl_pg_description(), scf_tmpl_pg_required(), scf_tmpl_pg_target(), and scf_tmpl_pg_type() functions will fail if: SCF_ERROR_BACKEND_ACCESS SCF_ERROR_CONNECTION_BROKEN SCF_ERROR_DELETED SCF_ERROR_HANDLE_DESTROYED SCF_ERROR_INTERNAL SCF_ERROR_NO_MEMORY SCF_ERROR_NO_RESOURCES SCF_ERROR_NOT_BOUND SCF_ERROR_PERMISSION_DENIED SCF_ERROR_TEMPLATE_INVALID

The scf_tmpl_pg_common_name() and scf_tmpl_pg_description() functions will fail if: SCF_ERROR_NOT_FOUND

SCF_ERROR_INVALID_ARGUMENT See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Interface Stability Committed

MT-Level Safe

setlocale (3C), scf_tmpl_pg_create (3SCF), attributes (7), smf_template (7), svc.configd (8)