scf_transaction_property_delete(3scf)

1scf_transaction_Scerrevaitcee(3CSoCnFf)iguration Facility Librasrcyf_Fturnacntsiaocntsion_create(3SCF)
2
3
4

NAME

6       scf_transaction_create,  scf_transaction_handle, scf_transaction_reset,
7       scf_transaction_reset_all,    scf_transaction_destroy,     scf_transac‐
8       tion_destroy_children,   scf_transaction_start,   scf_transaction_prop‐
9       erty_delete,    scf_transaction_property_new,     scf_transaction_prop‐
10       erty_change, scf_transaction_property_change_type, scf_transaction_com‐
11       mit - create and manipulate transaction in  the  Service  Configuration
12       Facility
13

SYNOPSIS

15       cc [ flag... ] file... -lscf [ library... ]
16       #include <libscf.h>
17
18       scf_transaction_t *scf_transaction_create(scf_handle_t *handle);
19
20
21       scf_handle_t *scf_transaction_handle(scf_transaction_t *tran);
22
23
24       void scf_transaction_reset(scf_transaction_t *tran);
25
26
27       void scf_transaction_reset_all(scf_transaction_t *tran);
28
29
30       void scf_transaction_destroy(scf_transaction_t *tran);
31
32
33       void scf_transaction_destroy_children(scf_transaction_t *tran);
34
35
36       int scf_transaction_start(scf_transaction_t *tran,
37            scf_propertygroup_t *pg);
38
39
40       int scf_transaction_property_delete(scf_transaction_t *tran,
41            scf_transaction_entry_t *entry, const char *prop_name);
42
43
44       int scf_transaction_property_new(scf_transaction_t *tran,
45            scf_transaction_entry_t *entry, const char *prop_name,
46            scf_type_t type);
47
48
49       int scf_transaction_property_change(scf_transaction_t *tran,
50            scf_transaction_entry_t *entry, const char *prop_name,
51            scf_type_t type);
52
53
54       int scf_transaction_property_change_type(
55            scf_transaction_t *tran, scf_transaction_entry_t *entry,
56            const char *prop_name, scf_type_t type);
57
58
59       int scf_transaction_commit(scf_transaction_t *tran);
60
61

DESCRIPTION

63       Transactions  are  the mechanism for changing property groups. They act
64       atomically, whereby either all of the updates occur or none of them do.
65       An scf_transaction_t is always in one of the following states:
66
67       reset        The  initial  state.  A  successful return of scf_transac‐
68                    tion_start() moves the transaction to the started state.
69
70
71       started      The transaction  has  started.  The  scf_transaction_prop‐
72                    erty_delete(),  scf_transaction_property_new(), scf_trans‐
73                    action_property_change(),    and     scf_transaction_prop‐
74                    erty_change_type() functions can be used to set up changes
75                    to properties. The scf_transaction_reset() and  scf_trans‐
76                    action_reset_all() functions return the transaction to the
77                    reset state.
78
79
80       committed    A call to scf_transaction_commit() (whether or not  it  is
81                    successful)  moves the transaction to the committed state.
82                    Modifying, resetting, or destroying the entries and values
83                    associated  with a transaction will move it to the invalid
84                    state.
85
86
87       invalid      The     scf_transaction_reset()      and      scf_transac‐
88                    tion_reset_all()  functions  return the transaction to the
89                    reset state.
90
91
92
93       The scf_transaction_create()  function  allocates  and  initializes  an
94       scf_transaction_t  bound to handle. The scf_transaction_destroy() func‐
95       tion resets, destroys, and frees tran. If there are any entries associ‐
96       ated  with  the  transaction,  scf_transaction_destroy() also effects a
97       call to scf_transaction_reset(). The scf_transaction_destroy_children()
98       function  resets, destroys, and frees all entries and values associated
99       the transaction.
100
101
102       The scf_transaction_handle() function gets the handle to which tran  is
103       bound.
104
105
106       The  scf_transaction_start() function sets up the transaction to modify
107       the property group to which pg is set. The time reference  used  by  pg
108       becomes  the  basis  of  the  transaction. The transaction fails if the
109       property group has been modified since the last update  of  pg  at  the
110       time when scf_transaction_commit() is called.
111
112
113       The  scf_transaction_property_delete(), scf_transaction_property_new(),
114       scf_transaction_property_change(),      and       scf_transaction_prop‐
115       erty_change_type()  functions add a new transaction entry to the trans‐
116       action. Each property  the  transaction  affects  must  have  a  unique
117       scf_transaction_entry_t. Each scf_transaction_entry_t can be associated
118       with only a single transaction at a time. These functions all  fail  if
119       the  transaction  is not in the started state, prop_name is not a valid
120       property name, or entry is already associated with a transaction. These
121       functions affect commit and failure as follows:
122
123       scf_transaction_property_delete()
124
125           This function deletes the property prop_name in the property group.
126           It fails if prop_name does not name  a  property  in  the  property
127           group.
128
129
130       scf_transaction_property_new()
131
132           This  function  adds a new property prop_name to the property group
133           with a value list of type type. It  fails  if  prop_name  names  an
134           existing property in the property group.
135
136
137       scf_transaction_property_change()
138
139           This  function  changes  the  value  list  for an existing property
140           prop_name in the property group. It fails  if  prop_name  does  not
141           name  an existing property in the property group or names an exist‐
142           ing property with a different type.
143
144
145       scf_transaction_property_change_type()
146
147           This function changes the value list and type for an existing prop‐
148           erty  prop_name  in  the property group. It fails if prop_name does
149           not name an existing property in the property group.
150
151
152
153       If the function call is successful, entry remains active in the  trans‐
154       action  until  scf_transaction_destroy(),  scf_transaction_reset(),  or
155       scf_transaction_reset_all() is  called.  The  scf_entry_add_value(3SCF)
156       manual  page  provides  information  for  setting up the value list for
157       entries that are not associated with scf_transaction_property_delete().
158       Resetting  or destroying an entry or value active in a transaction will
159       move it into the invalid state.
160
161
162       The scf_transaction_commit() function attempts to commit tran.
163
164
165       The scf_transaction_reset() function returns  the  transaction  to  the
166       reset  state  and  releases  all  of  the transaction entries that were
167       added.
168
169
170       The scf_transaction_reset_all() function returns the transaction to the
171       reset  state,  releases  all  of  the  transaction  entries,  and calls
172       scf_value_reset(3SCF) on all values associated with the entries.
173

