'\" 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]
.TH SCF_TMPL_PG_NAME 3SCF "Sep 15, 2024"
.SH 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
.SH SYNOPSIS
.nf
cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lscf\fR [ \fIlibrary\fR\&.\|.\|. ]
#include <libscf.h>

\fBssize_t\fR \fBscf_tmpl_pg_name\fR(\fBconst scf_pg_tmpl_t *\fR\fIpg_tmpl\fR,
     \fBchar **\fR\fIout\fR);
.fi

.LP
.nf
\fBssize_t\fR \fBscf_tmpl_pg_type\fR(\fBconst scf_pg_tmpl_t *\fR\fIpg_tmpl\fR,
     \fBchar **\fR\fIout\fR);
.fi

.LP
.nf
\fBssize_t\fR \fBscf_tmpl_pg_target\fR(\fBconst scf_pg_tmpl_t *\fR\fIpg_tmpl\fR,
     \fBchar **\fR\fIout\fR);
.fi

.LP
.nf
\fBint\fR \fBscf_tmpl_pg_required\fR(\fBconst scf_pg_tmpl_t *\fR\fIpg_tmpl\fR,
     \fBuint8_t *\fR\fIout\fR)
.fi

.LP
.nf
\fBssize_t\fR \fBscf_tmpl_pg_common_name\fR(\fBconst scf_pg_tmpl_t *\fR\fIpg_tmpl\fR,
     \fBconst char *\fR \fIlocale\fR, \fBchar **\fR\fIout\fR);
.fi

.LP
.nf
\fBssize_t\fR \fBscf_tmpl_pg_description\fR(\fBconst scf_pg_tmpl_t *\fR\fIpg_tmpl\fR,
     \fBconst char *\fR \fIlocale\fR, \fBchar **\fR\fIout\fR);
.fi

.SH 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 \fBscf_tmpl_pg_create\fR(3SCF) suite of functions.
.sp
.LP
The \fBscf_tmpl_pg_name()\fR function retrieves the name of the property group
template and place it in *\fIout\fR. If the property group name is implicitly
wildcarded (see \fBsmf_template\fR(7)) in the template, this function will
return a string containing \fBSCF_TMPL_WILDCARD\fR ("*") in *\fIout\fR. The
caller is responsible for freeing the *\fIout\fR buffer on success.
.sp
.LP
The \fBscf_tmpl_pg_type()\fR function will retrieve the type of the property
group template and place it in *\fIout\fR. If the property group type is
implicitly wildcarded (see \fBsmf_template\fR(7)) in the template, this
function will return a string containing \fBSCF_TMPL_WILDCARD\fR ("*") in
*\fIout\fR. The caller is responsible for freeing the *\fIout\fR buffer on
success.
.sp
.LP
The \fBscf_tmpl_pg_target()\fR function will retrieve the target of the
property group template and place it in *\fIout\fR. The caller is responsible
for freeing the *\fIout\fR buffer on success.
.sp
.LP
The \fBscf_tmpl_pg_required()\fR function will determine whether the property
group is required and place the result of that check in *\fIout\fR. If required
is unset, \fIout\fR will be the default value of 0. If the property is
explicitly set to required, \fIout\fR will be 1.
.sp
.LP
The \fBscf_tmpl_pg_common_name()\fR function will retrieve the property group's
localized common name as currently templated and place it in *\fIout\fR. A
locale (as described in \fBsetlocale\fR(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 *\fIout\fR buffer on
success.
.sp
.LP
The \fBscf_tmpl_pg_description()\fR function will retrieve the property group's
localized description as currently templated and place it in *\fIout\fR. A
locale (as described in \fBsetlocale\fR(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 *\fIout\fR buffer on
success.
.SH RETURN VALUES
Upon successful completion, \fBscf_tmpl_pg_name()\fR,
\fBscf_tmpl_pg_common_name()\fR, \fBscf_tmpl_pg_description()\fR,
\fBscf_tmpl_pg_target()\fR, and \fBscf_tmpl_pg_type()\fR return the length of
the string written, not including the terminating null byte. Otherwise, they
return -1.
.sp
.LP
Upon successful completion, \fBscf_tmpl_pg_required()\fR returns 0. Otherwise,
it returns -1.
.SH ERRORS
The \fBscf_tmpl_pg_name()\fR, \fBscf_tmpl_pg_common_name()\fR,
\fBscf_tmpl_pg_description()\fR, \fBscf_tmpl_pg_required()\fR,
\fBscf_tmpl_pg_target()\fR, and \fBscf_tmpl_pg_type()\fR functions will fail
if:
.sp
.ne 2
.na
\fB\fBSCF_ERROR_BACKEND_ACCESS\fR\fR
.ad
.sp .6
.RS 4n
The storage mechanism that the repository server (\fBsvc.configd\fR(8)) chose
for the operation denied access.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_CONNECTION_BROKEN\fR\fR
.ad
.sp .6
.RS 4n
The connection to the repository was lost.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_DELETED\fR\fR
.ad
.sp .6
.RS 4n
The template property group has been deleted.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_HANDLE_DESTROYED\fR\fR
.ad
.sp .6
.RS 4n
The handle passed in has been destroyed.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_INTERNAL\fR\fR
.ad
.sp .6
.RS 4n
An internal error occurred.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_NO_MEMORY\fR\fR
.ad
.sp .6
.RS 4n
There is not enough memory to populate the \fBscf_pg_tmpl_t\fR.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_NO_RESOURCES\fR\fR
.ad
.sp .6
.RS 4n
The server does not have adequate resources to complete the request.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_NOT_BOUND\fR\fR
.ad
.sp .6
.RS 4n
The handle is not currently bound.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_PERMISSION_DENIED\fR\fR
.ad
.sp .6
.RS 4n
The template could not be read due to access restrictions.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_TEMPLATE_INVALID\fR\fR
.ad
.sp .6
.RS 4n
The template data is invalid.
.RE

.sp
.LP
The \fBscf_tmpl_pg_common_name()\fR and \fBscf_tmpl_pg_description()\fR
functions will fail if:
.sp
.ne 2
.na
\fB\fBSCF_ERROR_NOT_FOUND\fR\fR
.ad
.RS 30n
The property does not exist or exists and has no value.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
.ad
.RS 30n
The locale string is too long.
.RE

.SH ATTRIBUTES
See \fBattributes\fR(7) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Committed
_
MT-Level	Safe
.TE

.SH SEE ALSO
.BR setlocale (3C),
.BR scf_tmpl_pg_create (3SCF),
.BR attributes (7),
.BR smf_template (7),
.BR svc.configd (8)