ham_action_restart()

QNX SDP8.0High Availability Framework Developer's GuideDeveloper

Add a restart action to a condition

Synopsis:

#include <ha/ham.h>

ham_action_t *ham_action_restart(
                ham_condition_t *chdl,
                const char *aname,
                const char *path,
                unsigned flags);

Arguments:

chdl
The HAM condition handle to which the action is added.
aname
The name of the action to add.
path
The external program or command line to be executed. See below.
flags
The flags indicating how the action should be operated. See below.

Library:

libham

Description:

You use the ham_action_restart() function to add an action (aname) to a given condition. In this case, the action will restart a program that has died.

Note:
Restart actions can be associated only with death conditions (CONDDEATH, CONDABNORMALDEATH).
Important:
There can be only one restart action over all the death conditions in an entity.

The handle (chdl) is obtained either:

  • from one of the ham_condition*() functions to add conditions

    or:

  • by calling any of the ham_condition_handle() functions to request a handle to a specific condition.

You use the path parameter to specify the external program or command line to be executed — path must contain the FULL path to the executable along with all parameters to be passed to it. If either the pathname or the arguments contain spaces that need to be passed on literally to the spawn call, then they need to be quoted.

As long as the subcomponents within the path arguments are quoted, using either of the following methods:

\'path with space\' or \"path with space\"

the following is allowed:

"\'path with space\' arg1 arg2 \"arg3 with space\""

This would be parsed as:

"path with space" -> path

arg1 = arg1

arg2 = arg2

arg3 = "arg3 with space"

The command line is in turn passed onto a spawn() command by the HAM to create a new process that will execute the command.

The action is executed when the appropriate condition is triggered.

Note:
This action also triggers a restart condition in the entity.

Currently the following flags are defined:

HREARMAFTERRESTART
Indicates that the action is to be automatically rearmed after the entity that it belongs to is restarted. By default, this flag is disabled — actions automatically get pruned across restarts of the entity.
Note:
If the condition that this action belongs to is pruned after a restart, then this action will also be removed, regardless of the value of this flag.
HACTIONBREAKONFAIL
Indicates that if this action were to fail, and it is part of a list of actions, then none of the actions following this one in the list of actions will be executed.
HACTIONKEEPONFAIL
Indicates that the action will be retained even if it fails. The default behavior is to remove failed actions. Nevertheless, if the condition that this action is associated with is not retained, then the action will get automatically removed.

Users can specify what will be done if an action fails. By adding action fail actions to a list associated with an action, users can determine what will be done in the case of an action failure. For every action that fails, the corresponding action fail list will be executed. Certain actions (e.g., ham_action_log() and ham_action_heartbeat_healthy()) never fail. For more details, refer to the appropriate section in the HAM API reference for the ham_action_fail_*() calls.

Returns:

A valid handle to an action in a condition, or NULL if an error occurred (errno is set).

Errors:

EBADF
Couldn't connect to the HAM.
EINVAL
The name given in aname is invalid (e.g., it contains the / character) or is NULL.
ENAMETOOLONG
The name given (in aname) is too long (i.e., it exceeds _POSIX_PATH_MAX (defined in <limits.h>).
Note:
The combined name length of an entity, condition, or action is also limited by _POSIX_PATH_MAX.
ENOENT
There's no entity or condition specified by the given handle (chdl).
ENOMEM
Not enough memory to create a new handle.

In addition to the above errors, the HAM returns any error it encounters while servicing this request.

Classification:

QNX OS

Safety:
Cancellation pointNo
Signal handlerNo
ThreadYes
Page updated: