Control the Desktop Screensaver Safely with xdg-screensaver

A screensaver about to lock mid-presentation is exactly what xdg-screensaver exists to stop. It checks, suspends, resumes and, when you really mean it, forces the screensaver on or off, for a graphical desktop session, not a root shell or a headless server. Allow about ten minutes for the read-only checks and a simple suspend-and-resume test.

The installed command here is xdg-utils 1.1.3-4.1ubuntu3 and reports itself as xdg-screensaver 1.1.3. The installed manual is labelled xdg-utils 1.0, so this guide treats the executable and its own output as the local authority where the two disagree on presentation.

You need a normal user shell inside an X desktop session for the window-related example. No command here needs sudo: running this tool as root is discouraged by its manual, because root usually does not own the desktop session it is meant to control.

1. Confirm the command and version

Start with harmless queries. None of these change the screensaver or the display:

$ command -v xdg-screensaver
/usr/bin/xdg-screensaver
$ xdg-screensaver --version
xdg-screensaver 1.1.3
$ dpkg-query -W -f='${Package} ${Version}\n' xdg-utils
xdg-utils 1.1.3-4.1ubuntu3

2. Read the current status

Run status before making a decision:

$ xdg-screensaver status
enabled

The command prints enabled when the screensaver is configured to turn on after inactivity, and disabled when it is not. This is a state query, not a test of whether the screen is currently blank or locked, and the exact answer depends on the desktop integration available to the current session.

Check the exit status when scripting it:

$ xdg-screensaver status >/tmp/xdg-screensaver-status
$ status_code=$?
$ test "$status_code" -eq 0 && cat /tmp/xdg-screensaver-status
enabled

Remove the temporary file afterwards if you do not need it. Capture output and status separately in a script: a non-zero status means the lookup failed, not that the word disabled was returned.

3. Suspend the screensaver for an existing X window

suspend stops the screensaver and monitor power management while a particular X window exists. It needs that window's X Window ID, decimal or hexadecimal beginning with 0x, and the ID must belong to an existing window of the calling application; you cannot hand it an arbitrary label or process ID.

$ xdg-screensaver suspend 0x1c00007
$ printf 'suspend exit status: %s\n' "$?"
suspend exit status: 0

The hexadecimal value above is only an example: replace 0x1c00007 with a real ID from the application you are controlling. The command can fail with exit code 4 when desktop integration cannot perform the action, and exit code 1 for invalid syntax. A successful return means the request was accepted, not that an invented or stale window ID happened to be valid.

Keep the window alive for the whole suspension. Several windows can be suspended at once, in which case every corresponding suspension must be resumed before normal screensaver operation returns.

4. Always resume the same window ID

Resume with the exact same ID used for the suspension:

$ xdg-screensaver resume 0x1c00007
$ printf 'resume exit status: %s\n' "$?"
resume exit status: 0

There is no general resume-all. If a program exits unexpectedly, its window can disappear while desktop integration still needs to reconcile the request. Re-run the resume with the recorded ID if the application can recreate the same window, then check xdg-screensaver status. If the desktop stays awake or behaves oddly, use the desktop's own power and screensaver settings to inspect the result.

For a program you write, pair the two operations across the program's lifetime and arrange cleanup on normal shutdown. Do not leave a one-off shell suspension in a startup script with no matching recovery path.

5. Understand the immediate actions before using them

These commands affect the current desktop immediately, so keep them out of unattended tests:

$ xdg-screensaver activate
$ xdg-screensaver lock
$ xdg-screensaver reset

• activate turns the screensaver on and may lock the screen according to existing policy.
• lock requests an immediate lock.
• reset turns the screensaver off immediately; if the screen is locked, the user may be asked to authenticate first.

6. Diagnose a failure without adding privileges

Ask for the built-in synopsis if you suspect a spelling or argument problem:

$ xdg-screensaver --help
xdg-screensaver - command line tool for controlling the screensaver

Synopsis

xdg-screensaver suspend WindowID
xdg-screensaver resume WindowID
xdg-screensaver { activate | lock | reset | status }

Exit code 1 reports command-line syntax errors, exit code 3 means a required helper tool could not be found, and exit code 4 means the requested action failed. These codes tell you more than repeatedly adding sudo, which can move the command into a different session and make desktop discovery less reliable.

On a Wayland-only desktop, an X Window ID may not exist for the application you have in mind, and the available backend may not support every action. Treat a failure as a desktop-integration or session problem first: check that DISPLAY and the relevant desktop session are present, then consult the desktop's native settings or lock command. An X-specific window ID cannot simply be swapped for a Wayland surface identifier.