1scf_pg_create(3SSCeFr)vice Configuration Facility Library Functisocnfs_pg_create(3SCF)
2
3
4

NAME

6       scf_pg_create,  scf_pg_handle,  scf_pg_destroy,  scf_pg_get_parent_ser‐
7       vice,     scf_pg_get_parent_instance,      scf_pg_get_parent_snaplevel,
8       scf_pg_get_name,   scf_pg_get_type,   scf_pg_get_flags,  scf_pg_update,
9       scf_service_get_pg,      scf_service_add_pg,       scf_instance_get_pg,
10       scf_instance_get_pg_composed,                      scf_instance_add_pg,
11       scf_snaplevel_get_pg, scf_pg_delete, scf_pg_get_underlying_pg -  create
12       and  manipulate  property group handles and property groups in the Ser‐
13       vice Configuration Facility
14

SYNOPSIS

16       cc [ flag... ] file... -lscf [ library... ]
17       #include <libscf.h>
18
19       scf_propertygroup_t *scf_pg_create(scf_handle_t *handle);
20
21
22       scf_handle_t *scf_pg_handle(scf_propertygroup_t *pg);
23
24
25       void scf_pg_destroy(scf_propertygroup_t *pg);
26
27
28       int scf_pg_get_parent_service(const scf_propertygroup_t *pg,
29            scf_service_t *svc);
30
31
32       int scf_pg_get_parent_instance(const scf_propertygroup_t *pg,
33            scf_instance_t *inst);
34
35
36       int scf_pg_get_parent_snaplevel(const scf_propertygroup_t *pg,
37            scf_snaplevel_t *level);
38
39
40       ssize_t scf_pg_get_name(const scf_propertygroup_t *pg, char *buf,
41            size_t size);
42
43
44       ssize_t scf_pg_get_type(const scf_propertygroup_t *pg, char *buf,
45            size_t size);
46
47
48       int scf_pg_get_flags(const scf_propertygroup_t *pg, uint32_t *out);
49
50
51       int scf_pg_update(const scf_propertygroup_t *pg);
52
53
54       int scf_service_get_pg(const scf_service_t *svc, const char *name,
55            scf_propertygroup_t *pg);
56
57
58       int scf_service_add_pg(const scf_service_t *svc,
59            const char *name, const char *group_type,
60            uint32_t flags, scf_propertygroup_t *pg);
61
62
63       int scf_instance_get_pg(const scf_instance_t *inst,
64            const char *name, scf_propertygroup_t *pg);
65
66
67       int scf_instance_get_pg_composed(const scf_instance_t *inst,
68            const scf_snapshot_t *snapshot, const char *name,
69            scf_propertygroup_t *pg);
70
71
72       int scf_instance_add_pg(const scf_instance_t *inst,
73            const char *name, const char *group_type, uint32_t flags,
74            scf_propertygroup_t *pg);
75
76
77       int scf_snaplevel_get_pg(const scf_snaplevel_t *level,
78            const char *name, scf_propertygroup_t *pg);
79
80
81       int scf_pg_delete(scf_propertygroup_t *pg);
82
83
84       int scf_pg_get_underlying_pg(const scf_propertygroup_t *pg,
85            scf_propertygroup_t *out);
86
87

DESCRIPTION

