---
name: "XGrabKeyboard"
section: "3"
platform: "linux"
package: "libx11"
version: "1.8.14-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/XGrabKeyboard"
---

# XGrabKeyboard(3)

grab the keyboard

## NAME

XGrabKeyboard, XUngrabKeyboard - grab the keyboard

## SYNTAX

int XGrabKeyboard(Display \**display*, Window *grab\_window*, Bool *owner\_events*, int *pointer\_mode*, int *keyboard\_mode*, Time *time*);

int XUngrabKeyboard(Display \**display*, Time *time*);

## ARGUMENTS

- *display*

  Specifies the connection to the X server.

- *grab\_window*

  Specifies the grab window.

- *keyboard\_mode*

  Specifies further processing of keyboard events. You can pass **GrabModeSync** or **GrabModeAsync**.

- *owner\_events*

  Specifies a Boolean value that indicates whether the keyboard events are to be reported as usual.

- *pointer\_mode*

  Specifies further processing of pointer events. You can pass **GrabModeSync** or **GrabModeAsync**.

- *time*

  Specifies the time. You can pass either a timestamp or **CurrentTime**.

## DESCRIPTION

The **XGrabKeyboard** function actively grabs control of the keyboard and generates **FocusIn** and **FocusOut** events. Further key events are reported only to the grabbing client. **XGrabKeyboard** overrides any active keyboard grab by this client. If owner\_events is **False**, all generated key events are reported with respect to grab\_window. If owner\_events is **True** and if a generated key event would normally be reported to this client, it is reported normally; otherwise, the event is reported with respect to the grab\_window. Both **KeyPress** and **KeyRelease** events are always reported, independent of any event selection made by the client.

If the keyboard\_mode argument is **GrabModeAsync**, keyboard event processing continues as usual. If the keyboard is currently frozen by this client, then processing of keyboard events is resumed. If the keyboard\_mode  argument is **GrabModeSync**, the state of the keyboard (as seen by client applications) appears to freeze, and the X server generates no further keyboard events until the grabbing client issues a releasing **XAllowEvents** call or until the keyboard grab is released. Actual keyboard changes are not lost while the keyboard is frozen; they are simply queued in the server for later processing.

If pointer\_mode is **GrabModeAsync**, pointer event processing is unaffected by activation of the grab. If pointer\_mode is **GrabModeSync**, the state of the pointer (as seen by client applications) appears to freeze, and the X server generates no further pointer events until the grabbing client issues a releasing **XAllowEvents** call or until the keyboard grab is released. Actual pointer changes are not lost while the pointer is frozen; they are simply queued in the server for later processing.

If the keyboard is actively grabbed by some other client, **XGrabKeyboard** fails and returns **AlreadyGrabbed**. If grab\_window is not viewable, it fails and returns **GrabNotViewable**. If the keyboard is frozen by an active grab of another client, it fails and returns **GrabFrozen**. If the specified time is earlier than the last-keyboard-grab time or later than the current X server time, it fails and returns **GrabInvalidTime**. Otherwise, the last-keyboard-grab time is set to the specified time (**CurrentTime** is replaced by the current X server time).

**XGrabKeyboard** can generate **BadValue** and **BadWindow** errors.

The **XUngrabKeyboard** function releases the keyboard and any queued events if this client has it actively grabbed from either **XGrabKeyboard** or **XGrabKey**. **XUngrabKeyboard** does not release the keyboard and any queued events if the specified time is earlier than the last-keyboard-grab time or is later than the current X server time. It also generates **FocusIn** and **FocusOut** events. The X server automatically performs an **UngrabKeyboard** request if the event window for an active keyboard grab becomes not viewable.

## DIAGNOSTICS

- **BadValue**

  Some numeric value falls outside the range of values accepted by the request. Unless a specific range is specified for an argument, the full range defined by the argument's type is accepted. Any argument defined as a set of alternatives can generate this error.

- **BadWindow**

  A value for a Window argument does not name a defined Window.

## SEE ALSO

[**XAllowEvents**(3)](/XAllowEvents/3.md), [**XGrabButton**(3)](/XGrabButton/3.md), [**XGrabKey**(3)](/XGrabKey/3.md), [**XGrabPointer**(3)](/XGrabPointer/3.md)\
 *Xlib - C Language X Interface*