scf_instance_create(3SCF)			 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 Facility

SYNOPSIS

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

       scf_instance_create(scf_handle_t *handle);

       scf_instance_handle(scf_instance_t *inst);

       scf_instance_destroy(scf_instance_t *inst);

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

       scf_instance_get_name(const scf_instance_t *inst, size_t size);

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

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

       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() 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_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_NO_RESOURCES

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

       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_NOT_FOUND

	   No instance specified by name was found.

       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.

ATTRIBUTES

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

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Evolving			   |
       +-----------------------------+-----------------------------+
       |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.

SunOS 5.10							    20 Dec 2004 					 scf_instance_create(3SCF)