iofunc_notify()

Install, poll, or remove a notification handler

Synopsis:

#include <sys/iofunc.h>

int iofunc_notify( resmgr_context_t *ctp,
                   io_notify_t *msg,
                   iofunc_notify_t *nop,
                   int trig,
                   const int *notifycounts,
                   int *armed );

Library:

libc

Description:

The POSIX layer helper function iofunc_notify() is used by a resource manager to implement notification.

The routine examines the message that the resource manager received (passed in the msg argument), and determines what action the client code is attempting to perform (see below).

The caller supplies four additional parameters, as follows (ones marked optional may be passed as NULL):

iofunc_notify_t *nop: (Required) This structure points to an array of three elements representing, (in order), the input, output, and out-of-band notification lists. Generally, this structure is maintained by the resource manager within an extended attributes structure.
int trig: (Required) A bitmask indicating which sources are currently satisfied, and could cause a trigger to occur. The valid value is any combination of _NOTIFY_COND_INPUT, _NOTIFY_COND_OUTPUT and _NOTIFY_COND_OBAND. The caller typically sets this value, based on the conditions in effect when iofunc_notify() is called.
const int *notifycounts: (Optional) An array of three integers representing, (in order), the number of elements that must be present in the input, output, and out-of-band queues in order to trigger the event. Note that if any condition is met, nothing is armed. Only if none of the conditions are met does the event get armed in accordance with the notifycounts parameter. If this parameter isn't specified (passed as NULL), a value of 1 is assumed for all three counts.
int *armed: (Optional) A return value, if set to 1 indicates that a notification entry is armed, else set to 0.

Based upon the client message's action member, the following occurs:

_NOTIFY_ACTION_POLL: Returns a one-part IOV with the flags field set to indicate which conditions (input, output, or out of band) are available. The caller should return this value (_RESMGR_NPARTS(1)) back to the resource manager library, which returns a one-part message to the client.
_NOTIFY_ACTION_POLLARM: Similar to _NOTIFY_ACTION_POLL, with the additional characteristic of arming the event if none of the conditions are met.
_NOTIFY_ACTION_TRANARM: For each of the sources specified, creates a notification entry and stores the client's struct sigevent event structure in it. Note that only one transition arm is allowed at a time per device. If the client specifies an event of SIGEV_NONE, the action is to disarm. When the event is triggered, the notification is automatically disarmed.

Returns:

EBUSY: A notification was already armed for this resource, and this library function enforces a restriction of one per resource.
_RESMGR_NPARTS (1): Normal return, indicates a one-part IOV should be returned to the client.

Examples:

See the Writing a Resource Manager chapter of Programmer's Guide.

Classification:

QNX 6

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