te
Copyright (c) 2009, 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_decode_fmri, scf_scope_to_fmri, scf_service_to_fmri, scf_instance_to_fmri, scf_pg_to_fmri, scf_property_to_fmri - convert between objects and FMRIs in the Service Configuration Facility

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

int scf_handle_decode_fmri(scf_handle_t *handle, const char *fmri,
 scf_scope_t *scope, scf_service_t *service,
 scf_instance_t *instance, scf_propertygroup_t *pg,
 scf_property_t *property, int flag);

ssize_t scf_scope_to_fmri(const scf_scope_t *object,
 char *buffer, size_t sz);

ssize_t scf_service_to_fmri(const scf_scope_t *object,
 char *buffer, size_t sz);

ssize_t scf_instance_to_fmri(const scf_instance_t *inst,
 char *buffer, size_t sz);

ssize_t scf_pg_to_fmri(const scf_propertygroup_t *pg, char *out,
 size_t sz);

ssize_t scf_property_to_fmri(const scf_scope_t *object,
 char *buffer, size_t sz);

The scf_handle_decode_fmri() function decodes an FMRI string into a set of repository entries. Any number of the entity handles can be NULL. The validation and decoding of the FMRI are determined by the flags argument and by those arguments that are NULL.

If flags == 0, any FMRI is accepted as long as it is well-formed and exists in the repository.

If SCF_DECODE_FMRI_EXACT is set in flags, the last part of the FMRI must match the last non-null entity handle. For example, if property is NULL and pg is non-null, the FMRI must be a property group FMRI.

If SCF_DECODE_FMRI_TRUNCATE is set in flags, there is no check for the existence of any objects specified in the FMRI that follow the last non-null entity handle. For example, if property is NULL, pg is non-null, and a property FMRI is passed in, scf_handle_decode_fmri() succeeds as long as the property group exists, even if the referenced property does not exist.

If SCF_DECODE_FMRI_REQUIRE_INSTANCE (or SCF_FMRI_REQUIRE_NO_INSTANCE) is set in flags, then the FMRI must (or must not) specify an instance.

If an error occurs, all of the entity handles that were passed to the function are reset.

The scf_scope_to_fmri(), scf_service_to_fmri(), scf_instance_to_fmri(), scf_pg_to_fmri(), and scf_property_to_fmri() functions convert an entity handle to an FMRI.

Upon successful completion, scf_handle_decode_fmri() returns 0. Otherwise, it returns -1.

Upon successful completion, scf_scope_to_fmri(), scf_service_to_fmri(), scf_instance_to_fmri(), scf_pg_to_fmri(), and scf_property_to_fmri() return the length of the FMRI. The buffer will be null-terminated if sz > 0, similar to strlcpy(3C). Otherwise, they return -1 and the contents of buffer are undefined.

The scf_handle_decode_fmri() function will fail if:

SCF_ERROR_BACKEND_ACCESS

SCF_ERROR_CONNECTION_BROKEN

SCF_ERROR_CONSTRAINT_VIOLATED

SCF_ERROR_DELETED

SCF_ERROR_HANDLE_MISMATCH

SCF_ERROR_INTERNAL

SCF_ERROR_INVALID_ARGUMENT

SCF_ERROR_NO_RESOURCES

SCF_ERROR_NOT_BOUND

SCF_ERROR_NOT_FOUND

SCF_ERROR_NOT_SET

The scf_scope_to_fmri(), scf_service_to_fmri(), scf_instance_to_fmri(), scf_pg_to_fmri(), and scf_property_to_fmri() functions will fail if:

SCF_ERROR_NOT_SET

SCF_ERROR_DELETED

SCF_ERROR_NOT_BOUND

SCF_ERROR_CONNECTION_BROKEN

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	Safe

libscf(3LIB), scf_error(3SCF), attributes(5)