Service Configuration Facility Library Functions
scf_instance_create(3SCF)
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 FacilitySYNOPSIS
cc [ flag... ] file... -lscf [ library... ]
#include
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 ConfigurationFacility repository tree. An instance is the child of a ser-
vice and has two sets of children: Property Groups These hold configuration information specific to this instance. Seescf_pg_create(3SCF),
scf_iter_instance_pgs(3SCF), and
scf_iter_instance_pgs_typed(3SCF).
SunOS 5.11 Last change: 24 Sep 2007 1
Service Configuration Facility Library Functionsscf_instance_create(3SCF)
Snapshots These are complete configuration snapshots that hold unchanging copies of all of the property groups necessary to run the instance. Seescf_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 des-
troys 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.SunOS 5.11 Last change: 24 Sep 2007 2
Service Configuration Facility Library Functionsscf_instance_create(3SCF)
Upon successful completion, scf_instance_get_name() returns
the length of the string written, not including the ter-
minating 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 anscf_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:
SunOS 5.11 Last change: 24 Sep 2007 3
Service Configuration Facility Library Functionsscf_instance_create(3SCF)
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.SunOS 5.11 Last change: 24 Sep 2007 4
Service Configuration Facility Library Functionsscf_instance_create(3SCF)
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.SunOS 5.11 Last change: 24 Sep 2007 5
Service Configuration Facility Library Functionsscf_instance_create(3SCF)
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 han-
dle.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_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:SunOS 5.11 Last change: 24 Sep 2007 6
Service Configuration Facility Library Functionsscf_instance_create(3SCF)
[domain,]identifier where domain is either a stock ticker symbol such as SUNW ora Java-style reversed domain name such as com.sun. Identif-
iers begin with a letter or underscore and contain only letters, digits, underscores, and dashes.SunOS 5.11 Last change: 24 Sep 2007 7
Service Configuration Facility Library Functionsscf_instance_create(3SCF)
SunOS 5.11 Last change: 24 Sep 2007 8