Control the Desktop Screensaver Safely with xdg-screensaver

You will use xdg-screensaver to check whether the screensaver is enabled, suspend it for an existing X window, restore it, and deliberately activate or lock the screen when needed. The commands are intended 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 output as the local authority where they differ in presentation.

You need a normal user shell inside an X desktop session for the window-related example. No command in this guide 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. They do not 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

Checkpoint: if command -v prints nothing, stop and install or repair xdg-utils through your normal package-management process. Do not copy a script from an unrelated host just to make the command name resolve.

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. 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 after reading it if you do not need it. In a script, capture the output and status separately. A non-zero status means the action or lookup failed; it does not mean that the word disabled was returned.

3. Suspend the screensaver for an existing X window

suspend prevents the screensaver and monitor power management while a particular X window exists. It requires that window's X Window ID, written as decimal or as hexadecimal beginning with 0x. The ID must belong to an existing window of the calling application, so this is not a command that can accept an arbitrary label or process ID.

If your application already documents its window ID, use that value directly:

$ 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 may fail with exit code 4 when the desktop integration cannot perform the action, and exit code 1 for invalid command-line syntax. A successful return means the request was accepted, not that an invented or stale window ID was valid.

Keep the window alive for the whole suspension. The screensaver can also be suspended against several windows at once. In that case, every corresponding suspension must be resumed before normal screensaver operation is restored.

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 command in this interface. If a program exits unexpectedly, its window may disappear while the desktop integration still needs to reconcile the request. Re-run the resume operation with the recorded ID if the application can recreate the same window, then check xdg-screensaver status. If a desktop remains awake or behaves unexpectedly, use the desktop's own power and screensaver settings to inspect the resulting state.

For a program you write, pair the two operations in the program's lifetime and arrange cleanup on normal shutdown. Do not leave a one-off shell suspension in a startup script without a 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.

Do not paste these three commands into a deployment hook or a remote session unless an interrupted display is an acceptable result. A lock or activation can disrupt someone using the workstation. The undo for activate or lock is normally to authenticate and return to the desktop, or to use reset where the desktop permits it. The command does not bypass the desktop's authentication policy.

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. Exit code 4 means the requested action failed. These codes are more useful 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 xdg-utils 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. Do not assume that an X-specific window ID can be substituted with a Wayland surface identifier.