man/man3scf/scf_handle_create.3scf

         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 3SCF "Aug 17, 2007"
 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 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(5)