89       Property groups are an atomically-updated group  of  typed  properties.
90       Property groups of services (see scf_service_create(3SCF)) or instances
91       (see scf_instance_create(3SCF))  are  modifiable.  Property  groups  of
92       snaplevels (see scf_snaplevel_create(3SCF)) are not modifiable.
93
94
95       An  scf_propertygroup_t is an opaque handle that can be set to a single
96       property group at any given time. When an scf_propertygroup_t  is  set,
97       it  references  a frozen-in-time version of the property group to which
98       it is set. Updates to the property group  will  not  be  visible  until
99       either scf_pg_update() is called or the property group is set again.
100
101
102       This  static  view is propagated to the scf_property_ts set to children
103       of the property group. They will not see updates, even if the scf_prop‐
104       ertygroup_t is updated.
105
106
107       The  scf_pg_create() function allocates and initializes a new scf_prop‐
108       ertygroup_t bound to handle. The scf_pg_destroy() function destroys and
109       frees pg.
110
111
112       The scf_pg_handle() function retrieves the handle to which pg is bound.
113
114
115       The   scf_pg_get_parent_service(),   scf_pg_get_parent_instance(),  and
116       scf_pg_get_parent_snaplevel() functions retrieve the  property  group's
117       parent, if it is of the requested type.
118
119
120       The scf_pg_get_name() and scf_pg_get_type() functions retrieve the name
121       and type, respectively, of the property group to which pg is set.
122
123
124       The scf_pg_get_flags() function retrieves the flags  for  the  property
125       group  to  which  pg  is  set. If SCF_PG_FLAG_NONPERSISTENT is set, the
126       property group is not included in snapshots and will lose its  contents
127       upon  system  shutdown  or  reboot.  Non-persistent property groups are
128       mainly used for smf-internal state. See smf(5).
129
130
131       The scf_pg_update() function ensures that pg is attached  to  the  most
132       recent version of the pg to which it is set.
133
134
135       The        scf_service_get_pg(),       scf_instance_get_pg(),       and
136       scf_snaplevel_get_pg() functions set pg to the property group specified
137       by  name  in  the  service  specified by svc, the instance specified by
138       inst, or the snaplevel specified by level, respectively.
139
140
141       The scf_instance_get_pg_composed() function sets  pg  to  the  property
142       group  specified by name in the composed view of inst at the time snap‐
143       shot was taken. If snapshot is NULL, the current properties  are  used.
144       The composed view of an instance's properties is the union of the prop‐
145       erties of the instance and its ancestors. Properties  of  the  instance
146       take  precedence  over  properties  of  the  service with the same name
147       (including the  property  group  name).  After  a  successful  call  to
148       scf_instance_get_pg_composed(), the parent of pg might not be inst, and
149       the parents of properties obtained from pg might not be pg. If inst and
150       its parent have property groups with the same name but different types,
151       the properties in the property group of the parent are excluded.
152
153
154       The scf_service_add_pg() and scf_instance_add_pg() functions  create  a
155       new  property  group  specified  by  name whose type is group_type, and
156       attach the pg handle (if non-null) to the new object. The  flags  argu‐
157       ment must be either 0 or SCF_PG_FLAG_NONPERSISTENT.
158
159
160       The  scf_pg_delete()  function  deletes the property group. Versions of
161       the property group in snapshots are not affected.
162
163
164       The scf_pg_get_underlying_pg() function gets the first existing  under‐
165       lying  property  group.  If  the  property  group specified by pg is an
166       instance property group, out is set to the property group of  the  same
167       name in the instance's parent.
168
169
170       Applications  can  use  a  transaction  to modify a property group. See
171       scf_transaction_create(3SCF).
172

RETURN VALUES

174       Upon successful completion, scf_pg_create() returns a new scf_property‐
175       group_t. Otherwise, it returns NULL.
176
177
178       Upon  successful  completion,  scf_pg_handle() returns a pointer to the
179       handle to which pg is bound. Otherwise, it returns NULL.
180
181
182       Upon successful completion, scf_instance_handle()  returns  the  handle
183       instance with which it is associated. Otherwise, it returns NULL.
184
185
186       Upon  successful  completion,  scf_pg_get_name()  and scf_pg_get_type()
187       return the length of the string written, not including the  terminating
188       null byte. Otherwise, they return -1.
189
190
191       The  scf_pg_update() function returns 1 if the object was updated, 0 if
192       the object was already up to date, and -1 on failure.
193
194
195       Upon      successful      completion,      scf_pg_get_parent_service(),
196       scf_pg_get_parent_snaplevel(),       scf_pg_get_flags(),       scf_ser‐
197       vice_get_pg(),   scf_service_add_pg(),    scf_pg_get_parent_instance(),
198       scf_instance_get_pg(),                  scf_instance_get_pg_composed(),
199       scf_instance_add_pg(),  scf_snaplevel_get_pg(),  scf_pg_delete(),   and
200       scf_pg_get_underlying_pg() return 0. Otherwise, they return -1.
201

ERRORS

