XDG-ASSIST(1)

📦 version 1.12, in nixos 26.05, nixpkgs unstable

okay so bestie, welcome to the manual page for xdg-assist 💖 — it lives in the User Commands section, and it's all about startup-notification assist for window managers and clients.

✨ NAME ✨

xdg-assist — startup-notification assist window managers and clients 🫶

🦋 SYNOPSIS 🦋

xdg-assist [OPTIONS]

🎀 DESCRIPTION 🎀

xdg-assist is a "C"-language daemon process that assists light-weight window managers and non-conforming clients with startup-notification and EWMH support. It is a background process that should be started before the window manager or any other client. 💅

🌈 OPTIONS 🌈

The options detailed below are recognized by xdg-assist. It uses getopt_long_only(3), so unambiguous abbreviations of long options and long options with a single dash are also supported. ✨

xdg-assist supports these options:

💅 COMMAND OPTIONS 💅

The default is to start xdg-assist and daemonize it (placing it in the background). 👑

  • -a, --assist — (the original page shows this one bracketed as [-a, --assist]) Run as a startup notification assistant. This is the default if no other command option is specified. Only one instance of xdg-assist can run as a launch assistant. 🎀
  • -r, --replace — Restart xdg-assist by replacing the existing running launch assistant with the current one. 🔁
  • -q, --quit — Asks a running xdg-assist launch assistant process to stop. 🛑
  • -m, --monitor — Normally xdg-assist will run a single instance as a launch assistant. This option requests that xdg-assist provide monitoring of startup notification only and that it not provide any assistance. This is useful for running xdg-assist with debugging and verbosity set high to observe and debug the startup notification process, so the debug and output levels are set to three (3). Any number of instances can be run at the same time. The --quit option will not cause a monitor process to quit. 👀
  • -h, --help — Prints usage information to standard output and exits. 💖
  • -V, --version — Prints detailed version information and exits. ⭐
  • -C, --copying — Prints detailed copying permissions and exits. 📜

🌸 GENERAL OPTIONS 🌸

  • -g, --guard TIMEOUT — Specifies the amount of time, TIMEOUT, in milliseconds, that xdg-assist will wait for a desktop application to launch. The default is 15000 milliseconds (15 seconds). ⏳
  • -v, --verbose [LEVEL] — Print diagnostic information to standard error during operation. This option can be repeated to increase the verbosity of output. The default level is 1. 🗣️
  • -D, --debug [LEVEL] — Prints debugging information to standard error during operation. This option can be repeated to increase the debugging level. The default level is 0. 🐛

🦋 USAGE 🦋

The primary purpose of the xdg-assist program is to support window managers and clients for launchers other than xdg-launch(1). xdg-launch(1) can provide its own startup notification monitoring and completion in a superior fashion to xdg-assist. Why? Because xdg-launch(1) runs on the same host as the launched process, whereas xdg-assist may not be running on the same host that launched and is running the process. 👀

Nevertheless, it is advantageous to start xdg-assist(1) and run it as a background process before the window manager starts. An XDG autostart .desktop file is provided for this purpose. When xdg-assist detects a window manager that supports startup notification completion, it will exit with a zero exit status. ✨

A window manager that supports startup notification completion is one that supports NetWM/EWMH and lists _NET_STARTUP_ID, _NET_STARTUP_INFO_BEGIN and _NET_STARTUP_INFO in _NET_SUPPORTED. 💅

🧚 BEHAVIOUR 🧚

Non-startup-notification aware clients and window managers are assisted when xdg-assist is running and it detects that the window manager does not support full startup notification. 🫶

When running and when xdg-assist detects that the client or window manager does not support startup notification (or cannot decide one way or the other), xdg-assist will perform the following actions:

  1. xdg-assist runs a launch assistant process. This process will run until killed, or stopped using the --quit or --replace options on another invocation. 💀
  2. xdg-assist monitors for startup notification messages and collects outstanding startup notification sequences. 📨
  3. xdg-assist monitors for the appearance of a window manager and assesses the capabilities of the window manager. When the window manager supports startup notification completion, xdg-assist exits with a zero exit status. 🏁

