'\" te
.\" Copyright (c) 2007, 2011, Oracle and/or its affiliates. All rights reserved.
.TH scf_instance_create 3SCF "16 Jun 2011" "SunOS 5.11" "Service Configuration Facility Library Functions"
.SH 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_is_complete, scf_instance_delete \- create and manipulate instance handles and instances in the Service Configuration Facility
.SH SYNOPSIS
.LP
.nf
cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lscf\fR [ \fIlibrary\fR\&.\|.\|. ] 
#include <libscf.h>

\fBscf_instance_t *\fR\fBscf_instance_create\fR(\fBscf_handle_t *\fR\fIhandle\fR);
.fi

.LP
.nf
\fBscf_handle_t *\fR\fBscf_instance_handle\fR(\fBscf_instance_t *\fR\fIinst\fR);
.fi

.LP
.nf
\fBvoid\fR \fBscf_instance_destroy\fR(\fBscf_instance_t *\fR\fIinst\fR);
.fi

.LP
.nf
\fBint\fR \fBscf_instance_get_parent\fR(\fBconst scf_instance_t *\fR\fIinst\fR,
     \fBscf_service_t *\fR\fIsvc\fR);
.fi

.LP
.nf
\fBssize_t\fR \fBscf_instance_get_name\fR(\fBconst scf_instance_t *\fR\fIinst\fR,
     \fBchar *\fR\fIname\fR, \fBsize_t\fR \fIsize\fR);
.fi

.LP
.nf
\fBint\fR \fBscf_service_get_instance\fR(\fBconst scf_service_t *\fR\fIsvc\fR,
     \fBconst char *\fR\fIname\fR, \fBscf_instance_t *\fR\fIinst\fR);
.fi

.LP
.nf
\fBint\fR \fBscf_service_add_instance\fR(\fBconst scf_service_t *\fR\fIsvc\fR,
     \fBconst char *\fR\fIname\fR, \fBscf_instance_t *\fR\fIinst\fR);
.fi

.LP
.nf
\fBint\fR \fBscf_instance_is_complete\fR(\fBscf_instance_t *\fR\fIinst\fR);
.fi

.LP
.nf
\fBint\fR \fBscf_instance_delete\fR(\fBscf_instance_t *\fR\fIinst\fR);
.fi

.SH DESCRIPTION
.sp
.LP
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:
.sp
.ne 2
.mk
.na
\fBProperty Groups\fR
.ad
.RS 19n
.rt  
These hold configuration information specific to this instance. See \fBscf_pg_create\fR(3SCF), \fBscf_iter_instance_pgs\fR(3SCF), and \fBscf_iter_instance_pgs_typed\fR(3SCF).
.RE

.sp
.ne 2
.mk
.na
\fBSnapshots\fR
.ad
.RS 19n
.rt  
These are complete configuration snapshots that hold unchanging copies of all of the property groups necessary to run the instance. See \fBscf_snapshot_create\fR(3SCF) and \fBscf_iter_instance_snapshots\fR(3SCF).
.RE

.sp
.LP
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 \fBscf_instance_is_complete()\fR function can be used to determine whether the instance is complete.
.sp
.LP
See \fBsmf\fR(5) for information about instances.
.sp
.LP
An \fBscf_instance_t\fR is an opaque handle that can be set to a single instance at any given time. The \fBscf_instance_create()\fR function allocates and initializes a new \fBscf_instance_t\fR bound to \fIhandle\fR. The \fBscf_instance_destroy()\fR function destroys and frees \fIinst\fR.
.sp
.LP
The \fBscf_instance_handle()\fR function retrieves the handle to which \fIinst\fR is bound.
.sp
.LP
The \fBscf_inst_get_parent()\fR function sets \fIsvc\fR to the service that is the parent of \fIinst\fR.
.sp
.LP
The \fBscf_instance_get_name()\fR function retrieves the name of the instance to which \fIinst\fR is set.
.sp
.LP
The \fBscf_service_get_instance()\fR function sets \fIinst\fR to the child instance of the service \fIsvc\fR specified by \fIname\fR.
.sp
.LP
The \fBscf_service_add_instance()\fR function sets \fIinst\fR to a new child instance of the service \fIsvc\fR specified by \fIname\fR.
.sp
.LP
The \fBscf_instance_delete()\fR function deletes the instance to which \fIinst\fR is set, as well all of the children of the instance.
.SH RETURN VALUES
.sp
.LP
Upon successful completion, \fBscf_instance_create()\fR returns a new \fBscf_instance_t\fR. Otherwise it returns \fINULL\fR.
.sp
.LP
Upon successful completion, \fBscf_instance_handle()\fR returns the handle to which \fIinst\fR is bound. Otherwise, it returns \fINULL\fR.
.sp
.LP
Upon successful completion, \fBscf_instance_get_name()\fR returns the length of the string written, not including the terminating null character. Otherwise it returns -1.
.sp
.LP
Upon successful completion, \fBscf_instance_get_parent()\fR, \fBscf_service_get_instance()\fR, \fBscf_service_add_instance()\fR, and \fBscf_instance_delete()\fR functions return 0. Otherwise, they return -1.
.sp
.LP
The \fBscf_instance_is_complete()\fR function returns 1 if the instance is complete, 0 if it is not, and -1 if there was an error.
.SH ERRORS
.sp
.LP
The \fBscf_instance_create()\fR and \fBscf_instance_is_complete()\fR functions will fail if:
.sp
.ne 2
.mk
.na
\fB\fBSCF_ERROR_HANDLE_DESTROYED\fR\fR
.ad
.sp .6
.RS 4n
An object was bound to a destroyed handle.
.RE

