'\" te .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. .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)