Redirection (Eshell: The Emacs Shell)

5.2 Redirection

Redirection in Eshell is similar to that of other command shells. You can use the output redirection operators > and >>, but there is not yet any support for input redirection. In the cases below, fd specifies the file descriptor to redirect; if not specified, file descriptor 1 (standard output) will be used by default.

> dest

fd> dest

Redirect output to dest, overwriting its contents with the new output.

>> dest

fd>> dest

Redirect output to dest, appending it to the existing contents of dest.

>>> dest

fd>>> dest

Redirect output to dest, inserting it at the current mark if dest is a buffer, at the beginning of the file if dest is a file, or otherwise behaving the same as >>.

&> dest

>& dest

Redirect both standard output and standard error to dest, overwriting its contents with the new output.

&>> dest

>>& dest

Redirect both standard output and standard error to dest, appending it to the existing contents of dest.

&>>> dest

>>>& dest

Redirect both standard output and standard error to dest, inserting it like with >>> dest.

>&other-fd

fd>&other-fd

Duplicate the file descriptor other-fd to fd (or 1 if unspecified). The order in which this is used is significant, so

command > file 2>&1

redirects both standard output and standard error to file, whereas

command 2>&1 > file

only redirects standard output to file (and sends standard error to the display via standard output’s original handle).

Eshell supports redirecting output to several different types of targets:

files, including virtual targets (see below);
buffers (see Buffers in GNU Emacs Lisp Reference Manual);
markers (see Markers in GNU Emacs Lisp Reference Manual);
processes (see Processes in GNU Emacs Lisp Reference Manual); and
symbols (see Symbols in GNU Emacs Lisp Reference Manual).

Virtual Targets

5.2.1 Virtual Targets

Virtual targets are mapping of device names to functions. Eshell comes with four virtual devices:

/dev/null: Does nothing with the output passed to it.
/dev/eshell: Writes the text passed to it to the display.
/dev/kill: Adds the text passed to it to the kill ring.
/dev/clip: Adds the text passed to it to the clipboard.

You can, of course, define your own virtual targets. These are entries in eshell-virtual-targets with the form ‘(filename output-function pass-mode)’. The first element, filename, is the device name, usually of the form ‘"/dev/name"’. The second, output-function, should be a function: Eshell will repeatedly call it with the redirected output. This argument can also be an eshell-generic-target instance. In this case, Eshell will repeatedly call the generic function eshell-output-object-to-target with the output; once the redirection has completed, Eshell will then call the generic function eshell-close-target, passing non-nil if the redirected command succeeded.

If pass-mode is non-nil, then Eshell will pass the redirection mode as an argument to output-function as a symbol: overwrite for >, append for >>, or insert for >>>. In this case, output-function should return the real output function (either an ordinary function or an eshell-generic-target as described above).

Function: eshell-function-target-create output-function &optional close-function ¶: Create a new virtual target for Eshell that repeatedly calls output-function with the redirected output, as described above. If close-function is non-nil, Eshell will call it when closing the target, passing non-nil if the redirected command succeeded.