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_instance_create, scf_instance_handle, scf_instance_destroy, scf_instance_get_parent, scf_instance_get_name, scf_service_get_instance, scf_service_add_instance, scf_instance_delete - create and manipulate instance handles and instances in the Service Configuration Facility

cc [ flag.\|.\|. ] file.\|.\|. -lscf [ library.\|.\|. ] 
#include <libscf.h>

scf_instance_t *scf_instance_create(scf_handle_t *handle);

scf_handle_t *scf_instance_handle(scf_instance_t *inst);

void scf_instance_destroy(scf_instance_t *inst);

int scf_instance_get_parent(const scf_instance_t *inst,
 scf_service_t *svc);

ssize_t scf_instance_get_name(const scf_instance_t *inst,
 char *name, size_t size);

int scf_service_get_instance(const scf_service_t *svc,
 const char *name, scf_instance_t *inst);

int scf_service_add_instance(const scf_service_t *svc,
 const char *name, scf_instance_t *inst);

int scf_instance_delete(scf_instance_t *inst);

Instances form the bottom layer of the Service Configuration Facility repository tree. An instance is the child of a service and has two sets of children:

Property Groups

Snapshots

See smf(5) for information about instances.

An scf_instance_t is an opaque handle that can be set to a single instance at any given time. The scf_instance_create() function allocates and initializes a new scf_instance_t bound to handle. The scf_instance_destroy() function destroys and frees inst.

The scf_instance_handle() function retrieves the handle to which inst is bound.

The scf_inst_get_parent() function sets svc to the service that is the parent of inst.

The scf_instance_get_name() function retrieves the name of the instance to which inst is set.

The scf_service_get_instance() function sets inst to the child instance of the service svc specified by name.

The scf_service_add_instance() function sets inst to a new child instance of the service svc specified by name.

The scf_instance_delete() function deletes the instance to which inst is set, as well all of the children of the instance.

Upon successful completion, scf_instance_create() returns a new scf_instance_t. Otherwise it returns NULL.

Upon successful completion, scf_instance_handle() returns the handle to which inst is bound. Otherwise, it returns NULL.

Upon successful completion, scf_instance_get_name() returns the length of the string written, not including the terminating null character. Otherwise it returns -1.

Upon successful completion, scf_instance_get_parent(), scf_service_get_instance(), scf_service_add_instance(), and scf_instance_delete() functions return 0. Otherwise, they return -1.

The scf_instance_create() function will fail if:

SCF_ERROR_HANDLE_DESTROYED

SCF_ERROR_INTERNAL

SCF_ERROR_INVALID_ARGUMENT

SCF_ERROR_NO_MEMORY

SCF_ERROR_NO_RESOURCES

The scf_instance_handle() function will fail if:

SCF_ERROR_HANDLE_DESTROYED

The scf_instance_get_name(), scf_instance_get_parent(), and scf_instance_delete() functions will fail if:

SCF_ERROR_DELETED

SCF_ERROR_NOT_SET

SCF_ERROR_NOT_BOUND

SCF_ERROR_CONNECTION_BROKEN

The scf_service_add_instance() function will fail if:

SCF_ERROR_EXISTS

SCF_ERROR_INTERNAL

SCF_ERROR_NO_RESOURCES

SCF_ERROR_NOT_BOUND

The scf_service_get_instance() function will fail if:

SCF_ERROR_BACKEND_ACCESS

SCF_ERROR_INTERNAL

SCF_ERROR_NOT_BOUND

SCF_ERROR_NOT_FOUND

SCF_ERROR_NO_RESOURCES

The scf_service_add_instance() and scf_service_get_instance() functions will fail if:

SCF_ERROR_NOT_SET

SCF_ERROR_DELETED

SCF_ERROR_INVALID_ARGUMENT

SCF_ERROR_HANDLE_MISMATCH

SCF_ERROR_CONNECTION_BROKEN

The scf_instance_get_parent() function will fail if:

SCF_ERROR_HANDLE_MISMATCH

The scf_service_add_instance() and scf_instance_delete() functions will fail if:

SCF_ERROR_PERMISSION_DENIED

SCF_ERROR_BACKEND_READONLY

SCF_ERROR_BACKEND_ACCESS

The scf_instance_delete() function will fail if:

SCF_ERROR_NO_RESOURCES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Committed
MT-Level	Safe

libscf(3LIB), scf_error(3SCF), scf_iter_instance_pgs(3SCF), scf_iter_instance_pgs_typed(3SCF), scf_iter_instance_snapshots(3SCF), scf_pg_create(3SCF), scf_snapshot_create(3SCF), attributes(5), smf(5)

Instance names are of the form:

[domain,]identifier

where domain is either a stock ticker symbol such as SUNW or a Java-style reversed domain name such as com.sun. Identifiers begin with a letter or underscore and contain only letters, digits, underscores, and dashes.