XSUSPENDER(1)

📦 version 1.3, in nixpkgs unstable

💅 xsuspender(1) — like, the whole manual, bestie

okay so real talk: this is the manual page for xsuspender, from the General Commands Manual section. it's a command-line program, it's iconic, and by the end of this page you're gonna get it fr fr. 🫶

✨ NAME ✨

xsuspender — auto-suspend inactive X11 applications

like... it puts your apps to sleep when you're not looking at them. no cap.

🦋 SYNOPSIS 🦋

xsuspender

that's it. that's the whole invocation. she's low-maintenance. 💅

🌸 DESCRIPTION 🌸

okay so picture this: modern desktop GUI apps can use up a significant amount of system resources — CPU time and everything — just by sitting there idly running. like they're not even doing anything and they're still eating your CPU?? the audacity. 😭

XSuspender handles that. it respects your (very expressive) configuration and moderates those applications so they suspend all activity shortly after their windows lose focus. how? by sending them the Unix signal SIGSTOP. (or by executing a custom script — see the exec_suspend key down in CONFIGURATION 👀). then when the application window gets focus back, XSuspender sends it SIGCONT and it resumes execution exactly where it left off. slay.

the payoff is genuinely real: significant reduction in CPU use, which prolongs battery run-time (5-500%; subject to your own computing habits, bestie), reduces CPU fan noise 🍃, and stops resource-hogging applications from plotting stuff behind your back — at least while you're not actively using them. main character energy for your laptop tbh.

buuut the method also has its share of drawbacks. see BUGS below. 🙈

✨ OPTIONS ✨

the program is mainly run without arguments. she knows what to do.

  • -h, --help — print short help and exit. that's the whole list, we love a minimal queen 👑

💜 ENVIRONMENT 💜

  • G_MESSAGES_DEBUG — set G_MESSAGES_DEBUG=xsuspender and the program will report debug messages about its activity to standard error. extremely useful, iykyk 🔥
  • XDG_CONFIG_HOME — if it's set, this is the directory where the xsuspender.conf configuration file can be found. if it's missing, this location defaults to ~/.config.

🎀 FILES 🎀

  • ~/.config/xsuspender.conf — the configuration file the program reads.
  • $XDG_CONFIG_HOME/xsuspender.conf — alternative configuration file, used when that variable is set.
  • share/doc/xsuspender/examples/xsuspender.conf — example configuration file shipped with the program. go peek, it's giving tutorial 🦋
  • etc/xdg/autostart/xsuspender.desktop — a desktop session auto-start launcher. disabled by default. to enable it, copy it into the ~/.config/autostart directory (or $XDG_CONFIG_HOME/autostart where applicable) and edit it, setting Hidden=false. alternatively, you may be able to enable it via the session application auto-start manager. your call bestie ✨

👑 CONFIGURATION 👑

