1scf_pg_create(3SSCeFr)vice Configuration Facility Library Functisocnfs_pg_create(3SCF)
2
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
16 cc [ flag... ] file... -lscf [ library... ]
17 #include <libscf.h>
18 scf_propertygroup_t *scf_pg_create(scf_handle_t *handle);
20 scf_handle_t *scf_pg_handle(scf_propertygroup_t *pg);
23 void scf_pg_destroy(scf_propertygroup_t *pg);
26 int scf_pg_get_parent_service(const scf_propertygroup_t *pg,
29 scf_service_t *svc);
30 int scf_pg_get_parent_instance(const scf_propertygroup_t *pg,
33 scf_instance_t *inst);
34 int scf_pg_get_parent_snaplevel(const scf_propertygroup_t *pg,
37 scf_snaplevel_t *level);
38 ssize_t scf_pg_get_name(const scf_propertygroup_t *pg, char *buf,
41 size_t size);
42 ssize_t scf_pg_get_type(const scf_propertygroup_t *pg, char *buf,
45 size_t size);
46 int scf_pg_get_flags(const scf_propertygroup_t *pg, uint32_t *out);
49 int scf_pg_update(const scf_propertygroup_t *pg);
52 int scf_service_get_pg(const scf_service_t *svc, const char *name,
55 scf_propertygroup_t *pg);
56 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 int scf_instance_get_pg(const scf_instance_t *inst,
64 const char *name, scf_propertygroup_t *pg);
65 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 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 int scf_snaplevel_get_pg(const scf_snaplevel_t *level,
78 const char *name, scf_propertygroup_t *pg);
79 int scf_pg_delete(scf_propertygroup_t *pg);
82 int scf_pg_get_underlying_pg(const scf_propertygroup_t *pg,
85 scf_propertygroup_t *out);
86
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 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 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 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 The scf_pg_handle() function retrieves the handle to which pg is bound.
113 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 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 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 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 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 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 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 The scf_pg_delete() function deletes the property group. Versions of
161 the property group in snapshots are not affected.
162 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 Applications can use a transaction to modify a property group. See
171 scf_transaction_create(3SCF).
172
174 Upon successful completion, scf_pg_create() returns a new scf_property‐
175 group_t. Otherwise, it returns NULL.
176 Upon successful completion, scf_pg_handle() returns a pointer to the
179 handle to which pg is bound. Otherwise, it returns NULL.
180 Upon successful completion, scf_instance_handle() returns the handle
183 instance with which it is associated. Otherwise, it returns NULL.
184 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 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 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
203 The scf_pg_create() function will fail if:
204 SCF_ERROR_INVALID_ARGUMENT
206 The handle argument is NULL.
208 SCF_ERROR_NO_MEMORY
211 There is not enough memory to allocate an scf_propertygroup_t.
213 SCF_ERROR_NO_RESOURCES
216 The server does not have adequate resources for a new property
218 group handle.
219 The scf_pg_handle() function will fail if:
223 SCF_ERROR_HANDLE_DESTROYED
225 The handle associated with pg has been destroyed.
227 The scf_pg_update() function will fail if:
231 SCF_ERROR_CONNECTION_BROKEN
233 The connection to the repository was lost.
235 SCF_ERROR_DELETED
238 An ancestor of the property group specified by pg has been deleted.
240 SCF_ERROR_INTERNAL
243 An internal error occurred. This can happen if pg has been cor‐
245 rupted.
246 SCF_ERROR_INVALID_ARGUMENT
249 The pg argument refers to an invalid scf_propertygroup_t.
251 SCF_ERROR_NOT_BOUND
254 The handle is not bound.
256 SCF_ERROR_NOT_SET
259 The property group specified by pg is not set.
261 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 SCF_ERROR_BACKEND_ACCESS
269 The storage mechanism that the repository server (svc.con‐
271 figd(1M)) chose for the operation denied access.
272 SCF_ERROR_INTERNAL
275 An internal error occurred.
277 SCF_ERROR_NO_RESOURCES
280 The server does not have the resources to complete the request.
282 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 SCF_ERROR_DELETED
290 The property group specified by pg has been deleted.
292 SCF_ERROR_NOT_SET
295 The property group specified by pg is not set.
297 SCF_ERROR_NOT_BOUND
300 The handle is not bound.
302 SCF_ERROR_CONNECTION_BROKEN
305 The connection to the repository was lost.
307 The scf_pg_get_parent_service(), scf_pg_get_parent_snaplevel(), and
311 scf_pg_get_parent_instance() functions will fail if:
312 SCF_ERROR_CONSTRAINT_VIOLATED
314 The requested parent type does not match the actual type of the
316 parent of the property group specified by pg.
317 SCF_ERROR_HANDLE_MISMATCH
320 The property group and either the instance, the service, or the
322 snaplevel are not derived from the same handle.
323 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 SCF_ERROR_NOT_FOUND
331 The property group specified by name was not found.
333 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 SCF_ERROR_DELETED
341 The service or instance has been deleted.
343 SCF_ERROR_NOT_SET
346 The instance is not set.
348 SCF_ERROR_INVALID_ARGUMENT
351 The value of the name argument is not a valid property group name.
353 SCF_ERROR_HANDLE_MISMATCH
356 The property group and either the instance, the service, or the
358 level are not derived from the same handle.
359 SCF_ERROR_NOT_BOUND
362 The handle is not bound.
364 SCF_ERROR_CONNECTION_BROKEN
367 The connection to the repository was lost.
369 The scf_service_add_pg() and scf_instance_add_pg() functions will fail
373 if:
374 SCF_ERROR_PERMISSION_DENIED
376 The caller does not have permission to create the requested prop‐
378 erty group.
379 SCF_ERROR_BACKEND_READONLY
382 The repository backend is read-only.
384 SCF_ERROR_BACKEND_ACCESS
387 The repository backend refused the modification.
389 SCF_ERROR_EXISTS
392 A {service,instance,property group} named name already exists.
394 SCF_ERROR_NO_RESOURCES
397 The server does not have the resources to complete the request.
399 The scf_pg_delete() function will fail if:
403 SCF_ERROR_BACKEND_ACCESS
405 The repository backend refused the modification.
407 SCF_ERROR_BACKEND_READONLY
410 The repository backend is read-only.
412 SCF_ERROR_CONNECTION_BROKEN
415 The connection to the repository was lost.
417 SCF_ERROR_DELETED
420 The property group has been deleted by someone else.
422 SCF_ERROR_NO_RESOURCES
425 The server does not have adequate resources for a new property
427 group handle.
428 SCF_ERROR_NOT_SET
431 The property group has not been set.
433 SCF_ERROR_PERMISSION_DENIED
436 The caller does not have permission to delete this property group.
438 The scf_pg_get_underlying_pg() function will fail if:
442 SCF_ERROR_CONNECTION_BROKEN
444 The connection to the repository was lost.
446 SCF_ERROR_CONSTRAINT_VIOLATED
449 A required constraint was not met.
451 SCF_ERROR_DELETED
454 The property group has been deleted.
456 SCF_ERROR_HANDLE_MISMATCH
459 The property group and out are not derived from the same handle.
461 SCF_ERROR_INVALID_ARGUMENT
464 An argument is invalid.
466 SCF_ERROR_NOT_BOUND
469 The handle is not bound.
471 SCF_ERROR_NOT_SET
474 The property group has not been set.
476 The scf_error(3SCF) function can be used to retrieve the error value.
480
482 Example 1 Perform a layered lookup of name in pg.
483 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 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 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
516 See attributes(5) for descriptions of the following attributes:
517 ┌─────────────────────────────┬─────────────────────────────┐
522 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
523 ├─────────────────────────────┼─────────────────────────────┤
524 │Interface Stability │Committed │
525 ├─────────────────────────────┼─────────────────────────────┤
526 │MT-Level │Safe │
527 └─────────────────────────────┴─────────────────────────────┘
528
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)
534SunOS 5.11 29 Jun 2009 scf_pg_create(3SCF)