man/man3scf/scf_snapshot_create.3scf

         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]
 SCF_SNAPSHOT_CREATE 3SCF "Aug 27, 2007"
 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
 SYNOPSIS

cc [ flag.\|.\|. ] file.\|.\|. -lscf [ library.\|.\|. ]
#include <libscf.h>

scf_snapshot_t *scf_snapshot_create(scf_handle_t *handle);


scf_handle_t *scf_snapshot_handle(scf_snapshot_t *snap);


void scf_snapshot_destroy(scf_snapshot_t *snap);


int scf_snapshot_get_parent(const scf_snapshot_t *snap,
 scf_instance_t *inst);


ssize_t scf_snapshot_get_name(const scf_snapshot_t *snap,
 char *buf, size_t size);


int scf_snapshot_update(scf_snapshot_t *snap);


int scf_instance_get_snapshot(const scf_instance_t *inst,
 const char *name, scf_snapshot_t *snap);


 DESCRIPTION

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 smf(5).

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.

The scf_snapshot_create() function allocates and initializes a new
scf_snapshot_t bound to handle. The scf_snapshot_destroy()
function destroys and frees snap.

The scf_snapshot_handle() function retrieves the handle to which
snap is bound.

The scf_snapshot_get_parent() function sets inst to the parent of
the snapshot to which snap is set.

The scf_snapshot_get_name() function retrieves the name of the snapshot
to which snap is set.

The scf_snapshot_update() function reattaches snap to the latest
version of the snapshot to which snap is set.

The scf_instance_get_snapshot() function sets snap to the snapshot
specified by name in the instance specified by inst. To walk all of
the snapshots, see scf_iter_instance_snapshots(3SCF).

To access the snaplevels of a snapshot, see
scf_snapshot_get_base_snaplevel(3SCF).
 RETURN VALUES

Upon successful completion, scf_snapshot_create() returns a new
scf_snapshot_t. Otherwise, it returns NULL.

Upon successful completion, scf_snapshot_handle() returns the handle to
which snap is bound. Otherwise, it returns NULL.

Upon successful completion, scf_snapshot_get_name() returns the length of
the string written, not including the terminating null byte. Otherwise, it
returns NULL.

The scf_snapshot_update() function returns 1 if the snapshot was updated,
0 if the snapshot had not been updated, and -1 on failure.

Upon successful completion, scf_snapshot_get_parent() and
scf_instance_get_snapshot() return 0. Otherwise, they return -1.
 ERRORS

The scf_snapshot_create() function will fail if:
SCF_ERROR_INVALID_ARGUMENT

The handle argument is NULL.


SCF_ERROR_NO_MEMORY

There is not enough memory to allocate an scf_snapshot_t.


SCF_ERROR_NO_RESOURCES

The server does not have adequate resources for a new instance handle.


The scf_snapshot_handle() function will fail if:
SCF_ERROR_HANDLE_DESTROYED

The handle associated with snap has been destroyed.


The scf_snapshot_get_name() and scf_snapshot_get_parent() functions
will fail if:
SCF_ERROR_DELETED

The snapshot has been deleted.


SCF_ERROR_NOT_SET

The snapshot is not set.


SCF_ERROR_NOT_BOUND

The handle is not bound.


SCF_ERROR_CONNECTION_BROKEN

The connection to the repository was lost.


The scf_snapshot_update() function will fail if:
SCF_ERROR_CONNECTION_BROKEN

The connection to the repository was lost.


SCF_ERROR_DELETED

An ancestor of the snapshot specified by snap has been deleted.


SCF_ERROR_INTERNAL

An internal error occurred. This can happen if snap has been corrupted.


SCF_ERROR_INVALID_ARGUMENT

The snap argument refers to an invalid scf_snapshot_t.


SCF_ERROR_NOT_BOUND

The handle is not bound.


SCF_ERROR_NOT_SET

The snapshot specified by snap is not set.


The scf_instance_get_snapshot() function will fail if:
SCF_ERROR_BACKEND_ACCESS

The storage mechanism that the repository server (svc.configd(1M))
chose for the operation denied access.


SCF_ERROR_CONNECTION_BROKEN

The connection to the repository was lost.


SCF_ERROR_DELETED

The instance has been deleted.


SCF_ERROR_HANDLE_MISMATCH

The instance and snapshot are not derived from the same handle.


SCF_ERROR_INTERNAL

An internal error occurred.


SCF_ERROR_INVALID_ARGUMENT

The value of the name argument is not a valid snapshot name.


SCF_ERROR_NO_RESOURCES

The server does not have the resources to complete the request.


SCF_ERROR_NOT_BOUND

The handle is not bound.


SCF_ERROR_NOT_FOUND

The snapshot specified by name was not found.


SCF_ERROR_NOT_SET

The instance is not set.


The scf_error(3SCF) function can be used to retrieve the error value.
 ATTRIBUTES

See attributes(5) for descriptions of the following attributes:


ATTRIBUTE TYPE ATTRIBUTE VALUE
Interface Stability Committed
MT-Level Safe


 SEE ALSO

libscf(3LIB), scf_error(3SCF),
scf_iter_instance_snapshots(3SCF),
scf_snapshot_get_base_snaplevel(3SCF), attributes(5), smf(5)