# Module `awful.spawn`

Spawning of programs.

This module provides methods to start programs and supports startup notifications, which allows for callbacks and applying properties to the program after it has been launched. This requires currently that the applicaton supports them.

Rules of thumb when a shell is needed:

- A shell is required when the commands contain `&&`, `;`, `||`, `&` or any other unix shell language syntax
- When shell variables are defined as part of the command
- When the command is a shell alias

Note that a shell is not a terminal emulator. A terminal emulator is something like XTerm, Gnome-terminal or Konsole. A shell is something like `bash`, `zsh`, `busybox sh` or `Debian ash`.

If you wish to open a process in a terminal window, check that your terminal emulator supports the common `-e` option. If it does, then something like this should work:

    awful.spawn(terminal.." -e my_command")

Note that some terminals, such as rxvt-unicode (urxvt) support full commands using quotes, while other terminal emulators require to use quoting.

Understanding clients versus PID versus commands versus class:

A process has a PID (process identifier). It can have 0, 1 or many windows.

A command if what is used to start process(es). It has no direct relation with process, client or window. When a command is executed, it will usually start a process which keeps running until it exits. This however is not always the case as some applications use scripts as command and others use various single-instance mechanisms (usually client/server) and merge with an existing process.

A client corresponds to a window. It is owned by a process. It can have both a parent and one or many children. A client has a class, an instance, a role, and a type. See client.class, client.instance, client.role and client.type for more information about these properties.

The startup notification protocol:

The startup notification protocol is an optional specification implemented by X11 applications to bridge the chain of knowledge between the moment a program is launched to the moment its window (client) is shown. It can be found on the FreeDesktop.org website.

Awesome has support for the various events that are part of the protocol, but the most useful is the identifier, usually identified by its `SNID` acronym in the documentation. It isn't usually necessary to even know it exists, as it is all done automatically. However, if more control is required, the identifier can be specified by an environment variable called `DESKTOP_STARTUP_ID`. For example, let us consider execution of the following command:

    DESKTOP_STARTUP_ID="something_TIME$(date '+%s')" my_command

This should (if the program correctly implements the protocol) result in `c.startup_id` to at least match `something`. This identifier can then be used in awful.rules to configure the client.

Awesome can automatically set the `DESKTOP_STARTUP_ID` variable. This is used by awful.spawn to specify additional rules for the startup. For example:

    awful.spawn("urxvt -e maxima -name CALCULATOR", {
        floating  = true,
        tag       = mouse.screen.selected_tag,
        placement = awful.placement.bottom_right,
    })

This can also be used from the command line:

    awesome-client 'awful=require("awful");
      awful.spawn("urxvt -e maxima -name CALCULATOR", {
        floating  = true,
        tag       = mouse.screen.selected_tag,
        placement = awful.placement.bottom_right,
      })'

Getting a command's output:

First, do not use io.popen ever. It is synchronous. Synchronous functions block everything until they are done. All visual applications lock (as Awesome no longer responds), you will probably lose some keyboard and mouse events and will have higher latency when playing games. This is also true when reading files synchronously, but this is another topic.

Awesome provides a few ways to get output from commands. One is to use the `Gio` libraries directly. This is usually very complicated, but gives a lot of control on the command execution.