the configuration key-value file is in INI format. notice, please and thank you:

  • the file must be encoded in UTF-8
  • comments follow the # character
  • section and key names are case-sensitive (so don't get cute with the caps)

the file should contain a [Default] section which all other sections inherit and override on a per-key basis. very inheritance, very chic.

each non-[Default] section constitutes a rule that XSuspender will try to match and follow. sections can define the following keys (listed with their built-in default values, if any):

  • match_wm_name_contains, match_wm_class_contains, match_wm_class_group_contains — these keys order xsuspender to apply the rule only to windows that contain the verbatim value string in their WM_NAME and WM_CLASS window manager hints. when multiple matching keys are specified, their logical conjunction (intersection) applies — meaning yes, all of them gotta match. to find applicable values, run:
xprop -notype WM_NAME WM_CLASS

and click on the window of interest. class group is the second string in the WM_CLASS atom. iykyk 💅

  • suspend_delay = 10 — integer seconds to wait after the window loses focus before suspending it. setting a reasonable value avoids suspending processes too early during rapid task switching (we all alt-tab like maniacs, it's fine). if you set this value too low, upon process termination the process may stall in its termination routine if it hasn't been able to finish in time. and since we're unable to detect this — yeah — best give your processes ample time. be generous, she deserves it 🫶
  • resume_every = 50 — resume the suspended process every this many integer seconds to have it do (some of) its backlog of work. little stretch break, love that for them ✨
  • resume_for = 5 — resume the suspended process only for this long before suspending it again. blink and it's back to sleep 😴
  • only_on_battery = true — apply the rule only when on battery power. you may wish to set this to false for hopelessly annoying processes such as virtual machines running Windos. (their spelling, not mine 💀)
  • auto_suspend_on_battery = true — if true, automatically apply this rule when switching to batter power, even if the matching window didn't just lose focus (but lost it some time before). yes the original says "batter". we respect the typo 🍓
  • suspend_subtree_pattern — extended regular expression. if provided, when XSuspender suspends a process, it will also suspend all its descendant processes (children, grandchildren etc.) whose command-line string matches the pattern. set it to . to match and kill all descendants. this setting only applies when send_signals is also true.
  • exec_suspend, exec_resume — before suspending / resuming the process, execute the string as a command-line shell script. if the script execution is successful (exit status 0), proceed with process suspension, otherwise abort it. (process resumption is never aborted.) the executed script gets passed via the environment the following variables: PID (process id), XID (X11 window id of the triggering window), and WM_NAME (window title). you can use these keys to control suspension of your processes or disjoint components thereof in a custom way. in this case, you may also find the send_signals key to be of use. very DIY, very build-a-bear 🧚
  • send_signals = true — if true, XSuspender kills the matching process with SIGSTOP / SIGCONT Unix signals. if false, XSuspender sends no signals of its own, deferring to custom exec_suspend and exec_resume scripts to do the work. you're in charge now 👑
  • downclock_on_battery = 0 — set to greater than zero to decrease the CPU time allotted to the matching process when running on battery power. for every one time slice running, the process sleeps for this many slices. thus, a value 1 decreases the CPU consumption of the process by 50%, a value of 2 by 66%, a value of N by N/(N+1)%, and so on. a value of 0 disables downclocking. this is a separate, stand-alone mechanism that limits CPU consumption of — also and in particular — focused windows. math ate, ngl 🔥

💀 BUGS 💀

the following limitations and quirks are known (read this part, bestie, it matters):

  • don't configure XSuspender for software you want to keep continuously alive in the background, such as music players and daemons. if you suspend IM clients, wake them up frequently (configuration key resume_every) so they can process their queued network events. if you like to stream music from YouTube or similar, you might want to exempt your browser from suspension, or consider using a lighter-weight native client, such as Musictube. 🎵
  • windows that minimize to system tray, such as torrent and IM clients, need to be resumed frequently to respond to tray icon click events in a seamless manner. no one likes a laggy tray icon 🙈
  • pasting from clipboard is prevented while the selection source process is suspended. mitigate by using a clipboard manager that takes ownership of the selection. (this one bites people, fr fr.)
  • suspended windows might not redraw until regaining focus. if something covers them, expect visual artifacts. that's just how it is 💅
  • mouse-wheel scrolling might not work in suspended windows. they require keyboard input focus to resume.
  • processes that take a long time to shut down after their window already disappears may be stopped in the middle of their termination routines. avoid with a reasonably generous suspend_delay. ⚠️
  • XSuspender won't work in remote X sessions.
  • XSuspender won't work with Wayland. (sorry wayland girlies 😭)

please raise any further bugs and ideas on the project's GitHub issue tracker. we love feedback 🫶

🌈 EXAMPLE 🌈

here's an example configuration section for VirtualBox — steal it, it's cute:

# This is a comment.

[Default]
suspend_delay = 10
resume_every = 50
resume_for = 5
only_on_battery = true
auto_suspend_on_battery = true
send_signals = true

# Rule name is an alphanumeric string.
# Rule VirtualBox inherits from Default rule

[VirtualBox]
match_wm_class_contains = VirtualBox

# VirtualBox suspension is managed by VBoxManage utility.
send_signals = false

# We get the VM UUID via its process command line.
# NOTE: Unlike in this example, the whole script should be
# on a single line.
exec_suspend = VBoxManage controlvm "$(ps -o args= -q $PID | \
               sed -E 's/.*--startvm ([a-f0-9-]+).*/\1/')" pause
exec_resume  = VBoxManage controlvm "$(ps -o args= -q $PID | \
               sed -E 's/.*--startvm ([a-f0-9-]+).*/\1/')" resume

find further examples in the example configuration file accompanying this distribution (see section FILES above). ✨

and to debug your configuration rules, run this:

G_MESSAGES_DEBUG=xsuspender xsuspender

honestly that one command will save you so much time. you're welcome 💖

🦋 SEE ALSO 🦋

kill(1), xprop(1), regex(7), signal(7)

okay that's the whole page, you made it to the end!! 🎉 this has been xsuspender(1) from the General Commands Manual, dated 2017-12-13 — yes she's an older icon but she still serves. go suspend something, have fun, hydrate, and remember: don't suspend your music player 💅✨🎀

📦 where this page comes from