man pages section 3: Extended Library Functions, Volume 4

Exit Print View

Updated: July 2014
 
 

scf_actionset_next_error(3SCF)

Name

scf_actionset_create, scf_actionset_add, scf_actionset_destroy, scf_actionset_initiate, scf_actionset_prepare, scf_actionset_perform, scf_actionset_next_error - create sets of administrative actions which apply to the Service Configuration Facility, and perform them either synchronously or asynchronously

Synopsis

cc [flag... ] file... -lscf [ 
library... ]
#include <libscf.h>
scf_actionset_t *scf_actionset_create(scf_handle_t *handle);

int scf_actionset_add(scf_actionset_t *set, const char *fmri,
	 scf_action_t action, int flags);
int scf_actionset_perform(scf_actionset_t *set, int timeout);
scf_actionset_t *scf_actionset_prepare(scf_handle_t *handle,
	 const char *fmri, scf_action_t action, int flags, ...);

int scf_actionset_next_error(scf_actionset_t *set);

void scf_actionset_destroy(scf_actionset_t *set);

Description

These functions provide administrative control over groups of services and instances. Using these interfaces, it is possible to start, stop, restart, refresh, mark, or clear a group of instances as well as transition between milestones. After creating a set of actions, the set of actions can be performed either synchronously or asynchronously.

scf_actionset_create() allocates and initializes a scf_actionset_t and returns a pointer to the allocated structure. Actions can then be added to the structure which can be executed later. Conversely, scf_actionset_destroy() will clean scf_actionset_t which has been passed in. After calling this function, further use of the destroyed action set is illegal.

The scf_actionset_add() function adds actions to a previously created set. The specified action is performed on the fmri, subject to flags. For a detailed explanation of which actions take what flags, see smf_enable_instance(3SCF). The available actions are defined as follows:


typedef enum {
		 SCF_ENABLE,
		 SCF_DISABLE,
		 SCF_RESTART,
		 SCF_REFRESH,
		 SCF_DEGRADE,
		 SCF_MAINTENANCE,
		 SCF_CLEAR,
		 SCF_MILESTONE
	    } scf_action_t;

scf_actionset_prepare() is a convenience function which combines scf_actionset_create() and scf_actionset_add(). The function returns an action set which contains all the actions specified in the argument list. Each action is fully defined by an ordered triple which must be the same order as the explicit arguments in the function signature, that is fmri , action, flags. The list of arguments is terminated by a triple consisting of NULL, 0, 0. If libscf.h is included in a file being compiled against a C99 compliant toolset, the macro SCF_ACTIONSET_PREPARE() is provided. This macro simply defined as a call to scf_actionset_prepare() with the termination triple automatically appends to the arguments provided to the macro.

scf_actionset_perform() executes all the actions in a set either asynchronously, or synchronously subject to timeout. Each action is performed in the order in which it was added to the set. If each action is completed successfully within timeout seconds, the function returns SCF_COMPLETE. If the timeout is reached, the function returns SCF_SUCCESS. If one or more errors occur while processing any of the actions in the set, SCF_FAILED is returned. Note that scf_actionset_perform () often handles more than one action, each of which can have errors associated with it. As such, scf_error() does not necessarily correspond to the error which cause scf_actionset_perform () to fail. If timeout is -1, scf_actionset_perform () waits for actions to complete indefinitely. A 0 second timeout returns immediately after initiating all the actions in set, making the call effectively asynchronous.

scf_actionset_next_error() extracts the details of any errors which may have occurred during scf_actionset_perform (), one error at a time. See scf_error(3SCF) for a detailed explanation of possible values. Errors are iterated in the order they occur that naturally follows the order in which actions were added to the set. Each time the function returns, the arguments are populated with the following values:

action_id

The string passed to scf_actionset_add(3SCF) via the fmri argument corresponding to the action which caused the current error.

fmri

The FMRI of the particular entity for which the error occurred.

action

The code representing which action was attempted on action_id.

For example, if enabling svcA failed due to a dependency, the action svcB failing to come online will be set to SCF_ENABLE. Then, fmri will be populated with the FMRI for svcB, and action_id will be populated with svcA.

Actions are considered complete once the following conditions have been met:

SCF_ENABLE

restarter/state is either online or degraded or in maintenance

SCF_DISABLE

restarter/state is disabled

SCF_RESTART

restarter/state_timestamp has a later time when the command was issued

SCF_REFRESH

restarter/state_timestamp has a later time when the command was issued and restarter/state is either online, degraded, or maintenance

SCF_DEGRADE

restarter/state is degraded

SCF_MAINTENANCE

restarter/state is maintenance

SCF_CLEAR

restarter/state is either online or degraded or in maintenance and state transition has occurred

SCF_MILESTONE

A milestone is considered reached in one of two ways, depending on if a milestone is higher or lower than the current requested milestone. On transition to a higher milestone, the milestone is considered reached when that milestone's service is online just like enabling any other service. However, on transition to a lower milestone, the service for the requested milestone will already be in the online state. Furthermore, the service for the current milestone will transition to disabled before any of it's dependencies transition. Thus, it is necessary for all services to wait, which constitute the current milestone are not participants in any lower milestone, to transition to disabled state. More precisely, on a transition to a lower milestone, the milestone is considered reached when the set of services from all higher milestones which have either no dependencies or have a direct dependency on a service in the target milestone have transitioned to offline.

Additionally, any action is considered complete when all instances which have not met the conditions listed above are unable to do so without further administrative action (such as an unsatisfied dependency).

The scf_actionset_create() function returns either a pointer to an initialized scf_actionset_t, or NULL if an error occurs.

The scf_actionset_add() function returns SCF_SUCCESS upon success, and SCF_FAILED should an error occur.

The scf_actionset_perform() function returns SCF_COMPLETE if all actions are completed before the specified timeout. If all actions were initiated successfully and no errors occur but the timeout expires, the function returns SCF_SUCCESS. SCF_FAILED will be returned in all other cases.

The scf_actionset_prepare() function returns either a pointer to an initialized scf_actionset_t populated with all the actions specified in the arguments list, or NULL if an error occurs.

The scf_actionset_next_error() function returns the error code for the current error. Once there are no errors to iterate over, the function returns 0. If an error occurs, SCF_FAILED is returned.

Errors

The scf_actionset_create() and scf_actionset_prepare () functions return NULL if memory could not be allocated.

The scf_actionset_add() function will fail if:

SCF_ERROR_NO_MEMORY

The memory allocation failed.

SCF_ERROR_INVALID_ACTION

Either fmri did not correspond to a service or instance, or flags were invalid for the specified action.

The scf_actionset_next_error() function will fail if:

SCF_ERROR_INVALID_ARGUMENT

Set is NULL.

The scf_actionset_perform() function fails if an error occurred initiating or waiting for the completion of any actions in the set. Should a failure occur, the details of any error can be extracted through the error iterator interface. Note that the value returned by the scf_error(3SCF) function after calling this function is meaningless and does not correspond to any particular error.

Attributes

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

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Interface Stability
Committed
MT-Level
Safe

See also

libscf(3LIB) , smf(5) , attributes (5), svc.configd(1M) , svc.startd (1M),