XDG-LAUNCH(1)

NAME
xdg-launch - an XDG compliant startup notification launcher

SYNOPSIS
xdg-launch [OPTIONS] [APPID [FILE|URL]]

xdg-launch [OPTIONS] -c command and arguments

DESCRIPTION
xdg-launch is a "C" language program that can be used to launch XDG desktop applications with startup notification.

ARGUMENTS
The program accepts the following arguments:

APPID
    Specifies the application identifier of an XDG desktop application to launch. The application identifier, APPID, can be one of the following:

    1.  the name of a desktop entry file without the .desktop suffix (e.g. "gvim");

    2.  the name of a desktop entry file with the .desktop suffix (e.g. "gvim.desktop"); or,

    3.  the full path (absolute or relative) and filename of a desktop entry file (e.g. /usr/share/applications/gvim.desktop).

    Providing a non-option application identifier argument is mandatory unless the --exec or --appid options are specified.

FILE
    Specifies the file name with which to launch the application. This is used in %f substitutions in the "Exec" field of the XDG desktop entry file or --exec command line. This may also be Specified with the --file option.

URL Specifies the URL with which to launch the application. This is used in %u substitutions in the "Exec" field of the XDG desktop entry file or --exec command line. This may also be specified with the --url option.

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

  COMMAND OPTIONS
The default is to launch the application specified by "APPID". When any of the following options are specified, the command mode changes:

-c, --command command arguments
    When specified, this option must be the last option on the command line. Options processing stops abruptly at this option and remaining arguments are considered to be the command and the command arguments to execute. xdg-launch will execve(3) the arguments under startup notification control in a similar fashion to "sh -c".

-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.

  CONFIGURATION OPTIONS
The following are primary configuration options:

-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.

  LAUNCH OPTIONS
The following options affect the parameters of the startup notification "new" message that is sent for launch:

-L, --launcher LAUNCHER
    Specifies the string that will be used as the launcher when generating a startup notification identifier. The default is the name of this program (i.e. "xdg-launch").

-l, --launchee LAUNCHEE
    Specifies the string that will be used as the launcher when generating a startup notification identifier. The default is the application identifier.

-n, --hostname HOSTNAME
    Specifies the host name that will be used when generating a startup notification identifier. The default, when unspecified, is the result of "hostname -f".

-m, --monitor MONITOR
    Specifies the monitor, MONITOR, on which the XDG application, APPID, is to launch. When unspecified, the monitor currently containing the pointer is used. MONITOR must be numerical zero-based index of the desired monitor. This value is placed in the "MONITOR" key-value entry in the startup notification "new" message. No value will be placed when Xinerama (or RANDR) is not active for the display, or for single-screen Xinerama (or RANDR) setups ("SCREEN" is used in this case). See "Multiple Monitors", below.

-s, --screen SCREEN
    Specifies the screen, SCREEN, on which the XDG application, APPID, is to launch. When unspecified, the screen containing the pointer used. For single-screen Xinerama (or RANDR) setups, the value of MONITOR is used for SCREEN. SCREEN must be the numerical zero-based index of the desired screen. This value is placed in the SCREEN key-value entry in the startup notification "new" message. No value will be placed when there is a single screen, and Xinerama (or RANDR) is not active for the display. See "Multiple Screens", below.

-w, --workspace DESKTOP
    Specifies the desktop, DESKTOP, on which the XDG application is to launch. The default, when unspecified, is the current desktop for the screen, SCREEN. This value is placed in the "DESKTOP" key-value entry in the startup notification "new" message.

-t, --timestamp TIMESTAMP
    Specifies an X Server time stamp that corresponds to the X window event that caused the launch to occur. This is only useful in conjunction with specification of an APPID argument. When the time stamp is not specified, xdg-launch will use the time of the last event (or generate an event) for the time stamp. The resulting time stamp (whether specified or not) is used in the "_TIME" portion of the startup notification identifier, as well as the "TIMESTAMP" key-value entry in the startup notification "new" message.

-N, --name NAME
    Specify the name of the XDG application. This overrides the "Name" field from the XDG desktop entry file. When unspecified, the default is the "Name" field from the XDG desktop entry file. This value, when available, is placed in the "NAME" key-value entry in the startup notification "new" message.

