'\" te
.\" Copyright (c) 2008, 2011, Oracle and/or its affiliates. All rights reserved.
.TH scf_tmpl_prop_create 3SCF "14 Jan 2011" "SunOS 5.11" "Service Configuration Facility Library Functions"
.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,
     \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 0 for successful iteration to the next item, 1 for iteration successfully reaching its end, and \(em1 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
.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 instance or its 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_INVALID_ARGUMENT\fR\fR
.ad
.sp .6
.RS 4n
One of the arguments is invalid.
.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_prop_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
.LP
The \fBscf_tmpl_get_by_prop()\fR function will fail if:
.sp
.ne 2
.mk
.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
.mk
.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
.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_prop_create()\fR function will fail if:
.sp
.ne 2
.mk
.na
\fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
.ad
.RS 30n
.rt  
The \fIhandle\fR argument is \fINULL\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fBSCF_ERROR_NO_MEMORY\fR\fR
.ad
.RS 30n
.rt  
There is no memory available.
.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), \fBscf_tmpl_prop_name\fR(3SCF), \fBattributes\fR(5), \fBsmf_template\fR(5)