Service Configuration Facility Library Functions
scf_pg_create(3SCF)
NAME
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 Configura-
tion FacilitySYNOPSIS
cc [ flag... ] file... -lscf [ library... ]
#include
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);
SunOS 5.11 Last change: 29 Jun 2009 1
Service Configuration Facility Library Functionsscf_pg_create(3SCF)
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);
DESCRIPTION
Property groups are an atomically-updated group of typed
properties. Property groups of services (seescf_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 anscf_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 eitherscf_pg_update() is called or the property group is set
again.SunOS 5.11 Last change: 29 Jun 2009 2
Service Configuration Facility Library Functionsscf_pg_create(3SCF)
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 pro-
perty 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. IfSCF_PG_FLAG_NONPERSISTENT is set, the property group is not
included in snapshots and will lose its contents upon systemshutdown 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 nameSunOS 5.11 Last change: 29 Jun 2009 3
Service Configuration Facility Library Functionsscf_pg_create(3SCF)
(including the property group name). After a successful callto 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 isgroup_type, and attach the pg handle (if non-null) to the
new object. The flags argument must be either 0 orSCF_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 propertygroup. See scf_transaction_create(3SCF).
RETURN VALUES
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, theyreturn -1.
SunOS 5.11 Last change: 29 Jun 2009 4
Service Configuration Facility Library Functionsscf_pg_create(3SCF)
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.
ERRORS
The scf_pg_create() function will fail if:
SCF_ERROR_INVALID_ARGUMENT
The handle argument is NULL.SCF_ERROR_NO_MEMORY
There is not enough memory to allocate anscf_propertygroup_t.
SCF_ERROR_NO_RESOURCES
The server does not have adequate resources for a new property group handle.The scf_pg_handle() function will fail if:
SCF_ERROR_HANDLE_DESTROYED
The handle associated with pg has been destroyed.The scf_pg_update() function will fail if:
SCF_ERROR_CONNECTION_BROKEN
The connection to the repository was lost.SunOS 5.11 Last change: 29 Jun 2009 5
Service Configuration Facility Library Functionsscf_pg_create(3SCF)
SCF_ERROR_DELETED
An ancestor of the property group specified by pg has been deleted.SCF_ERROR_INTERNAL
An internal error occurred. This can happen if pg has been corrupted.SCF_ERROR_INVALID_ARGUMENT
The pg argument refers to an invalidscf_propertygroup_t.
SCF_ERROR_NOT_BOUND
The handle is not bound.SCF_ERROR_NOT_SET
The property group specified by pg is 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
The storage mechanism that the repository server (svc.configd(1M)) chose for the operation denied access.SCF_ERROR_INTERNAL
An internal error occurred.SCF_ERROR_NO_RESOURCES
The server does not have the resources to complete the request.SunOS 5.11 Last change: 29 Jun 2009 6
Service Configuration Facility Library Functionsscf_pg_create(3SCF)
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
The property group specified by pg has been deleted.SCF_ERROR_NOT_SET
The property group specified by pg is not set.SCF_ERROR_NOT_BOUND
The handle is not bound.SCF_ERROR_CONNECTION_BROKEN
The connection to the repository was lost.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
The requested parent type does not match the actual type of the parent of the property group specified by pg.SCF_ERROR_HANDLE_MISMATCH
The property group and either the instance, the service, or the snaplevel are not derived from the same handle.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 property group specified by name was not found.SunOS 5.11 Last change: 29 Jun 2009 7
Service Configuration Facility Library Functionsscf_pg_create(3SCF)
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
The service or instance has been deleted.SCF_ERROR_NOT_SET
The instance is not set.SCF_ERROR_INVALID_ARGUMENT
The value of the name argument is not a valid property group name.SCF_ERROR_HANDLE_MISMATCH
The property group and either the instance, the service, or the level are not derived from the same handle.SCF_ERROR_NOT_BOUND
The handle is not bound.SCF_ERROR_CONNECTION_BROKEN
The connection to the repository was lost.The scf_service_add_pg() and scf_instance_add_pg() functions
will fail if:SCF_ERROR_PERMISSION_DENIED
The caller does not have permission to create the requested property group.SCF_ERROR_BACKEND_READONLY
The repository backend is read-only.
SunOS 5.11 Last change: 29 Jun 2009 8
Service Configuration Facility Library Functionsscf_pg_create(3SCF)
SCF_ERROR_BACKEND_ACCESS
The repository backend refused the modification.SCF_ERROR_EXISTS
A {service,instance,property group} named name already exists.SCF_ERROR_NO_RESOURCES
The server does not have the resources to complete the request.The scf_pg_delete() function will fail if:
SCF_ERROR_BACKEND_ACCESS
The repository backend refused the modification.SCF_ERROR_BACKEND_READONLY
The repository backend is read-only.
SCF_ERROR_CONNECTION_BROKEN
The connection to the repository was lost.SCF_ERROR_DELETED
The property group has been deleted by someone else.SCF_ERROR_NO_RESOURCES
The server does not have adequate resources for a new property group handle.SCF_ERROR_NOT_SET
The property group has not been set.SunOS 5.11 Last change: 29 Jun 2009 9
Service Configuration Facility Library Functionsscf_pg_create(3SCF)
SCF_ERROR_PERMISSION_DENIED
The caller does not have permission to delete this pro-
perty group.The scf_pg_get_underlying_pg() function will fail if:
SCF_ERROR_CONNECTION_BROKEN
The connection to the repository was lost.SCF_ERROR_CONSTRAINT_VIOLATED
A required constraint was not met.SCF_ERROR_DELETED
The property group has been deleted.SCF_ERROR_HANDLE_MISMATCH
The property group and out are not derived from the same handle.SCF_ERROR_INVALID_ARGUMENT
An argument is invalid.SCF_ERROR_NOT_BOUND
The handle is not bound.SCF_ERROR_NOT_SET
The property group has not been set.The scf_error(3SCF) function can be used to retrieve the
error value.EXAMPLES
SunOS 5.11 Last change: 29 Jun 2009 10
Service Configuration Facility Library Functionsscf_pg_create(3SCF)
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);
}ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Interface Stability | Committed ||_____________________________|_____________________________|
| MT-Level | Safe |
|_____________________________|_____________________________|
SEE ALSO
libscf(3LIB), scf_error(3SCF), scf_handle_decode_fmri(3SCF),
scf_instance_create(3SCF), scf_pg_to_fmri(3SCF),
SunOS 5.11 Last change: 29 Jun 2009 11
Service Configuration Facility Library Functionsscf_pg_create(3SCF)
scf_service_create(3SCF), scf_snaplevel_create(3SCF),
scf_transaction_create(3SCF), attributes(5), smf(5)
SunOS 5.11 Last change: 29 Jun 2009 12
Service Configuration Facility Library Functionsscf_pg_create(3SCF)
SunOS 5.11 Last change: 29 Jun 2009 13