path: root/usr/src/man/man3scf/scf_entry_create.3scf

'\" te
.\" Copyright (c) 2008, 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_ENTRY_CREATE 3SCF "Jul 17, 2008"
.SH NAME
scf_entry_create, scf_entry_handle, scf_entry_destroy,
scf_entry_destroy_children, scf_entry_reset, scf_entry_add_value \- 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_entry_t *\fR\fBscf_entry_create\fR(\fBscf_handle_t *\fR\fIhandle\fR);
.fi

.LP
.nf
\fBscf_handle_t *\fR\fBscf_entry_handle\fR(\fBscf_transaction_entry_t *\fR\fIentry\fR);
.fi

.LP
.nf
\fBvoid\fR \fBscf_entry_destroy\fR(\fBscf_transaction_entry_t *\fR\fIentry\fR);
.fi

.LP
.nf
\fBvoid\fR \fBscf_entry_destroy_children\fR(\fBscf_transaction_entry_t *\fR\fIentry\fR);
.fi

.LP
.nf
\fBvoid\fR \fBscf_entry_reset\fR(\fBscf_transaction_entry_t *\fR\fIentry\fR);
.fi

.LP
.nf
\fBint\fR \fBscf_entry_add_value\fR(\fBscf_transaction_entry_t *\fR\fIentry\fR,
     \fBscf_value_t *\fR\fIvalue\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The \fBscf_entry_create()\fR function allocates a new transaction entry handle.
The \fBscf_entry_destroy()\fR function destroys the transaction entry handle.
.sp
.LP
The \fBscf_entry_handle()\fR function retrieves the handle associated with
\fIentry\fR.
.sp
.LP
A transaction entry represents a single action on a property in a property
group. If an entry is added to a transaction using
\fBscf_transaction_property_new\fR(3SCF),
\fBscf_transaction_property_change\fR(3SCF), or
\fBscf_transaction_property_change_type\fR(3SCF), \fBscf_entry_add_value()\fR
can be called zero or more times to set up the set of values for that property.
Each value must be set and of a compatible type to the type associated with the
entry. When later retrieved from the property, the values will have the type of
the entry. If the values are committed successfully with
\fBscf_transaction_commit\fR(3SCF), they will be set in the order in which they
were added with \fBscf_entry_add_value()\fR.
.sp
.LP
The \fBscf_entry_reset()\fR function resets a transaction entry, disassociating
it from any transaction it is a part of (invalidating the transaction in the
process), and disassociating any values that were added to it.
.sp
.LP
The \fBscf_entry_destroy_children()\fR function destroys all values associated
with the transaction entry. The entry itself is not destroyed.
.SH RETURN VALUES
.sp
.LP
Upon successful completion, \fBscf_entry_create()\fR returns a new
\fBscf_transaction_entry_t\fR. Otherwise, it returns \fINULL\fR.
.sp
.LP
Upon successful completion, \fBscf_entry_handle()\fR returns the handle
associated with the transaction entry. Otherwise, it returns \fINULL\fR.
.sp
.LP
Upon successful completion, \fBscf_entry_add_value()\fR returns 0. Otherwise,
it returns -1.
.SH ERRORS
.sp
.LP
The \fBscf_entry_create()\fR function will fail if:
.sp
.ne 2
.na
\fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
.ad
.RS 30n
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_entry_t\fR.
.RE

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

.sp
.LP
The \fBscf_entry_add_value()\fR function will fail if:
.sp
.ne 2
.na
\fB\fBSCF_ERROR_HANDLE_MISMATCH\fR\fR
.ad
.RS 30n
The \fIvalue\fR and \fIentry\fR arguments are not derived from the same handle.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_IN_USE\fR\fR
.ad
.RS 30n
The value has been added to another entry.
.RE

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

.sp
.ne 2
.na
\fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
.ad
.RS 30n
The \fIvalue\fR argument is not set, or the entry was added to the transaction
using \fBscf_transaction_property_delete\fR(3SCF).
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_NOT_SET\fR\fR
.ad
.RS 30n
The transaction entry is not associated with a transaction.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_TYPE_MISMATCH\fR\fR
.ad
.RS 30n
The type of the \fIvalue\fR argument does not match the type that was set using
\fBscf_transaction_property_new()\fR, \fBscf_transaction_property_change()\fR,
or \fBscf_transaction_property_change_type()\fR.
.RE

.sp
.LP
The \fBscf_error\fR(3SCF) function can be used to retrieve the error value.
.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_error\fR(3SCF), \fBscf_transaction_commit\fR(3SCF),
\fBscf_transaction_property_change\fR(3SCF),
\fBscf_transaction_property_change_type\fR(3SCF),
\fBscf_transaction_property_delete\fR(3SCF),
\fBscf_transaction_property_new\fR(3SCF), \fBscf_transaction_reset\fR(3SCF),
\fBattributes\fR(5)