ham_condition_handle()
Get a handle to a condition in an entity
Synopsis:
#include <ha/ham.h>
ham_condition_t *ham_condition_handle(
int reserved,
const char *ename,
const char *cname,
unsigned flags );
Arguments:
- reserved
- Set this argument to 0.
- ename
- The name of the entity that contains the condition in cname.
- cname
- The name of the condition to which the function returns a handle.
- flags
- Currently not used.
Library:
libham
Description:
The ham_condition_handle() function returns a handle to a condition (cname) in an entity (ename).
The handle obtained from this function can be passed to other functions, such as ham_action_restart() or ham_condition_handle_free().
The handle returned is opaque; its contents are internal to the library.
There are no flags defined at this time.
Returns:
A valid ham_condition_t, or NULL if an error occurred (errno is set).
Errors:
- EINVAL
- The name given in cname or ename is invalid (e.g., it
contains the
character), or cname is NULL./ - ENAMETOOLONG
- The name given (in aname) 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 condition by the name cname defined in an entity by name ename in the current context of the HAM.
- ENOMEM
- Not enough memory to create a new handle.
Classification:
| Safety: | |
|---|---|
| Cancellation point | No |
| Signal handler | No |
| Thread | Yes |
Caveats:
A call to ham_condition_handle() and a subsequent use of the handle returned in a call such as ham_action_restart() are completely asynchronous. Therefore, a valid action/condition/entity may no longer exist when the handle is used to attach actions at a later time.
In such an event, the ham_action() function will return an error (ENOENT) that the condition doesn't exist in the given entity.