What's an X11 server grab?

An X11 protocol mechanism where one client claims exclusive access to mouse and keyboard. Used historically by games for raw input. If the client crashes without releasing the grab, the entire X session is unusable until X is restarted — mouse and keyboard go nowhere.

How do I avoid grabbing the X server?

Use SDL2’s SDL_SetRelativeMouseMode for FPS-style mouse capture; it handles grab/release safely. Don’t call XGrabPointer/XGrabKeyboard directly unless you have specific need and have crash-safe release logic.

Does Wayland have the same issue?

Wayland doesn’t expose server-wide grabs to clients. Mouse/keyboard capture is per-window via pointer constraints; if the client dies, the OS releases automatically. Modern recommendation: target Wayland; X11 only as fallback.

Fix: Linux Game Stuck on X11 Server Grab

Quick answer: Use SDL2’s SDL_SetRelativeMouseMode for mouse capture — never call XGrabPointer directly. SDL handles release safely on crash. Target Wayland where possible.

Player runs your game in fullscreen Linux. Game crashes mid-session. The entire desktop is now unresponsive: mouse and keyboard send no input. The only escape is switching to a TTY (Ctrl+Alt+F2) and killing X. Classic X11 grab leak.

Server Grabs Are Dangerous

X11’s XGrabPointer and XGrabKeyboard take exclusive control of input devices. The X server enforces this: until the grabbing client releases, no other client gets input. If the grabber crashes (segfault, OOM kill), the grab leaks until the X server itself is killed or restarted.

This is why old Linux games sometimes lock the entire system on crash. Modern games avoid the issue.

Use SDL Relative Mouse Mode

For FPS-style mouse capture (cursor hidden, infinite drag), use:

SDL_SetRelativeMouseMode(SDL_TRUE);
// ... game loop ...
SDL_SetRelativeMouseMode(SDL_FALSE);   // on quit/menu

SDL2 implements this via XInput2 (no server grab) or via a per-window pointer constraint (Wayland). If the process dies, the OS releases automatically.

Engine Defaults

Modern engines use safe input capture:

Unity: Cursor.lockState = CursorLockMode.Locked uses platform-safe locking.
Unreal: PlayerController bShowMouseCursor + input mode handles it.
Godot: Input.set_mouse_mode(MOUSE_MODE_CAPTURED) similarly.

If you’re writing a custom engine or using a low-level toolkit, ensure your platform layer uses SDL2 or equivalent — don’t hand-roll Xlib grabs.

Crash Safety

Even with safe APIs, add a SIGTERM/SIGINT handler that releases any locks:

void signal_handler(int sig) {
    SDL_SetRelativeMouseMode(SDL_FALSE);
    SDL_Quit();
    _exit(1);
}
signal(SIGTERM, signal_handler);
signal(SIGINT, signal_handler);

Graceful release on common termination paths. SIGSEGV (segfault) is harder to handle safely; SDL’s default is your safety net.

Wayland Recommendation

Run under Wayland when possible. The protocol prevents server-wide grabs; pointer/keyboard locks are per-window and OS-cleaned on client exit. SteamOS and Ubuntu 24.04+ default to Wayland; supporting it is the modern Linux baseline.

Verifying

Run the game; kill it from another terminal mid-grab (kill -9 PID). Mouse and keyboard should immediately work in the OS desktop. With unsafe Xlib grabs, the system locks; with SDL/Wayland, recovery is automatic.

“X11 server grabs leak on crash. Use SDL2’s safe capture APIs; better yet, target Wayland.”

If your players report “Linux lockup” bugs, you likely have a grab leak path — audit input capture code and consider an SDL2-based abstraction.