svcadm(8)을 검색하려면 섹션에서 8 을 선택하고, 맨 페이지 이름에 svcadm을 입력하고 검색을 누른다.
scf_service_add_pg(3scf)
sc...ate(3SCF) Service Configuration Facility Library Functions sc...ate(3SCF)
NAME
scf_pg_create, scf_pg_handle, scf_pg_destroy, scf_pg_get_parent_ser‐
vice, scf_pg_get_parent_instance, scf_pg_get_parent_snaplevel,
scf_pg_get_parent_pg, scf_pg_get_name, scf_pg_get_type,
scf_pg_get_flags, scf_pg_update, scf_service_get_pg, scf_ser‐
vice_add_pg, scf_instance_get_pg, scf_instance_get_pg_composed, scf_in‐
stance_add_pg, scf_pg_get_pg, scf_pg_add_pg, scf_snaplevel_get_pg,
scf_pg_delete, scf_pg_get_underlying_pg - create and manipulate prop‐
erty group handles and property groups in the Service Configuration Fa‐
cility
SYNOPSIS
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);
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);
int scf_pg_get_parent_pg(const scf_propertygroup_t *pg,
scf_propertygroup_t *parent_pg);
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_pg_get_pg(const scf_propertygroup_t *parent_pg,
const char *name, scf_propertygroup_t *pg);
int scf_pg_add_pg(const scf_propertygroup_t *parent_pg,
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 or instances can be modified. Property
groups of snaplevels cannot be modified. For more information, see the
scf_service_create(3SCF), scf_instance_create(3SCF), and
scf_snaplevel_create(3SCF) man pages.
scf_propertygroup_t is an opaque handle that can be set to a single
property group at any given time. When 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
the scf_pg_update() function 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_prop‐
ertygroup_t is updated.
The scf_pg_create() function allocates and initializes a new scf_prop‐
ertygroup_t bound to handle. The scf_pg_destroy() function destroys and
frees pg. The scf_error() function is not modified by this call.
The scf_pg_handle() function retrieves the handle to which pg is bound.
The scf_pg_get_parent_service(), scf_pg_get_parent_instance(),
scf_pg_get_parent_snaplevel(), and scf_pg_get_parent_pg() functions re‐
trieve the parent of the property group, if it is requested.
The scf_pg_get_name() and scf_pg_get_type() functions retrieve the name
and type 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. For more information, see the
smf(7) man page.
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(), scf_pg_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, the property group specified by parent_pg, or the snaplevel spec‐
ified 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 the
snapshot is taken. If the snapshot is NULL, the current properties are
used. The composed view of the properties of an instance 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
the scf_instance_get_pg_composed() function, 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(), scf_instance_add_pg(), and scf_pg_add_pg()
functions create a new property group specified by name whose type is
group_type, and attach the pg handle to the new object if the handle is
not NULL. The flags argument must either be 0 or SCF_PG_FLAG_NONPERSIS‐
TENT.
The scf_pg_delete() function deletes the property group. However, ver‐
sions of the property group in snapshots are not affected.
The scf_pg_get_underlying_pg() function gets the first existing under‐
lying property group. If the property group specified by pg is an in‐
stance property group, out is set to the property group of the same
name in the parent of the instance.
Applications can use a transaction to modify a property group. For more
information, see the scf_transaction_create(3SCF) man page.
RETURN VALUES
On successful completion, the scf_pg_create() function returns a new
scf_propertygroup_t. Else, it returns NULL.
On successful completion, the scf_pg_handle() function returns a
pointer to the handle to which pg is bound. Else, it returns NULL.
On successful completion, the scf_instance_handle() function returns
the handle instance with which it is associated. Else, it returns NULL.
On successful completion, the scf_pg_get_name() and scf_pg_get_type()
functions return the length of the string written, not including the
terminating NULL byte. Else, they return -1.
The scf_pg_update() function returns 1 if the object is updated, 0 if
the object is already up to date, and -1 on failure.
Upon successful completion, the scf_pg_get_parent_service(),
scf_pg_get_parent_snaplevel(), scf_pg_get_parent_pg(),
scf_pg_get_flags(), scf_service_get_pg(), scf_service_add_pg(),
scf_pg_get_parent_instance(), scf_instance_get_pg(), scf_in‐
stance_get_pg_composed(), scf_instance_add_pg(), scf_pg_get_pg(),
scf_pg_add_pg(), scf_snaplevel_get_pg(), scf_pg_delete(), and
scf_pg_get_underlying_pg() functions 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 an
scf_propertygroup_t.
SCF_ERROR_NO_RESOURCES The server does not have adequate re‐
sources for a new property group handle.
The scf_pg_handle() function will fail if:
SCF_ERROR_HANDLE_DESTROYED The handle associated with pg is de‐
stroyed.
The scf_pg_update() function will fail if:
SCF_ERROR_CONNECTION_BROKEN
The connection to the repository is lost.
SCF_ERROR_DELETED
An ancestor of the property group specified by pg is deleted.
SCF_ERROR_INTERNAL
An internal error occurred. This can happen if pg is corrupted.
SCF_ERROR_INVALID_ARGUMENT
The pg argument refers to an invalid scf_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_in‐
stance_get_pg_composed(), scf_snaplevel_get_pg(), and scf_pg_get_under‐
lying_pg() functions will fail if:
SCF_ERROR_BACKEND_ACCESS The storage mechanism that the repository
server chooses for the operation denies ac‐
cess. For more information, see the
svc.configd(8) man page.
SCF_ERROR_INTERNAL An internal error occurred.
SCF_ERROR_NO_RESOURCES The server does not have the resources to
complete the request.
The scf_pg_get_name(), scf_pg_get_type(), scf_pg_get_flags(),
scf_pg_get_parent_service(), scf_pg_get_parent_snaplevel(),
scf_pg_get_parent_instance(), and scf_pg_get_parent_pg() functions will
fail if:
SCF_ERROR_DELETED
The property group specified by pg is 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 is lost.
The scf_pg_get_parent_service(), scf_pg_get_parent_snaplevel(),
scf_pg_get_parent_instance(), and scf_pg_get_parent_pg() 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 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_ser‐
vice_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 is not
found.
The scf_service_add_pg(), scf_service_get_pg(), scf_instance_add_pg(),
scf_instance_get_pg(), scf_instance_get_pg_composed(), scf_pg_add_pg(),
scf_pg_get_pg(), and scf_snaplevel_get_pg() functions will fail if:
SCF_ERROR_DELETED
The service, instance, or property group is deleted.
SCF_ERROR_NOT_SET
The service, instance, or property group 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 the parent property group, 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 is lost.
The scf_service_add_pg(), scf_instance_add_pg(), and scf_pg_add_pg()
functions will fail if:
SCF_ERROR_PERMISSION_DENIED
The caller does not have permission to create the requested prop‐
erty group.
SCF_ERROR_BACKEND_READONLY
The repository backend is read-only.
SCF_ERROR_BACKEND_ACCESS
The repository backend refuses the modification.
SCF_ERROR_EXISTS
The name of the service, instance, or property group already ex‐
ists.
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_READONLY
The repository backend is read-only.
SCF_ERROR_BACKEND_READONLY
The repository backend is read-only.
SCF_ERROR_CONNECTION_BROKEN
The connection to the repository is lost.
SCF_ERROR_DELETED
The property group is deleted by another user.
SCF_ERROR_NO_RESOURCES
The server does not have adequate resources for a new property
group handle.
SCF_ERROR_NOT_SET
The property group is not set.
SCF_ERROR_PERMISSION_DENIED
The caller does not have permission to delete this property group.
The scf_pg_get_underlying_pg() function will fail if:
SCF_ERROR_CONNECTION_BROKEN
The connection to the repository is lost.
SCF_ERROR_CONSTRAINT_VIOLATED
A required constraint is not met.
SCF_ERROR_DELETED
The property group is 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 is been set.
The scf_error(3SCF) function can be used to retrieve the error value.
EXAMPLES
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);
}
Example 2 Retrieve a Property Group called name nested in parent_pg.
scf_propertygroup_t *
get_nested_pg(scf_propertygroup_t *parent_pg, const char *name)
{
scf_handle_t *handle = scf_pg_handle(parent_pg);
scf_propertygroup_t *pg;
if (handle == NULL) {
return (NULL);
}
pg = scf_pg_create(handle);
if (pg == NULL) {
return (NULL);
}
if (scf_pg_get_pg(parent_pg, name, pg) != 0) {
scf_pg_destroy(pg);
return (NULL);
}
return (pg);
}
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) ATTRIBUTE TYPEAT‐
TRIBUTE VALUE _ Interface StabilityCommitted _ MT-LevelSafe
SEE ALSO
libscf(3LIB), scf_error(3SCF), scf_handle_decode_fmri(3SCF), scf_in‐
stance_create(3SCF), scf_pg_to_fmri(3SCF), scf_service_create(3SCF),
scf_snaplevel_create(3SCF), scf_transaction_create(3SCF), attrib‐
utes(7), smf(7)
Oracle Solaris 11.4 14 Aug 2017 sc...ate(3SCF)