RETURN VALUES

175       Upon successful  completion,  scf_transaction_create()  returns  a  new
176       scf_transaction_t. Otherwise, it returns NULL.
177
178
179       Upon successful completion, scf_transaction_handle() returns the handle
180       associated with the transaction. Otherwise, it returns NULL.
181
182
183       Upon  successful  completion,   scf_transaction_start(),   scf_transac‐
184       tion_property_delete(),   scf_transaction_property_new(),  scf_transac‐
185       tion_property_change(),   and    scf_transaction_property_change_type()
186       return 0. Otherwise, they return −1.
187
188
189       The scf_transaction_commit() function returns 1 upon successful commit,
190       0 if the property group set in scf_transaction_start() is not the  most
191       recent, and -1 on failure.
192

ERRORS

194       The scf_transaction_create() function will fail if:
195
196       SCF_ERROR_INVALID_ARGUMENT    The value of the handle argument is NULL.
197
198
199       SCF_ERROR_NO_MEMORY           There is not enough memory to allocate an
200                                     scf_transaction_t.
201
202
203       SCF_ERROR_NO_RESOURCES        The  server  does   not   have   adequate
204                                     resources for a new transaction handle.
205
206
207
208       The scf_transaction_handle() function will fail if:
209
210       SCF_ERROR_HANDLE_DESTROYED    The  handle associated with tran has been
211                                     destroyed.
212
213
214
215       The scf_transaction_start() function will fail if:
216
217       SCF_ERROR_BACKEND_ACCESS
218
219           The repository backend refused the modification.
220
221
222       SCF_ERROR_BACKEND_READONLY
223
224           The repository backend refused modification  because  it  is  read-
225           only.
226
227
228       SCF_ERROR_CONNECTION_BROKEN
229
230           The connection to the repository was lost.
231
232
233       SCF_ERROR_DELETED
234
235           The property group has been deleted.
236
237
238       SCF_ERROR_HANDLE_MISMATCH
239
240           The  transaction  and  property group are not derived from the same
241           handle.
242
243
244       SCF_ERROR_IN_USE
245
246           The transaction  is  not  in  the  reset  state.  The  scf_transac‐
247           tion_reset()  and scf_transaction_reset_all() functions can be used
248           to return the transaction to the reset state.
249
250
251       SCF_ERROR_NO_RESOURCES
252
253           The server does not have the resources to complete the request.
254
255
256       SCF_ERROR_NOT_BOUND
257
258           The handle was never bound or has been unbound.
259
260
261       SCF_ERROR_NOT_SET
262
263           The property group specified by pg is not set.
264
265
266       SCF_ERROR_PERMISSION_DENIED
267
268           The user does not have sufficient privileges to modify the property
269           group.
270
271
272
273       The  scf_transaction_property_delete(), scf_transaction_property_new(),
274       scf_transaction_property_change(),      and       scf_transaction_prop‐
275       erty_change_type() functions will fail if:
276
277       SCF_ERROR_BACKEND_ACCESS
278
279           The   storage   mechanism   that  the   repository server (svc.con‐
280           figd(1M)) chose for the operation denied access.
281
282
283       SCF_ERROR_CONNECTION_BROKEN
284
285           The connection to the repository was lost.
286
287
288       SCF_ERROR_DELETED
289
290           The property group the transaction is changing has been deleted.
291
292
293       SCF_ERROR_HANDLE_MISMATCH
294
295           The transaction and entry are not derived from the same handle.
296
297
298       SCF_ERROR_IN_USE
299
300           The property already has an entry in the transaction.
301
302
303       SCF_ERROR_INTERNAL
304
305           An internal error occurred.
306
307
308       SCF_ERROR_INVALID_ARGUMENT
309
310           The prop_name argument is not a valid property name.
311
312
313       SCF_ERROR_NO_RESOURCES
314
315           The server does not have the resources to complete the request.
316
317
318       SCF_ERROR_NOT_BOUND
319
320           The handle is not bound.
321
322
323       SCF_ERROR_NOT_SET
324
325           The transaction has not been started.
326
327
328       SCF_ERROR_TYPE_MISMATCH
329
330           The tran argument is not of a type compatible with type.
331
332
333
334       The      scf_transaction_property_delete(),       scf_transaction_prop‐
335       erty_change(),   and  scf_transaction_property_change_type()  functions
336       will fail if:
337
338       SCF_ERROR_EXISTS       The object already exists.
339
340
341       SCF_ERROR_NOT_FOUND    The property group does not contain  a  property
342                              named prop_name.
343
344
345
346       The scf_transaction_property_new() , scf_transaction_property_change(),
347       and scf_transaction_property_change_type() functions will fail if:
348
349       SCF_ERROR_INVALID_ARGUMENT    The prop_name argument is not not a valid
350                                     property name, or the type argument is an
351                                     invalid type.
352
353
354
355       The scf_transaction_property_new() function will fail if:
356
357       SCF_ERROR_EXISTS       The property group already contains  a  property
358                              named prop_name.
359
360
361       SCF_ERROR_NOT_FOUND    Nothing of that name was found.
362
363
364
365       The scf_transaction_property_change() function will fail if:
366
367       SCF_ERROR_TYPE_MISMATCH    The property prop_name is not of type type.
368
369
370
371       The scf_transaction_commit() function will fail if:
372
373       SCF_ERROR_BACKEND_READONLY
374
375           The repository backend is read-only.
376
377
378       SCF_ERROR_BACKEND_ACCESS
379
380           The repository backend refused the modification.
381
382
383       SCF_ERROR_NOT_BOUND
384
385           The handle is not bound.
386
387
388       SCF_ERROR_CONNECTION_BROKEN
389
390           The connection to the repository was lost.
391
392
393       SCF_ERROR_INVALID_ARGUMENT
394
395           The transaction is in an invalid state.
396
397
398       SCF_ERROR_DELETED
399
400           The property group the transaction is acting on has been deleted.
401
402
403       SCF_ERROR_NOT_SET
404
405           The transaction has not been started.
406
407
408       SCF_ERROR_PERMISSION_DENIED
409
410           The user does not have sufficient privileges to modify the property
411           group.
412
413
414       SCF_ERROR_NO_RESOURCES
415
416           The server does not have sufficient resources to commit the  trans‐
417           action.
418
419
420
421       The scf_error(3SCF) function can be used to retrieve the error value.
422

