For attaching/detaching all other entities

Updated: May 06, 2022

ham_entity_t *ham_attach(char *ename, int nd, pid_t pid, char *line, 
              unsigned flags);
ham_entity_t *ham_attach_node(char *ename, const char *nodename, pid_t pid, 
              char *line, unsigned flags);
int ham_detach(ham_entity_t *ehdl, unsigned flags);
int ham_detach_name(int nd, char *ename, unsigned flags);
int ham_detach_name_node(const char *nodename, char *ename, unsigned flags);


These attach/detach/detach-name functions are very similar to the *_self() functions above, except here the calling process asks a HAM to monitor a different process.

This mechanism allows for arbitrary monitoring of entities that already exist and aren't compiled against the HAM API library. In fact, the entities that are being monitored needn't even be aware that they're being monitored.

You can use the ham_attach() call either to:

In the ham_attach() call, if pid is -1, then we assume that the entity isn't running. The entity is started now using line as the startup command line for it. But if pid is greater than 0, then line is ignored and the pid given is attached to as an entity. Again ename needs to be unique across all entities currently registered.

The nd specifier in ham_attach() and ham_detach_name(), and the nodename specifier in the ham_attach_node() and ham_detach_name_node() versions of the calls are used to refer to a remote HAM across Qnet. The nd that is passed to the function is the node identifier that refers to the remote host at the instant the call is made. Since node identifiers are transient values, it is essential that the node identifier is obtained just prior to the call. The other option is to use the fully qualified node name (FQNN) of the host and to pass this as the nodename parameter. An nd of ND_LOCAL_NODE (a constant defined in sys/netmgr.h or a nodename of NULL (or the empty string) are equivalent, and refer to the current node.

The ham_detach*() functions stop monitoring a given entity. The ham_detach() call takes as an argument the original handle returned by ham_attach(). You can also call ham_detach_name(), which uses the entity's name instead of the handle.

Note that the entity handle can also be used later to add conditions to the entity (described below).