'\" 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_SERVICE_CREATE 3SCF "Aug 27, 2007"
.SH NAME
scf_service_create, scf_service_handle, scf_service_destroy,
scf_service_get_parent, scf_service_get_name, scf_scope_get_service,
scf_scope_add_service, scf_service_delete \- create and manipulate service
handles and services in the Service Configuration Facility
.SH SYNOPSIS
.LP
.nf
cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lscf\fR [ \fIlibrary\fR\&.\|.\|. ]
#include <libscf.h>

\fBscf_service_t *\fR\fBscf_service_create\fR(\fBscf_handle_t *\fR\fIhandle\fR);
.fi

.LP
.nf
\fBscf_handle_t *\fR\fBscf_service_handle\fR(\fBscf_service_t *\fR\fIsvc\fR);
.fi

.LP
.nf
\fBvoid\fR \fBscf_service_destroy\fR(\fBscf_service_t *\fR\fIsvc\fR);
.fi

.LP
.nf
\fBint\fR \fBscf_service_get_parent\fR(\fBscf_service_t *\fR\fIsvc\fR, \fBscf_scope_t *\fR\fIsc\fR);
.fi

.LP
.nf
\fBssize_t\fR \fBscf_service_get_name\fR(\fBconst scf_service_t *\fR\fIsvc\fR, \fBchar *\fR\fIbuf\fR,
     \fBsize_t\fR \fIsize\fR);
.fi

.LP
.nf
\fBint\fR \fBscf_scope_get_service\fR(\fBconst scf_scope_t *\fR\fIsc\fR, \fBconst char *\fR\fIname\fR,
     \fBscf_service_t *\fR\fIsvc\fR);
.fi

.LP
.nf
\fBint\fR \fBscf_scope_add_service\fR(\fBconst scf_scope_t *\fR\fIsc\fR, \fBconst char *\fR\fIname\fR,
     \fBscf_service_t *\fR\fIsvc\fR);
.fi

.LP
.nf
\fBint\fR \fBscf_service_delete\fR(\fBscf_service_t *\fR\fIsvc\fR);
.fi

.SH DESCRIPTION
.sp
.LP
Services form the middle layer of the Service Configuration Facility repository
tree. Services are children of a scope (see \fBscf_scope_create\fR(3SCF)) and
have three sets of children:
.sp
.ne 2
.na
\fBProperty groups\fR
.ad
.RS 19n
These hold configuration information shared by all of the instances of the
service. See \fBscf_pg_create\fR(3SCF), \fBscf_iter_service_pgs\fR(3SCF), and
\fBscf_iter_service_pgs_typed\fR(3SCF).
.RE

.sp
.ne 2
.na
\fBInstances\fR
.ad
.RS 19n
A particular instantiation of the service. See \fBscf_instance_create\fR(3SCF).
.RE

.sp
.LP
A service groups one or more related instances and provides a shared
configuration for them.
.sp
.LP
An \fBscf_service_t\fR is an opaque handle that can be set to a single service
at any given time. The \fBscf_service_create()\fR function allocates and
initializes a new \fBscf_service_t\fR bound to \fIhandle\fR. The
\fBscf_service_destroy()\fR function destroys and frees svc.
.sp
.LP
The \fBscf_service_handle()\fR function retrieves the handle to which \fIsvc\fR
is bound.
.sp
.LP
The \fBscf_service_get_parent()\fR function sets \fIsc\fR to the scope that is
the parent of \fIsvc\fR.
.sp
.LP
The \fBscf_service_get_name()\fR function retrieves the name of the service to
which \fIsvc\fR is set.
.sp
.LP
The \fBscf_scope_get_service()\fR function sets \fIsvc\fR to the service
specified by \fIname\fR in the scope specified by \fIsc\fR.
.sp
.LP
The \fBscf_scope_add_service()\fR function sets \fIsvc\fR to a new service
specified by \fIname\fR in the scope specified by \fIsc\fR.
.sp
.LP
The \fBscf_service_delete()\fR function deletes the service to which \fIsvc\fR
is set, as well as all of its children.
.SH RETURN VALUES
.sp
.LP
Upon successful completion, \fBscf_service_create()\fR returns a new
\fBscf_service_t\fR. Otherwise, it returns \fINULL\fR.
.sp
.LP
Upon successful completion, \fBscf_service_handle()\fR returns the handle to
which svc is bound. Otherwise, it returns \fINULL\fR.
.sp
.LP
Upon successful completion, \fBscf_service_get_name()\fR returns the length of
the string written, not including the terminating null byte. Otherwise, it
returns -1.
.sp
.LP
Upon successful completion, \fBscf_service_get_parent()\fR,
\fBscf_scope_get_service()\fR, \fBscf_scope_add_service()\fR, and
\fBscf_service_delete()\fR return 0. Otherwise, it returns -1.
.SH ERRORS
.sp
.LP
The \fBscf_service_create()\fR function will fail if:
.sp
.ne 2
.na
\fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
.ad
.RS 30n
The value of the \fIhandle\fR argument is \fINULL\fR.
.RE

.sp
.ne 2
.na
\fB\fBSCF_ERROR_NO_MEMORY\fR\fR
.ad
.RS 30n
There is not enough memory to allocate an \fBscf_service_t\fR.
.RE

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

.sp
.LP
The \fBscf_service_handle()\fR function will fail if:
.sp
.ne 2
.na
\fB\fBSCF_ERROR_HANDLE_DESTROYED\fR\fR
.ad
.RS 30n
The handle associated with \fIsvc\fR has been destroyed.
.RE

.sp
.LP
The \fBscf_service_get_name()\fR, \fBscf_service_get_parent()\fR, and
\fBscf_service_delete()\fR functions will fail if:
.sp
.ne 2
.na
\fB\fBSCF_ERROR_DELETED\fR\fR
.ad
.sp .6
.RS 4n
The service has been deleted by someone else.
.RE

.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_NOT_BOUND\fR\fR
.ad
.sp .6
.RS 4n
The 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_delete()\fR function will fail if:
.sp
.ne 2
.na
\fB\fBSCF_ERROR_EXISTS\fR\fR
.ad
.RS 26n
The service contains instances.
.RE

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

.sp
.LP
The \fBscf_scope_add_service()\fR function will fail if:
.sp
.ne 2
.na
\fB\fBSCF_ERROR_EXISTS\fR\fR
.ad
.RS 20n
A {service,instance,property group} named \fIname\fR already exists.
.RE

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

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

.sp
.ne 2
.na
\fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR
.ad
.sp .6
.RS 4n
The value of the \fIname\fR argument is not a valid service name.
.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
.ne 2
.na
\fB\fBSCF_ERROR_NOT_FOUND\fR\fR
.ad
.sp .6
.RS 4n
The service specified by \fIname\fR was not found.
.RE

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

.sp
.LP
The \fBscf_scope_add_service()\fR and \fBscf_service_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 a service.
.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_error\fR(3SCF) function can be used to retrieve the error value.
.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_handle_decode_fmri\fR(3SCF),
\fBscf_iter_service_pgs\fR(3SCF), \fBscf_iter_service_pgs_typed\fR(3SCF),
\fBscf_instance_create\fR(3SCF), \fBscf_pg_create\fR(3SCF),
\fBscf_scope_create\fR(3SCF), \fBscf_service_to_fmri\fR(3SCF),
\fBattributes\fR(5), \fBsmf\fR(5)