-i, --icon ICON
    Specifies the icon name of the XDG application, ICON. This overrides the "Icon" field from the XDG desktop entry file. When unspecified, the default is the "Icon" field from the XDG desktop entry file. This value, when available, is placed in the "ICON" key-value entry in the startup notification "new" message.

-b, --binary BIN
    Specifies the name of the binary for the XDG application, BIN. This overrides the "TryExec" and "Exec" fields from the XDG desktop entry file. When unspecified, default is the "TryExec" field, or the "argv[0]" option of the "Exec" field, from the XDG desktop entry file. This value, when available, is placed in the "BIN" key-value entry in the startup notification "new" message.

-D, --description DESCRIPTION
    Specifies the description of the XDG application, DESCRIPTION. This overrides the "Comment" field from the XDG desktop entry file. When unspecified, the default is to use the "Comment" field from the XDG desktop entry file, or a descriptive sequence such as "Staring Name". This value, when available, is placed in the "DESCRIPTION" key-value entry in the startup notification "new" message.

-W, --wmclass WMCLASS
    Specify the window manager class (matched against the "res_name" or "res_class" of the "WM_CLASS" property on a window), of the top-level window that the XDG application is expected to map. This overrides the "StartupWMClass" field of the XDG desktop entry file. When unspecified, the default is the "StartupWMClass" field of the XDG desktop entry file. This value, when available, is placed in the "WMCLASS" key-value entry in the startup notification "new" message.

-q, --silent SILENT
    Specify a boolean value (0/1) choosing whether visual feedback should be provided for the launching XDG application, SILENT. Normally, when unspecified, visual feedback would be determined from the presence of a value of a "StartupNotify" or "StartupWMClass" field in the XDG desktop entry file. The SILENT argument should be some boolean value like 0 or 1 or "yes" or "no" or "true" or "false". The default when unspecified is to determine the value from the other fields of the XDG desktop entry file. This value, when available, is placed in the "SILENT" key-value entry in the startup notification "new" message.

    When unspecified, the "SILENT" argument to the startup notification message is set when the XDG desktop entry has neither a "StartupNotify" nor a "StartupWMClass" field, or it only has a "StartupNotify" field but it is set to false.

-p, --pid PID
    Specifies the process identifier for the launch sequence. The default is the process identifier of the xdg-launch program.

-a, --appid APPLICATION_ID
    Override the application identifier. This overrides the name of the XDG application file. When unspecified, the default is to use the non-option APPID argument to determine the application identifier. This value, when available, is placed in the "APPLICATION_ID" key-value entry in the startup notification "new" message.

-x, --exec COMMAND
    Specifies the command to execute. This overrides the "Exec" field of the XDG desktop entry file. When unspecified, the default is the "Exec" field of the XDG desktop entry file.

-f, --file FILE
    Specifies a filename, FILE, to be substituted into the XDG desktop entry "Exec" command in accordance with XDG desktop entry specifications. The default is to use the non-option FILE argument, or no filename. When --url or URL is specified as a file:// URL, this option defaults to the URL with the file: portion removed.

-u, --url URL
    Specifies a URL, URL, to be substituted into the XDG desktop entry "Exec" command in accordance with XDG desktop entry specifications. The default is to use the non-option URL argument, or no URL. When --file or FILE is specified, this option defaults to the FILE with a file:// portion prefixed.

-P, --pointer
    When specified, xdg-launch will determine the screen or monitor from the current location of the pointer. This option should be used when xdg-launch is invoked from a menu or mouse binding. This option has no effect on the screen when the screen was specified using either the DISPLAY environment variable or the --screen option. This option has no effect on the monitor when the --monitor option is also specified.

-K, --keyboard
    When specified, xdg-launch will determine the screen or monitor from the location of the window with the current keyboard focus. This option should be used when xdg-launch is invoked from a command line or keyboard binding. This option has no effect on the screen when the screen was specified using either the DISPLAY environment variable or the --screen option. This option has no effect on the monitor when the --monitor option is also specified.

-A, --assist
    Assist a window manager that is not startup-notification aware. The default is to automatically determine whether the window manager needs assistance and provide it when needed.

BEHAVIOUR
xdg-launch exhibits the following behaviour:

  TIME STAMPS