203       The scf_pg_create() function will fail if:
204
205       SCF_ERROR_INVALID_ARGUMENT
206
207           The handle argument is NULL.
208
209
210       SCF_ERROR_NO_MEMORY
211
212           There is not enough memory to allocate an scf_propertygroup_t.
213
214
215       SCF_ERROR_NO_RESOURCES
216
217           The  server  does  not  have  adequate resources for a new property
218           group handle.
219
220
221
222       The scf_pg_handle() function will fail if:
223
224       SCF_ERROR_HANDLE_DESTROYED
225
226           The handle associated with pg has been destroyed.
227
228
229
230       The scf_pg_update() function will fail if:
231
232       SCF_ERROR_CONNECTION_BROKEN
233
234           The connection to the repository was lost.
235
236
237       SCF_ERROR_DELETED
238
239           An ancestor of the property group specified by pg has been deleted.
240
241
242       SCF_ERROR_INTERNAL
243
244           An internal error occurred. This can happen if  pg  has  been  cor‐
245           rupted.
246
247
248       SCF_ERROR_INVALID_ARGUMENT
249
250           The pg argument refers to an invalid scf_propertygroup_t.
251
252
253       SCF_ERROR_NOT_BOUND
254
255           The handle is not bound.
256
257
258       SCF_ERROR_NOT_SET
259
260           The property group specified by pg is not set.
261
262
263
264       The             scf_service_get_pg(),            scf_instance_get_pg(),
265       scf_instance_get_pg_composed(),       scf_snaplevel_get_pg(),       and
266       scf_pg_get_underlying_pg() functions will fail if:
267
268       SCF_ERROR_BACKEND_ACCESS
269
270           The   storage   mechanism   that  the   repository server (svc.con‐
271           figd(1M)) chose for the operation denied access.
272
273
274       SCF_ERROR_INTERNAL
275
276           An internal error occurred.
277
278
279       SCF_ERROR_NO_RESOURCES
280
281           The server does not have the resources to complete the request.
282
283
284
285       The    scf_pg_get_name(),    scf_pg_get_type(),     scf_pg_get_flags(),
286       scf_pg_get_parent_service(),     scf_pg_get_parent_snaplevel(),     and
287       scf_pg_get_parent_instance() functions will fail if:
288
289       SCF_ERROR_DELETED
290
291           The property group specified by pg has been deleted.
292
293
294       SCF_ERROR_NOT_SET
295
296           The property group specified by pg is not set.
297
298
299       SCF_ERROR_NOT_BOUND
300
301           The handle is not bound.
302
303
304       SCF_ERROR_CONNECTION_BROKEN
305
306           The connection to the repository was lost.
307
308
309
310       The  scf_pg_get_parent_service(),  scf_pg_get_parent_snaplevel(),   and
311       scf_pg_get_parent_instance() functions will fail if:
312
313       SCF_ERROR_CONSTRAINT_VIOLATED
314
315           The  requested  parent  type  does not match the actual type of the
316           parent of the property group specified by pg.
317
318
319       SCF_ERROR_HANDLE_MISMATCH
320
321           The property group and either the instance,  the  service,  or  the
322           snaplevel are not derived from the same handle.
323
324
325
326       The   scf_instance_get_pg(),  scf_instance_get_pg_composed(),  scf_ser‐
327       vice_get_pg(), scf_pg_get_underlying_pg(),  and  scf_snaplevel_get_pg()
328       functions will fail if:
329
330       SCF_ERROR_NOT_FOUND
331
332           The property group specified by name was not found.
333
334
335
336       The  scf_service_add_pg(), scf_service_get_pg(), scf_instance_add_pg(),
337       scf_instance_get_pg(),       scf_instance_get_pg_composed(),        and
338       scf_snaplevel_get_pg() functions will fail if:
339
340       SCF_ERROR_DELETED
341
342           The service or instance has been deleted.
343
344
345       SCF_ERROR_NOT_SET
346
347           The instance is not set.
348
349
350       SCF_ERROR_INVALID_ARGUMENT
351
352           The value of the name argument is not a valid property group name.
353
354
355       SCF_ERROR_HANDLE_MISMATCH
356
357           The  property  group  and  either the instance, the service, or the
358           level are not derived from the same handle.
359
360
361       SCF_ERROR_NOT_BOUND
362
363           The handle is not bound.
364
365
366       SCF_ERROR_CONNECTION_BROKEN
367
368           The connection to the repository was lost.
369
370
371
372       The scf_service_add_pg() and scf_instance_add_pg() functions will  fail
373       if:
374
375       SCF_ERROR_PERMISSION_DENIED
376
377           The  caller  does not have permission to create the requested prop‐
378           erty group.
379
380
381       SCF_ERROR_BACKEND_READONLY
382
383           The repository backend is read-only.
384
385
386       SCF_ERROR_BACKEND_ACCESS
387
388           The repository backend refused the modification.
389
390
391       SCF_ERROR_EXISTS
392
393           A {service,instance,property group} named name already exists.
394
395
396       SCF_ERROR_NO_RESOURCES
397
398           The server does not have the resources to complete the request.
399
400
401
402       The scf_pg_delete() function will fail if:
403
404       SCF_ERROR_BACKEND_ACCESS
405
406           The repository backend refused the modification.
407
408
409       SCF_ERROR_BACKEND_READONLY
410
411           The repository backend is read-only.
412
413
414       SCF_ERROR_CONNECTION_BROKEN
415
416           The connection to the repository was lost.
417
418
419       SCF_ERROR_DELETED
420
421           The property group has been deleted by someone else.
422
423
424       SCF_ERROR_NO_RESOURCES
425
426           The server does not have adequate  resources  for  a  new  property
427           group handle.
428
429
430       SCF_ERROR_NOT_SET
431
432           The property group has not been set.
433
434
435       SCF_ERROR_PERMISSION_DENIED
436
437           The caller does not have permission to delete this property group.
438
439
440
441       The scf_pg_get_underlying_pg() function will fail if:
442
443       SCF_ERROR_CONNECTION_BROKEN
444
445           The connection to the repository was lost.
446
447
448       SCF_ERROR_CONSTRAINT_VIOLATED
449
450           A required constraint was not met.
451
452
453       SCF_ERROR_DELETED
454
455           The property group has been deleted.
456
457
458       SCF_ERROR_HANDLE_MISMATCH
459
460           The property group and out are not derived from the same handle.
461
462
463       SCF_ERROR_INVALID_ARGUMENT
464
465           An argument is invalid.
466
467
468       SCF_ERROR_NOT_BOUND
469
470           The handle is not bound.
471
472
473       SCF_ERROR_NOT_SET
474
475           The property group has not been set.
476
477
478
479       The scf_error(3SCF) function can be used to retrieve the error value.
480

