SCF_SCOPE_CREATE(3SCF) Service Configuration Facility Library Functions


NAME


scf_scope_create, scf_scope_handle, scf_scope_destroy,
scf_scope_get_name, scf_handle_get_scope - create and manipulate scope
handles in the Service Configuration Facility

SYNOPSIS


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

scf_scope_t *scf_scope_create(scf_handle_t *handle);


scf_handle_t *scf_scope_handle(scf_scope_t *sc);


void scf_scope_destroy(scf_scope_t *sc);


ssize_t scf_scope_get_name(scf_scope_t *sc, char *buf, size_t size);


int scf_handle_get_scope(scf_handle_t *handle, const char *name,
scf_scope_t *out);


DESCRIPTION


Scopes are the top level of the Service Configuration Facility's
repository tree. The children of a scope are services (see
scf_service_create(3SCF)) and can be walked using
scf_iter_scope_services(3SCF).


There is a distinguished scope with the name SCF_SCOPE_LOCAL that is the
root for all available services on the local machine. In the current
implementation, there are no other scopes.


An scf_scope_t is an opaque handle that can be set to a single scope at
any given time. The scf_scope_create() function allocates a new
scf_scope_t bound to handle. The scf_scope_destroy() function destroys
and frees sc.


The scf_scope_handle() function retrieves the handle to which sc is
bound.


The scf_scope_get_name() function retrieves the name of the scope to
which sc is set.


The scf_handle_get_scope() function sets out to the scope specified by
name for the repository handle specified by handle. The
scf_iter_handle_scopes(3SCF) and scf_iter_next_scope(3SCF) calls can be
used to iterate through all available scopes.

RETURN VALUES


Upon successful completion, scf_scope_create() returns a new scf_scope_t.
Otherwise, it returns NULL.


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


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


Upon successful completion, scf_handle_get_scope() returns 0. Otherwise,
it returns -1.

ERRORS


The scf_scope_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_scope_t.


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


The scf_scope_handle() function will fail if:

SCF_ERROR_HANDLE_DESTROYED
The handle associated with sc has been
destroyed.


The scf_scope_get_name() function will fail if:

SCF_ERROR_NOT_SET

The scope 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_handle_get_scope() function will fail if:

SCF_ERROR_NOT_FOUND

No scope named name was found.


SCF_ERROR_INVALID_ARGUMENT

The name argument is not a valid scope name.


SCF_ERROR_NOT_BOUND

The handle is not bound.


SCF_ERROR_CONNECTION_BROKEN

The connection to the repository was lost.


SCF_ERROR_HANDLE_MISMATCH

The value of the out argument is not derived from handle.


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 | Evolving |
+--------------------+-----------------+
|MT-Level | Safe |
+--------------------+-----------------+

SEE ALSO


libscf(3LIB), scf_error(3SCF), scf_handle_decode_fmri(3SCF),
scf_iter_handle_scopes(3SCF), scf_iter_next_scope(3SCF),
scf_iter_scope_services(3SCF), scf_scope_to_fmri(3SCF),
scf_service_create(3SCF), attributes(5)


September 9, 2004 SCF_SCOPE_CREATE(3SCF)