te
Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved.
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. 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. 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]
scf_pg_create, scf_pg_handle, scf_pg_destroy, scf_pg_get_parent_service, scf_pg_get_parent_instance, scf_pg_get_parent_snaplevel, scf_pg_get_name, scf_pg_get_type, scf_pg_get_flags, scf_pg_update, scf_service_get_pg, scf_service_add_pg, scf_instance_get_pg, scf_instance_get_pg_composed, scf_instance_add_pg, scf_snaplevel_get_pg, scf_pg_delete, scf_pg_get_underlying_pg - create and manipulate property group handles and property groups in the Service Configuration Facility

cc [ flag.\|.\|. ] file.\|.\|. -lscf [ library.\|.\|. ]
#include <libscf.h>

scf_propertygroup_t *scf_pg_create(scf_handle_t *handle);

scf_handle_t *scf_pg_handle(scf_propertygroup_t *pg);

void scf_pg_destroy(scf_propertygroup_t *pg);

int scf_pg_get_parent_service(const scf_propertygroup_t *pg,
 scf_service_t *svc);

int scf_pg_get_parent_instance(const scf_propertygroup_t *pg,
 scf_instance_t *inst);

int scf_pg_get_parent_snaplevel(const scf_propertygroup_t *pg,
 scf_snaplevel_t *level);

ssize_t scf_pg_get_name(const scf_propertygroup_t *pg, char *buf,
 size_t size);

ssize_t scf_pg_get_type(const scf_propertygroup_t *pg, char *buf,
 size_t size);

int scf_pg_get_flags(const scf_propertygroup_t *pg, uint32_t *out);

int scf_pg_update(const scf_propertygroup_t *pg);

int scf_service_get_pg(const scf_service_t *svc, const char *name,
 scf_propertygroup_t *pg);

int scf_service_add_pg(const scf_service_t *svc,
 const char *name, const char *group_type,
 uint32_t flags, scf_propertygroup_t *pg);

int scf_instance_get_pg(const scf_instance_t *inst,
 const char *name, scf_propertygroup_t *pg);

int scf_instance_get_pg_composed(const scf_instance_t *inst,
 const scf_snapshot_t *snapshot, const char *name,
 scf_propertygroup_t *pg);

int scf_instance_add_pg(const scf_instance_t *inst,
 const char *name, const char *group_type, uint32_t flags,
 scf_propertygroup_t *pg);

int scf_snaplevel_get_pg(const scf_snaplevel_t *level,
 const char *name, scf_propertygroup_t *pg);

int scf_pg_delete(scf_propertygroup_t *pg);

int scf_pg_get_underlying_pg(const scf_propertygroup_t *pg,
 scf_propertygroup_t *out);

Property groups are an atomically-updated group of typed properties. Property groups of services (see scf_service_create(3SCF)) or instances (see scf_instance_create(3SCF)) are modifiable. Property groups of snaplevels (see scf_snaplevel_create(3SCF)) are not modifiable.

An scf_propertygroup_t is an opaque handle that can be set to a single property group at any given time. When an scf_propertygroup_t is set, it references a frozen-in-time version of the property group to which it is set. Updates to the property group will not be visible until either scf_pg_update() is called or the property group is set again.

This static view is propagated to the scf_property_ts set to children of the property group. They will not see updates, even if the scf_propertygroup_t is updated.

The scf_pg_create() function allocates and initializes a new scf_propertygroup_t bound to handle. The scf_pg_destroy() function destroys and frees pg.

The scf_pg_handle() function retrieves the handle to which pg is bound.

The scf_pg_get_parent_service(), scf_pg_get_parent_instance(), and scf_pg_get_parent_snaplevel() functions retrieve the property group's parent, if it is of the requested type.

The scf_pg_get_name() and scf_pg_get_type() functions retrieve the name and type, respectively, of the property group to which pg is set.

The scf_pg_get_flags() function retrieves the flags for the property group to which pg is set. If SCF_PG_FLAG_NONPERSISTENT is set, the property group is not included in snapshots and will lose its contents upon system shutdown or reboot. Non-persistent property groups are mainly used for smf-internal state. See smf(5).

The scf_pg_update() function ensures that pg is attached to the most recent version of the pg to which it is set.

The scf_service_get_pg(), scf_instance_get_pg(), and scf_snaplevel_get_pg() functions set pg to the property group specified by name in the service specified by svc, the instance specified by inst, or the snaplevel specified by level, respectively.

The scf_instance_get_pg_composed() function sets pg to the property group specified by name in the composed view of inst at the time snapshot was taken. If snapshot is NULL, the current properties are used. The composed view of an instance's properties is the union of the properties of the instance and its ancestors. Properties of the instance take precedence over properties of the service with the same name (including the property group name). After a successful call to scf_instance_get_pg_composed(), the parent of pg might not be inst, and the parents of properties obtained from pg might not be pg. If inst and its parent have property groups with the same name but different types, the properties in the property group of the parent are excluded.

The scf_service_add_pg() and scf_instance_add_pg() functions create a new property group specified by name whose type is group_type, and attach the pg handle (if non-null) to the new object. The flags argument must be either 0 or SCF_PG_FLAG_NONPERSISTENT.

The scf_pg_delete() function deletes the property group. Versions of the property group in snapshots are not affected.

The scf_pg_get_underlying_pg() function gets the first existing underlying property group. If the property group specified by pg is an instance property group, out is set to the property group of the same name in the instance's parent.

Applications can use a transaction to modify a property group. See scf_transaction_create(3SCF).

Upon successful completion, scf_pg_create() returns a new scf_propertygroup_t. Otherwise, it returns NULL.

