share/man/man3scf/scf_entry_create.3scf

   1 '\" te
   2 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH SCF_ENTRY_CREATE 3SCF "Jul 17, 2008"
   7 .SH NAME
   8 scf_entry_create, scf_entry_handle, scf_entry_destroy,
   9 scf_entry_destroy_children, scf_entry_reset, scf_entry_add_value \- create and
  10 manipulate transaction in the Service Configuration Facility
  11 .SH SYNOPSIS
  12 .LP
  13 .nf
  14 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lscf\fR [ \fIlibrary\fR\&.\|.\|. ]
  15 #include <libscf.h>
  16
  17 \fBscf_transaction_entry_t *\fR\fBscf_entry_create\fR(\fBscf_handle_t *\fR\fIhandle\fR);
  18 .fi
  19
  20 .LP
  21 .nf
  22 \fBscf_handle_t *\fR\fBscf_entry_handle\fR(\fBscf_transaction_entry_t *\fR\fIentry\fR);
  23 .fi
  24
  25 .LP
  26 .nf
  27 \fBvoid\fR \fBscf_entry_destroy\fR(\fBscf_transaction_entry_t *\fR\fIentry\fR);
  28 .fi
  29
  30 .LP
  31 .nf
  32 \fBvoid\fR \fBscf_entry_destroy_children\fR(\fBscf_transaction_entry_t *\fR\fIentry\fR);
  33 .fi
  34
  35 .LP
  36 .nf
  37 \fBvoid\fR \fBscf_entry_reset\fR(\fBscf_transaction_entry_t *\fR\fIentry\fR);
  38 .fi
  39
  40 .LP
  41 .nf
  42 \fBint\fR \fBscf_entry_add_value\fR(\fBscf_transaction_entry_t *\fR\fIentry\fR,
  43      \fBscf_value_t *\fR\fIvalue\fR);
  44 .fi
  45
  46 .SH DESCRIPTION
  47 .sp
  48 .LP
  49 The \fBscf_entry_create()\fR function allocates a new transaction entry handle.
  50 The \fBscf_entry_destroy()\fR function destroys the transaction entry handle.
  51 .sp
  52 .LP
  53 The \fBscf_entry_handle()\fR function retrieves the handle associated with
  54 \fIentry\fR.
  55 .sp
  56 .LP
  57 A transaction entry represents a single action on a property in a property
  58 group. If an entry is added to a transaction using
  59 \fBscf_transaction_property_new\fR(3SCF),
  60 \fBscf_transaction_property_change\fR(3SCF), or
  61 \fBscf_transaction_property_change_type\fR(3SCF), \fBscf_entry_add_value()\fR
  62 can be called zero or more times to set up the set of values for that property.
  63 Each value must be set and of a compatible type to the type associated with the
  64 entry. When later retrieved from the property, the values will have the type of
  65 the entry. If the values are committed successfully with
  66 \fBscf_transaction_commit\fR(3SCF), they will be set in the order in which they
  67 were added with \fBscf_entry_add_value()\fR.
  68 .sp
  69 .LP
  70 The \fBscf_entry_reset()\fR function resets a transaction entry, disassociating
  71 it from any transaction it is a part of (invalidating the transaction in the
  72 process), and disassociating any values that were added to it.
  73 .sp
  74 .LP
  75 The \fBscf_entry_destroy_children()\fR function destroys all values associated
  76 with the transaction entry. The entry itself is not destroyed.
  77 .SH RETURN VALUES
  78 .sp
  79 .LP
  80 Upon successful completion, \fBscf_entry_create()\fR returns a new
  81 \fBscf_transaction_entry_t\fR. Otherwise, it returns \fINULL\fR.
  82 .sp
  83 .LP
  84 Upon successful completion, \fBscf_entry_handle()\fR returns the handle
  85 associated with the transaction entry. Otherwise, it returns \fINULL\fR.
  86 .sp
  87 .LP
  88 Upon successful completion, \fBscf_entry_add_value()\fR returns 0. Otherwise,
  89 it returns -1.
  90 .SH ERRORS
  91 .sp
  92 .LP
  93 The \fBscf_entry_create()\fR function will fail if:
  94 .sp
  95 .ne 2
  96 .na
  97 \fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
  98 .ad
  99 .RS 30n
 100 The \fIhandle\fR argument is \fINULL\fR.
 101 .RE
 102
 103 .sp
 104 .ne 2
 105 .na
 106 \fB\fBSCF_ERROR_NO_MEMORY\fR\fR
 107 .ad
 108 .RS 30n
 109 There is not enough memory to allocate an \fBscf_transaction_entry_t\fR.
 110 .RE
 111
 112 .sp
 113 .LP
 114 The \fBscf_entry_handle()\fR function will fail if:
 115 .sp
 116 .ne 2
 117 .na
 118 \fB\fBSCF_ERROR_HANDLE_DESTROYED\fR\fR
 119 .ad
 120 .RS 30n
 121 The handle associated with entry has been destroyed.
 122 .RE
 123
 124 .sp
 125 .LP
 126 The \fBscf_entry_add_value()\fR function will fail if:
 127 .sp
 128 .ne 2
 129 .na
 130 \fB\fBSCF_ERROR_HANDLE_MISMATCH\fR\fR
 131 .ad
 132 .RS 30n
 133 The \fIvalue\fR and \fIentry\fR arguments are not derived from the same handle.
 134 .RE
 135
 136 .sp
 137 .ne 2
 138 .na
 139 \fB\fBSCF_ERROR_IN_USE\fR\fR
 140 .ad
 141 .RS 30n
 142 The value has been added to another entry.
 143 .RE
 144
 145 .sp
 146 .ne 2
 147 .na
 148 \fB\fBSCF_ERROR_INTERNAL\fR\fR
 149 .ad
 150 .RS 30n
 151 An internal error occurred.
 152 .RE
 153
 154 .sp
 155 .ne 2
 156 .na
 157 \fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
 158 .ad
 159 .RS 30n
 160 The \fIvalue\fR argument is not set, or the entry was added to the transaction
 161 using \fBscf_transaction_property_delete\fR(3SCF).
 162 .RE
 163
 164 .sp
 165 .ne 2
 166 .na
 167 \fB\fBSCF_ERROR_NOT_SET\fR\fR
 168 .ad
 169 .RS 30n
 170 The transaction entry is not associated with a transaction.
 171 .RE
 172
 173 .sp
 174 .ne 2
 175 .na
 176 \fB\fBSCF_ERROR_TYPE_MISMATCH\fR\fR
 177 .ad
 178 .RS 30n
 179 The type of the \fIvalue\fR argument does not match the type that was set using
 180 \fBscf_transaction_property_new()\fR, \fBscf_transaction_property_change()\fR,
 181 or \fBscf_transaction_property_change_type()\fR.
 182 .RE
 183
 184 .sp
 185 .LP
 186 The \fBscf_error\fR(3SCF) function can be used to retrieve the error value.
 187 .SH ATTRIBUTES
 188 .sp
 189 .LP
 190 See \fBattributes\fR(5) for descriptions of the following attributes:
 191 .sp
 192
 193 .sp
 194 .TS
 195 box;
 196 c | c
 197 l | l .
 198 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 199 _
 200 Interface Stability     Committed
 201 _
 202 MT-Level        Safe
 203 .TE
 204
 205 .SH SEE ALSO
 206 .sp
 207 .LP
 208 \fBlibscf\fR(3LIB), \fBscf_error\fR(3SCF), \fBscf_transaction_commit\fR(3SCF),
 209 \fBscf_transaction_property_change\fR(3SCF),
 210 \fBscf_transaction_property_change_type\fR(3SCF),
 211 \fBscf_transaction_property_delete\fR(3SCF),
 212 \fBscf_transaction_property_new\fR(3SCF), \fBscf_transaction_reset\fR(3SCF),
 213 \fBattributes\fR(5)