EXAMPLES

482       Example 1 Perform a layered lookup of name in pg.
483
484         int layered_lookup(scf_propertygroup_t *pg, const char *name,
485         scf_property_t *out) {
486              scf_handle_t *handle = scf_pg_handle(out);
487              scf_propertygroup_t *new_pg;
488              scf_propertygroup_t *cur, *other;
489              int state = 0;
490
491              if (handle == NULL) {
492                   return (-1);
493              }
494              new_pg = scf_pg_create(handle);
495              if (new_pg == NULL) {
496                   return (-1);
497              }
498              for (;;) {
499                   cur =   state ? pg : new_pg;
500                   other = state ? new_pg : pg;
501                   state = !state;
502
503                   if (scf_pg_get_property(cur, name, out) != -1) {
504                        scf_pg_destroy(new_pg);
505                        return (SUCCESS);
506                   }
507                   if (scf_pg_get_underlying_pg(cur, other) == -1)
508                        break;
509              }
510              scf_pg_destroy(new_pg);
511              return (NOT_FOUND);
512         }
513
514

ATTRIBUTES

516       See attributes(5) for descriptions of the following attributes:
517
518
519
520
521       ┌─────────────────────────────┬─────────────────────────────┐
522       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
523       ├─────────────────────────────┼─────────────────────────────┤
524       │Interface Stability          │Committed                    │
525       ├─────────────────────────────┼─────────────────────────────┤
526       │MT-Level                     │Safe                         │
527       └─────────────────────────────┴─────────────────────────────┘
528

SEE ALSO

530       libscf(3LIB),       scf_error(3SCF),      scf_handle_decode_fmri(3SCF),
531       scf_instance_create(3SCF),    scf_pg_to_fmri(3SCF),    scf_service_cre‐
532       ate(3SCF),   scf_snaplevel_create(3SCF),  scf_transaction_create(3SCF),
533       attributes(5), smf(5)
534
535
536
537SunOS 5.11                        29 Jun 2009              scf_pg_create(3SCF)
Impressum