| Current File : //usr/share/man/man3scf/scf_service_create.3scf |
'\" 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 <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
.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)