Service Configuration Facility Library Functions
scf_transaction_create(3SCF)
NAME
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 Confi-
guration FacilitySYNOPSIS
cc [ flag... ] file... -lscf [ library... ]
#include
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);
SunOS 5.11 Last change: 28 Aug 2007 1
Service Configuration Facility Library Functionsscf_transaction_create(3SCF)
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 occuror none of them do. An scf_transaction_t is always in one of
the following states: reset The initial state. A successful return ofscf_transaction_start() moves the transaction
to the started state. started The transaction has started. Thescf_transaction_property_delete(),
scf_transaction_property_new(),
scf_transaction_property_change(), and
scf_transaction_property_change_type() func-
tions can be used to set up changes to proper-
ties. The scf_transaction_reset() and
scf_transaction_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_transaction_reset_all() functions return
the transaction to the reset state.The scf_transaction_create() function allocates and initial-
izes an scf_transaction_t bound to handle. The
scf_transaction_destroy() function resets, destroys, and
frees tran. If there are any entries associated with thetransaction, scf_transaction_destroy() also effects a call
to scf_transaction_reset(). The
scf_transaction_destroy_children() function resets,
SunOS 5.11 Last change: 28 Aug 2007 2
Service Configuration Facility Library Functionsscf_transaction_create(3SCF)
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 modi-
fied since the last update of pg at the time whenscf_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 uniquescf_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 startedstate, 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 pro-
perty group. It fails if prop_name does not name a pro-
perty in the property group.scf_transaction_property_new()
This function adds a new property prop_name to the pro-
perty group with a value list of type type. It fails ifprop_name names an existing property in the property
group.scf_transaction_property_change()
This function changes the value list for an existingproperty prop_name in the property group. It fails if
prop_name does not name an existing property in the pro-
perty group or names an existing property with a dif-
ferent type.SunOS 5.11 Last change: 28 Aug 2007 3
Service Configuration Facility Library Functionsscf_transaction_create(3SCF)
scf_transaction_property_change_type()
This function changes the value list and type for anexisting property 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 inthe 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 thatare not associated with scf_transaction_property_delete().
Resetting or destroying an entry or value active in a tran-
saction 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 tran-
saction to the reset state, releases all of the transactionentries, and calls scf_value_reset(3SCF) on all values asso-
ciated 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_transaction_property_delete(),
scf_transaction_property_new(),
scf_transaction_property_change(), and
scf_transaction_property_change_type() return 0. Otherwise,
they return -1.
SunOS 5.11 Last change: 28 Aug 2007 4
Service Configuration Facility Library Functionsscf_transaction_create(3SCF)
The scf_transaction_commit() function returns 1 upon suc-
cessful commit, 0 if the property group set inscf_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 argu-
ment 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 ade-
quate 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 itis read-only.
SCF_ERROR_CONNECTION_BROKEN
The connection to the repository was lost.SCF_ERROR_DELETED
The property group has been deleted.SunOS 5.11 Last change: 28 Aug 2007 5
Service Configuration Facility Library Functionsscf_transaction_create(3SCF)
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. Thescf_transaction_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_property_change_type() functions 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
SunOS 5.11 Last change: 28 Aug 2007 6
Service Configuration Facility Library Functionsscf_transaction_create(3SCF)
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.SunOS 5.11 Last change: 28 Aug 2007 7
Service Configuration Facility Library Functionsscf_transaction_create(3SCF)
The scf_transaction_property_delete(),
scf_transaction_property_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
SunOS 5.11 Last change: 28 Aug 2007 8
Service Configuration Facility Library Functionsscf_transaction_create(3SCF)
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 transaction.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);
SunOS 5.11 Last change: 28 Aug 2007 9
Service Configuration Facility Library Functionsscf_transaction_create(3SCF)
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 attri-
butes:____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Interface Stability | Committed ||_____________________________|_____________________________|
| MT-Level | Safe |
|_____________________________|_____________________________|
SEE ALSO
libscf(3LIB), scf_value_reset(3SCF), scf_error(3SCF),
scf_pg_create(3SCF), attributes(5)
SunOS 5.11 Last change: 28 Aug 2007 10
Service Configuration Facility Library Functionsscf_transaction_create(3SCF)
SunOS 5.11 Last change: 28 Aug 2007 11