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_transaction_create, scf_transaction_handle, scf_transaction_reset, scf_transaction_reset_all, scf_transaction_destroy, scf_transaction_destroy_children, scf_transaction_start, scf_transaction_property_delete, scf_transaction_property_new, scf_transaction_property_change, scf_transaction_property_change_type, scf_transaction_commit - create and manipulate transaction in the Service Configuration Facility

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

scf_transaction_t *scf_transaction_create(scf_handle_t *handle);

scf_handle_t *scf_transaction_handle(scf_transaction_t *tran);

void scf_transaction_reset(scf_transaction_t *tran);

void scf_transaction_reset_all(scf_transaction_t *tran);

void scf_transaction_destroy(scf_transaction_t *tran);

void scf_transaction_destroy_children(scf_transaction_t *tran);

int scf_transaction_start(scf_transaction_t *tran,
 scf_propertygroup_t *pg);

int scf_transaction_property_delete(scf_transaction_t *tran,
 scf_transaction_entry_t *entry, const char *prop_name);

int scf_transaction_property_new(scf_transaction_t *tran,
 scf_transaction_entry_t *entry, const char *prop_name,
 scf_type_t type);

int scf_transaction_property_change(scf_transaction_t *tran,
 scf_transaction_entry_t *entry, const char *prop_name,
 scf_type_t type);

int scf_transaction_property_change_type(
 scf_transaction_t *tran, scf_transaction_entry_t *entry,
 const char *prop_name, scf_type_t type);

int scf_transaction_commit(scf_transaction_t *tran);

Transactions are the mechanism for changing property groups. They act atomically, whereby either all of the updates occur or none of them do. An scf_transaction_t is always in one of the following states: reset

started committed invalid

The scf_transaction_create() function allocates and initializes an scf_transaction_t bound to handle. The scf_transaction_destroy() function resets, destroys, and frees tran. If there are any entries associated with the transaction, scf_transaction_destroy() also effects a call to scf_transaction_reset(). The scf_transaction_destroy_children() function resets, destroys, and frees all entries and values associated the transaction.

The scf_transaction_handle() function gets the handle to which tran is bound.

The scf_transaction_start() function sets up the transaction to modify the property group to which pg is set. The time reference used by pg becomes the basis of the transaction. The transaction fails if the property group has been modified since the last update of pg at the time when scf_transaction_commit() is called.

The scf_transaction_property_delete(), scf_transaction_property_new(), scf_transaction_property_change(), and scf_transaction_property_change_type() functions add a new transaction entry to the transaction. Each property the transaction affects must have a unique scf_transaction_entry_t. Each scf_transaction_entry_t can be associated with only a single transaction at a time. These functions all fail if the transaction is not in the started state, prop_name is not a valid property name, or entry is already associated with a transaction. These functions affect commit and failure as follows: scf_transaction_property_delete()

scf_transaction_property_new() scf_transaction_property_change() scf_transaction_property_change_type()

If the function call is successful, entry remains active in the transaction until scf_transaction_destroy(), scf_transaction_reset(), or scf_transaction_reset_all() is called. The scf_entry_add_value(3SCF) manual page provides information for setting up the value list for entries that are not associated with scf_transaction_property_delete(). Resetting or destroying an entry or value active in a transaction will move it into the invalid state.

The scf_transaction_commit() function attempts to commit tran.

The scf_transaction_reset() function returns the transaction to the reset state and releases all of the transaction entries that were added.

The scf_transaction_reset_all() function returns the transaction to the reset state, releases all of the transaction entries, and calls scf_value_reset(3SCF) on all values associated with the entries.

Upon successful completion, scf_transaction_create() returns a new scf_transaction_t. Otherwise, it returns NULL.

Upon successful completion, scf_transaction_handle() returns the handle associated with the transaction. Otherwise, it returns NULL.