xdg-launch is intended on being invoked directly from a user interface, such as the root menu of a light-weight window manager, or an X windows application such as a system tray menu. To perform proper startup notification, xdg-launch determines the X server time stamp of the invocation as follows:

1.  When xdg-lanuch is invoked directly (executed) from an application that has access to the X server event that invoked the launch, it can supply the X server time stamp directly to xdg-launch using the --timestamp option (see "OPTIONS"). xdg-launch will use this time stamp in the generation of the DESKTOP_STARTUP_ID as well as the "TIMESTAMP" key-value pair in the startup notification "new" message.

2.  When xdg-launch is invoked by an application that does not have access to the X event that invoked the launch, xdg-launch will change the _TIMESTAMP_PROP property on the root window to obtain a time stamp. In this way, xdg-launch can simply be executed using the execute mechanism of a light-weight window manager root menu or key binding.

3.  When xdg-launch is invoked by another startup notification launcher, it will obtain the time stamp (and other information) from the DESKTOP_STARTUP_ID environment variable.

  MULTIPLE HEADS
xdg-launch fully supports multiple heads (screens) and Xinerama (or RANDR) multiple physical monitors per screen.

Multiple Screens

When there are multiple screens, some window managers will adjust the DISPLAY environment variable to include the screen number for launched applications. For example, if the window manager DISPLAY environment variable is ":7" and a program is launched on screen 1, the program will be launched with a DISPLAY environment variable of ":7.1". Therefore, when xdg-launch detects a screen number in its DISPLAY environment variable, the screen used will be that specified in the environment variable, unless the --keyboard, --pointer or --screen options are specified. When xdg-launch launches the ultimate desktop application, it adjusts the DISPLAY environment variable to include the screen. As most applications launch on the default screen, this manages to get the desktop application to launch on the correct screen.

Multiple Monitors

xdg-launch detects Xinerama and RANDR multiple monitor setups. When the --keyboard or --pointer options are specified, xdg-launch determines the monitor number from the keyboard focus window or pointer location. This monitor number is placed in the "MONITOR=" field of the startup notification "new" message. However, launched desktop applications have no way of determining information outside of the DESKTOP_STARTUP_ID with which they were launched (the screen number can be obtained from the DISPLAY environment variable). The DESKTOP_STARTUP_ID is formatted (ala libstartup-notification) as follows:

    %s/%s/%d-%d-%s_TIME%lu

Where the fields are the launcher, launchee, pid, sequence, host and timestamp. The sequence number is of no use to the application and it is also of no use to xdg-launch because the PID changes with each invocation. Therefore, when the launcher is xdg-launch, the application (or window manager) can use the sequence field as the monitor index.

  WINDOW MANAGERS
xdg-launch interacts with window managers in the following ways:

1.  xdg-launch creates startup notification identifiers using the technique from the libstartup-notification library. This consists of the following:

        while((p = strchr(launcher, '/'))) *p = '|';
        while((p = strchr(launchee, '/'))) *p = '|';
        sprintf(id, "%s/%s/%d-%d-%s_TIME%lu",
            launcher, launchee, getpid(), monitor,
            hostname, timestamp);

    Compliant applications will place the startup notification identifier from the DESKTOP_STARTUP_ID environment variable in the _NET_STARTUP_ID property on its group leader top-level window before it is mapped. The window manager can use the "_TIME%lu" portion of the startup identifier to determine the X server time stamp for the event that launched the application. When the client does not set an initial _NET_WM_USER_TIME, this time stamp can be used in its stead. It can also use the "/%d-" portion of the startup identifier to determine the process identifier, the "-%d-" portion to determine the monitor on which to start the application, and the "-%s_TIME" portion of the identifier to determine the host name of the launching machine.

2.  Window managers that monitor startup notification messages may also use the "TIMESTAMP=" key-field entry in the "new:" message for this purpose, particularly when the "WMCLASS=" field matches the resource name or class of a newly mapped top-level window.

3.  xdg-launch neither changes nor removes the startup notification sequence and is only responsible for issuing in the "new:" or "change:" message. The window manager or desktop environment should issue a "remove:" message when it first manages a top-level window with a resource name or class than matches the "WMCLASS=" field of an outstanding "new:" message.

