'\" te
.\" Copyright (c) 2007, 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_SNAPLEVEL_CREATE 3SCF "Aug 27, 2007"
.SH NAME
scf_snaplevel_create, scf_snaplevel_handle, scf_snaplevel_destroy,
scf_snaplevel_get_parent, scf_snaplevel_get_scope_name,
scf_snaplevel_get_service_name, scf_snaplevel_get_instance_name,
scf_snapshot_get_base_snaplevel, scf_snaplevel_get_next_snaplevel \- create and
manipulate snaplevel handles in the Service Configuration Facility
.SH SYNOPSIS
.LP
.nf
cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lscf\fR [ \fIlibrary\fR\&.\|.\|. ]
#include <libscf.h>

\fBscf_snaplevel_t *\fR\fBscf_snaplevel_create\fR(\fBscf_handle_t *\fR\fIhandle\fR);
.fi

.LP
.nf
\fBscf_handle_t *\fR\fBscf_snaplevel_handle\fR(\fBscf_snaplevel_t *\fR\fIlevel\fR);
.fi

.LP
.nf
\fBvoid\fR \fBscf_snaplevel_destroy\fR(\fBscf_snaplevel_t *\fR\fIlevel\fR);
.fi

.LP
.nf
\fBint\fR \fBscf_snaplevel_get_parent\fR(\fBconst scf_snaplevel_t *\fR\fIlevel\fR,
     \fBconst scf_snapshot_t *\fR\fIsnap\fR);
.fi

.LP
.nf
\fBssize_t\fR \fBscf_snaplevel_get_scope_name\fR(\fBconst scf_snaplevel_t *\fR\fIlevel\fR,
     \fBchar *\fR\fIbuf\fR, \fBsize_t\fR \fIsize\fR);
.fi

.LP
.nf
\fBssize_t\fR \fBscf_snaplevel_get_service_name\fR(\fBconst scf_snaplevel_t *\fR\fIlevel\fR,
     \fBchar *\fR\fIbuf\fR, \fBsize_t\fR \fIsize\fR);
.fi

.LP
.nf
\fBssize_t\fR \fBscf_snaplevel_get_instance_name\fR(\fBconst scf_snaplevel_t *\fR\fIlevel\fR,
     \fBchar *\fR\fIbuf\fR, \fBsize_t\fR \fIsize\fR);
.fi

.LP
.nf
\fBint\fR \fBscf_snapshot_get_base_snaplevel\fR(\fBconst scf_snapshot_t *\fR\fIsnap\fR,
     \fBscf_snaplevel_t *\fR\fIlevel\fR);
.fi

.LP
.nf
\fBint\fR \fBscf_snaplevel_get_next_snaplevel\fR(\fBscf_snaplevel_t *\fR\fIin\fR,
     \fBscf_snaplevel_t *\fR\fIout\fR);
.fi

.SH DESCRIPTION
.sp
.LP
A snaplevel holds all of the property groups associated with either a service
or an instance. Each snapshot has an ordered list of snaplevels. Snaplevels
contain the names of the instance or service from which they are derived.
.sp
.LP
An \fBscf_snaplevel_t\fR is an opaque handle that can be set to a single
snaplevel at any given time. When set, the \fBscf_snaplevel_t\fR inherits the
point in time from the \fBscf_snapshot_t\fR from which it comes.
.sp
.LP
The \fBscf_snaplevel_create()\fR function allocates and initializes a new
\fBscf_snaplevel_t\fR bound to \fIhandle\fR. The \fBscf_snaplevel_destroy()\fR
function destroys and frees \fIlevel\fR.
.sp
.LP
The \fBscf_snaplevel_handle()\fR function retrieves the handle to which
\fIlevel\fR is bound.
.sp
.LP
The \fBscf_snaplevel_get_parent()\fR function sets \fIsnap\fR to the parent
snapshot of the snaplevel to which \fIlevel\fR is set.  The snapshot specified
by \fIsnap\fR is attached to the same point in time as level.
.sp
.LP
The \fBscf_snaplevel_get_scope_name()\fR,
\fBscf_snaplevel_get_service_name()\fR, and
\fBscf_snaplevel_get_instance_name()\fR functions retrieve the name of the
scope, service, and instance for the snapshot to which \fIsnap\fR is set. If
the snaplevel is from an instance, all three succeed. If the snaplevel is from
a service, \fBscf_snaplevel_get_instance_name()\fR fails.
.sp
.LP
The \fBscf_snapshot_get_base_snaplevel()\fR function sets \fIlevel\fR to the
first snaplevel in the snapshot to which \fIsnap\fR is set. The
\fBscf_snaplevel_get_next_snaplevel()\fR function sets \fIout\fR to the next
snaplevel after the snaplevel to which \fIin\fR is set. Both the \fIin\fR and
\fIout\fR arguments can point to the same \fBscf_snaplevel_t\fR.
.sp
.LP
To retrieve the property groups associated with a snaplevel, see
\fBscf_iter_snaplevel_pgs\fR(3SCF), \fBscf_iter_snaplevel_pgs_typed\fR(3SCF),
and \fBscf_snaplevel_get_pg\fR(3SCF).
.SH RETURN VALUES
.sp
.LP
Upon successful completion, \fBscf_snaplevel_create()\fR returns a new
\fBscf_snaplevel_t\fR. Otherwise, it returns \fINULL\fR.
.sp
.LP
Upon successful completion, \fBscf_snaplevel_get_scope_name()\fR,
\fBscf_snaplevel_get_service_name()\fR, and
\fBscf_snaplevel_get_instance_name()\fR return the length of the string
written, not including the terminating null byte. Otherwise, they return -1.
.sp
.LP
Upon successful completion, \fBscf_snaplevel_get_parent()\fR,
\fBscf_snapshot_get_base_snaplevel()\fR, and
\fBscf_snaplevel_get_next_snaplevel()\fR return. Otherwise, they return -1.
.SH ERRORS
.sp
.LP
The \fBscf_snaplevel_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 not enough memory to allocate an \fBscf_snaplevel_t\fR.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_NO_RESOURCES\fR\fR
.ad
.RS 30n
The server does not have adequate resources for a new snapshot handle.
.RE

