te
Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
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

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.

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

SCF_ERROR_VERSION_MISMATCH

The scf_handle_decorate() function will fail if:

SCF_ERROR_INVALID_ARGUMENT

SCF_ERROR_TYPE_MISMATCH

SCF_ERROR_NOT_SET

SCF_ERROR_IN_USE

SCF_ERROR_HANDLE_MISMATCH

The scf_handle_bind() function will fail if:

SCF_ERROR_INVALID_ARGUMENT

SCF_ERROR_NO_SERVER

SCF_ERROR_NO_RESOURCES

SCF_ERROR_IN_USE

The scf_handle_unbind() function will fail if:

SCF_ERROR_NOT_BOUND

The scf_handle_myname() function will fail if:

SCF_ERROR_CONNECTION_BROKEN

SCF_ERROR_NOT_BOUND

SCF_ERROR_NOT_SET

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

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