'\" te
.\" Copyright (c) 2008, Sun Microsystems Inc. All Rights Reserved.
.TH scf_tmpl_pg_name 3SCF "28 Oct 2008" "SunOS 5.11" "Service Configuration Facility Library Functions"
.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
.LP
.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,
     \fBchar *\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,
     \fBchar *\fR \fIlocale\fR, \fBchar **\fR\fIout\fR);
.fi

.SH DESCRIPTION
.sp
.LP
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(5)) 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(5)) 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
.sp
.LP
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
.sp
.LP
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
.mk
.na
\fB\fBSCF_ERROR_BACKEND_ACCESS\fR\fR
.ad
.sp .6
.RS 4n
The storage mechanism that the repository server (\fBsvc.configd\fR(1M)) chose for the operation denied access.
.RE

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

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

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

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

.sp
.ne 2
.mk
.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
.mk
.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
.mk
.na
\fB\fBSCF_ERROR_NOT_BOUND\fR\fR
.ad
.sp .6
.RS 4n
The handle is not currently bound.
.RE

.sp
.ne 2
.mk
.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
.mk
.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
.mk
.na
\fB\fBSCF_ERROR_NOT_FOUND\fR\fR
.ad
.RS 30n
.rt  
The property does not exist or exists and has no value.
.RE

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

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

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Interface StabilityCommitted
_
MT-LevelSafe
.TE

.SH SEE ALSO
.sp
.LP
\fBsvc.configd\fR(1M), \fBscf_tmpl_pg_create\fR(3SCF), \fBsetlocale\fR(3C), \fBattributes\fR(5), \fBsmf_template\fR(5)