Content-type: text/html Man page of scf_handle_create

scf_handle_create

Section: Service Configuration Facility Library Functions (3SCF)
Updated: 17 Aug 2007
Index Return to Main Contents
 

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(1M) 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(5) for descriptions of the following attributes:

ATTRIBUTE TYPEATTRIBUTE VALUE

Interface StabilityCommitted

MT-Level

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(5)


 

Index

NAME
SYNOPSIS
DESCRIPTION
RETURN VALUES
ERRORS
ATTRIBUTES
SEE ALSO

This document was created by man2html, using the manual pages.
Time: 02:39:18 GMT, October 02, 2010