Window managers that support startup notification completion are NetWM/EWMH compliant window managers that list atoms _NET_STARTUP_ID, _NET_STARTUP_INFO_BEGIN and _NET_STARTUP_INFO in their supported atoms list, _NET_SUPPORTED.

  1. xdg-assist monitors for the appearance of new top-level and client windows. 🪟
    • For EWMH/NetWM compliant window managers, this can be determined using the _NET_CLIENT_LIST property on the root window of the screen on which the client is launching. 🖥️
    • For WMH/WinWM compliant window managers, this can be determined using the _WIN_CLIENT_LIST property on the root window. 🪞
    • For ICCCM compliant window managers, the appearance of a WM_STATE property on a top-level window with a state other than "WithdrawnState" can be used. 📌
  2. When a definitive match can be made from the properties of the mapped window, xdg-launch will populate the following properties unless otherwise populated by the client or window manager:
okay so yes, bestie — the original page literally says xdg-launch in this step, not xdg-assist; I'm keeping it exactly as printed. No cap. 😭
  • _NET_STARTUP_ID — This property will be populated with the startup id of the launched desktop application when it is missing. (Very few applications in fact populate this property: not because their toolkits do not support it, but because the facility of the toolkit has not been invoked.) Note that the GTK2 toolkit always places this property on its leader window when the DESKTOP_STARTUP_ID environment variable is present at startup (this is part of gtk_ini()). 🪪
  • _NET_WM_USER_TIME — This property will be populated with the time stamp, unless it already exists. ⏱️
  • _NET_WM_PID — This property will be populated with the launched process id. 🆔
  • _NET_WM_DESKTOP, _WIN_WORKSPACE, _DT_WORKSPACE_PRESENCE — These properties will be populated with the desktop for the launched application unless this property was set by the client (and not the window manager). If the property was not set by the client but was set by the window manager and it does not match the value requested during launch, xdg-launch will send the appropriate client messages to effect the transfer. 🗂️
  • WM_NAME, _NET_WM_NAME, _NET_WM_VISIBLE_NAME — When none of these properties are present, xdg-launch will populate them from the "NAME=" field of the startup notification sequence. 📛
  • WM_ICON, _NET_WM_ICON, _KDE_NET_WM_ICON — When none of these properties are present, xdg-assist will populate them from the "ICON=" field of the startup notification sequence. 🖼️
  • _NET_WM_FULLSCREEN_MONITORS — This property will be populated with the monitor number on which the desktop application was to launch. If the client has already mapped, a client message to change the value will be sent to the root window when the window manager supports such things. 🖥️
  • WM_HINTS — If the client window has mapped on the incorrect monitor, and the client has not specified the initial location using WM_HINTS, xdg-launch will unmap the window, set the WM_HINTS property for the appropriate monitor, and remap the window. 🪄
  • WM_COMMAND — This property will be populated with the command and arguments of the launched process, unless otherwise populated. 🧾
  • WM_CLIENT_MACHINE — This property will be populated with the fully qualified host name even when populated by the client. 🖥️
  1. xdg-assist monitors for the creation and removal of process ids (using inotify(7) on the /proc file system). It performs startup notification completion on process ids that are removed or which perform an execve(3) or related function that changes the current executable, and command arguments. 🔍

xdg-assist can also monitor when process ids appear that have a specified DESKTOP_STARTUP_ID variable in their environment. (This is provided that the appearing process is run as the same user as was xdg-assist.) 👯

🌟 ENVIRONMENT 🌟

The following environment variables are examined by xdg-assist, both in its own environment as well as in the environments of monitored processes:

  • DISPLAY — Used by xdg-assist to determine the X display and default screen on which it has been invoked. 🖥️
  • DESKTOP_STARTUP_ID — Used by xdg-assist at program startup to determine whether it itself has been launched with startup notification. The DESKTOP_STARTUP_ID is removed from the environment in this case and a startup notification "remove:" message is issued to complete its own startup. 🫧

xdg-assist also monitors for this environment variables in processes to which it has access to match appearing processes with startup notification. A client that properly supports desktop startup notification will remove this environment variable from its environment at startup. One that ignores the environment variable will not remove it. 👀

💀 BUGS 💀

xdg-assist has no known bugs. Please report bugs to the source code repository at https://github.com/bbidulock/xdg-launch/issues. 🐛

🌈 SEE ALSO 🌈

👑 AUTHOR 👑

Brian Bidulock <mailto:bidulock@openss7.org> 💖

💜 that's the whole page, bestie — source/version xdg-launch 1.12, dated 2022-01-28, manual page XDG-ASSIST(1). 🫶

📦 where this page comes from