'\" te
.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
.TH scf_snaplevel_create 3SCF "27 Aug 2007" "SunOS 5.11" "Service Configuration Facility Library Functions"
.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
.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 not enough memory to allocate an \fBscf_snaplevel_t\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fBSCF_ERROR_NO_RESOURCES\fR\fR
.ad
.RS 30n
.rt  
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
.mk
.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
.mk
.na
\fB\fBSCF_ERROR_NOT_SET\fR\fR
.ad
.sp .6
.RS 4n
The snaplevel 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_snaplevel_get_instance_name()\fR function will fail if:
.sp
.ne 2
.mk
.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
.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 snapshot has been deleted.
.RE

.sp
.ne 2
.mk
.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
.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
There are no snaplevels in this snapshot.
.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
.LP
The \fBscf_snaplevel_get_next_snaplevel()\fR function will fail if:
.sp
.ne 2
.mk
.na
\fB\fBSCF_ERROR_DELETED\fR\fR
.ad
.sp .6
.RS 4n
The snaplevel has been deleted.
.RE

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

.sp
.ne 2
.mk
.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
.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
.ne 2
.mk
.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
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_snaplevel_pgs\fR(3SCF), \fBscf_iter_snaplevel_pgs_typed\fR(3SCF), \fBscf_snaplevel_get_pg\fR(3SCF), \fBattributes\fR(5)