4.  Window managers that monitor startup notification messages and associates them with managed top-level windows may use the following fields to populate missing properties on those windows:

    "ID="
        The window manager may use this field to populate the _NET_STARTUP_ID property on the window (group) when it is missing.

    "HOSTNAME="
        The window manager may use this field to populate the WM_CLIENT_MACHINE property when it is missing or is not a fully qualified domain name. This field can also be derived from the "ID=" field.

    "PID="
        The window manager may use this field to populate the _NET_WM_PID property when it is missing. This field can also be derived from the "ID=" field.

    "MONITOR="
        The window manager may use this field to choose the Xinerama (or RANDR) screen on which the top-level window (group) will be mapped. It may also be used to populate the _NET_WM_FULLSCREEN_MONITORS property when it is missing.

    "SCREEN="
        The window manager may use this field to choose the Xinerama (or RANDR) or multi-head screen on which the top-level window (group) will be mapped. When it specifies a Xinerama (or RANDR) screen, it may also be used to populate the _NET_WM_FULLSCREEN_MONITORS property when it is missing.

    "DESKTOP="
        The window manager may use this field to populate the _NET_WM_DESKTOP, _WIN_WORKSPACE, or _DT_WORKSPACE_PRESENCE property when missing or otherwise unspecified.

    "TIMESTAMP="
        The window manager may use this field to populate the _NET_WM_USER_TIME property when it is missing. This field can also be derived from the "ID=" field.

    "NAME="
        The window manager may use this field to populate the WM_NAME, _NET_WM_NAME, or _NET_WM_VISIBLE_NAME properties when they are missing or empty.

    "ICON="
        The window manager may use this field to establish an icon for the window when the WM_ICON, _NET_WM_ICON or _KDE_NET_WM_ICON properties are missing or otherwise unusable.

    "WMCLASS="
        The window manager may use this field to associate a startup notification sequence with a newly mapped top-level window.

    "COMMAND="
        The window manager may use this field when the WM_COMMAND field is missing (and for the same purposes). Because rather complicated shell expansion would be required to expand the command, it cannot be used to populate the WM_COMMAND property; however, it may be executed by passing it literally as a shell command. I suppose one could populate WM_COMMAND with "sh", "COMMAND" if necessary.

5.  Window managers that are not startup notification aware will be automatically assisted in performing startup notification completion. When it is detected that assistance is required, xdg-launch will fork a background process to monitor for startup completion.

    It can be detected whether an EWMH compliant window manager performs startup notification completion by the presence or absence of the _NET_STARTUP_ID atom in the _NET_SUPPORTED list of atoms. Non-EWMH compliant window managers are assumed to not support startup notification.

  WM/CLIENT ASSISTANCE
Non-startup-notification aware clients and window managers can be assisted using the --assist command line option or when xdg-launch detects that the window manager does not support startup notification.

When the --assist command line option is specified, or when xdg-launch detects that the client or window manager does not support startup notification (or cannot decide one way or the other), xdg-launch performs the following actions:

1.  xdg-launch forks a monitoring process that is a proper child of the launched process. This is so that if the launched process exists, the monitoring process also exits.

2.  The monitoring process monitors for the appearance of a client window.

    •   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.

3.  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:

    _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.)

    _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.

ENVIRONMENT
The following environment variables are examined by xdg-launch:

DISPLAY
    Use by xdg-launch to determine the X display and default screen On which it has been invoked.

DESKTOP_STARTUP_ID
    Used by xdg-launch at program startup to determine whether it itself has been launched with startup notification. The DESKTOP_STARTUP_ID is reused in this case. This environment variable is set to the startup notification identifier just prior to executing the launched program.

LANG
    Used by xdg-launch at program startup to determine the language to use to select the language for "Name=" and "Comment=" fields from the desktop entry file.

HOME
    Used by xdg-launch to determine the user's home directory.

XDG_DATA_HOME
    Used by xdg-launch to determine the user's XDG data directory. This defaults to $HOME/.local/share. The applications subdirectory under this directory is the first searched to locate desktop entry files. See the XDG Desktop Entry file specification for more information.

XDG_DATA_DIRS
    Used by xdg-launch to determine the system XDG data directories. This defaults to /usr/local/share:/usr/share. The applications subdirectory under these directories are searched in order to locate desktop entry files. See the XDG Desktop Entry file specification for more information.

AUTHOR
Brian Bidulock <bidulock@openss7.org>