SCF_SERVICE_CREATE(3SCF) Service Configuration Facility Library Functions


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

SYNOPSIS


cc [ flag... ] file... -lscf [ library... ]
#include <libscf.h>

scf_service_t *scf_service_create(scf_handle_t *handle);


scf_handle_t *scf_service_handle(scf_service_t *svc);


void scf_service_destroy(scf_service_t *svc);


int scf_service_get_parent(scf_service_t *svc, scf_scope_t *sc);


ssize_t scf_service_get_name(const scf_service_t *svc, char *buf,
size_t size);


int scf_scope_get_service(const scf_scope_t *sc, const char *name,
scf_service_t *svc);


int scf_scope_add_service(const scf_scope_t *sc, const char *name,
scf_service_t *svc);


int scf_service_delete(scf_service_t *svc);


DESCRIPTION


Services form the middle layer of the Service Configuration Facility
repository tree. Services are children of a scope (see
scf_scope_create(3SCF)) and have three sets of children:

Property groups
These hold configuration information shared by all of
the instances of the service. See scf_pg_create(3SCF),
scf_iter_service_pgs(3SCF), and
scf_iter_service_pgs_typed(3SCF).


Instances
A particular instantiation of the service. See
scf_instance_create(3SCF).


A service groups one or more related instances and provides a shared
configuration for them.


An scf_service_t is an opaque handle that can be set to a single service
at any given time. The scf_service_create() function allocates and
initializes a new scf_service_t bound to handle. The
scf_service_destroy() function destroys and frees svc.


The scf_service_handle() function retrieves the handle to which svc is
bound.


The scf_service_get_parent() function sets sc to the scope that is the
parent of svc.


The scf_service_get_name() function retrieves the name of the service to
which svc is set.


The scf_scope_get_service() function sets svc to the service specified by
name in the scope specified by sc.


The scf_scope_add_service() function sets svc to a new service specified
by name in the scope specified by sc.


The scf_service_delete() function deletes the service to which svc is
set, as well as all of its children.

RETURN VALUES


Upon successful completion, scf_service_create() returns a new
scf_service_t. Otherwise, it returns NULL.


Upon successful completion, scf_service_handle() returns the handle to
which svc is bound. Otherwise, it returns NULL.


Upon successful completion, scf_service_get_name() returns the length of
the string written, not including the terminating null byte. Otherwise,
it returns -1.


Upon successful completion, scf_service_get_parent(),
scf_scope_get_service(), scf_scope_add_service(), and
scf_service_delete() return 0. Otherwise, it returns -1.

ERRORS


The scf_service_create() function will fail if:

SCF_ERROR_INVALID_ARGUMENT
The value of the handle argument is NULL.


SCF_ERROR_NO_MEMORY
There is not enough memory to allocate an
scf_service_t.


SCF_ERROR_NO_RESOURCES
The server does not have adequate resources
for a new scope handle.


The scf_service_handle() function will fail if:

SCF_ERROR_HANDLE_DESTROYED
The handle associated with svc has been
destroyed.


The scf_service_get_name(), scf_service_get_parent(), and
scf_service_delete() functions will fail if:

SCF_ERROR_DELETED

The service has been deleted by someone else.


SCF_ERROR_NOT_SET

The service is not set.


SCF_ERROR_NOT_BOUND

The handle is not bound.


SCF_ERROR_CONNECTION_BROKEN

The connection to the repository was lost.


The scf_service_delete() function will fail if:

SCF_ERROR_EXISTS
The service contains instances.


SCF_ERROR_NO_RESOURCES
The server does not have adequate resources for
a new scope handle.


The scf_scope_add_service() function will fail if:

SCF_ERROR_EXISTS
A {service,instance,property group} named name
already exists.


The scf_scope_get_service() function will fail if:

SCF_ERROR_BACKEND_ACCESS
The storage mechanism that the
repository server (svc.configd(1M)) chose for
the operation denied access.


SCF_ERROR_INTERNAL
An internal error occurred.


The scf_scope_add_service() and scf_scope_get_service() functions will
fail if:

SCF_ERROR_CONNECTION_BROKEN

The connection to the repository was lost.


SCF_ERROR_DELETED

The parent entity has been deleted.


SCF_ERROR_HANDLE_MISMATCH

The scope and service are not derived from the same handle.


SCF_ERROR_INVALID_ARGUMENT

The value of the name argument is not a valid service name.


SCF_ERROR_NO_RESOURCES

The server does not have the resources to complete the request.


SCF_ERROR_NOT_BOUND

The handle is not bound.


SCF_ERROR_NOT_FOUND

The service specified by name was not found.


SCF_ERROR_NOT_SET

The scope is not set.


The scf_scope_add_service() and scf_service_delete() functions will fail
if:

SCF_ERROR_PERMISSION_DENIED

The user does not have sufficient privileges to create or delete a
service.


SCF_ERROR_BACKEND_READONLY

The repository backend is read-only.


SCF_ERROR_BACKEND_ACCESS

The repository backend refused the modification.


The scf_error(3SCF) function can be used to retrieve the error value.

ATTRIBUTES


See attributes(5) for descriptions of the following attributes:


+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|Interface Stability | Committed |
+--------------------+-----------------+
|MT-Level | Safe |
+--------------------+-----------------+

SEE ALSO


libscf(3LIB), scf_error(3SCF), scf_handle_decode_fmri(3SCF),
scf_iter_service_pgs(3SCF), scf_iter_service_pgs_typed(3SCF),
scf_instance_create(3SCF), scf_pg_create(3SCF), scf_scope_create(3SCF),
scf_service_to_fmri(3SCF), attributes(5), smf(5)


August 27, 2007 SCF_SERVICE_CREATE(3SCF)