Tribblix: manual page: scf_entry

SCF_ENTRY_CREATE(3SCF) Service Configuration Facility Library Functions

NAME

scf_entry_create, scf_entry_handle, scf_entry_destroy,
scf_entry_destroy_children, scf_entry_reset, scf_entry_add_value -
create and manipulate transaction in the Service Configuration
Facility

SYNOPSIS

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

scf_transaction_entry_t *scf_entry_create(scf_handle_t *handle);

scf_handle_t *scf_entry_handle(scf_transaction_entry_t *entry);

void scf_entry_destroy(scf_transaction_entry_t *entry);

void scf_entry_destroy_children(scf_transaction_entry_t *entry);

void scf_entry_reset(scf_transaction_entry_t *entry);

int scf_entry_add_value(scf_transaction_entry_t *entry,
scf_value_t *value);

DESCRIPTION

The scf_entry_create() function allocates a new transaction entry
handle. The scf_entry_destroy() function destroys the transaction
entry handle.

The scf_entry_handle() function retrieves the handle associated with
entry.

A transaction entry represents a single action on a property in a
property group. If an entry is added to a transaction using
scf_transaction_property_new(3SCF),
scf_transaction_property_change(3SCF), or
scf_transaction_property_change_type(3SCF), scf_entry_add_value() can
be called zero or more times to set up the set of values for that
property. Each value must be set and of a compatible type to the
type associated with the entry. When later retrieved from the
property, the values will have the type of the entry. If the values
are committed successfully with scf_transaction_commit(3SCF), they
will be set in the order in which they were added with
scf_entry_add_value().

The scf_entry_reset() function resets a transaction entry,
disassociating it from any transaction it is a part of (invalidating
the transaction in the process), and disassociating any values that
were added to it.

The scf_entry_destroy_children() function destroys all values
associated with the transaction entry. The entry itself is not
destroyed.

RETURN VALUES

Upon successful completion, scf_entry_create() returns a new
scf_transaction_entry_t. Otherwise, it returns NULL.

Upon successful completion, scf_entry_handle() returns the handle
associated with the transaction entry. Otherwise, it returns NULL.

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

ERRORS

The scf_entry_create() function will fail if:

SCF_ERROR_INVALID_ARGUMENT
The handle argument is NULL.

SCF_ERROR_NO_MEMORY
There is not enough memory to allocate
an scf_transaction_entry_t.

The scf_entry_handle() function will fail if:

SCF_ERROR_HANDLE_DESTROYED
The handle associated with entry has
been destroyed.

The scf_entry_add_value() function will fail if:

SCF_ERROR_HANDLE_MISMATCH
The value and entry arguments are not
derived from the same handle.

SCF_ERROR_IN_USE
The value has been added to another
entry.

SCF_ERROR_INTERNAL
An internal error occurred.

SCF_ERROR_INVALID_ARGUMENT
The value argument is not set, or the
entry was added to the transaction
using
scf_transaction_property_delete(3SCF).

SCF_ERROR_NOT_SET
The transaction entry is not associated
with a transaction.

SCF_ERROR_TYPE_MISMATCH
The type of the value argument does not
match the type that was set using
scf_transaction_property_new(),
scf_transaction_property_change(), or
scf_transaction_property_change_type().

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