EXAMPLES

424       Example 1 Set an existing boolean value to true.
425
426         tx = scf_transaction_create(handle);
427         e1 = scf_entry_create(handle);
428         v1 = scf_value_create(handle);
429
430         do {
431              if (scf_pg_update(pg) == -1)
432                   goto fail;
433              if (scf_transaction_start(tx, pg) == -1)
434                   goto fail;
435
436              /* set up transaction entries */
437              if (scf_transaction_property_change(tx, e1, "property",
438                 SCF_TYPE_BOOLEAN) == -1) {
439                     scf_transaction_reset(tx);
440                     goto fail;
441              }
442              scf_value_set_boolean(v1, 1);
443              scf_entry_add_value(e1, v1);
444
445
446              result = scf_transaction_commit(tx);
447
448              scf_transaction_reset(tx);
449         } while (result == 0);
450
451         if (result < 0)
452              goto fail;
453
454         /* success */
455
456            cleanup:
457         scf_transaction_destroy(tx);
458         scf_entry_destroy(e1);
459         scf_value_destroy(v1);
460
461

ATTRIBUTES

463       See attributes(5) for descriptions of the following attributes:
464
465
466
467
468       ┌─────────────────────────────┬─────────────────────────────┐
469       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
470       ├─────────────────────────────┼─────────────────────────────┤
471       │Interface Stability          │Committed                    │
472       ├─────────────────────────────┼─────────────────────────────┤
473       │MT-Level                     │Safe                         │
474       └─────────────────────────────┴─────────────────────────────┘
475