'\" 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_PROP_CREATE 3SCF "Oct 28, 2008"
.SH NAME
scf_tmpl_prop_create, scf_tmpl_prop_reset, scf_tmpl_prop_destroy,
scf_tmpl_get_by_prop, scf_tmpl_iter_props \- template property functions
.SH SYNOPSIS
.LP
.nf
cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lscf\fR [ \fIlibrary\fR\&.\|.\|. ]
#include <libscf.h>

\fBscf_prop_tmpl_t *\fR\fBscf_tmpl_prop_create\fR(\fBscf_handle_t *\fR\fIhandle\fR);
.fi

.LP
.nf
\fBvoid\fR \fBscf_tmpl_prop_reset\fR(\fBscf_prop_tmpl_t *\fR\fIprop_tmpl\fR);
.fi

.LP
.nf
\fBvoid\fR \fBscf_tmpl_prop_destroy\fR(\fBscf_prop_tmpl_t *\fR\fIprop_tmpl\fR);
.fi

.LP
.nf
\fBint\fR \fBscf_tmpl_get_by_prop\fR(\fBscf_pg_tmpl_t *\fR\fIpg_tmpl\fR,
     \fBconst char *\fR\fIprop\fR, \fBscf_prop_tmpl_t *\fR\fIprop_tmpl\fR, \fBint\fR \fIflags\fR)
.fi

.LP
.nf
\fBint\fR \fBscf_tmpl_iter_props\fR(\fBscf_pg_tmpl_t *\fR\fIpg_tmpl\fR, \fBconst char *\fR\fIfmri\fR,
     \fBscf_prop_tmpl_t *\fR\fIprop_tmpl\fR, \fBint\fR \fIflags\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The template property functions locate and give access to metadata about
properties.  They require that the template for the property group containing
the property has already been located by one of the
\fBscf_tmpl_pg_create\fR(3SCF) suite of functions.
.sp
.LP
Once retrieved, the \fBscf_prop_tmpl_t\fR can be explored using the
\fBscf_tmpl_prop_name\fR(3SCF) suite of functions.
.sp
.LP
Before calling \fBscf_tmpl_get_by_prop()\fR or \fBscf_tmpl_iter_props()\fR, the
\fBscf_prop_tmpl_t\fR must be allocated by \fBscf_tmpl_prop_create\fR. The
\fBscf_prop_tmpl_t\fR can be reset to contain no template information with
\fBscf_tmpl_prop_reset()\fR, so that it can be used to start an iteration from
scratch. All associated memory can be freed with \fBscf_tmpl_prop_destroy()\fR.
.sp
.LP
The \fBscf_tmpl_get_by_prop()\fR function locates template data about the
property name specified.
.sp
.LP
The \fBscf_tmpl_iter_props()\fR function iterates across all property templates
defined in the specified property group template.
.sp
.LP
The iterator state for \fBscf_tmpl_iter_props()\fR is stored on the property
template data structure. The data structure should be allocated with
\fBscf_tmpl_prop_create()\fR, and to continue the iteration the previously
returned structure should be passed in as an argument.
.SH RETURN VALUES
.sp
.LP
The \fBscf_tmpl_get_by_prop()\fR function returns -1 on failure and 0 on
success.
.sp
.LP
The \fBscf_tmpl_iter_props()\fR function returns 1 on successful completion. If
the iteration is complete, it returns 0. It returns -1 on error.
.SH ERRORS
.sp
.LP
The \fBscf_tmpl_get_by_prop()\fR and \fBscf_tmpl_iter_props()\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(1M)) 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 instance or its 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_INVALID_ARGUMENT\fR\fR
.ad
.sp .6
.RS 4n
One of the arguments is invalid.
.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_prop_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
.LP
The \fBscf_tmpl_get_by_prop()\fR function will fail if:
.sp
.ne 2
.na
\fB\fBSCF_ERROR_NOT_FOUND\fR\fR
.ad
.sp .6
.RS 4n
Template object matching property doesn't exist in the repository.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_TYPE_MISMATCH\fR\fR
.ad
.sp .6
.RS 4n
Matching template object is the wrong type in the repository.
.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_prop_create()\fR function will fail if:
.sp
.ne 2
.na
\fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
.ad
.RS 30n
The \fIhandle\fR argument is \fINULL\fR.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_NO_MEMORY\fR\fR
.ad
.RS 30n
There is no memory available.
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) 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
.sp
.LP
\fBsvc.configd\fR(1M), \fBscf_tmpl_pg_create\fR(3SCF),
\fBscf_tmpl_prop_name\fR(3SCF), \fBattributes\fR(5), \fBsmf_template\fR(5)