SCF_HANDLE_DECODE_FMRI(3SCF) Service Configuration Facility Library Functions


NAME


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

SYNOPSIS


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);


DESCRIPTION


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.

RETURN VALUES


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.

ERRORS


The scf_handle_decode_fmri() function will fail if:

SCF_ERROR_BACKEND_ACCESS

The storage mechanism that the repository server
(svc.configd(1M)) chose for the operation denied access.


SCF_ERROR_CONNECTION_BROKEN

The connection to the repository was lost.


SCF_ERROR_CONSTRAINT_VIOLATED

The FMRI does not meet the restrictions requested in the flag
argument.


SCF_ERROR_DELETED

The object argument refers to an object that has been deleted.


SCF_ERROR_HANDLE_MISMATCH

One or more of the entity handles was not derived from handle.


SCF_ERROR_INTERNAL

An internal error occurred.


SCF_ERROR_INVALID_ARGUMENT

The fmri argument is not a valid FMRI.


SCF_ERROR_NO_RESOURCES

The server does not have adequate resources to complete the request.


SCF_ERROR_NOT_BOUND

The handle is not currently bound.


SCF_ERROR_NOT_FOUND

The FMRI is well-formed but there is no object in the repository
matching it.


SCF_ERROR_NOT_SET

Cannot use unset value.


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

The object argument is not currently set.


SCF_ERROR_DELETED

The object argument refers to an object that has been deleted.


SCF_ERROR_NOT_BOUND

The handle is not currently bound.


SCF_ERROR_CONNECTION_BROKEN

The connection to the repository was lost.


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 | Safe |
+--------------------+-----------------+

SEE ALSO


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


June 4, 2009 SCF_HANDLE_DECODE_FMRI(3SCF)