Upon successful completion, scf_transaction_start(), scf_transaction_property_delete(), scf_transaction_property_new(), scf_transaction_property_change(), and scf_transaction_property_change_type() return 0. Otherwise, they return -1.

The scf_transaction_commit() function returns 1 upon successful commit, 0 if the property group set in scf_transaction_start() is not the most recent, and -1 on failure.

The scf_transaction_create() function will fail if: SCF_ERROR_INVALID_ARGUMENT

SCF_ERROR_NO_MEMORY SCF_ERROR_NO_RESOURCES

The scf_transaction_handle() function will fail if: SCF_ERROR_HANDLE_DESTROYED

The scf_transaction_start() function will fail if: SCF_ERROR_BACKEND_ACCESS

SCF_ERROR_BACKEND_READONLY SCF_ERROR_CONNECTION_BROKEN SCF_ERROR_DELETED SCF_ERROR_HANDLE_MISMATCH SCF_ERROR_IN_USE SCF_ERROR_NO_RESOURCES SCF_ERROR_NOT_BOUND SCF_ERROR_NOT_SET SCF_ERROR_PERMISSION_DENIED

The scf_transaction_property_delete(), scf_transaction_property_new(), scf_transaction_property_change(), and scf_transaction_property_change_type() functions will fail if: SCF_ERROR_BACKEND_ACCESS

SCF_ERROR_CONNECTION_BROKEN SCF_ERROR_DELETED SCF_ERROR_HANDLE_MISMATCH SCF_ERROR_IN_USE SCF_ERROR_INTERNAL SCF_ERROR_INVALID_ARGUMENT SCF_ERROR_NO_RESOURCES SCF_ERROR_NOT_BOUND SCF_ERROR_NOT_SET SCF_ERROR_TYPE_MISMATCH

The scf_transaction_property_delete(), scf_transaction_property_change(), and scf_transaction_property_change_type() functions will fail if: SCF_ERROR_EXISTS

SCF_ERROR_NOT_FOUND

The scf_transaction_property_new() , scf_transaction_property_change(), and scf_transaction_property_change_type() functions will fail if: SCF_ERROR_INVALID_ARGUMENT

The scf_transaction_property_new() function will fail if: SCF_ERROR_EXISTS

SCF_ERROR_NOT_FOUND

The scf_transaction_property_change() function will fail if: SCF_ERROR_TYPE_MISMATCH

The scf_transaction_commit() function will fail if: SCF_ERROR_BACKEND_READONLY

SCF_ERROR_BACKEND_ACCESS SCF_ERROR_NOT_BOUND SCF_ERROR_CONNECTION_BROKEN SCF_ERROR_INVALID_ARGUMENT SCF_ERROR_DELETED SCF_ERROR_NOT_SET SCF_ERROR_PERMISSION_DENIED SCF_ERROR_NO_RESOURCES

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

Example 1 Set an existing boolean value to true.

tx = scf_transaction_create(handle);
e1 = scf_entry_create(handle);
v1 = scf_value_create(handle);

do {
 if (scf_pg_update(pg) == -1)
 goto fail;
 if (scf_transaction_start(tx, pg) == -1)
 goto fail;

 /* set up transaction entries */
 if (scf_transaction_property_change(tx, e1, "property",
 SCF_TYPE_BOOLEAN) == -1) {
 scf_transaction_reset(tx);
 goto fail;
 }
 scf_value_set_boolean(v1, 1);
 scf_entry_add_value(e1, v1);


 result = scf_transaction_commit(tx);

 scf_transaction_reset(tx);
} while (result == 0);

if (result < 0)
 goto fail;

/* success */

 cleanup:
scf_transaction_destroy(tx);
scf_entry_destroy(e1);
scf_value_destroy(v1);

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

ATTRIBUTE TYPE ATTRIBUTE VALUE

Interface Stability Committed

MT-Level Safe

libscf (3LIB), scf_error (3SCF), scf_pg_create (3SCF), scf_value_reset (3SCF), attributes (7)