ham_attach(), ham_attach_node()

Attach an entity

Synopsis:

#include <ha/ham.h>

ham_entity_t *ham_attach( const char *ename, 
                          int nd,
                          pid_t pid,  
                          const char *line, 
                          unsigned flags );

ham_entity_t *ham_attach_node( const char *ename, 
                          const char *nodename, 
                          pid_t pid,  
                          const char *line, 
                          unsigned flags );

Library:

libham

Description:

You use the ham_attach() function to attach an entity to the HAM. The ham_attach_node() function is used when a nodename is used to specify a remote HAM instead of a node identifier (nd). An entity can be any process on the system. You can use this function to:

Once an entity has been attached, you can add conditions and actions to it. For arbitrary processes, the HAM can monitor either:

Note: Since the ham_attach*() functions open a connection to the HAM, for convenience they also perform the initial ham_connect() call. So any client that makes a ham_attach() call doesn't need to call ham_connect() or ham_disconnect() before and after the call to ham_attach().

The arguments are as follows:

ename
The name of the entity; it must be unique across the whole context of the HAM.
nd
This ham_attach() parameter specifies the node identifier of the remote node on which the entity being targeted is running (or will be run). The nd 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.
pid
Process ID to attach to, if the process is already running. If pid ≤ 0, the HAM starts the process and begins monitoring it. In this case, line must also be specified with the FULL path (including all required arguments) to start the process.
nodename
This ham_attach_node() parameter is a fully qualified node name (FQNN).
line
This contains the FULL command line, including arguments, to start the process. This is used ONLY if pid ≤ 0 and is ignored otherwise. If either the pathname or the arguments contain spaces that need to be passed literally to the spawn call, 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".
  
flags
Currently, the following flag is defined:
HENTITYKEEPONDEATH
Indicates that the entity and all it conditions will be retained when the entity dies and is not restarted. The default is to remove all entities that aren't restarted.

Returns:

A valid handle to an entity on success; otherwise, NULL (errno is set).

Errors:

EBADF
Couldn't connect to the HAM.
EEXIST
The name provided for the entity already exists.
EINVAL
The name given in ename is invalid (e.g., it contains the / character) or is NULL.

The pid provided is ≤ 0, but no line was provided.

ENAMETOOLONG
The name given (in ename) 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
(QNX Neutrino 7.0 or later) There isn't a process with the specified pid.
ENOMEM
Not enough memory to create a new handle.

In addition to the above errors, the HAM returns any error it encounters while servicing the request to add a new entity to its context.

Classification:

QNX Neutrino

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