Upon successful completion, scf_pg_handle() returns a pointer to the handle to which pg is bound. Otherwise, it returns NULL.

Upon successful completion, scf_instance_handle() returns the handle instance with which it is associated. Otherwise, it returns NULL.

Upon successful completion, scf_pg_get_name() and scf_pg_get_type() return the length of the string written, not including the terminating null byte. Otherwise, they return -1.

The scf_pg_update() function returns 1 if the object was updated, 0 if the object was already up to date, and -1 on failure.

Upon successful completion, scf_pg_get_parent_service(), scf_pg_get_parent_snaplevel(), scf_pg_get_flags(), scf_service_get_pg(), scf_service_add_pg(), scf_pg_get_parent_instance(), scf_instance_get_pg(), scf_instance_get_pg_composed(), scf_instance_add_pg(), scf_snaplevel_get_pg(), scf_pg_delete(), and scf_pg_get_underlying_pg() return 0. Otherwise, they return -1.

The scf_pg_create() function will fail if: SCF_ERROR_INVALID_ARGUMENT

SCF_ERROR_NO_MEMORY SCF_ERROR_NO_RESOURCES

The scf_pg_handle() function will fail if: SCF_ERROR_HANDLE_DESTROYED

The scf_pg_update() function will fail if: SCF_ERROR_CONNECTION_BROKEN

SCF_ERROR_DELETED SCF_ERROR_INTERNAL SCF_ERROR_INVALID_ARGUMENT SCF_ERROR_NOT_BOUND SCF_ERROR_NOT_SET

The scf_service_get_pg(), scf_instance_get_pg(), scf_instance_get_pg_composed(), scf_snaplevel_get_pg(), and scf_pg_get_underlying_pg() functions will fail if: SCF_ERROR_BACKEND_ACCESS

SCF_ERROR_INTERNAL SCF_ERROR_NO_RESOURCES

The scf_pg_get_name(), scf_pg_get_type(), scf_pg_get_flags(), scf_pg_get_parent_service(), scf_pg_get_parent_snaplevel(), and scf_pg_get_parent_instance() functions will fail if: SCF_ERROR_DELETED

SCF_ERROR_NOT_SET SCF_ERROR_NOT_BOUND SCF_ERROR_CONNECTION_BROKEN

The scf_pg_get_parent_service(), scf_pg_get_parent_snaplevel(), and scf_pg_get_parent_instance() functions will fail if: SCF_ERROR_CONSTRAINT_VIOLATED

SCF_ERROR_HANDLE_MISMATCH

The scf_instance_get_pg(), scf_instance_get_pg_composed(), scf_service_get_pg(), scf_pg_get_underlying_pg(), and scf_snaplevel_get_pg() functions will fail if: SCF_ERROR_NOT_FOUND

The scf_service_add_pg(), scf_service_get_pg(), scf_instance_add_pg(), scf_instance_get_pg(), scf_instance_get_pg_composed(), and scf_snaplevel_get_pg() functions will fail if: SCF_ERROR_DELETED

SCF_ERROR_NOT_SET SCF_ERROR_INVALID_ARGUMENT SCF_ERROR_HANDLE_MISMATCH SCF_ERROR_NOT_BOUND SCF_ERROR_CONNECTION_BROKEN

The scf_service_add_pg() and scf_instance_add_pg() functions will fail if: SCF_ERROR_PERMISSION_DENIED

SCF_ERROR_BACKEND_READONLY SCF_ERROR_BACKEND_ACCESS SCF_ERROR_EXISTS SCF_ERROR_NO_RESOURCES

The scf_pg_delete() function will fail if: SCF_ERROR_BACKEND_ACCESS

SCF_ERROR_BACKEND_READONLY SCF_ERROR_CONNECTION_BROKEN SCF_ERROR_DELETED SCF_ERROR_NO_RESOURCES SCF_ERROR_NOT_SET SCF_ERROR_PERMISSION_DENIED

The scf_pg_get_underlying_pg() function will fail if: SCF_ERROR_CONNECTION_BROKEN

SCF_ERROR_CONSTRAINT_VIOLATED SCF_ERROR_DELETED SCF_ERROR_HANDLE_MISMATCH SCF_ERROR_INVALID_ARGUMENT SCF_ERROR_NOT_BOUND SCF_ERROR_NOT_SET

The scf_error(3SCF) function can be used to retrieve the error value.

Example 1 Perform a layered lookup of name in pg.

int layered_lookup(scf_propertygroup_t *pg, const char *name,
scf_property_t *out) {
 scf_handle_t *handle = scf_pg_handle(out);
 scf_propertygroup_t *new_pg;
 scf_propertygroup_t *cur, *other;
 int state = 0;

 if (handle == NULL) {
 return (-1);
 }
 new_pg = scf_pg_create(handle);
 if (new_pg == NULL) {
 return (-1);
 }
 for (;;) {
 cur = state ? pg : new_pg;
 other = state ? new_pg : pg;
 state = !state;

 if (scf_pg_get_property(cur, name, out) != -1) {
 scf_pg_destroy(new_pg);
 return (SUCCESS);
 }
 if (scf_pg_get_underlying_pg(cur, other) == -1)
 break;
 }
 scf_pg_destroy(new_pg);
 return (NOT_FOUND);
}

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Interface Stability Committed

MT-Level Safe

libscf(3LIB), scf_error(3SCF), scf_handle_decode_fmri(3SCF), scf_instance_create(3SCF), scf_pg_to_fmri(3SCF), scf_service_create(3SCF), scf_snaplevel_create(3SCF), scf_transaction_create(3SCF), attributes(5), smf(5)