Debugging Central

This page is part of the debugging series — pages with debugging details for a variety of Ubuntu packages.


Screen locking is a complex combination of many different packages, applications, and tools. Different desktop environments, such as GNOME and KDE, do not lock the screen using the same applications. This wiki page documents the screen locking process for each desktop environment.

Gnome (Ubuntu)



gnome-screensaver is the main application that starts the screensaver and displays the locked screen authentication dialog. It has an application to set preferences and has a DBus interface. It also comes with a command-line tool called "gnome-screensaver-command" that can be used to control gnome-screensaver.

gnome-screensaver supports native "themes" and xscreensaver "hacks".

The screensaver can be activated in one of the following ways: with an idle timeout or from being manually triggered by the user.

Beginning with Ubuntu 9.10 (Karmic), gnome-screensaver relies on gnome-session's idle signal, instead of using its own idle watcher. (Ref.:

GNOME Power Manager

GNOME Power Manager is a session daemon that manages, among other things, automatically blanking the screen and suspending the computer after a timeout or when the battery is low.

The screen blanking is unrelated to gnome-screensaver, and uses DPMS to actually turn the screen off. It uses a different idle timeout than the one set for the screensaver.

When GNOME Power Manager wants to put the computer into a suspend state, it performs the following steps:

  • Locks the GNOME Keyring (by default, only for hibernate. See /apps/gnome-power-manager/lock in gconf)
  • Using DBus, sends a "lock screen" signal to gnome-screensaver
  • Waits to get confirmation from gnome-screensaver that the screen is locked (with a 5 second timeout)
  • Tells DeviceKit-Power to suspend the hardware (prior to Karmic, HAL was used)

GNOME Power Manager waits for confirmation from gnome-screensaver before triggering the suspend so the hardware doesn't suspend while gnome-screensaver is fading the screen. If that happens, when the machine is resumed, the desktop will be visible for a couple of seconds before the lock screen authentication dialog appears.

Unfortunately, if gnome-screensaver is not running, or if it doesn't respond in 5 seconds, GNOME Power Manager will suspend anyway. This may result in bug reports about the desktop being visible after resume, or bug reports about resume not coming up with a locked screen.

(Ref.: src/gpm-control.c and src/gpm-screensaver.c in gnome-power-manager)

The Session Menu

indicator-applet-session is the GNOME panel applet that provides status changing, user choosing and session management. It can be used to lock the screen, or to suspend/hibernate the computer. It is a front-end to indicator-session.

When a user selects "Lock Screen" from the applet, indicator-session sends a "Lock" message to gnome-screensaver via DBus.

When a user selects "Suspend" from the applet, indicator-session does the following:

  • Using DBus, sends a "lock screen" signal to gnome-screensaver
  • Waits for 1 second
  • Tells DeviceKit-Power to suspend the hardware

(Ref.: src/session-service.c and src/lock-helper.c in indicator-session)


xdg-screensaver is part of the xdg-utils package and is a command-line tool for controlling the screensaver in a desktop environment-independent way. When running under a GNOME desktop, it acts as a wrapper around the gnome-screensaver-command utility.

"Lock Screen" gnome-panel applet

gnome-panel has an applet called "Lock Screen" that enables a user to lock the screen by clicking on it. When the applet is clicked, gnome-panel performs the following actions:

  • Checks if gnome-screensaver-command is available, or else falls back to xscreensaver-command
  • Calls the appropriate command with the "--lock" parameter

(Ref.: gnome-panel/panel-util.c in gnome-panel)

"Lock screen" keyboard shortcut (usually Ctrl-Alt-L)

gnome-settings-daemon handles the keyboard shortcuts. When the "Lock screen" keyboard shortcut is pressed, gnome-settings-daemon performs the following actions:

  • Checks if gnome-screensaver-command is available, or else falls back to xscreensaver-command
  • Calls the appropriate command with the "--lock" parameter

(Ref.: plugins/media-keys/gsd-media-keys-manager.c in gnome-settings-daemon)

Screensaver Inhibiting

Prior to Karmic, applications that wished to temporarily suspend the screensaver from coming up could periodically send the "poke" command to gnome-screensaver, either using the DBus API, or with the gnome-screensaver-command tool. This would cause gnome-screensaver to reset the idle counter, preventing it from reaching the preset value.

Beginning with Karmic, the proper way to suspend the screensaver is to use the gnome-screensaver DBus API "Inhibit" method. (Ref.: gnome-screensaver FAQ)

Unfortunately, many applications such as VLC, Mplayer and xdg-screensaver still use the "poke" command, which was deprecated and disabled in the current gnome-screensaver codebase. See the following bugs for more information:

KDE (Kubuntu)

(This section needs to be completed.)

Xfce 4 (Xubuntu, Mythbuntu)

Screen locking is handled by the xflock4 script that is a small command dispatcher to the following commands:

  • xscreensaver-command when found xscreensaver running

  • gnome-screensaver-command when found gnome-screensaver running

  • slock when available

  • xlock when the above three options failed

First found from the above will be called with the appropriate parameters.

CategoryBugSquad CategoryDebugging

DebuggingScreenLocking/HowScreenLockingWorks (last edited 2018-03-02 19:01:24 by nathanst)