| blob | b895683679332928f000883e1be33721ddbf9af5 |
1 '\" te
2 .\" Copyright (c) 2007, 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_TRANSACTION_CREATE 3SCF "Aug 28, 2007"
7 .SH NAME
8 scf_transaction_create, scf_transaction_handle, scf_transaction_reset,
9 scf_transaction_reset_all, scf_transaction_destroy,
10 scf_transaction_destroy_children, scf_transaction_start,
11 scf_transaction_property_delete, scf_transaction_property_new,
12 scf_transaction_property_change, scf_transaction_property_change_type,
13 scf_transaction_commit \- create and manipulate transaction in the Service
14 Configuration Facility
15 .SH SYNOPSIS
16 .LP
17 .nf
18 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lscf\fR [ \fIlibrary\fR\&.\|.\|. ]
19 #include <libscf.h>
21 \fBscf_transaction_t *\fR\fBscf_transaction_create\fR(\fBscf_handle_t *\fR\fIhandle\fR);
22 .fi
24 .LP
25 .nf
26 \fBscf_handle_t *\fR\fBscf_transaction_handle\fR(\fBscf_transaction_t *\fR\fItran\fR);
27 .fi
29 .LP
30 .nf
31 \fBvoid\fR \fBscf_transaction_reset\fR(\fBscf_transaction_t *\fR\fItran\fR);
32 .fi
34 .LP
35 .nf
36 \fBvoid\fR \fBscf_transaction_reset_all\fR(\fBscf_transaction_t *\fR\fItran\fR);
37 .fi
39 .LP
40 .nf
41 \fBvoid\fR \fBscf_transaction_destroy\fR(\fBscf_transaction_t *\fR\fItran\fR);
42 .fi
44 .LP
45 .nf
46 \fBvoid\fR \fBscf_transaction_destroy_children\fR(\fBscf_transaction_t *\fR\fItran\fR);
47 .fi
49 .LP
50 .nf
51 \fBint\fR \fBscf_transaction_start\fR(\fBscf_transaction_t *\fR\fItran\fR,
52 \fBscf_propertygroup_t *\fR\fIpg\fR);
53 .fi
55 .LP
56 .nf
57 \fBint\fR \fBscf_transaction_property_delete\fR(\fBscf_transaction_t *\fR\fItran\fR,
58 \fBscf_transaction_entry_t *\fR\fIentry\fR, \fBconst char *\fR\fIprop_name\fR);
59 .fi
61 .LP
62 .nf
63 \fBint\fR \fBscf_transaction_property_new\fR(\fBscf_transaction_t *\fR\fItran\fR,
64 \fBscf_transaction_entry_t *\fR\fIentry\fR, \fBconst char *\fR\fIprop_name\fR,
65 \fBscf_type_t\fR \fItype\fR);
66 .fi
68 .LP
69 .nf
70 \fBint\fR \fBscf_transaction_property_change\fR(\fBscf_transaction_t *\fR\fItran\fR,
71 \fBscf_transaction_entry_t *\fR\fIentry\fR, \fBconst char *\fR\fIprop_name\fR,
72 \fBscf_type_t\fR \fItype\fR);
73 .fi
75 .LP
76 .nf
77 \fBint\fR \fBscf_transaction_property_change_type\fR(
78 \fBscf_transaction_t *\fR\fItran\fR, \fBscf_transaction_entry_t *\fR\fIentry\fR,
79 \fBconst char *\fR\fIprop_name\fR, \fBscf_type_t\fR \fItype\fR);
80 .fi
82 .LP
83 .nf
84 \fBint\fR \fBscf_transaction_commit\fR(\fBscf_transaction_t *\fR\fItran\fR);
85 .fi
87 .SH DESCRIPTION
88 .sp
89 .LP
90 Transactions are the mechanism for changing property groups. They act
91 atomically, whereby either all of the updates occur or none of them do. An
92 \fBscf_transaction_t\fR is always in one of the following states:
93 .sp
94 .ne 2
95 .na
96 \fBreset\fR
97 .ad
98 .RS 13n
99 The initial state. A successful return of \fBscf_transaction_start()\fR moves
100 the transaction to the started state.
101 .RE
103 .sp
104 .ne 2
105 .na
106 \fBstarted\fR
107 .ad
108 .RS 13n
109 The transaction has started. The \fBscf_transaction_property_delete()\fR,
110 \fBscf_transaction_property_new()\fR, \fBscf_transaction_property_change()\fR,
111 and \fBscf_transaction_property_change_type()\fR functions can be used to set
112 up changes to properties. The \fBscf_transaction_reset()\fR and
113 \fBscf_transaction_reset_all()\fR functions return the transaction to the reset
114 state.
115 .RE
117 .sp
118 .ne 2
119 .na
120 \fBcommitted\fR
121 .ad
122 .RS 13n
123 A call to \fBscf_transaction_commit()\fR (whether or not it is successful)
124 moves the transaction to the committed state. Modifying, resetting, or
125 destroying the entries and values associated with a transaction will move it to
126 the invalid state.
127 .RE
129 .sp
130 .ne 2
131 .na
132 \fBinvalid\fR
133 .ad
134 .RS 13n
135 The \fBscf_transaction_reset()\fR and \fBscf_transaction_reset_all()\fR
136 functions return the transaction to the reset state.
137 .RE
139 .sp
140 .LP
141 The \fBscf_transaction_create()\fR function allocates and initializes an
142 \fBscf_transaction_t\fR bound to \fIhandle\fR. The
143 \fBscf_transaction_destroy()\fR function resets, destroys, and frees
144 \fItran\fR. If there are any entries associated with the transaction,
145 \fBscf_transaction_destroy()\fR also effects a call to
146 \fBscf_transaction_reset()\fR. The \fBscf_transaction_destroy_children()\fR
147 function resets, destroys, and frees all entries and values associated the
148 transaction.
149 .sp
150 .LP
151 The \fBscf_transaction_handle()\fR function gets the handle to which \fItran\fR
152 is bound.
153 .sp
154 .LP
155 The \fBscf_transaction_start()\fR function sets up the transaction to modify
156 the property group to which \fIpg\fR is set. The time reference used by
157 \fIpg\fR becomes the basis of the transaction. The transaction fails if the
158 property group has been modified since the last update of \fIpg\fR at the time
159 when \fBscf_transaction_commit()\fR is called.
160 .sp
161 .LP
162 The \fBscf_transaction_property_delete()\fR,
163 \fBscf_transaction_property_new()\fR, \fBscf_transaction_property_change()\fR,
164 and \fBscf_transaction_property_change_type()\fR functions add a new
165 transaction entry to the transaction. Each property the transaction affects
166 must have a unique \fBscf_transaction_entry_t\fR. Each
167 \fBscf_transaction_entry_t\fR can be associated with only a single transaction
168 at a time. These functions all fail if the transaction is not in the started
169 state, \fIprop_name\fR is not a valid property name, or \fIentry\fR is already
170 associated with a transaction. These functions affect commit and failure as
171 follows:
172 .sp
173 .ne 2
174 .na
175 \fB\fBscf_transaction_property_delete()\fR\fR
176 .ad
177 .sp .6
178 .RS 4n
179 This function deletes the property \fIprop_name\fR in the property group. It
180 fails if \fIprop_name\fR does not name a property in the property group.
181 .RE
183 .sp
184 .ne 2
185 .na
186 \fB\fBscf_transaction_property_new()\fR\fR
187 .ad
188 .sp .6
189 .RS 4n
190 This function adds a new property prop_name\fI\fR to the property group with a
191 value list of type \fItype\fR. It fails if \fIprop_name\fR names an existing
192 property in the property group.
193 .RE
195 .sp
196 .ne 2
197 .na
198 \fB\fBscf_transaction_property_change()\fR\fR
199 .ad
200 .sp .6
201 .RS 4n
202 This function changes the value list for an existing property \fIprop_name\fR
203 in the property group. It fails if \fIprop_name\fR does not name an existing
204 property in the property group or names an existing property with a different
205 type.
206 .RE
208 .sp
209 .ne 2
210 .na
211 \fB\fBscf_transaction_property_change_type()\fR\fR
212 .ad
213 .sp .6
214 .RS 4n
215 This function changes the value list and type for an existing property
216 \fIprop_name\fR in the property group. It fails if \fIprop_name\fR does not
217 name an existing property in the property group.
218 .RE
220 .sp
221 .LP
222 If the function call is successful, \fIentry\fR remains active in the
223 transaction until \fBscf_transaction_destroy()\fR,
224 \fBscf_transaction_reset()\fR, or \fBscf_transaction_reset_all()\fR is called.
225 The \fBscf_entry_add_value\fR(3SCF) manual page provides information for
226 setting up the value list for entries that are not associated with
227 \fBscf_transaction_property_delete()\fR. Resetting or destroying an entry or
228 value active in a transaction will move it into the invalid state.
229 .sp
230 .LP
231 The \fBscf_transaction_commit()\fR function attempts to commit \fItran\fR.
232 .sp
233 .LP
234 The \fBscf_transaction_reset()\fR function returns the transaction to the reset
235 state and releases all of the transaction entries that were added.
236 .sp
237 .LP
238 The \fBscf_transaction_reset_all()\fR function returns the transaction to the
239 reset state, releases all of the transaction entries, and calls
240 \fBscf_value_reset\fR(3SCF) on all values associated with the entries.
241 .SH RETURN VALUES
242 .sp
243 .LP
244 Upon successful completion, \fBscf_transaction_create()\fR returns a new
245 \fBscf_transaction_t\fR. Otherwise, it returns \fINULL\fR.
246 .sp
247 .LP
248 Upon successful completion, \fBscf_transaction_handle()\fR returns the handle
249 associated with the transaction. Otherwise, it returns \fINULL\fR.
250 .sp
251 .LP
252 Upon successful completion, \fBscf_transaction_start()\fR,
253 \fBscf_transaction_property_delete()\fR, \fBscf_transaction_property_new()\fR,
254 \fBscf_transaction_property_change()\fR, and
255 \fBscf_transaction_property_change_type()\fR return 0. Otherwise, they return
256 \(mi1.
257 .sp
258 .LP
259 The \fBscf_transaction_commit()\fR function returns 1 upon successful commit, 0
260 if the property group set in \fBscf_transaction_start()\fR is not the most
261 recent, and -1 on failure.
262 .SH ERRORS
263 .sp
264 .LP
265 The \fBscf_transaction_create()\fR function will fail if:
266 .sp
267 .ne 2
268 .na
269 \fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
270 .ad
271 .RS 30n
272 The value of the \fIhandle\fR argument is \fINULL\fR.
273 .RE
275 .sp
276 .ne 2
277 .na
278 \fB\fBSCF_ERROR_NO_MEMORY\fR\fR
279 .ad
280 .RS 30n
281 There is not enough memory to allocate an \fBscf_transaction_t\fR.
282 .RE
284 .sp
285 .ne 2
286 .na
287 \fB\fBSCF_ERROR_NO_RESOURCES\fR\fR
288 .ad
289 .RS 30n
290 The server does not have adequate resources for a new transaction handle.
291 .RE
293 .sp
294 .LP
295 The \fBscf_transaction_handle()\fR function will fail if:
296 .sp
297 .ne 2
298 .na
299 \fB\fBSCF_ERROR_HANDLE_DESTROYED\fR\fR
300 .ad
301 .RS 30n
302 The handle associated with \fItran\fR has been destroyed.
303 .RE
305 .sp
306 .LP
307 The \fBscf_transaction_start()\fR function will fail if:
308 .sp
309 .ne 2
310 .na
311 \fB\fBSCF_ERROR_BACKEND_ACCESS\fR\fR
312 .ad
313 .sp .6
314 .RS 4n
315 The repository backend refused the modification.
316 .RE
318 .sp
319 .ne 2
320 .na
321 \fB\fBSCF_ERROR_BACKEND_READONLY\fR\fR
322 .ad
323 .sp .6
324 .RS 4n
325 The repository backend refused modification because it is read-only.
326 .RE
328 .sp
329 .ne 2
330 .na
331 \fB\fBSCF_ERROR_CONNECTION_BROKEN\fR\fR
332 .ad
333 .sp .6
334 .RS 4n
335 The connection to the repository was lost.
336 .RE
338 .sp
339 .ne 2
340 .na
341 \fB\fBSCF_ERROR_DELETED\fR\fR
342 .ad
343 .sp .6
344 .RS 4n
345 The property group has been deleted.
346 .RE
348 .sp
349 .ne 2
350 .na
351 \fB\fBSCF_ERROR_HANDLE_MISMATCH\fR\fR
352 .ad
353 .sp .6
354 .RS 4n
355 The transaction and property group are not derived from the same handle.
356 .RE
358 .sp
359 .ne 2
360 .na
361 \fB\fBSCF_ERROR_IN_USE\fR\fR
362 .ad
363 .sp .6
364 .RS 4n
365 The transaction is not in the \fBreset\fR state. The
366 \fBscf_transaction_reset()\fR and \fBscf_transaction_reset_all()\fR functions
367 can be used to return the transaction to the \fBreset\fR state.
368 .RE
370 .sp
371 .ne 2
372 .na
373 \fB\fBSCF_ERROR_NO_RESOURCES\fR\fR
374 .ad
375 .sp .6
376 .RS 4n
377 The server does not have the resources to complete the request.
378 .RE
380 .sp
381 .ne 2
382 .na
383 \fB\fBSCF_ERROR_NOT_BOUND\fR\fR
384 .ad
385 .sp .6
386 .RS 4n
387 The handle was never bound or has been unbound.
388 .RE
390 .sp
391 .ne 2
392 .na
393 \fB\fBSCF_ERROR_NOT_SET\fR\fR
394 .ad
395 .sp .6
396 .RS 4n
397 The property group specified by \fIpg\fR is not set.
398 .RE
400 .sp
401 .ne 2
402 .na
403 \fB\fBSCF_ERROR_PERMISSION_DENIED\fR\fR
404 .ad
405 .sp .6
406 .RS 4n
407 The user does not have sufficient privileges to modify the property group.
408 .RE
410 .sp
411 .LP
412 The \fBscf_transaction_property_delete()\fR,
413 \fBscf_transaction_property_new()\fR, \fBscf_transaction_property_change()\fR,
414 and \fBscf_transaction_property_change_type()\fR functions will fail if:
415 .sp
416 .ne 2
417 .na
418 \fB\fBSCF_ERROR_BACKEND_ACCESS\fR\fR
419 .ad
420 .sp .6
421 .RS 4n
422 The storage mechanism that the repository server (\fBsvc.configd\fR(1M))
423 chose for the operation denied access.
424 .RE
426 .sp
427 .ne 2
428 .na
429 \fB\fBSCF_ERROR_CONNECTION_BROKEN\fR\fR
430 .ad
431 .sp .6
432 .RS 4n
433 The connection to the repository was lost.
434 .RE
436 .sp
437 .ne 2
438 .na
439 \fB\fBSCF_ERROR_DELETED\fR\fR
440 .ad
441 .sp .6
442 .RS 4n
443 The property group the transaction is changing has been deleted.
444 .RE
446 .sp
447 .ne 2
448 .na
449 \fB\fBSCF_ERROR_HANDLE_MISMATCH\fR\fR
450 .ad
451 .sp .6
452 .RS 4n
453 The transaction and entry are not derived from the same handle.
454 .RE
456 .sp
457 .ne 2
458 .na
459 \fB\fBSCF_ERROR_IN_USE\fR\fR
460 .ad
461 .sp .6
462 .RS 4n
463 The property already has an entry in the transaction.
464 .RE
466 .sp
467 .ne 2
468 .na
469 \fB\fBSCF_ERROR_INTERNAL\fR\fR
470 .ad
471 .sp .6
472 .RS 4n
473 An internal error occurred.
474 .RE
476 .sp
477 .ne 2
478 .na
479 \fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
480 .ad
481 .sp .6
482 .RS 4n
483 The \fIprop_name\fR argument is not a valid property name.
484 .RE
486 .sp
487 .ne 2
488 .na
489 \fB\fBSCF_ERROR_NO_RESOURCES\fR\fR
490 .ad
491 .sp .6
492 .RS 4n
493 The server does not have the resources to complete the request.
494 .RE
496 .sp
497 .ne 2
498 .na
499 \fB\fBSCF_ERROR_NOT_BOUND\fR\fR
500 .ad
501 .sp .6
502 .RS 4n
503 The handle is not bound.
504 .RE
506 .sp
507 .ne 2
508 .na
509 \fB\fBSCF_ERROR_NOT_SET\fR\fR
510 .ad
511 .sp .6
512 .RS 4n
513 The transaction has not been started.
514 .RE
516 .sp
517 .ne 2
518 .na
519 \fB\fBSCF_ERROR_TYPE_MISMATCH\fR\fR
520 .ad
521 .sp .6
522 .RS 4n
523 The \fItran\fR argument is not of a type compatible with \fItype\fR.
524 .RE
526 .sp
527 .LP
528 The \fBscf_transaction_property_delete()\fR,
529 \fBscf_transaction_property_change()\fR, and
530 \fBscf_transaction_property_change_type()\fR functions will fail if:
531 .sp
532 .ne 2
533 .na
534 \fB\fBSCF_ERROR_EXISTS\fR\fR
535 .ad
536 .RS 23n
537 The object already exists.
538 .RE
540 .sp
541 .ne 2
542 .na
543 \fB\fBSCF_ERROR_NOT_FOUND\fR\fR
544 .ad
545 .RS 23n
546 The property group does not contain a property named \fIprop_name\fR.
547 .RE
549 .sp
550 .LP
551 The \fBscf_transaction_property_new()\fR ,
552 \fBscf_transaction_property_change()\fR, and
553 \fBscf_transaction_property_change_type()\fR functions will fail if:
554 .sp
555 .ne 2
556 .na
557 \fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
558 .ad
559 .RS 30n
560 The \fIprop_name\fR argument is not not a valid property name, or the
561 \fItype\fR argument is an invalid type.
562 .RE
564 .sp
565 .LP
566 The \fBscf_transaction_property_new()\fR function will fail if:
567 .sp
568 .ne 2
569 .na
570 \fB\fBSCF_ERROR_EXISTS\fR\fR
571 .ad
572 .RS 23n
573 The property group already contains a property named \fIprop_name\fR.
574 .RE
576 .sp
577 .ne 2
578 .na
579 \fB\fBSCF_ERROR_NOT_FOUND\fR\fR
580 .ad
581 .RS 23n
582 Nothing of that name was found.
583 .RE
585 .sp
586 .LP
587 The \fBscf_transaction_property_change()\fR function will fail if:
588 .sp
589 .ne 2
590 .na
591 \fB\fBSCF_ERROR_TYPE_MISMATCH\fR\fR
592 .ad
593 .RS 27n
594 The property \fIprop_name\fR is not of type \fItype\fR.
595 .RE
597 .sp
598 .LP
599 The \fBscf_transaction_commit()\fR function will fail if:
600 .sp
601 .ne 2
602 .na
603 \fB\fBSCF_ERROR_BACKEND_READONLY\fR\fR
604 .ad
605 .sp .6
606 .RS 4n
607 The repository backend is read-only.
608 .RE
610 .sp
611 .ne 2
612 .na
613 \fB\fBSCF_ERROR_BACKEND_ACCESS\fR\fR
614 .ad
615 .sp .6
616 .RS 4n
617 The repository backend refused the modification.
618 .RE
620 .sp
621 .ne 2
622 .na
623 \fB\fBSCF_ERROR_NOT_BOUND\fR\fR
624 .ad
625 .sp .6
626 .RS 4n
627 The handle is not bound.
628 .RE
630 .sp
631 .ne 2
632 .na
633 \fB\fBSCF_ERROR_CONNECTION_BROKEN\fR\fR
634 .ad
635 .sp .6
636 .RS 4n
637 The connection to the repository was lost.
638 .RE
640 .sp
641 .ne 2
642 .na
643 \fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
644 .ad
645 .sp .6
646 .RS 4n
647 The transaction is in an invalid state.
648 .RE
650 .sp
651 .ne 2
652 .na
653 \fB\fBSCF_ERROR_DELETED\fR\fR
654 .ad
655 .sp .6
656 .RS 4n
657 The property group the transaction is acting on has been deleted.
658 .RE
660 .sp
661 .ne 2
662 .na
663 \fB\fBSCF_ERROR_NOT_SET\fR\fR
664 .ad
665 .sp .6
666 .RS 4n
667 The transaction has not been started.
668 .RE
670 .sp
671 .ne 2
672 .na
673 \fB\fBSCF_ERROR_PERMISSION_DENIED\fR\fR
674 .ad
675 .sp .6
676 .RS 4n
677 The user does not have sufficient privileges to modify the property group.
678 .RE
680 .sp
681 .ne 2
682 .na
683 \fB\fBSCF_ERROR_NO_RESOURCES\fR\fR
684 .ad
685 .sp .6
686 .RS 4n
687 The server does not have sufficient resources to commit the transaction.
688 .RE
690 .sp
691 .LP
692 The \fBscf_error\fR(3SCF) function can be used to retrieve the error value.
693 .SH EXAMPLES
694 .LP
695 \fBExample 1 \fRSet an existing boolean value to true.
696 .sp
697 .in +2
698 .nf
699 tx = scf_transaction_create(handle);
700 e1 = scf_entry_create(handle);
701 v1 = scf_value_create(handle);
703 do {
704 if (scf_pg_update(pg) == -1)
705 goto fail;
706 if (scf_transaction_start(tx, pg) == -1)
707 goto fail;
709 /* set up transaction entries */
710 if (scf_transaction_property_change(tx, e1, "property",
711 SCF_TYPE_BOOLEAN) == -1) {
712 scf_transaction_reset(tx);
713 goto fail;
714 }
715 scf_value_set_boolean(v1, 1);
716 scf_entry_add_value(e1, v1);
719 result = scf_transaction_commit(tx);
721 scf_transaction_reset(tx);
722 } while (result == 0);
724 if (result < 0)
725 goto fail;
727 /* success */
729 cleanup:
730 scf_transaction_destroy(tx);
731 scf_entry_destroy(e1);
732 scf_value_destroy(v1);
733 .fi
734 .in -2
736 .SH ATTRIBUTES
737 .sp
738 .LP
739 See \fBattributes\fR(5) for descriptions of the following attributes:
740 .sp
742 .sp
743 .TS
744 box;
745 c | c
746 l | l .
747 ATTRIBUTE TYPE ATTRIBUTE VALUE
748 _
749 Interface Stability Committed
750 _
751 MT-Level Safe
752 .TE
754 .SH SEE ALSO
755 .sp
756 .LP
757 \fBlibscf\fR(3LIB), \fBscf_value_reset\fR(3SCF), \fBscf_error\fR(3SCF),
758 \fBscf_pg_create\fR(3SCF), \fBattributes\fR(5)