scf_instance_create

, scf_instance_handle

, scf_instance_destroy

, scf_instance_get_parent

, scf_instance_get_name

, scf_service_get_instance

, scf_service_add_instance

, scf_instance_is_complete

, scf_instance_delete

- create and manipulate instance handles and instances in the Service Configuration Facility

Synopsis

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

scf_instance_t *scf_instance_create(scf_handle_t *handle);

scf_handle_t *scf_instance_handle(scf_instance_t *inst);

void scf_instance_destroy(scf_instance_t *inst);

int scf_instance_get_parent(const scf_instance_t *inst,
     scf_service_t *svc);

ssize_t scf_instance_get_name(const scf_instance_t *inst,
     char *name, size_t size);

int scf_service_get_instance(const scf_service_t *svc,
     const char *name, scf_instance_t *inst);

int scf_service_add_instance(const scf_service_t *svc,
     const char *name, scf_instance_t *inst);

int scf_instance_is_complete(scf_instance_t *inst);

int scf_instance_delete(scf_instance_t *inst);

Description

Instances form the bottom layer of the Service Configuration Facility repository tree. An instance is the child of a service and has two sets of children:

Property Groups

These hold configuration information specific to this instance. See scf_pg_create(3SCF), scf_iter_instance_pgs(3SCF), and scf_iter_instance_pgs_typed(3SCF).

Snapshots

These are complete configuration snapshots that hold unchanging copies of all of the property groups necessary to run the instance. See scf_snapshot_create(3SCF) and scf_iter_instance_snapshots(3SCF).

Not all instances retrieved by the functions described here are complete. Some instances may contain only partial specifications, such as when customizations are delivered by a profile, but the instance itself is not described in the manifest. The scf_instance_is_complete() function can be used to determine whether the instance is complete.

See smf(5) for information about instances.

An scf_instance_t is an opaque handle that can be set to a single instance at any given time. The scf_instance_create() function allocates and initializes a new scf_instance_t bound to handle. The scf_instance_destroy() function destroys and frees inst.

The scf_instance_handle() function retrieves the handle to which inst is bound.

The scf_inst_get_parent() function sets svc to the service that is the parent of inst.

The scf_instance_get_name() function retrieves the name of the instance to which inst is set.

The scf_service_get_instance() function sets inst to the child instance of the service svc specified by name.

The scf_service_add_instance() function sets inst to a new child instance of the service svc specified by name.

The scf_instance_delete() function deletes the instance to which inst is set, as well all of the children of the instance.

Return Values

Upon successful completion, scf_instance_create() returns a new scf_instance_t. Otherwise it returns NULL.

Upon successful completion, scf_instance_handle() returns the handle to which inst is bound. Otherwise, it returns NULL.

Upon successful completion, scf_instance_get_name() returns the length of the string written, not including the terminating null character. Otherwise it returns -1.

Upon successful completion, scf_instance_get_parent(), scf_service_get_instance(), scf_service_add_instance(), and scf_instance_delete() functions return 0. Otherwise, they return -1.

The scf_instance_is_complete() function returns 1 if the instance is complete, 0 if it is not, and -1 if there was an error.

Errors

The scf_instance_create() and scf_instance_is_complete() functions will fail if:

SCF_ERROR_HANDLE_DESTROYED

An object was bound to a destroyed handle.

SCF_ERROR_INTERNAL

An internal error occurred.

SCF_ERROR_INVALID_ARGUMENT

The handle argument is NULL.

SCF_ERROR_NO_MEMORY

There is not enough memory to allocate an scf_instance_t.

SCF_ERROR_NO_RESOURCES

The server does not have adequate resources for a new instance handle.

The scf_instance_handle() function will fail if:

SCF_ERROR_HANDLE_DESTROYED

The handle associated with inst has been destroyed.

The scf_instance_get_name(), scf_instance_get_parent(), scf_instance_is_complete(), and scf_instance_delete() functions will fail if:

SCF_ERROR_DELETED

The instance has been deleted.

SCF_ERROR_NOT_SET

The instance is not set.

SCF_ERROR_NOT_BOUND

The repository handle is not bound.

SCF_ERROR_CONNECTION_BROKEN

The connection to the repository was lost.

The scf_service_add_instance() function will fail if:

SCF_ERROR_EXISTS

An instance named name already exists.

SCF_ERROR_INTERNAL

An internal error occurred.

SCF_ERROR_NO_RESOURCES

The server does not have the resources to complete the request.

SCF_ERROR_NOT_BOUND

The handle is not bound.

The scf_service_get_instance() function 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_NOT_BOUND

The handle is not bound.

SCF_ERROR_NOT_FOUND

No instance specified by name was found.

SCF_ERROR_NO_RESOURCES

The repository server is out of resources.

The scf_service_add_instance() and scf_service_get_instance() functions will fail if:

SCF_ERROR_NOT_SET

The service is not set.

SCF_ERROR_DELETED

The service has been deleted.

SCF_ERROR_INVALID_ARGUMENT

The name argument is not a valid instance name.

SCF_ERROR_HANDLE_MISMATCH

The service and instance are not derived from the same handle.

SCF_ERROR_CONNECTION_BROKEN

The connection to the repository was lost.

The scf_instance_get_parent() function will fail if:

SCF_ERROR_HANDLE_MISMATCH

The service and instance arguments are not derived from the same handle.

The scf_service_add_instance() and scf_instance_delete() functions will fail if:

SCF_ERROR_PERMISSION_DENIED

The user does not have sufficient privileges to create or delete an instance.

SCF_ERROR_BACKEND_READONLY

The repository backend is read-only.

SCF_ERROR_BACKEND_ACCESS

The repository backend refused the modification.

The scf_instance_delete() function will fail if:

SCF_ERROR_NO_RESOURCES

The server does not have adequate resources for a new instance handle.

The scf_instance_is_complete() function 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_NOT_FOUND

The complete property or one of its parents was not found.

Attributes

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

See Also

svc.configd(1M), libscf(3LIB), scf_error(3SCF), scf_iter_instance_pgs(3SCF), scf_iter_instance_pgs_typed(3SCF), scf_iter_instance_snapshots(3SCF), scf_pg_create(3SCF), scf_snapshot_create(3SCF), attributes(5), smf(5)

Notes

Instance names are of the form:

[domain,]identifier

where domain is either a stock ticker symbol such as ORCL or a Java-style reversed domain name such as com.oracle. Identifiers begin with a letter or underscore and contain only letters, digits, underscores, and dashes.