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 3SCF "Oct 28, 2008"
 NAME
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

 SYNOPSIS


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,
 char * locale, char **out);






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




 DESCRIPTION

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.

 RETURN VALUES

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.

 ERRORS

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


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 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_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_PERMISSION_DENIED


The template could not be read due to access restrictions.



SCF_ERROR_TEMPLATE_INVALID


The template data is invalid.





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


The property does not exist or exists and has no value.



SCF_ERROR_INVALID_ARGUMENT


The locale string is too long.




 ATTRIBUTES

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






ATTRIBUTE TYPE ATTRIBUTE VALUE
Interface Stability Committed
MT-Level Safe



 SEE ALSO

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