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 available decorations are:
(count) Set the debugging flags.
(boolean) This connection to the repository should show entities masked by the administrator. See scf_service_is_masked(3SCF) for details.
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 The scf_error() function is not modified by this call. 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:
There is no memory available.
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:
The param argument is not a recognized parameter.
The value argument does not match the expected type for param.
The value argument is not set.
The handle is currently bound.
The value argument is not derived from handle.
The scf_handle_bind() function will fail if:
One of the decorations was invalid.
The repository server is not running.
The server does not have adequate resources for a new connection.
The handle is already bound.
The scf_handle_unbind() function will fail if:
The handle is not bound.
The scf_myname() function will fail if:
The connection to the repository was lost.
The handle is not bound.
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:
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.