.sp
.ne 2
.mk
.na
\fB\fBSCF_ERROR_INTERNAL\fR\fR
.ad
.sp .6
.RS 4n
An internal error occurred.
.RE

.sp
.ne 2
.mk
.na
\fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
.ad
.sp .6
.RS 4n
The \fIhandle\fR argument is \fINULL\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fBSCF_ERROR_NO_MEMORY\fR\fR
.ad
.sp .6
.RS 4n
There is not enough memory to allocate an \fBscf_instance_t\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fBSCF_ERROR_NO_RESOURCES\fR\fR
.ad
.sp .6
.RS 4n
The server does not have adequate resources for a new instance handle.
.RE

.sp
.LP
The \fBscf_instance_handle()\fR function will fail if:
.sp
.ne 2
.mk
.na
\fB\fBSCF_ERROR_HANDLE_DESTROYED\fR\fR
.ad
.sp .6
.RS 4n
The handle associated with \fIinst\fR has been destroyed.
.RE

.sp
.LP
The \fBscf_instance_get_name()\fR, \fBscf_instance_get_parent()\fR, \fBscf_instance_is_complete()\fR, and \fBscf_instance_delete()\fR functions will fail if:
.sp
.ne 2
.mk
.na
\fB\fBSCF_ERROR_DELETED\fR\fR
.ad
.sp .6
.RS 4n
The instance has been deleted.
.RE

.sp
.ne 2
.mk
.na
\fB\fBSCF_ERROR_NOT_SET\fR\fR
.ad
.sp .6
.RS 4n
The instance is not set.
.RE

.sp
.ne 2
.mk
.na
\fB\fBSCF_ERROR_NOT_BOUND\fR\fR
.ad
.sp .6
.RS 4n
The repository handle is not bound.
.RE

.sp
.ne 2
.mk
.na
\fB\fBSCF_ERROR_CONNECTION_BROKEN\fR\fR
.ad
.sp .6
.RS 4n
The connection to the repository was lost.
.RE

.sp
.LP
The \fBscf_service_add_instance()\fR function will fail if:
.sp
.ne 2
.mk
.na
\fB\fBSCF_ERROR_EXISTS\fR\fR
.ad
.sp .6
.RS 4n
An instance named \fIname\fR already exists.
.RE

.sp
.ne 2
.mk
.na
\fB\fBSCF_ERROR_INTERNAL\fR\fR
.ad
.sp .6
.RS 4n
An internal error occurred.
.RE

.sp
.ne 2
.mk
.na
\fB\fBSCF_ERROR_NO_RESOURCES\fR\fR
.ad
.sp .6
.RS 4n
The server does not have the resources to complete the request.
.RE

.sp
.ne 2
.mk
.na
\fB\fBSCF_ERROR_NOT_BOUND\fR\fR
.ad
.sp .6
.RS 4n
The handle is not bound.
.RE

.sp
.LP
The \fBscf_service_get_instance()\fR function will fail if:
.sp
.ne 2
.mk
.na
\fB\fBSCF_ERROR_BACKEND_ACCESS\fR\fR
.ad
.sp .6
.RS 4n
The  storage  mechanism  that  the   repository server (\fBsvc.configd\fR(1M)) chose for the operation denied access.
.RE

.sp
.ne 2
.mk
.na
\fB\fBSCF_ERROR_INTERNAL\fR\fR
.ad
.sp .6
.RS 4n
An internal error occurred.
.RE

