'\" 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_SNAPSHOT_CREATE 3SCF "Aug 27, 2007"
.SH NAME
scf_snapshot_create, scf_snapshot_handle, scf_snapshot_destroy,
scf_snapshot_get_parent, scf_snapshot_get_name, scf_snapshot_update,
scf_instance_get_snapshot \- create and manipulate snapshot handles and
snapshots in the Service Configuration Facility
.SH SYNOPSIS
.LP
.nf
cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lscf\fR [ \fIlibrary\fR\&.\|.\|. ]
#include <libscf.h>

\fBscf_snapshot_t *\fR\fBscf_snapshot_create\fR(\fBscf_handle_t *\fR\fIhandle\fR);
.fi

.LP
.nf
\fBscf_handle_t *\fR\fBscf_snapshot_handle\fR(\fBscf_snapshot_t *\fR\fIsnap\fR);
.fi

.LP
.nf
\fBvoid\fR \fBscf_snapshot_destroy\fR(\fBscf_snapshot_t *\fR\fIsnap\fR);
.fi

.LP
.nf
\fBint\fR \fBscf_snapshot_get_parent\fR(\fBconst scf_snapshot_t *\fR\fIsnap\fR,
     \fBscf_instance_t *\fR\fIinst\fR);
.fi

.LP
.nf
\fBssize_t\fR \fBscf_snapshot_get_name\fR(\fBconst scf_snapshot_t *\fR\fIsnap\fR,
     \fBchar *\fR\fIbuf\fR, \fBsize_t\fR \fIsize\fR);
.fi

.LP
.nf
\fBint\fR \fBscf_snapshot_update\fR(\fBscf_snapshot_t *\fR\fIsnap\fR);
.fi

.LP
.nf
\fBint\fR \fBscf_instance_get_snapshot\fR(\fBconst scf_instance_t *\fR\fIinst\fR,
     \fBconst char *\fR\fIname\fR, \fBscf_snapshot_t *\fR\fIsnap\fR);
.fi

.SH DESCRIPTION
.sp
.LP
A snapshot is an unchanging picture of the full set of property groups
associated with an instance. Snapshots are automatically created and managed by
the Solaris Management Facility. See \fBsmf\fR(5).
.sp
.LP
A snapshot consists of a set of snaplevels, each of which holds copies of the
property groups associated with an instance or service in the resolution path
of the base instance. Typically, there is one snaplevel for the instance and
one for the instance's parent service.
.sp
.LP
The \fBscf_snapshot_create()\fR function allocates and initializes a new
\fBscf_snapshot_t\fR bound to \fIhandle\fR. The \fBscf_snapshot_destroy()\fR
function destroys and frees \fIsnap\fR.
.sp
.LP
The \fBscf_snapshot_handle()\fR function retrieves the handle to which
\fIsnap\fR is bound.
.sp
.LP
The \fBscf_snapshot_get_parent()\fR function sets \fIinst\fR to the parent of
the snapshot to which \fIsnap\fR is set.
.sp
.LP
The \fBscf_snapshot_get_name()\fR function retrieves the name of the snapshot
to which \fIsnap\fR is set.
.sp
.LP
The \fBscf_snapshot_update()\fR function reattaches \fIsnap\fR to the latest
version of the snapshot to which \fIsnap\fR is set.
.sp
.LP
The \fBscf_instance_get_snapshot()\fR function sets \fIsnap\fR to the snapshot
specified by \fIname\fR in the instance specified by \fIinst\fR. To walk all of
the snapshots, see \fBscf_iter_instance_snapshots\fR(3SCF).
.sp
.LP
To access the snaplevels of a snapshot, see
\fBscf_snapshot_get_base_snaplevel\fR(3SCF).
.SH RETURN VALUES
.sp
.LP
Upon successful completion, \fBscf_snapshot_create()\fR returns a new
\fBscf_snapshot_t\fR. Otherwise, it returns \fINULL\fR.
.sp
.LP
Upon successful completion, \fBscf_snapshot_handle()\fR returns the handle to
which \fIsnap\fR is bound. Otherwise, it returns \fINULL\fR.
.sp
.LP
Upon successful completion, \fBscf_snapshot_get_name()\fR returns the length of
the string written, not including the terminating null byte. Otherwise, it
returns \fINULL\fR.
.sp
.LP
The \fBscf_snapshot_update()\fR function returns 1 if the snapshot was updated,
0 if the snapshot had not been updated, and -1 on failure.
.sp
.LP
Upon successful completion, \fBscf_snapshot_get_parent()\fR and
\fBscf_instance_get_snapshot()\fR return 0. Otherwise, they return -1.
.SH ERRORS
.sp
.LP
The \fBscf_snapshot_create()\fR function will fail if:
.sp
.ne 2
.na
\fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
.ad
.sp .6
.RS 4n
The \fIhandle\fR argument is \fINULL\fR.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_NO_MEMORY\fR\fR
.ad
.sp .6
.RS 4n
There is not enough memory to allocate an \fBscf_snapshot_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 for a new instance handle.
.RE

.sp
.LP
The \fBscf_snapshot_handle()\fR function will fail if:
.sp
.ne 2
.na
\fB\fBSCF_ERROR_HANDLE_DESTROYED\fR\fR
.ad
.sp .6
.RS 4n
The handle associated with \fIsnap\fR has been destroyed.
.RE

.sp
.LP
The \fBscf_snapshot_get_name()\fR and \fBscf_snapshot_get_parent()\fR functions
will fail if:
.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_NOT_SET\fR\fR
.ad
.sp .6
.RS 4n
The snapshot 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_snapshot_update()\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
An ancestor of the snapshot specified by \fIsnap\fR has been deleted.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_INTERNAL\fR\fR
.ad
.sp .6
.RS 4n
An internal error occurred. This can happen if \fIsnap\fR has been corrupted.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
.ad
.sp .6
.RS 4n
The \fIsnap\fR argument refers to an invalid \fBscf_snapshot_t\fR.
.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_SET\fR\fR
.ad
.sp .6
.RS 4n
The snapshot specified by \fIsnap\fR is not set.
.RE

.sp
.LP
The \fBscf_instance_get_snapshot()\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 has been deleted.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_HANDLE_MISMATCH\fR\fR
.ad
.sp .6
.RS 4n
The instance and snapshot are not derived from the same handle.
.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 value of the \fIname\fR argument is not a valid snapshot name.
.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
The snapshot specified by \fIname\fR was not found.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_NOT_SET\fR\fR
.ad
.sp .6
.RS 4n
The instance is not set.
.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_instance_snapshots\fR(3SCF),
\fBscf_snapshot_get_base_snaplevel\fR(3SCF), \fBattributes\fR(5), \fBsmf\fR(5)