This modules provides with_line_callback and easy_async for convenience. First, lets add this bash command to `rc.lua`:

    local noisy = [[bash -c '
      for I in $(seq 1 5); do
        date
        echo err >&2
        sleep 2
      done
    ']]

It prints a bunch of junk on the standard output (stdout) and error (stderr) streams. This command would block Awesome for 10 seconds if it were executed synchronously, but will not block it at all using the asynchronous functions.

with_line_callback will execute the callbacks every time a new line is printed by the command:

    awful.spawn.with_line_callback(noisy, {
        stdout = function(line)
            naughty.notify { text = "LINE:"..line }
        end,
        stderr = function(line)
            naughty.notify { text = "ERR:"..line}
        end,
    })

If only the full output is needed, then easy_async is the right choice:

    awful.spawn.easy_async(noisy, function(stdout, stderr, reason, exit_code)
        naughty.notify { text = stdout }
    end)

Default applications:

If the intent is to open a file/document, then it is recommended to use the following standard command. The default application will be selected according to the Shared MIME-info Database specification. The `xdg-utils` package provided by most distributions includes the `xdg-open` command:

    awful.spawn({"xdg-open", "/path/to/file"})

Awesome does not manage, modify or otherwise influence the database for default applications. For information about how to do this, consult the ARCH Linux Wiki.

If you wish to change how the default applications behave, then consult the Desktop Entry specification.

### Info:

- Copyright: 2008 Julien Danjou,2014 Emmanuel Lepage Vallee
- Author: Julien Danjou <julien@danjou.info>,Emmanuel Lepage Vallee <elv1313@gmail.com>

## Functions

spawn (cmd[, sn_rules=true[, callback]]) | Spawn a program, and optionally apply properties and/or run a callback.
with_shell (cmd) | Spawn a program using the shell.
with_line_callback (cmd, callbacks) | Spawn a program and asynchronously capture its output line by line.
easy_async (cmd, callback) | Asynchronously spawn a program and capture its output.
read_lines (input_stream, line_callback[, done_callback[, close=false]]) | Read lines from a Gio input stream

## Functions

Methods

spawn (cmd[, sn_rules=true[, callback]])
  Spawn a program, and optionally apply properties and/or run a callback.

  Applying properties or running a callback requires the program/client to support startup notifications.

  See awful.rules.execute for more details about the format of `sn_rules`.

  - cmd string or table The command.
  - sn_rules table or boolean A table of properties to be applied after startup; `false` to disable startup notifications. (default true)
  - callback function A callback function to be run after startup. (optional)

  ### Returns:

  1. integer The forked PID.
  2. optional string The startup notification ID, if `sn` is not false, or a `callback` is provided.

  ### Or

  string Error message.
with_shell (cmd)
  Spawn a program using the shell. This calls `cmd` with `$SHELL -c` (via awful.util.shell).
  - cmd string The command.
with_line_callback (cmd, callbacks)
  Spawn a program and asynchronously capture its output line by line.
  - cmd string or table The command.
  - callbacks Table containing callbacks that should be invoked on various conditions.
    - stdout function Function that is called with each line of output on stdout, e.g. `stdout(line)`. (optional)
    - stderr function Function that is called with each line of output on stderr, e.g. `stderr(line)`. (optional)
    - output_done function Function to call when no more output is produced. (optional)
    - exit function Function to call when the spawned process exits. This function gets the exit reason and code as its arguments. The reason can be "exit" or "signal". For "exit", the second argument is the exit code. For "signal", the second argument is the signal causing process termination. (optional)

  ### Returns:

  Integer the PID of the forked process.

  ### Or

  string Error message.
easy_async (cmd, callback)
  Asynchronously spawn a program and capture its output. (wraps spawn.with_line_callback).
  - cmd string or table The command.
  - callback Function with the following arguments
    - stdout string Output on stdout.
    - stderr string Output on stderr.
    - exitreason string Exit Reason. The reason can be "exit" or "signal".
    - exitcode integer Exit code. For "exit" reason it's the exit code. For "signal" reason — the signal causing process termination.

  ### Returns:

  Integer the PID of the forked process.

  ### Or

  string Error message.

  ### See also:

  spawn.with_line_callback
read_lines (input_stream, line_callback[, done_callback[, close=false]])
  Read lines from a Gio input stream
  - input_stream Gio.InputStream The input stream to read from.
  - line_callback function Function that is called with each line read, e.g. `line_callback(line_from_stream)`.
  - done_callback function Function that is called when the operation finishes (e.g. due to end of file). (optional)
  - close boolean Should the stream be closed after end-of-file? (default false)

generated by LDoc 1.4.6 Last updated 2017-01-20 01:17:18