path: root/usr/src/man/man3scf/scf_instance_create.3scf

'\" te
.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH SCF_INSTANCE_CREATE 3SCF "Sep 24, 2007"
.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_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_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
.na
\fBProperty Groups\fR
.ad
.RS 19n
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
.na
\fBSnapshots\fR
.ad
.RS 19n
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
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.
.SH ERRORS
.sp
.LP
The \fBscf_instance_create()\fR function will fail if:
.sp
.ne 2
.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
.na
\fB\fBSCF_ERROR_INTERNAL\fR\fR
.ad
.sp .6
.RS 4n
An internal error occurred.
.RE

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

.sp
.ne 2
.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
.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
.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, and
\fBscf_instance_delete()\fR functions will fail if:
.sp
.ne 2
.na
\fB\fBSCF_ERROR_DELETED\fR\fR
.ad
.sp .6
.RS 4n
The instance has been deleted.
.RE

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

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

.sp
.ne 2
.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
.na
\fB\fBSCF_ERROR_EXISTS\fR\fR
.ad
.sp .6
.RS 4n
An instance named \fIname\fR already exists.
.RE

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

.sp
.ne 2
.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
.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
.na
\fB\fBSCF_ERROR_BACKEND_ACCESS\fR\fR
.ad
.RS 28n
The  storage  mechanism  that  the   repository server (\fBsvc.configd\fR(1M))
chose for the operation denied access.
.RE

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

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

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

.sp
.ne 2
.na
\fB\fBSCF_ERROR_NO_RESOURCES\fR\fR
.ad
.RS 28n
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
.na
\fB\fBSCF_ERROR_NOT_SET\fR\fR
.ad
.sp .6
.RS 4n
The service is not set.
.RE

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

.sp
.ne 2
.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
.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
.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
.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
.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
.na
\fB\fBSCF_ERROR_BACKEND_READONLY\fR\fR
.ad
.sp .6
.RS 4n
The repository backend is read-only.
.RE

.sp
.ne 2
.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
.na
\fB\fBSCF_ERROR_NO_RESOURCES\fR\fR
.ad
.RS 26n
The server does not have adequate resources for a new instance handle.
.RE

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

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Committed
_
MT-Level	Safe
.TE

.SH SEE ALSO
.sp
.LP
\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 SUNW or a Java-style
reversed domain name such as \fBcom.sun\fR. Identifiers begin with a letter or
underscore and contain only letters, digits, underscores, and dashes.