SCF_TRANSACTION_CREATE(3SCF)SCF_TRANSACTION_CREATE(3SCF)NAME
scf_transaction_create, scf_transaction_handle, scf_transaction_reset,
scf_transaction_reset_all, scf_transaction_destroy, scf_transac‐
tion_destroy_children, scf_transaction_start, scf_transaction_prop‐
erty_delete, scf_transaction_property_new, scf_transaction_prop‐
erty_change, scf_transaction_property_change_type, scf_transaction_com‐
mit - create and manipulate transaction in the Service Configuration
Facility
SYNOPSIS
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);
DESCRIPTION
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
The initial state. A successful return of scf_transac‐
tion_start() moves the transaction to the started state.
started
The transaction has started. The scf_transaction_prop‐
erty_delete(), scf_transaction_property_new(), scf_trans‐
action_property_change(), and scf_transaction_prop‐
erty_change_type() functions can be used to set up changes
to properties. The scf_transaction_reset() and scf_trans‐
action_reset_all() functions return the transaction to the
reset state.
committed
A call to scf_transaction_commit() (whether or not it is
successful) moves the transaction to the committed state.
Modifying, resetting, or destroying the entries and values
associated with a transaction will move it to the invalid
state.
invalid
The scf_transaction_reset() and scf_transac‐
tion_reset_all() functions return the transaction to the
reset state.
The scf_transaction_create() function allocates and initializes an
scf_transaction_t bound to handle. The scf_transaction_destroy() func‐
tion resets, destroys, and frees tran. If there are any entries associ‐
ated 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_prop‐
erty_change_type() functions add a new transaction entry to the trans‐
action. 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()
This function deletes the property prop_name in the property group.
It fails if prop_name does not name a property in the property
group.
scf_transaction_property_new()
This function adds a new property prop_name to the property group
with a value list of type type. It fails if prop_name names an
existing property in the property group.
scf_transaction_property_change()
This function changes the value list for an existing property
prop_name in the property group. It fails if prop_name does not
name an existing property in the property group or names an exist‐
ing property with a different type.
scf_transaction_property_change_type()
This function changes the value list and type for an existing prop‐
erty prop_name in the property group. It fails if prop_name does
not name an existing property in the property group.
If the function call is successful, entry remains active in the trans‐
action 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.
RETURN VALUES
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_transac‐
tion_property_delete(), scf_transaction_property_new(), scf_transac‐
tion_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.
ERRORS
The scf_transaction_create() function will fail if:
SCF_ERROR_INVALID_ARGUMENT
The value of the handle argument is NULL.
SCF_ERROR_NO_MEMORY
There is not enough memory to allocate an
scf_transaction_t.
SCF_ERROR_NO_RESOURCES
The server does not have adequate
resources for a new transaction handle.
The scf_transaction_handle() function will fail if:
SCF_ERROR_HANDLE_DESTROYED
The handle associated with tran has been
destroyed.
The scf_transaction_start() function will fail if:
SCF_ERROR_BACKEND_ACCESS
The repository backend refused the modification.
SCF_ERROR_BACKEND_READONLY
The repository backend refused modification because it is read-
only.
SCF_ERROR_CONNECTION_BROKEN
The connection to the repository was lost.
SCF_ERROR_DELETED
The property group has been deleted.
SCF_ERROR_HANDLE_MISMATCH
The transaction and property group are not derived from the same
handle.
SCF_ERROR_IN_USE
The transaction is not in the reset state. The scf_transac‐
tion_reset() and scf_transaction_reset_all() functions can be used
to return the transaction to the reset state.
SCF_ERROR_NO_RESOURCES
The server does not have the resources to complete the request.
SCF_ERROR_NOT_BOUND
The handle was never bound or has been unbound.
SCF_ERROR_NOT_SET
The property group specified by pg is not set.
SCF_ERROR_PERMISSION_DENIED
The user does not have sufficient privileges to modify the property
group.
The scf_transaction_property_delete(), scf_transaction_property_new(),
scf_transaction_property_change(), and scf_transaction_prop‐
erty_change_type() functions will fail if:
SCF_ERROR_BACKEND_ACCESS
The storage mechanism that the repository server (svc.con‐
figd(1M)) chose for the operation denied access.
SCF_ERROR_CONNECTION_BROKEN
The connection to the repository was lost.
SCF_ERROR_DELETED
The property group the transaction is changing has been deleted.
SCF_ERROR_HANDLE_MISMATCH
The transaction and entry are not derived from the same handle.
SCF_ERROR_IN_USE
The property already has an entry in the transaction.
SCF_ERROR_INTERNAL
An internal error occurred.
SCF_ERROR_INVALID_ARGUMENT
The prop_name argument is not a valid property 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_SET
The transaction has not been started.
SCF_ERROR_TYPE_MISMATCH
The tran argument is not of a type compatible with type.
The scf_transaction_property_delete(), scf_transaction_prop‐
erty_change(), and scf_transaction_property_change_type() functions
will fail if:
SCF_ERROR_EXISTS
The object already exists.
SCF_ERROR_NOT_FOUND
The property group does not contain a property
named prop_name.
The scf_transaction_property_new() , scf_transaction_property_change(),
and scf_transaction_property_change_type() functions will fail if:
SCF_ERROR_INVALID_ARGUMENT
The prop_name argument is not not a valid
property name, or the type argument is an
invalid type.
The scf_transaction_property_new() function will fail if:
SCF_ERROR_EXISTS
The property group already contains a property
named prop_name.
SCF_ERROR_NOT_FOUND
Nothing of that name was found.
The scf_transaction_property_change() function will fail if:
SCF_ERROR_TYPE_MISMATCH
The property prop_name is not of type type.
The scf_transaction_commit() function will fail if:
SCF_ERROR_BACKEND_READONLY
The repository backend is read-only.
SCF_ERROR_BACKEND_ACCESS
The repository backend refused the modification.
SCF_ERROR_NOT_BOUND
The handle is not bound.
SCF_ERROR_CONNECTION_BROKEN
The connection to the repository was lost.
SCF_ERROR_INVALID_ARGUMENT
The transaction is in an invalid state.
SCF_ERROR_DELETED
The property group the transaction is acting on has been deleted.
SCF_ERROR_NOT_SET
The transaction has not been started.
SCF_ERROR_PERMISSION_DENIED
The user does not have sufficient privileges to modify the property
group.
SCF_ERROR_NO_RESOURCES
The server does not have sufficient resources to commit the trans‐
action.
The scf_error(3SCF) function can be used to retrieve the error value.
EXAMPLES
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);
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
┌────────────────────┬─────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├────────────────────┼─────────────────┤
│Interface Stability │ Committed │
├────────────────────┼─────────────────┤
│MT-Level │ Safe │
└────────────────────┴─────────────────┘
SEE ALSOlibscf(3LIB), scf_value_reset(3SCF), scf_error(3SCF), scf_pg_cre‐
ate(3SCF), attributes(5)
Aug 28, 2007 SCF_TRANSACTION_CREATE(3SCF)
