path: root/usr/src/man/man3scf/scf_tmpl_validate_fmri.3scf

'\" 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_VALIDATE_FMRI 3SCF "Oct 28, 2008"
.SH NAME
scf_tmpl_validate_fmri, scf_tmpl_errors_destroy, scf_tmpl_next_error,
scf_tmpl_reset_errors, scf_tmpl_strerror, scf_tmpl_error_type,
scf_tmpl_error_source_fmri, scf_tmpl_error_pg_tmpl, scf_tmpl_error_pg,
scf_tmpl_error_prop_tmpl, scf_tmpl_error_prop, scf_tmpl_error_value \- template
validation functions
.SH SYNOPSIS
.LP
.nf
cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lscf\fR [ \fIlibrary\fR\&.\|.\|. ]
#include <libscf.h>

\fBint\fR \fBscf_tmpl_validate_fmri\fR(\fBscf_handle_t *\fR\fIh\fR, \fBconst char *\fR\fIfmri\fR,
     \fBconst char *\fR\fIsnapshot\fR, \fBscf_tmpl_errors_t **\fR\fIerrs\fR, \fBint\fR \fIflags\fR);
.fi

.LP
.nf
\fBvoid\fR \fBscf_tmpl_errors_destroy\fR(\fBscf_tmpl_errors_t *\fR\fIerrs\fR);
.fi

.LP
.nf
\fBscf_tmpl_error_t *\fR\fBscf_tmpl_next_error\fR(\fBscf_tmpl_errors_t *\fR\fIerrs\fR,
     \fBscf_tmpl_errors_t *\fR\fIerr\fR)
.fi

.LP
.nf
\fBvoid\fR \fBscf_tmpl_reset_errors\fR(\fBscf_tmpl_errors_t *\fR\fIerrs\fR);
.fi

.LP
.nf
\fBint\fR \fBscf_tmpl_strerror\fR(\fBscf_tmpl_error_t *\fR\fIerr\fR, \fBchar *\fR\fIs\fR,
     \fBsize_t\fR \fIn\fR, \fBint\fR \fIflags\fR);
.fi

.LP
.nf
\fBint\fR \fBscf_tmpl_error_type\fR(\fBconst scf_tmpl_error_t *\fR\fIerr\fR,
     \fBscf_tmpl_error_type_t *\fR\fItype\fR);
.fi

.LP
.nf
\fBint\fR \fBscf_tmpl_error_source_fmri\fR(\fBconst scf_tmpl_error_t *\fR\fIerr\fR,
     \fBchar *\fR\fIfmri\fR);
.fi

.LP
.nf
\fBint\fR \fBscf_tmpl_error_pg_tmpl\fR(\fBconst scf_tmpl_error_t *\fR\fIerr\fR, \fBchar *\fR\fIname\fR,
     \fBchar *\fR\fItype\fR);
.fi

.LP
.nf
\fBint\fR \fBscf_tmpl_error_pg\fR(\fBconst scf_tmpl_error_t *\fR\fIerr\fR,
     \fBchar **\fR\fIname\fR, \fBchar **\fR\fItype\fR);
.fi

.LP
.nf
\fBint\fR \fBscf_tmpl_error_prop_tmpl\fR(\fBconst scf_tmpl_error_t *\fR\fIerr\fR, \fBchar **\fR\fIname\fR,
     \fBchar **\fR\fItype\fR);
.fi

.LP
.nf
\fBint\fR \fBscf_tmpl_error_prop\fR(\fBconst scf_tmpl_error_t *\fR\fIerr\fR, \fBchar **\fR\fIname\fR,
     \fBchar **\fR\fItype\fR,);
.fi

