'\" te
.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
.TH scf_snapshot_create 3SCF "27 Aug 2007" "SunOS 5.11" "Service Configuration Facility Library Functions"
.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
.mk
.na
\fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
.ad
.sp .6
.RS 4n
The \fIhandle\fR argument is \fINULL\fR.
.RE

.sp
.ne 2
.mk
.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
.mk
.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
.mk
.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
.mk
.na
\fB\fBSCF_ERROR_DELETED\fR\fR
.ad
.sp .6
.RS 4n
The snapshot has been deleted.
.RE

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

.sp
.ne 2
.mk
.na
\fB\fBSCF_ERROR_NOT_BOUND\fR\fR
.ad
.sp .6
.RS 4n
The handle is not bound.
.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
.LP
The \fBscf_snapshot_update()\fR function will fail if:
.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
An ancestor of the snapshot specified by \fIsnap\fR has been deleted.
.RE

.sp
.ne 2
.mk
.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
.mk
.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
.mk
.na
\fB\fBSCF_ERROR_NOT_BOUND\fR\fR
.ad
.sp .6
.RS 4n
The handle is not bound.
.RE

.sp
.ne 2
.mk
.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
.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 has been deleted.
.RE

.sp
.ne 2
.mk
.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
.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
The value of the \fIname\fR argument is not a valid snapshot name.
.RE

.sp
.ne 2
.mk
.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
.mk
.na
\fB\fBSCF_ERROR_NOT_BOUND\fR\fR
.ad
.sp .6
.RS 4n
The handle is not bound.
.RE

.sp
.ne 2
.mk
.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
.mk
.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
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
\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)