Service Configuration Facility Library Functions
scftransactioncreate(3SCF)
NAME
scftransactioncreate, scftransactionhandle,
scftransactionreset, scftransactionresetall,
scftransactiondestroy, scftransactiondestroychildren,
scftransactionstart, scftransactionpropertydelete,
scftransactionpropertynew,
scftransactionpropertychange,
scftransactionpropertychangetype, scftransactioncommit
- create and manipulate transaction in the Service Confi-
guration Facility
SYNOPSIS
cc [ flag... ] file... -lscf [ library... ]
#include
scftransactiont *scftransactioncreate(scfhandlet *handle);
scfhandlet *scftransactionhandle(scftransactiont *tran);
void scftransactionreset(scftransactiont *tran);
void scftransactionresetall(scftransactiont *tran);
void scftransactiondestroy(scftransactiont *tran);
void scftransactiondestroychildren(scftransactiont *tran);
int scftransactionstart(scftransactiont *tran,
scfpropertygroupt *pg);
int scftransactionpropertydelete(scftransactiont *tran,
scftransactionentryt *entry, const char *propname);
int scftransactionpropertynew(scftransactiont *tran,
scftransactionentryt *entry, const char *propname,
scftypet type);
int scftransactionpropertychange(scftransactiont *tran,
scftransactionentryt *entry, const char *propname,
scftypet type);
SunOS 5.11 Last change: 28 Aug 2007 1
Service Configuration Facility Library Functions
scftransactioncreate(3SCF)
int scftransactionpropertychangetype(
scftransactiont *tran, scftransactionentryt *entry,
const char *propname, scftypet type);
int scftransactioncommit(scftransactiont *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 scftransactiont is always in one of
the following states:
reset The initial state. A successful return of
scftransactionstart() moves the transaction
to the started state.
started The transaction has started. The
scftransactionpropertydelete(),
scftransactionpropertynew(),
scftransactionpropertychange(), and
scftransactionpropertychangetype() func-
tions can be used to set up changes to proper-
ties. The scftransactionreset() and
scftransactionresetall() functions return
the transaction to the reset state.
committed A call to scftransactioncommit() (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 scftransactionreset() and
scftransactionresetall() functions return
the transaction to the reset state.
The scftransactioncreate() function allocates and initial-
izes an scftransactiont bound to handle. The
scftransactiondestroy() function resets, destroys, and
frees tran. If there are any entries associated with the
transaction, scftransactiondestroy() also effects a call
to scftransactionreset(). The
scftransactiondestroychildren() function resets,
SunOS 5.11 Last change: 28 Aug 2007 2
Service Configuration Facility Library Functions
scftransactioncreate(3SCF)
destroys, and frees all entries and values associated the
transaction.
The scftransactionhandle() function gets the handle to
which tran is bound.
The scftransactionstart() 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 when
scftransactioncommit() is called.
The scftransactionpropertydelete(),
scftransactionpropertynew(),
scftransactionpropertychange(), and
scftransactionpropertychangetype() functions add a new
transaction entry to the transaction. Each property the
transaction affects must have a unique
scftransactionentryt. Each scftransactionentryt can be
associated with only a single transaction at a time. These
functions all fail if the transaction is not in the started
state, propname is not a valid property name, or entry is
already associated with a transaction. These functions
affect commit and failure as follows:
scftransactionpropertydelete()
This function deletes the property propname in the pro-
perty group. It fails if propname does not name a pro-
perty in the property group.
scftransactionpropertynew()
This function adds a new property propname to the pro-
perty group with a value list of type type. It fails if
propname names an existing property in the property
group.
scftransactionpropertychange()
This function changes the value list for an existing
property propname in the property group. It fails if
propname 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 Functions
scftransactioncreate(3SCF)
scftransactionpropertychangetype()
This function changes the value list and type for an
existing property propname in the property group. It
fails if propname does not name an existing property in
the property group.
If the function call is successful, entry remains active in
the transaction until scftransactiondestroy(),
scftransactionreset(), or scftransactionresetall() is
called. The scfentryaddvalue(3SCF) manual page provides
information for setting up the value list for entries that
are not associated with scftransactionpropertydelete().
Resetting or destroying an entry or value active in a tran-
saction will move it into the invalid state.
The scftransactioncommit() function attempts to commit
tran.
The scftransactionreset() function returns the transaction
to the reset state and releases all of the transaction
entries that were added.
The scftransactionresetall() function returns the tran-
saction to the reset state, releases all of the transaction
entries, and calls scfvaluereset(3SCF) on all values asso-
ciated with the entries.
RETURN VALUES
Upon successful completion, scftransactioncreate() returns
a new scftransactiont. Otherwise, it returns NUL.
Upon successful completion, scftransactionhandle() returns
the handle associated with the transaction. Otherwise, it
returns NUL.
Upon successful completion, scftransactionstart(),
scftransactionpropertydelete(),
scftransactionpropertynew(),
scftransactionpropertychange(), and
scftransactionpropertychangetype() return 0. Otherwise,
they return -1.
SunOS 5.11 Last change: 28 Aug 2007 4
Service Configuration Facility Library Functions
scftransactioncreate(3SCF)
The scftransactioncommit() function returns 1 upon suc-
cessful commit, 0 if the property group set in
scftransactionstart() is not the most recent, and -1 on
failure.
ERORS
The scftransactioncreate() function will fail if:
SCFERORINVALIDARGUMENT The value of the handle argu-
ment is NUL.
SCFERORNOMEMORY There is not enough memory to
allocate an scftransactiont.
SCFERORNORESOURCES The server does not have ade-
quate resources for a new
transaction handle.
The scftransactionhandle() function will fail if:
SCFERORHANDLEDESTROYED The handle associated with
tran has been destroyed.
The scftransactionstart() function will fail if:
SCFERORBACKENDACES
The repository backend refused the modification.
SCFERORBACKENDREADONLY
The repository backend refused modification because it
is read-only.
SCFERORCONECTIONBROKEN
The connection to the repository was lost.
SCFERORDELETED
The property group has been deleted.
SunOS 5.11 Last change: 28 Aug 2007 5
Service Configuration Facility Library Functions
scftransactioncreate(3SCF)
SCFERORHANDLEMISMATCH
The transaction and property group are not derived from
the same handle.
SCFERORINUSE
The transaction is not in the reset state. The
scftransactionreset() and scftransactionresetall()
functions can be used to return the transaction to the
reset state.
SCFERORNORESOURCES
The server does not have the resources to complete the
request.
SCFERORNOTBOUND
The handle was never bound or has been unbound.
SCFERORNOTSET
The property group specified by pg is not set.
SCFERORPERMISIONDENIED
The user does not have sufficient privileges to modify
the property group.
The scftransactionpropertydelete(),
scftransactionpropertynew(),
scftransactionpropertychange(), and
scftransactionpropertychangetype() functions will fail
if:
SCFERORBACKENDACES
The storage mechanism that the repository server
(svc.configd(1M)) chose for the operation denied access.
SCFERORCONECTIONBROKEN
SunOS 5.11 Last change: 28 Aug 2007 6
Service Configuration Facility Library Functions
scftransactioncreate(3SCF)
The connection to the repository was lost.
SCFERORDELETED
The property group the transaction is changing has been
deleted.
SCFERORHANDLEMISMATCH
The transaction and entry are not derived from the same
handle.
SCFERORINUSE
The property already has an entry in the transaction.
SCFERORINTERNAL
An internal error occurred.
SCFERORINVALIDARGUMENT
The propname argument is not a valid property name.
SCFERORNORESOURCES
The server does not have the resources to complete the
request.
SCFERORNOTBOUND
The handle is not bound.
SCFERORNOTSET
The transaction has not been started.
SCFERORTYPEMISMATCH
The tran argument is not of a type compatible with type.
SunOS 5.11 Last change: 28 Aug 2007 7
Service Configuration Facility Library Functions
scftransactioncreate(3SCF)
The scftransactionpropertydelete(),
scftransactionpropertychange(), and
scftransactionpropertychangetype() functions will fail
if:
SCFEROREXISTS The object already exists.
SCFERORNOTFOUND The property group does not contain a
property named propname.
The scftransactionpropertynew() ,
scftransactionpropertychange(), and
scftransactionpropertychangetype() functions will fail
if:
SCFERORINVALIDARGUMENT The propname argument is not
not a valid property name, or
the type argument is an
invalid type.
The scftransactionpropertynew() function will fail if:
SCFEROREXISTS The property group already contains a
property named propname.
SCFERORNOTFOUND Nothing of that name was found.
The scftransactionpropertychange() function will fail if:
SCFERORTYPEMISMATCH The property propname is not of
type type.
The scftransactioncommit() function will fail if:
SCFERORBACKENDREADONLY
The repository backend is read-only.
SCFERORBACKENDACES
SunOS 5.11 Last change: 28 Aug 2007 8
Service Configuration Facility Library Functions
scftransactioncreate(3SCF)
The repository backend refused the modification.
SCFERORNOTBOUND
The handle is not bound.
SCFERORCONECTIONBROKEN
The connection to the repository was lost.
SCFERORINVALIDARGUMENT
The transaction is in an invalid state.
SCFERORDELETED
The property group the transaction is acting on has been
deleted.
SCFERORNOTSET
The transaction has not been started.
SCFERORPERMISIONDENIED
The user does not have sufficient privileges to modify
the property group.
SCFERORNORESOURCES
The server does not have sufficient resources to commit
the transaction.
The scferror(3SCF) function can be used to retrieve the
error value.
EXAMPLES
Example 1 Set an existing boolean value to true.
tx = scftransactioncreate(handle);
e1 = scfentrycreate(handle);
v1 = scfvaluecreate(handle);
SunOS 5.11 Last change: 28 Aug 2007 9
Service Configuration Facility Library Functions
scftransactioncreate(3SCF)
do {
if (scfpgupdate(pg) == -1)
goto fail;
if (scftransactionstart(tx, pg) == -1)
goto fail;
/* set up transaction entries */
if (scftransactionpropertychange(tx, e1, "property",
SCFTYPEBOLEAN) == -1) {
scftransactionreset(tx);
goto fail;
}
scfvaluesetboolean(v1, 1);
scfentryaddvalue(e1, v1);
result = scftransactioncommit(tx);
scftransactionreset(tx);
} while (result == 0);
if (result < 0)
goto fail;
/* success */
cleanup:
scftransactiondestroy(tx);
scfentrydestroy(e1);
scfvaluedestroy(v1);
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Committed
MT-Level Safe
SEE ALSO
libscf(3LIB), scfvaluereset(3SCF), scferror(3SCF),
scfpgcreate(3SCF), attributes(5)
SunOS 5.11 Last change: 28 Aug 2007 10
Service Configuration Facility Library Functions
scftransactioncreate(3SCF)
SunOS 5.11 Last change: 28 Aug 2007 11
|
