ham_action_notify_signal(), ham_action_notify_signal

Add a notify-signal action to a condition

Synopsis:

#include <ha/ham.h>

ham_action_t *ham_action_notify_signal(
                 ham_condition_t *chdl,
                 const char *aname, 
                 int nd,
                 pid_t topid,
                 int signum, 
                 int code, 
                 int value, 
                 unsigned flags);

ham_action_t *ham_action_notify_signal_node(
                 ham_condition_t *chdl,
                 const char *aname, 
                 const char *nodename, 
                 pid_t topid,
                 int signum, 
                 int code, 
                 int value, 
                 unsigned flags);

Arguments:

chdl: The HAM condition handle to which the action is added.
aname: The name of the action to add.
nd: (ham_action_notify_signal() only) The node identifier of the targeted remote node.
nodename: (ham_action_notify_signal_node() only) The targeted remote HAM.
topid: The process ID of the targeted process.
signum: Signum specifies the signal to deliver.
code: The code of the signal to deliver.
value: The value of the signal to deliver.
flags: The flags indicating how the action should be operated. See below.

Library:

libham

Description:

These functions add an action to a given condition. The action will deliver a signal notification to the process given in topid.

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.

The action is executed when the appropriate condition is triggered.

You use the node descriptor (nd) to specify where in the network the recipient of the notification resides.

The nd specifies the node identifier of the remote (or local) node to which the signal is targeted The nd specified is the node identifier of the remote node at the time the call is made.

Note: Since node identifiers are transient objects, you should obtain the value for nd immediately before the call, using netmgr_strtond() or another function that converts nodenames into node identifiers.

Use the ham_action_notify_signal_node() function when a nodename is used to specify a remote HAM instead of a node identifier (nd). The ham_action_notify_signal_node() function takes as a parameter a fully qualified node name (FQNN)

The signal in signum with the given value will be delivered to the process pid on node nd. This can also be used to terminate processes by sending them appropriate signals like SIGTERM, SIGKILL etc.

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 that if the condition that this action belongs to is pruned after a restart, 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, 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, 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 to a condition, or NULL if an error occurred (errno is set).

Errors:

EBADF: Couldn't connect to the HAM.
EEXIST: The name provided for the action already exists.
EINVAL: The name given in aname is invalid (e.g., it contains the “/” character) or is NULL.
The connection to the HAM is invalid. This happens when the process that opened the connection (using ham_connect()) and the process that's calling ham_action_notify_signal() aren't the same.
ENAMETOOLONG: The name given is too long, i.e. it exceeds _POSIX_PATH_MAX (defined in <limits.h>). Note that the combined length of an entity/condition/action name is also limited by _POSIX_PATH_MAX.
ENOENT: There's no action of the name aname in a condition cname defined in an entity ename in the HAM's current context.
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 Neutrino

Safety:
Cancellation point	No
Interrupt handler	No
Signal handler	No
Thread	Yes

ham_action_notify_signal(), ham_action_notify_signal_node()