'\" 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 "27 Aug 2007" "SunOS 5.11" "Service Configuration Facility Library Functions" .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 \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 .mk .na \fBProperty groups\fR .ad .RS 19n .rt 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 .mk .na \fBInstances\fR .ad .RS 19n .rt 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 .mk .na \fB\fBSCF_ERROR_INVALID_ARGUMENT\fR\fR .ad .RS 30n .rt The value of the \fIhandle\fR argument is \fINULL\fR. .RE .sp .ne 2 .mk .na \fB\fBSCF_ERROR_NO_MEMORY\fR\fR .ad .RS 30n .rt There is not enough memory to allocate an \fBscf_service_t\fR. .RE .sp .ne 2 .mk .na \fB\fBSCF_ERROR_NO_RESOURCES\fR\fR .ad .RS 30n .rt 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 .mk .na \fB\fBSCF_ERROR_HANDLE_DESTROYED\fR\fR .ad .RS 30n .rt 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 .mk .na \fB\fBSCF_ERROR_DELETED\fR\fR .ad .sp .6 .RS 4n The service has been deleted by someone else. .RE .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_NOT_BOUND\fR\fR .ad .sp .6 .RS 4n The 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_delete()\fR function will fail if: .sp .ne 2 .mk .na \fB\fBSCF_ERROR_EXISTS\fR\fR .ad .RS 26n .rt The service contains instances. .RE .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 scope handle. .RE .sp .LP The \fBscf_scope_add_service()\fR function will fail if: .sp .ne 2 .mk .na \fB\fBSCF_ERROR_EXISTS\fR\fR .ad .RS 20n .rt 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 .mk .na \fB\fBSCF_ERROR_BACKEND_ACCESS\fR\fR .ad .RS 28n .rt 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 .RS 28n .rt 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 .mk .na \fB\fBSCF_ERROR_CONNECTION_BROKEN\fR\fR .ad .sp .6 .RS 4n The connection to the repository was lost. .RE .sp .ne 2 .mk .na \fB\fBSCF_ERROR_DELETED\fR\fR .ad .sp .6 .RS 4n The parent entity has been deleted. .RE .sp .ne 2 .mk .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 .mk .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 .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 .ne 2 .mk .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 .mk .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 .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 a service. .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_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 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 \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)