libmctProgrammer’s Manual

mct_event_read(3)

Name

mct_event_read — Read a pending MCT event

Synopsis

#include <mct/event.h>

int mct_event_read(struct mct *mct,
	enum mct_event *e, unsigned int *id, int *s, int *err);

Description

The mct_event_read() function reads at most one pending event broadcast from the mctd. The given mct handle must be currently attached for event broadcasts by a call to mct_event_attach.

If the blocking parameter to mct_event_attach() is false (zero), then mct_event_read() will return immediately if there is no currently pending event to retrieve. The return value will be -1 and errno set to EWOULDBLOCK.

If the blocking parameter to mct_event_attach() is true (non-zero), then mct_event_read() will not return until an event has been retrieved from mctd, or an error occurs.

On successful retrieval of an event, mct_event_read() returns 0. On a successful return, various parameters are populated if their values are non-NULL. These parameters are: the event type, written to the e parameter; a sequential event ID, written to the id parameter; the session ID to which the event pertains, written to the s parameter; and an associated error code, written to the err parameter.

Event IDs are conceptually similar to SNMP counters; they increment with each event sent, and roll over to 0 when their maximum value is reached.

Event IDs may be skipped if (for example) the mct handle is detached from event broadcasts, mctd broadcasts an event, and then the mct handle is re-attached. In this way an application may identify that an event was missed.

The error code err is set 0 for events which occurred successfully. For events which have an associated error condition, err is set non-0 with the relevant error code as per errno. This may be looked up with strerror.

Return Value

The mct_event_read() function returns 0 on success. On failure this function returns -1 and errno is set accordingly.

Errors

The mct_event_read() function may fail for any of the reasons the socket API may produce.

In addition, mct_event_read() may fail for any of the reasons documented by mct_ipc.

In addition, mct_event_read() may fail for any of the following reasons:

EAGAIN

Event registration was attached non-blocking as per the call to mct_event_attach(), and an underlying system call was interrupted.

EWOULDBLOCK

Event registration was attached non-blocking as per the call to mct_event_attach(), and there are currently no events awaiting retrieval.

EBADMSG

An invalid event ID was returned by mctd.

ENOTCONN

The given mct handle is not currently attached for events.

Notes

When effecting a poll it is prudent to immediately poll again on successful return, and so on until mct_event_read() yields EWOULDBLOCK. This gives timely delivery of multiple queued events. When a subsequent poll does yield EWOULDBLOCK the application may sleep, or go about its other business.

Caveats

It is not currently possible to integrate event retrieval with a select-like application architecture.

See Also

mct, mct_ipc, mct_event_attach, errno, strerror.