---
name: "SDL_PeepEvents"
section: "3"
platform: "linux"
package: "libsdl3-doc"
version: "3.2.10+ds-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/SDL_PeepEvents"
---

# SDL\_PeepEvents(3)

Check the event queue for messages and optionally return them.

## NAME

SDL\_PeepEvents - Check the event queue for messages and optionally return them.

## HEADER FILE

Defined in SDL3/SDL\_events.h

## SYNOPSIS

```
#include "SDL3/SDL.h"
```

**int SDL\_PeepEvents(SDL\_Event \*events, int numevents, SDL\_EventAction action, Uint32 minType, Uint32 maxType);**

## DESCRIPTION

**action** may be any of the following:

•  **SDL\_ADDEVENT** : up to **numevents** events will be added to\
   the back of the event queue.

•  **SDL\_PEEKEVENT** : **numevents** events at the front of the\
   event queue, within the specified minimum and maximum type, will be\
   returned to the caller and will \_not\_ be removed from the queue. If you\
   pass NULL for **events** , then **numevents** is ignored and the total number\
   of matching events will be returned.

•  **SDL\_GETEVENT** : up to **numevents** events at the front of\
   the event queue, within the specified minimum and maximum type, will be\
   returned to the caller and will be removed from the queue.

You may have to call  **SDL\_PumpEvents** () before calling this function. Otherwise, the events may not be ready to be filtered when you call  **SDL\_PeepEvents** ().

## FUNCTION PARAMETERS

- *events*

  destination buffer for the retrieved events, may be NULL to leave the events in the queue and return the number of events that would have been stored.

- *numevents*

  if action is  **SDL\_ADDEVENT** , the number of events to add back to the event queue; if action is  **SDL\_PEEKEVENT**\
    or  **SDL\_GETEVENT** , the maximum number of events to retrieve.

- *action*

  action to take; see \[Remarks\](#remarks) for details.

- *minType*

  minimum value of the event type to be considered;  **SDL\_EVENT\_FIRST**\
    is a safe choice.

- *maxType*

  maximum value of the event type to be considered;  **SDL\_EVENT\_LAST**\
    is a safe choice.

## RETURN VALUE

Returns the number of events actually stored or -1 on failure; call

**SDL\_GetError** () for more information.

## THREAD SAFETY

It is safe to call this function from any thread.

## AVAILABILITY

This function is available since SDL 3.2.0.

## SEE ALSO

**•**(3), [**SDL\_PollEvent**(3)](/SDL_PollEvent/3.md), **•**(3), [**SDL\_PumpEvents**(3)](/SDL_PumpEvents/3.md), **•**(3), [**SDL\_PushEvent**(3)](/SDL_PushEvent/3.md)