path: root/usr/src/man/man3scf/scf_transaction_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]
.TH SCF_TRANSACTION_CREATE 3SCF "Aug 28, 2007"
.SH 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
Configuration Facility
.SH SYNOPSIS
.LP
.nf
cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lscf\fR [ \fIlibrary\fR\&.\|.\|. ]
#include <libscf.h>

\fBscf_transaction_t *\fR\fBscf_transaction_create\fR(\fBscf_handle_t *\fR\fIhandle\fR);
.fi

.LP
.nf
\fBscf_handle_t *\fR\fBscf_transaction_handle\fR(\fBscf_transaction_t *\fR\fItran\fR);
.fi

.LP
.nf
\fBvoid\fR \fBscf_transaction_reset\fR(\fBscf_transaction_t *\fR\fItran\fR);
.fi

.LP
.nf
\fBvoid\fR \fBscf_transaction_reset_all\fR(\fBscf_transaction_t *\fR\fItran\fR);
.fi

.LP
.nf
\fBvoid\fR \fBscf_transaction_destroy\fR(\fBscf_transaction_t *\fR\fItran\fR);
.fi

.LP
.nf
\fBvoid\fR \fBscf_transaction_destroy_children\fR(\fBscf_transaction_t *\fR\fItran\fR);
.fi

.LP
.nf
\fBint\fR \fBscf_transaction_start\fR(\fBscf_transaction_t *\fR\fItran\fR,
     \fBscf_propertygroup_t *\fR\fIpg\fR);
.fi

.LP
.nf
\fBint\fR \fBscf_transaction_property_delete\fR(\fBscf_transaction_t *\fR\fItran\fR,
     \fBscf_transaction_entry_t *\fR\fIentry\fR, \fBconst char *\fR\fIprop_name\fR);
.fi

.LP
.nf
\fBint\fR \fBscf_transaction_property_new\fR(\fBscf_transaction_t *\fR\fItran\fR,
     \fBscf_transaction_entry_t *\fR\fIentry\fR, \fBconst char *\fR\fIprop_name\fR,
     \fBscf_type_t\fR \fItype\fR);
.fi

.LP
.nf
\fBint\fR \fBscf_transaction_property_change\fR(\fBscf_transaction_t *\fR\fItran\fR,
     \fBscf_transaction_entry_t *\fR\fIentry\fR, \fBconst char *\fR\fIprop_name\fR,
     \fBscf_type_t\fR \fItype\fR);
.fi

.LP
.nf
\fBint\fR \fBscf_transaction_property_change_type\fR(
     \fBscf_transaction_t *\fR\fItran\fR, \fBscf_transaction_entry_t *\fR\fIentry\fR,
     \fBconst char *\fR\fIprop_name\fR, \fBscf_type_t\fR \fItype\fR);
.fi

.LP
.nf
\fBint\fR \fBscf_transaction_commit\fR(\fBscf_transaction_t *\fR\fItran\fR);
.fi

.SH DESCRIPTION
.sp
.LP
Transactions are the mechanism for changing property groups. They act
atomically, whereby either all of the updates occur or none of them do. An
\fBscf_transaction_t\fR is always in one of the following states:
.sp
.ne 2
.na
\fBreset\fR
.ad
.RS 13n
The initial state. A successful return of \fBscf_transaction_start()\fR moves
the transaction to the started state.
.RE

.sp
.ne 2
.na
\fBstarted\fR
.ad
.RS 13n
The transaction has started. The \fBscf_transaction_property_delete()\fR,
\fBscf_transaction_property_new()\fR, \fBscf_transaction_property_change()\fR,
and \fBscf_transaction_property_change_type()\fR functions can be used to set
up changes to properties. The \fBscf_transaction_reset()\fR and
\fBscf_transaction_reset_all()\fR functions return the transaction to the reset
state.
.RE

