SCF_INSTANCE_CREATE(3SCF) Service Configuration Facility Library Functions


NAME


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_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_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).


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.

ERRORS


The scf_instance_create() function 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(), 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.


ATTRIBUTES


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


+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|Interface Stability | Committed |
+--------------------+-----------------+
|MT-Level | Safe |
+--------------------+-----------------+

SEE ALSO


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 SUNW or a Java-style
reversed domain name such as com.sun. Identifiers begin with a letter or
underscore and contain only letters, digits, underscores, and dashes.


September 24, 2007 SCF_INSTANCE_CREATE(3SCF)