---
name: "giiEventsQueued"
section: "3"
platform: "linux"
package: "libgii1"
version: "1:1.0.2-4.1"
release: "Debian 7 (Wheezy)"
platforms: ["linux"]
url: "https://new.carta.tech/giiEventPoll"
---

# giiEventsQueued(3)

Wait for and receive events

Part of [giiEventPoll(3)](/giiEventPoll/3.md).

## NAME

**giiEventPoll**, **giiEventSelect**, **giiEventsQueued**, **giiEventRead** - Wait for and receive events

## SYNOPSIS

```
#include <ggi/gii.h>
gii_event_mask giiEventPoll(gii_input_t inp, gii_event_mask mask,
                            struct timeval *t);
int giiEventSelect(gii_input_t inp, gii_event_mask *mask, int n,
                   fd_set *readfds, fd_set *writefds, fd_set *exceptfds,
                   struct timeval *timeout);
int giiEventsQueued(gii_input_t inp, gii_event_mask mask);
int giiEventRead(gii_input_t inp, gii_event *ev, gii_event_mask mask);
```

## DESCRIPTION

**giiEventPoll** waits for specific events to become available on an input. This call somewhat resembles the Unix `select(2)` call, but only for LibGII events and is more portable.  The function returns after an event matching the given event mask is available or after the amount of time specified by *t* has elapsed, whichever occurs first.  If *t* is **NULL**, there is no timeout.

The timeout value on return is updated to the time that would have been remaining. So make sure to re-setup this value when calling **giiEventPoll** in a loop.

**giiEventSelect** is the combination of **giiEventPoll** and `select(2)` allowing to wait for both LibGII events and arbitrary file descriptors in any of the three states.  However, this function is **not** available if the operating system does not support the `select(2)` call, not even as a stub.

**giiEventsQueued** returns the number of events matching the specified event mask that are currently queued in the input.

**giiEventRead** blocks for and transfers an event from the given input to the location pointed to by *ev*. The event with the earliest timestamp that matches the given mask is returned to the application.

## RETURN VALUE

**giiEventPoll** returns a mask of available events (constrained by the given mask).  It is **0** if no events are available.  On error, an negative `gii-error(3)` code is returned.

**giiEventSelect** returns the same values as `select(2)`.  Unlike other LibGGI/LibGII functions, it also uses **errno**. It will update the timeout regardless of whether or not the system call does so.

**giiEventsQueued** returns the number of events.

**giiEventRead** returns the size of event on success, and **0** on error.

## EXAMPLES

This is one of the various ways of coding an event-polling loop:

```
for(;;) {
    tv.tv_sec = 0;
    tv.tv_usec = 100; /* change to 0 for non-blocking behaviour */
    ggiEventPoll(vis, emAll, &tv);
    n = ggiEventsQueued(vis, emAll);
    /* Process events in one gulp, when available */
    while(n--) {
        ggiEventRead(vis, &ggievent, emAll);
        switch(ggievent.any.type) {
            /* ... */
        }
    }
    /* Do other stuff */
}
```

**Note:** This code uses the LibGGI functions and types instead of the LibGII ones, since the former is the more common case.