.LP
.nf
\fBint\fR \fBscf_tmpl_error_value\fR(\fBconst scf_tmpl_error_t *\fR\fIerr\fR, \fBchar**\fR\fIval\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The template validation functions offer a way to validate the configuration
data of an service instance against the appropriate template data. The
\fBscf_tmpl_validate_fmri()\fR function returns the full set of errors for the
specified instance, and those errors can be printed or explored directly.
.sp
.LP
By default, the validation is performed on the composed data from the running
snapshot of an instance. A different snapshot can be explicitly selected by
specifying a valid snapshot name rather than \fINULL\fR for the \fIsnapshot\fR
argument. If \fIflags\fR includes \fBSCF_TMPL_VALIDATE_FLAG_CURRENT\fR, the
\fIsnapshot\fR argument is ignored and the current configuration is used.
.sp
.LP
By default, these functions also explore template data defined by the service
or instance itself, the service's restarter, and global template data. See
\fBsmf_template\fR(5) for more information about this composition.
.sp
.LP
An instance FMRI is required, and FMRIs that specify other entities (for
example, services) are explicitly rejected.
.sp
.LP
The \fBscf_tmpl_validate_fmri()\fR function validates an instance FMRI against
the template data in the repository. As described above, when the
\fIsnapshot\fR argument is \fINULL\fR, the default running snapshot is used. If
\fBscf_tmpl_errors_t **\fR is non-null, the structure is allocated and returned
to the caller for further perusal or printing of the errors.
.sp
.LP
The \fBscf_tmpl_errors_destroy()\fR function destroys and frees the
\fBscf_tmpl_errors_t\fR and all of the \fBscf_tmpl_error_t\fR structures to
which it refers.
.sp
.LP
The \fBscf_tmpl_next_error()\fR function takes a pointer to a
\fBscf_tmpl_errors_t\fR structure previously returned by
\fBscf_tmpl_validate_fmri()\fR. On the first call, it returns a pointer to the
first \fBscf_tmpl_error_t\fR found during validation. On subsequent calls, the
next error is returned. To resume processing from the first error, the caller
can use \fBscf_tmpl_reset_errors()\fR.
.sp
.LP
The contents of an \fBscf_tmpl_error_t\fR are determined by its type. Types
added as additional validation checks are introduced. Based on the error type,
a set of fields can be retrieved from the error.
.sp
.ne 2
.na
\fB\fBSCF_TERR_TYPE_INVALID\fR\fR
.ad
.sp .6
.RS 4n
reserved invalid type
.RE

.sp
.ne 2
.na
\fB\fBSCF_TERR_MISSING_PG\fR\fR
.ad
.sp .6
.RS 4n
required property group is missing
.br
.in +2
template source FMRI
.in -2
.br
.in +2
property group template name and type
.in -2
.RE

.sp
.ne 2
.na
\fB\fBSCF_TERR_WRONG_PG_TYPE\fR\fR
.ad
.sp .6
.RS 4n
property group type is incorrect
.br
.in +2
template source FMRI
.in -2
.br
.in +2
property group template name and type
.in -2
.br
.in +2
property group name and type
.in -2
.RE

.sp
.ne 2
.na
\fB\fBSCF_TERR_MISSING_PROP\fR\fR
.ad
.sp .6
.RS 4n
required property is missing
.br
.in +2
template source FMRI
.in -2
.br
.in +2
property group template name and type
.in -2
.br
.in +2
property template name and type
.in -2
.RE

.sp
.ne 2
.na
\fB\fBSCF_TERR_WRONG_PROP_TYPE\fR\fR
.ad
.sp .6
.RS 4n
property type is incorrect
.br
.in +2
template source FMRI
.in -2
.br
.in +2
property group template name and type
.in -2
.br
.in +2
property template name and type
.in -2
.br
.in +2
property group name and type
.in -2
.br
.in +2
property name and type
.in -2
.RE

.sp
.ne 2
.na
\fB\fBSCF_TERR_CARDINALITY_VIOLATION\fR\fR
.ad
.sp .6
.RS 4n
number of values violates cardinality
.br
.in +2
template source FMRI
.in -2
.br
.in +2
property group template name and type
.in -2
.br
.in +2
property template name and type
.in -2
.br
.in +2
property group name and type
.in -2
.br
.in +2
property name and type
.in -2
.br
.in +2
cardinality and cardinality limits
.in -2
.RE

.sp
.ne 2
.na
\fB\fBSCF_TERR_VALUE_CONSTRAINT_VIOLATED\fR\fR
.ad
.sp .6
.RS 4n
constraint violated for value
.br
.in +2
template source FMRI
.in -2
.br
.in +2
property group template name and type
.in -2
.br
.in +2
property template name and type
.in -2
.br
.in +2
property group name and type
.in -2
.br
.in +2
property name and type
.in -2
.br
.in +2
value
.in -2
.RE

.sp
.ne 2
.na
\fB\fBSCF_TERR_RANGE_VIOLATION\fR\fR
.ad
.sp .6
.RS 4n
value violated specified range
.br
.in +2
template source FMRI
.in -2
.br
.in +2
property group template name and type
.in -2
.br
.in +2
property template name and type
.in -2
.br
.in +2
property group name and type
.in -2
.br
.in +2
property name and type
.in -2
.br
.in +2
value
.in -2
.RE

.sp
.ne 2
.na
\fB\fBSCF_TERR_PROP_TYPE_MISMATCH\fR\fR
.ad
.sp .6
.RS 4n
value type is different from property type
.br
.in +2
template source FMRI
.in -2
.br
.in +2
property group template name and type
.in -2
.br
.in +2
property template name and type
.in -2
.RE

.sp
.ne 2
.na
\fB\fBSCF_TERR_VALUE_OUT_OF_RANGE\fR\fR
.ad
.sp .6
.RS 4n
value is out of template defined range
.br
.in +2
template source FMRI
.in -2
.br
.in +2
property group template name and type
.in -2
.br
.in +2
property template name and type
.in -2
.br
.in +2
value
.in -2
.RE

.sp
.ne 2
.na
\fB\fBSCF_TERR_INVALID_VALUE\fR\fR
.ad
.sp .6
.RS 4n
value violates template defined constraints
.br
.in +2
template source FMRI
.in -2
.br
.in +2
property group template name and type
.in -2
.br
.in +2
property template name and type
.in -2
.br
.in +2
value
.in -2
.RE

.sp
.LP
The \fBSCF_TERR_PROP_TYPE_MISMATCH\fR, \fBSCF_TERR_VALUE_OUT_OF_RANGE\fR and
\fBSCF_TERR_INVALID_VALUE\fR types are only set from calls to
\fBscf_tmpl_value_in_constraint\fR(3SCF).
.sp
.LP
The \fBscf_tmpl_error_type()\fR function retrieves the error type.
.sp
.LP
The \fBscf_tmpl_error_source_fmri()\fR function retrieves a string with the
FMRI of the source of the template that was violated. This string is freed by
\fBscf_tmpl_errors_destroy()\fR.
.sp
.LP
The \fBscf_tmpl_error_pg_tmpl()\fR function retrieves strings with the name and
type of the property group template that was violated. If the property group
name or type was implicitly wildcarded (see \fBsmf_template\fR(5)) in the
template, this function returns a string containing \fBSCF_TMPL_WILDCARD\fR
("*"). These strings are freed by \fBscf_tmpl_errors_destroy()\fR.
.sp
.LP
The \fBscf_tmpl_error_pg()\fR function retrieves strings with the name and type
of the property group that was violated. These strings are freed by
\fBscf_tmpl_errors_destroy()\fR.
.sp
.LP
The \fBscf_tmpl_error_prop_tmpl()\fR function retrieves strings with the name
and type of the property template that was violated. If the property type was
implicitly wildcarded (see \fBsmf_template\fR(5)) in the template, this
function returns a string containing \fBSCF_TMPL_WILDCARD\fR ("*"). These
strings are freed by \fBscf_tmpl_errors_destroy()\fR.
.sp
.LP
The \fBscf_tmpl_error_prop()\fR function retrieves strings with the name and
type of the property that was violated. These strings are freed by
\fBscf_tmpl_errors_destroy()\fR.
.sp
.LP
The \fBscf_tmpl_error_value()\fR function retrieves a string with the value
containing the error in \fIval\fR. This string are freed by
\fBscf_tmpl_errors_destroy()\fR.
.sp
.LP
The \fBscf_tmpl_strerror()\fR function takes an \fBscf_tmpl_error_t\fR
previously returned by \fBscf_tmpl_next_error()\fR and returns in \fIs\fR. If
flags includes \fBSCF_TMPL_STRERROR_HUMAN\fR, \fIs\fR is a human-readable,
localized description of the error. Otherwise, \fIs\fR is a one-line string
suitable for logfile output.
.SH RETURN VALUES
.sp
.LP
The \fBscf_tmpl_validate_fmri()\fR function returns 0 on successful completion
with no validation failures. It returns 1 if there are validation failures. It
returns -1 if there is an error validating the instance.
.sp
.LP
The \fBscf_tmpl_next_error()\fR function returns a pointer to the next
\fBscf_tmpl_error_t\fR. When none remain, it returns \fINULL\fR.
.sp
.LP
The \fBscf_tmpl_error_type()\fR, \fBscf_tmpl_error_source_fmri()\fR,
\fBscf_tmpl_error_pg_tmpl()\fR, \fBscf_tmpl_error_pg()\fR,
\fBscf_tmpl_error_prop_tmpl()\fR, \fBscf_tmpl_error_prop()\fR, and
\fBscf_tmpl_error_value()\fR functions return 0 on success and -1 on failure.
.sp
.LP
The \fBscf_tmpl_strerror()\fR function returns the number of bytes that would
have been written to s if n had been sufficiently large.
.SH ERRORS
.sp
.LP
The \fBscf_tmpl_validate_fmri()\fR function 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 one of its template property group have 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
The handle argument, FMRI argument, or snapshot name 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 validate the instance.
.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_NOT_FOUND\fR\fR
.ad
.sp .6
.RS 4n
An object matching FMRI does not exist in the repository, or the snapshot does
not exist.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_PERMISSION_DENIED\fR\fR
.ad
.sp .6
.RS 4n
The instance or 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_strerror()\fR, \fBscf_tmpl_error_type()\fR,
\fBscf_tmpl_error_source_fmri()\fR, \fBscf_tmpl_error_pg_tmpl()\fR,
\fBscf_tmpl_error_pg()\fR, \fBscf_tmpl_error_prop_tmpl()\fR,
\fBscf_tmpl_error_prop()\fR, and \fBscf_tmpl_error_value()\fR functions will
fail if:
.sp
.ne 2
.na
\fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
.ad
.RS 30n
The \fBscf_tmpl_errors_t\fR argument is invalid.
.RE

.sp
.LP
The \fBscf_tmpl_error_type()\fR, \fBscf_tmpl_error_source_fmri()\fR,
\fBscf_tmpl_error_pg_tmpl()\fR, \fBscf_tmpl_error_pg()\fR,
\fBscf_tmpl_error_prop_tmpl()\fR, \fBscf_tmpl_error_prop()\fR, and
\fBscf_tmpl_error_value()\fR functions will fail if:
.sp
.ne 2
.na
\fB\fBSCF_ERROR_NOT_FOUND\fR\fR
.ad
.RS 23n
The data requested is not available for the \fBscf_tmpl_error_t\fR argument
supplied.
.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_value_in_constraint\fR(3SCF),
\fBattributes\fR(5), \fBsmf_template\fR(5)