.sp
.ne 2
.mk
.na
\fB\fBSCF_ERROR_NOT_BOUND\fR\fR
.ad
.sp .6
.RS 4n
The handle is not bound.
.RE

.sp
.ne 2
.mk
.na
\fB\fBSCF_ERROR_NOT_FOUND\fR\fR
.ad
.sp .6
.RS 4n
No instance specified by \fIname\fR was found.
.RE

.sp
.ne 2
.mk
.na
\fB\fBSCF_ERROR_NO_RESOURCES\fR\fR
.ad
.sp .6
.RS 4n
The repository server is out of resources.
.RE

.sp
.LP
The \fBscf_service_add_instance()\fR and \fBscf_service_get_instance()\fR functions will fail if:
.sp
.ne 2
.mk
.na
\fB\fBSCF_ERROR_NOT_SET\fR\fR
.ad
.sp .6
.RS 4n
The service is not set.
.RE

.sp
.ne 2
.mk
.na
\fB\fBSCF_ERROR_DELETED\fR\fR
.ad
.sp .6
.RS 4n
The service has been deleted.
.RE

.sp
.ne 2
.mk
.na
\fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
.ad
.sp .6
.RS 4n
The \fIname\fR argument is not a valid instance name.
.RE

.sp
.ne 2
.mk
.na
\fB\fBSCF_ERROR_HANDLE_MISMATCH\fR\fR
.ad
.sp .6
.RS 4n
The service and instance are not derived from the same handle.
.RE

.sp
.ne 2
.mk
.na
\fB\fBSCF_ERROR_CONNECTION_BROKEN\fR\fR
.ad
.sp .6
.RS 4n
The connection to the repository was lost.
.RE

.sp
.LP
The \fBscf_instance_get_parent()\fR function will fail if:
.sp
.ne 2
.mk
.na
\fB\fBSCF_ERROR_HANDLE_MISMATCH\fR\fR
.ad
.sp .6
.RS 4n
The \fIservice\fR and \fIinstance\fR arguments are not derived from the same handle.
.RE

.sp
.LP
The \fBscf_service_add_instance()\fR and \fBscf_instance_delete()\fR functions will fail if:
.sp
.ne 2
.mk
.na
\fB\fBSCF_ERROR_PERMISSION_DENIED\fR\fR
.ad
.sp .6
.RS 4n
The user does not have sufficient privileges to create or delete an instance.
.RE

.sp
.ne 2
.mk
.na
\fB\fBSCF_ERROR_BACKEND_READONLY\fR\fR
.ad
.sp .6
.RS 4n
The repository backend is read-only.
.RE

.sp
.ne 2
.mk
.na
\fB\fBSCF_ERROR_BACKEND_ACCESS\fR\fR
.ad
.sp .6
.RS 4n
The repository backend refused the modification.
.RE

.sp
.LP
The \fBscf_instance_delete()\fR function will fail if:
.sp
.ne 2
.mk
.na
\fB\fBSCF_ERROR_NO_RESOURCES\fR\fR
.ad
.RS 26n
.rt  
The server does not have adequate resources for a new instance handle.
.RE

.sp
.LP
The \fBscf_instance_is_complete()\fR function will fail if:
.sp
.ne 2
.mk
.na
\fB\fBSCF_ERROR_BACKEND_ACCESS\fR\fR
.ad
.sp .6
.RS 4n
The storage mechanism that the repository server (\fBsvc.configd\fR(1M)) chose for the operation denied access.
.RE

.sp
.ne 2
.mk
.na
\fB\fBSCF_ERROR_NOT_FOUND\fR\fR
.ad
.sp .6
.RS 4n
The complete property or one of its parents was not found.
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Interface StabilityCommitted
_
MT-LevelSafe
.TE

.SH SEE ALSO
.sp
.LP
\fBsvc.configd\fR(1M), \fBlibscf\fR(3LIB), \fBscf_error\fR(3SCF), \fBscf_iter_instance_pgs\fR(3SCF), \fBscf_iter_instance_pgs_typed\fR(3SCF), \fBscf_iter_instance_snapshots\fR(3SCF), \fBscf_pg_create\fR(3SCF), \fBscf_snapshot_create\fR(3SCF), \fBattributes\fR(5), \fBsmf\fR(5)
.SH NOTES
.sp
.LP
Instance names are of the form:
.sp
.in +2
.nf
[\fIdomain\fR,]\fIidentifier\fR
.fi
.in -2
.sp

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