ham_entity_handle()
Get a handle to an entity
Synopsis:
#include <ha/ham.h>
ham_entity_t *ham_entity_handle( int reserved,
const char *ename,
unsigned flags );
Arguments:
- reserved
- Set this argument to 0.
- ename
- The name of the entity to which the function returns a handle.
- flags
- Currently not used.
Library:
libham
Description:
The ham_entity_handle() function returns a handle to an entity (ename). The handle can then be passed to other functions that expect a handle to an entity (such as ham_condition() or ham_entity_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_entity_t, or NULL if an error occurred (errno is set).
Errors:
- EINVAL
- The name given in ename is invalid (e.g., it
contains the
character)./ - 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
- There's no entity by this name defined 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_entity_handle() and a subsequent use of the handle returned in a call such as ham_condition() are completely asynchronous. Therefore, a valid action/condition/entity may no longer exist when the handle is used at a later time.
In such an event, the ham_condition*() functions will return an error (ENOENT) that the action in the condition doesn't exist in the given entity.