.sp
.LP
The \fBscf_snaplevel_get_scope_name()\fR,
\fBscf_snaplevel_get_service_name()\fR,
\fBscf_snaplevel_get_instance_name()\fR, and \fBscf_snaplevel_get_parent()\fR
functions will fail if:
.sp
.ne 2
.na
\fB\fBSCF_ERROR_DELETED\fR\fR
.ad
.sp .6
.RS 4n
The object referred to by \fIlevel\fR has been deleted.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_NOT_SET\fR\fR
.ad
.sp .6
.RS 4n
The snaplevel is not set.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_NOT_BOUND\fR\fR
.ad
.sp .6
.RS 4n
The handle is not bound.
.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
.LP
The \fBscf_snaplevel_get_instance_name()\fR function will fail if:
.sp
.ne 2
.na
\fB\fBSCF_ERROR_CONSTRAINT_VIOLATED\fR\fR
.ad
.sp .6
.RS 4n
The snaplevel is derived from a service.
.RE

.sp
.LP
The \fBscf_snapshot_get_base_snaplevel()\fR function will fail if:
.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 snapshot has been deleted.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_HANDLE_MISMATCH\fR\fR
.ad
.sp .6
.RS 4n
The snapshot and snaplevel are not derived from the same handle.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_NO_RESOURCES\fR\fR
.ad
.sp .6
.RS 4n
The server does not have the 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 bound.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_NOT_FOUND\fR\fR
.ad
.sp .6
.RS 4n
There are no snaplevels in this snapshot.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_NOT_SET\fR\fR
.ad
.sp .6
.RS 4n
The snapshot is not set.
.RE

.sp
.LP
The \fBscf_snaplevel_get_next_snaplevel()\fR function will fail if:
.sp
.ne 2
.na
\fB\fBSCF_ERROR_DELETED\fR\fR
.ad
.sp .6
.RS 4n
The snaplevel has been deleted.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_NOT_SET\fR\fR
.ad
.sp .6
.RS 4n
The snaplevel is not set.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_HANDLE_MISMATCH\fR\fR
.ad
.sp .6
.RS 4n
The \fIin\fR and \fIout\fR arguments are not derived from the same handle.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_NOT_BOUND\fR\fR
.ad
.sp .6
.RS 4n
The handle is not bound.
.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_NOT_FOUND\fR\fR
.ad
.sp .6
.RS 4n
There are no more snaplevels in this snapshot.
.RE

.sp
.LP
The \fBscf_error\fR(3SCF) function can be used to retrieve the error value.
.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
\fBlibscf\fR(3LIB), \fBscf_error\fR(3SCF), \fBscf_iter_snaplevel_pgs\fR(3SCF),
\fBscf_iter_snaplevel_pgs_typed\fR(3SCF), \fBscf_snaplevel_get_pg\fR(3SCF),
\fBattributes\fR(5)