ham_attach()
Attach an entity
Synopsis:
#include <ha/ham.h> ham_entity_t *ham_attach( const char *ename, int reserved, pid_t pid, const char *line, unsigned flags );
Arguments:
- ename
- The name of the entity; it must be unique across the whole context of the HAM.
- reserved
- Set this argument to 0.
- 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.
- 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.
Library:
libham
Description:
You use the ham_attach() function to attach an entity to the HAM. An entity can be any process on the system. You can use this function to:
- attach a process that's already running
or:
- tell the HAM to start a process and then add it as an entity to its context.
Once an entity has been attached, you can add conditions and actions to it.
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 or the line provided is too long, i.e., it exceeds _POSIX_PATH_MAX (defined in <limits.h>).
- 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:
Safety: | |
---|---|
Cancellation point | No |
Signal handler | No |
Thread | Yes |