'\" te
.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
.TH scf_entry_create 3SCF "17 Jul 2008" "SunOS 5.11" "Service Configuration Facility Library Functions"
.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
.mk
.na
\fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
.ad
.RS 30n
.rt  
The \fIhandle\fR argument is \fINULL\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fBSCF_ERROR_NO_MEMORY\fR\fR
.ad
.RS 30n
.rt  
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
.mk
.na
\fB\fBSCF_ERROR_HANDLE_DESTROYED\fR\fR
.ad
.RS 30n
.rt  
The handle associated with entry has been destroyed.
.RE

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

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

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

.sp
.ne 2
.mk
.na
\fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
.ad
.RS 30n
.rt  
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
.mk
.na
\fB\fBSCF_ERROR_NOT_SET\fR\fR
.ad
.RS 30n
.rt  
The transaction entry is not associated with a transaction.
.RE

.sp
.ne 2
.mk
.na
\fB\fBSCF_ERROR_TYPE_MISMATCH\fR\fR
.ad
.RS 30n
.rt  
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
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Interface StabilityCommitted
_
MT-LevelSafe
.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)