.sp
.ne 2
.na
\fBcommitted\fR
.ad
.RS 13n
A call to \fBscf_transaction_commit()\fR (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.
.RE

.sp
.ne 2
.na
\fBinvalid\fR
.ad
.RS 13n
The \fBscf_transaction_reset()\fR and \fBscf_transaction_reset_all()\fR
functions return the transaction to the reset state.
.RE

.sp
.LP
The \fBscf_transaction_create()\fR function allocates and initializes an
\fBscf_transaction_t\fR bound to \fIhandle\fR. The
\fBscf_transaction_destroy()\fR function resets, destroys, and frees
\fItran\fR. If there are any entries associated with the transaction,
\fBscf_transaction_destroy()\fR also effects a call to
\fBscf_transaction_reset()\fR. The \fBscf_transaction_destroy_children()\fR
function resets, destroys, and frees all entries and values associated the
transaction.
.sp
.LP
The \fBscf_transaction_handle()\fR function gets the handle to which \fItran\fR
is bound.
.sp
.LP
The \fBscf_transaction_start()\fR function sets up the transaction to modify
the property group to which \fIpg\fR is set. The time reference used by
\fIpg\fR becomes the basis of the transaction. The transaction fails if the
property group has been modified since the last update of \fIpg\fR at the time
when \fBscf_transaction_commit()\fR is called.
.sp
.LP
The \fBscf_transaction_property_delete()\fR,
\fBscf_transaction_property_new()\fR, \fBscf_transaction_property_change()\fR,
and \fBscf_transaction_property_change_type()\fR functions add a new
transaction entry to the transaction. Each property the transaction affects
must have a unique \fBscf_transaction_entry_t\fR. Each
\fBscf_transaction_entry_t\fR can be associated with only a single transaction
at a time. These functions all fail if the transaction is not in the started
state, \fIprop_name\fR is not a valid property name, or \fIentry\fR is already
associated with a transaction. These functions affect commit and failure as
follows:
.sp
.ne 2
.na
\fB\fBscf_transaction_property_delete()\fR\fR
.ad
.sp .6
.RS 4n
This function deletes the property \fIprop_name\fR in the property group. It
fails if \fIprop_name\fR does not name a property in the property group.
.RE

.sp
.ne 2
.na
\fB\fBscf_transaction_property_new()\fR\fR
.ad
.sp .6
.RS 4n
This function adds a new property prop_name\fI\fR to the property group with a
value list of type \fItype\fR. It fails if \fIprop_name\fR names an existing
property in the property group.
.RE

.sp
.ne 2
.na
\fB\fBscf_transaction_property_change()\fR\fR
.ad
.sp .6
.RS 4n
This function changes the value list for an existing property \fIprop_name\fR
in the property group. It fails if \fIprop_name\fR does not name an existing
property in the property group or names an existing property with a different
type.
.RE

.sp
.ne 2
.na
\fB\fBscf_transaction_property_change_type()\fR\fR
.ad
.sp .6
.RS 4n
This function changes the value list and type for an existing property
\fIprop_name\fR in the property group. It fails if \fIprop_name\fR does not
name an existing property in the property group.
.RE

.sp
.LP
If the function call is successful, \fIentry\fR remains active in the
transaction until \fBscf_transaction_destroy()\fR,
\fBscf_transaction_reset()\fR, or \fBscf_transaction_reset_all()\fR is called.
The \fBscf_entry_add_value\fR(3SCF) manual page provides information for
setting up the value list for entries that are not associated with
\fBscf_transaction_property_delete()\fR. Resetting or destroying an entry or
value active in a transaction will move it into the invalid state.
.sp
.LP
The \fBscf_transaction_commit()\fR function attempts to commit \fItran\fR.
.sp
.LP
The \fBscf_transaction_reset()\fR function returns the transaction to the reset
state and releases all of the transaction entries that were added.
.sp
.LP
The \fBscf_transaction_reset_all()\fR function returns the transaction to the
reset state, releases all of the transaction entries, and calls
\fBscf_value_reset\fR(3SCF) on all values associated with the entries.
.SH RETURN VALUES
.sp
.LP
Upon successful completion, \fBscf_transaction_create()\fR returns a new
\fBscf_transaction_t\fR. Otherwise, it returns \fINULL\fR.
.sp
.LP
Upon successful completion, \fBscf_transaction_handle()\fR returns the handle
associated with the transaction. Otherwise, it returns \fINULL\fR.
.sp
.LP
Upon successful completion, \fBscf_transaction_start()\fR,
\fBscf_transaction_property_delete()\fR, \fBscf_transaction_property_new()\fR,
\fBscf_transaction_property_change()\fR, and
\fBscf_transaction_property_change_type()\fR return 0. Otherwise, they return
\(mi1.
.sp
.LP
The \fBscf_transaction_commit()\fR function returns 1 upon successful commit, 0
if the property group set in \fBscf_transaction_start()\fR is not the most
recent, and -1 on failure.
.SH ERRORS
.sp
.LP
The \fBscf_transaction_create()\fR function will fail if:
.sp
.ne 2
.na
\fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
.ad
.RS 30n
The value of the \fIhandle\fR argument is \fINULL\fR.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_NO_MEMORY\fR\fR
.ad
.RS 30n
There is not enough memory to allocate an \fBscf_transaction_t\fR.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_NO_RESOURCES\fR\fR
.ad
.RS 30n
The server does not have adequate resources for a new transaction handle.
.RE

.sp
.LP
The \fBscf_transaction_handle()\fR function will fail if:
.sp
.ne 2
.na
\fB\fBSCF_ERROR_HANDLE_DESTROYED\fR\fR
.ad
.RS 30n
The handle associated with \fItran\fR has been destroyed.
.RE

.sp
.LP
The \fBscf_transaction_start()\fR function will fail if:
.sp
.ne 2
.na
\fB\fBSCF_ERROR_BACKEND_ACCESS\fR\fR
.ad
.sp .6
.RS 4n
The repository backend refused the modification.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_BACKEND_READONLY\fR\fR
.ad
.sp .6
.RS 4n
The repository backend refused modification because it is read-only.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_CONNECTION_BROKEN\fR\fR
.ad
.sp .6
.RS 4n
The connection to the repository was lost.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_DELETED\fR\fR
.ad
.sp .6
.RS 4n
The property group has been deleted.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_HANDLE_MISMATCH\fR\fR
.ad
.sp .6
.RS 4n
The transaction and property group are not derived from the same handle.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_IN_USE\fR\fR
.ad
.sp .6
.RS 4n
The transaction is not in the \fBreset\fR state. The
\fBscf_transaction_reset()\fR and \fBscf_transaction_reset_all()\fR functions
can be used to return the transaction to the \fBreset\fR state.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_NO_RESOURCES\fR\fR
.ad
.sp .6
.RS 4n
The server does not have the resources to complete the request.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_NOT_BOUND\fR\fR
.ad
.sp .6
.RS 4n
The handle was never bound or has been unbound.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_NOT_SET\fR\fR
.ad
.sp .6
.RS 4n
The property group specified by \fIpg\fR is not set.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_PERMISSION_DENIED\fR\fR
.ad
.sp .6
.RS 4n
The user does not have sufficient privileges to modify the property group.
.RE

.sp
.LP
The \fBscf_transaction_property_delete()\fR,
\fBscf_transaction_property_new()\fR, \fBscf_transaction_property_change()\fR,
and \fBscf_transaction_property_change_type()\fR functions will fail if:
.sp
.ne 2
.na
\fB\fBSCF_ERROR_BACKEND_ACCESS\fR\fR
.ad
.sp .6
.RS 4n
The  storage  mechanism  that  the   repository server (\fBsvc.configd\fR(1M))
chose for the operation denied access.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_CONNECTION_BROKEN\fR\fR
.ad
.sp .6
.RS 4n
The connection to the repository was lost.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_DELETED\fR\fR
.ad
.sp .6
.RS 4n
The property group the transaction is changing has been deleted.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_HANDLE_MISMATCH\fR\fR
.ad
.sp .6
.RS 4n
The transaction and entry are not derived from the same handle.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_IN_USE\fR\fR
.ad
.sp .6
.RS 4n
The property already has an entry in the transaction.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_INTERNAL\fR\fR
.ad
.sp .6
.RS 4n
An internal error occurred.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
.ad
.sp .6
.RS 4n
The \fIprop_name\fR argument is not a valid property name.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_NO_RESOURCES\fR\fR
.ad
.sp .6
.RS 4n
The server does not have the resources to complete the request.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_NOT_BOUND\fR\fR
.ad
.sp .6
.RS 4n
The handle is not bound.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_NOT_SET\fR\fR
.ad
.sp .6
.RS 4n
The transaction has not been started.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_TYPE_MISMATCH\fR\fR
.ad
.sp .6
.RS 4n
The \fItran\fR argument is not of a type compatible with \fItype\fR.
.RE

.sp
.LP
The \fBscf_transaction_property_delete()\fR,
\fBscf_transaction_property_change()\fR, and
\fBscf_transaction_property_change_type()\fR functions will fail if:
.sp
.ne 2
.na
\fB\fBSCF_ERROR_EXISTS\fR\fR
.ad
.RS 23n
The object already exists.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_NOT_FOUND\fR\fR
.ad
.RS 23n
The property group does not contain a property named \fIprop_name\fR.
.RE

.sp
.LP
The \fBscf_transaction_property_new()\fR ,
\fBscf_transaction_property_change()\fR, and
\fBscf_transaction_property_change_type()\fR functions will fail if:
.sp
.ne 2
.na
\fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
.ad
.RS 30n
The \fIprop_name\fR argument is not not a valid property name, or the
\fItype\fR argument is an invalid type.
.RE

.sp
.LP
The \fBscf_transaction_property_new()\fR function will fail if:
.sp
.ne 2
.na
\fB\fBSCF_ERROR_EXISTS\fR\fR
.ad
.RS 23n
The property group already contains a property named \fIprop_name\fR.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_NOT_FOUND\fR\fR
.ad
.RS 23n
Nothing of that name was found.
.RE

.sp
.LP
The \fBscf_transaction_property_change()\fR function will fail if:
.sp
.ne 2
.na
\fB\fBSCF_ERROR_TYPE_MISMATCH\fR\fR
.ad
.RS 27n
The property \fIprop_name\fR is not of type \fItype\fR.
.RE

.sp
.LP
The \fBscf_transaction_commit()\fR function will fail if:
.sp
.ne 2
.na
\fB\fBSCF_ERROR_BACKEND_READONLY\fR\fR
.ad
.sp .6
.RS 4n
The repository backend is read-only.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_BACKEND_ACCESS\fR\fR
.ad
.sp .6
.RS 4n
The repository backend refused the modification.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_NOT_BOUND\fR\fR
.ad
.sp .6
.RS 4n
The handle is not bound.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_CONNECTION_BROKEN\fR\fR
.ad
.sp .6
.RS 4n
The connection to the repository was lost.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
.ad
.sp .6
.RS 4n
The transaction is in an invalid state.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_DELETED\fR\fR
.ad
.sp .6
.RS 4n
The property group the transaction is acting on has been deleted.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_NOT_SET\fR\fR
.ad
.sp .6
.RS 4n
The transaction has not been started.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_PERMISSION_DENIED\fR\fR
.ad
.sp .6
.RS 4n
The user does not have sufficient privileges to modify the property group.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_NO_RESOURCES\fR\fR
.ad
.sp .6
.RS 4n
The server does not have sufficient resources to commit the transaction.
.RE

.sp
.LP
The \fBscf_error\fR(3SCF) function can be used to retrieve the error value.
.SH EXAMPLES
.LP
\fBExample 1 \fRSet an existing boolean value to true.
.sp
.in +2
.nf
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);
.fi
.in -2

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Committed
_
MT-Level	Safe
.TE

.SH SEE ALSO
.sp
.LP
\fBlibscf\fR(3LIB), \fBscf_value_reset\fR(3SCF), \fBscf_error\fR(3SCF),
\fBscf_pg_create\fR(3SCF), \fBattributes\fR(5)