SCF_HANDLE_CREATE(3SCF) Service Configuration Facility Library Functions
scf_handle_create, scf_handle_destroy, scf_handle_decorate,
scf_handle_bind, scf_handle_unbind, scf_myname - Service
Configuration Facility handle functions
cc [ flag... ] file... -lscf [ library... ]
#include <libscf.h>
scf_handle_t *scf_handle_create(scf_version_t version);
void scf_handle_destroy(scf_handle_t *handle);
int scf_handle_decorate(scf_handle_t *handle, const char *param,
scf_value_t *value);
int scf_handle_bind(scf_handle_t *handle);
int scf_handle_unbind(scf_handle_t *handle);
ssize_t scf_myname(scf_handle_t *handle, char *out, size_t sz);
The scf_handle_create() function creates a new Service Configuration
Facility handle that is used as the base for all communication with
the configuration repository. The version argument must be
SCF_VERSION.
The scf_handle_decorate() function sets a single connection-level
parameter, param, to the supplied value. If value is
SCF_DECORATE_CLEAR, param is reset to its default state. Values
passed to scf_handle_decorate() can be reset, reused, or destroyed.
The values set do not take effect until scf_handle_bind() is called.
Any invalid values will not cause errors prior to the call to
scf_handle_bind(). The only available decorations is:
debug
(count) Set the debugging flags.
The scf_handle_bind() function binds the handle to a running
svc.configd(8) daemon, using the current decorations to modify the
connection. All states derived from the handle are reset immediately
after a successful binding.
The scf_handle_unbind() function severs an existing repository
connection or clears the in-client state for a broken connection.
The scf_handle_destroy() function destroys and frees an SCF handle.
It is illegal to use the handle after calling scf_handle_destroy().
Actions on subordinate objects act as if the handle is unbound.
The scf_myname() function retrieves the FMRI for the service of which
the connecting process is a part. If the full FMRI does not fit in
the provided buffer, it is truncated and, if sz > 0, zero-terminated.
Upon successful completion, scf_handle_create() returns the new
handle. Otherwise, it returns NULL.
Upon successful completion, scf_handle_decorate(), scf_handle_bind(),
and scf_handle_unbind() return 0. Otherwise, they return -1.
The scf_myname() function returns the length of the full FMRI.
Otherwise, it returns -1.
The scf_handle_create() function will fail if:
SCF_ERROR_NO_MEMORY
There is no memory available.
SCF_ERROR_VERSION_MISMATCH
The version is invalid, or the
application was compiled against a
version of the library that is more
recent than the one on the system.
The scf_handle_decorate() function will fail if:
SCF_ERROR_INVALID_ARGUMENT
The param argument is not a recognized
parameter.
SCF_ERROR_TYPE_MISMATCH
The value argument does not match the
expected type for param.
SCF_ERROR_NOT_SET
The value argument is not set.
SCF_ERROR_IN_USE
The handle is currently bound.
SCF_ERROR_HANDLE_MISMATCH
The value argument is not derived from
handle.
The scf_handle_bind() function will fail if:
SCF_ERROR_INVALID_ARGUMENT
One of the decorations was invalid.
SCF_ERROR_NO_SERVER
The repository server is not running.
SCF_ERROR_NO_RESOURCES
The server does not have adequate
resources for a new connection.
SCF_ERROR_IN_USE
The handle is already bound.
The scf_handle_unbind() function will fail if:
SCF_ERROR_NOT_BOUND
The handle is not bound.
The scf_handle_myname() function will fail if:
SCF_ERROR_CONNECTION_BROKEN
The connection to the repository was lost.
SCF_ERROR_NOT_BOUND
The handle is not bound.
SCF_ERROR_NOT_SET
This process is not marked as a SMF service.
The scf_error(3SCF) function can be used to retrieve the error value.
See attributes(7) for descriptions of the following attributes:
+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|Interface Stability | Committed |
+--------------------+-----------------+
|MT-Level | See below. |
+--------------------+-----------------+
Operations on a single handle (and the objects associated with it)
are Safe. Operations on different handles are MT-Safe. Objects
associated with different handles cannot be mixed, as this will lead
to an SCF_ERROR_HANDLE_MISMATCH error.
libscf(3LIB), scf_error(3SCF), attributes(7)
August 17, 2007 SCF_HANDLE_CREATE(3SCF)
NAME
scf_handle_create, scf_handle_destroy, scf_handle_decorate,
scf_handle_bind, scf_handle_unbind, scf_myname - Service
Configuration Facility handle functions
SYNOPSIS
cc [ flag... ] file... -lscf [ library... ]
#include <libscf.h>
scf_handle_t *scf_handle_create(scf_version_t version);
void scf_handle_destroy(scf_handle_t *handle);
int scf_handle_decorate(scf_handle_t *handle, const char *param,
scf_value_t *value);
int scf_handle_bind(scf_handle_t *handle);
int scf_handle_unbind(scf_handle_t *handle);
ssize_t scf_myname(scf_handle_t *handle, char *out, size_t sz);
DESCRIPTION
The scf_handle_create() function creates a new Service Configuration
Facility handle that is used as the base for all communication with
the configuration repository. The version argument must be
SCF_VERSION.
The scf_handle_decorate() function sets a single connection-level
parameter, param, to the supplied value. If value is
SCF_DECORATE_CLEAR, param is reset to its default state. Values
passed to scf_handle_decorate() can be reset, reused, or destroyed.
The values set do not take effect until scf_handle_bind() is called.
Any invalid values will not cause errors prior to the call to
scf_handle_bind(). The only available decorations is:
debug
(count) Set the debugging flags.
The scf_handle_bind() function binds the handle to a running
svc.configd(8) daemon, using the current decorations to modify the
connection. All states derived from the handle are reset immediately
after a successful binding.
The scf_handle_unbind() function severs an existing repository
connection or clears the in-client state for a broken connection.
The scf_handle_destroy() function destroys and frees an SCF handle.
It is illegal to use the handle after calling scf_handle_destroy().
Actions on subordinate objects act as if the handle is unbound.
The scf_myname() function retrieves the FMRI for the service of which
the connecting process is a part. If the full FMRI does not fit in
the provided buffer, it is truncated and, if sz > 0, zero-terminated.
RETURN VALUES
Upon successful completion, scf_handle_create() returns the new
handle. Otherwise, it returns NULL.
Upon successful completion, scf_handle_decorate(), scf_handle_bind(),
and scf_handle_unbind() return 0. Otherwise, they return -1.
The scf_myname() function returns the length of the full FMRI.
Otherwise, it returns -1.
ERRORS
The scf_handle_create() function will fail if:
SCF_ERROR_NO_MEMORY
There is no memory available.
SCF_ERROR_VERSION_MISMATCH
The version is invalid, or the
application was compiled against a
version of the library that is more
recent than the one on the system.
The scf_handle_decorate() function will fail if:
SCF_ERROR_INVALID_ARGUMENT
The param argument is not a recognized
parameter.
SCF_ERROR_TYPE_MISMATCH
The value argument does not match the
expected type for param.
SCF_ERROR_NOT_SET
The value argument is not set.
SCF_ERROR_IN_USE
The handle is currently bound.
SCF_ERROR_HANDLE_MISMATCH
The value argument is not derived from
handle.
The scf_handle_bind() function will fail if:
SCF_ERROR_INVALID_ARGUMENT
One of the decorations was invalid.
SCF_ERROR_NO_SERVER
The repository server is not running.
SCF_ERROR_NO_RESOURCES
The server does not have adequate
resources for a new connection.
SCF_ERROR_IN_USE
The handle is already bound.
The scf_handle_unbind() function will fail if:
SCF_ERROR_NOT_BOUND
The handle is not bound.
The scf_handle_myname() function will fail if:
SCF_ERROR_CONNECTION_BROKEN
The connection to the repository was lost.
SCF_ERROR_NOT_BOUND
The handle is not bound.
SCF_ERROR_NOT_SET
This process is not marked as a SMF service.
The scf_error(3SCF) function can be used to retrieve the error value.
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|Interface Stability | Committed |
+--------------------+-----------------+
|MT-Level | See below. |
+--------------------+-----------------+
Operations on a single handle (and the objects associated with it)
are Safe. Operations on different handles are MT-Safe. Objects
associated with different handles cannot be mixed, as this will lead
to an SCF_ERROR_HANDLE_MISMATCH error.
SEE ALSO
libscf(3LIB), scf_error(3SCF), attributes(7)
August 17, 2007 SCF_HANDLE_CREATE(3SCF)