# Redirection

!!! warning "FIXME"
    To be continued

Redirection makes it possible to control where the output of a command
goes to, and where the input of a command comes from. It's a mighty
tool that, together with pipelines, makes the shell powerful. The
redirection operators are checked whenever a [simple command is about to
be executed](../syntax/grammar/parser_exec.md).

Under normal circumstances, there are 3 files open, accessible by the
file descriptors 0, 1 and 2, all connected to your terminal:

|Name|FD|Description|
|----|--|-----------|
|`stdin`|0|standard input stream (e.g. keyboard)|
|`stdout`|1|standard output stream (e.g. monitor)|
|`stderr`|2|standard error output stream (usually also on monitor)|



!!! info "INFO"
    The terms "monitor" and "keyboard" refer to the
    same device, the **terminal** here. Check your preferred UNIX(r)-FAQ for
    details, I'm too lazy to explain what a terminal is ;-)

Both, `stdout` and `stderr` are output file descriptors. Their
difference is the **convention** that a program outputs payload on
`stdout` and diagnostic- and error-messages on `stderr`. If you write a
script that outputs error messages, please make sure you follow this
convention!

Whenever you **name** such a filedescriptor, i.e. you want to redirect
this descriptor, you just use the number:

    # this executes the cat-command and redirects its error messages (stderr) to the bit bucket
    cat some_file.txt 2>/dev/null

Whenever you **reference** a descriptor, to point to its current target
file, then you use a "`&`" followed by a the descriptor number:

    # this executes the echo-command and redirects its normal output (stdout) to the standard error target
    echo "There was an error" 1>&2

The redirection operation can be **anywhere** in a simple command, so
these examples are equivalent:

    cat foo.txt bar.txt >new.txt
    cat >new.txt foo.txt bar.txt
    >new.txt cat foo.txt bar.txt

!!! info "important"
    Every redirection operator takes one or two
    words as operands. If you have to use operands (e.g. filenames to
    redirect to) that contain spaces you **must** quote them!

## Valid redirection targets and sources

This syntax is recognized whenever a `TARGET` or a `SOURCE`
specification (like below in the details descriptions) is used.

|Syntax|Description|
|------|-----------|
|`FILENAME`|references a normal, ordinary filename from the filesystem (which can of course be a FIFO, too. Simply everything you can reference in the filesystem)|
|`&N`|references the current target/source of the filedescriptor `N` ("duplicates" the filedescriptor)|
|`&-`|closes the redirected filedescriptor, useful instead of `> /dev/null` constructs (`> &-`)|
|`/dev/fd/N`|duplicates the filedescriptor `N`, if `N` is a valid integer|
|`/dev/stdin`|duplicates filedescriptor 0 (`stdin`)|
|`/dev/stdout`|duplicates filedescriptor 1 (`stdout`)|
|`/dev/stderr`|duplicates filedescriptor 2 (`stderr`)|
|`/dev/tcp/HOST/PORT`|assuming `HOST` is a valid hostname or IP address, and `PORT` is a valid port number or service name: redirect from/to the corresponding TCP socket|
|`/dev/udp/HOST/PORT`|assuming `HOST` is a valid hostname or IP address, and `PORT` is a valid port number or service name: redirect from/to the corresponding UDP socket|

If a target/source specification fails to open, the whole redirection
operation fails. Avoid referencing file descriptors above 9, since you
may collide with file descriptors Bash uses internally.

## Redirecting output

    N > TARGET

This redirects the file descriptor number `N` to the target `TARGET`. If
`N` is omitted, `stdout` is assumed (FD 1). The `TARGET` is
**truncated** before writing starts.

If the option `noclobber` is set with [the set
builtin](../commands/builtin/set.md), with cause the redirection to fail,
when `TARGET` names a regular file that already exists. You can manually
override that behaviour by forcing overwrite with the redirection
operator `>|` instead of `>`.

## Appending redirected output

    N >> TARGET

This redirects the file descriptor number `N` to the target `TARGET`. If
`N` is omitted, `stdout` is assumed (FD 1). The `TARGET` is **not
truncated** before writing starts.

## Redirecting output and error output

    &> TARGET

    >& TARGET

This special syntax redirects both, `stdout` and `stderr` to the
specified target. It's **equivalent** to

    > TARGET 2>&1

Since Bash4, there's `&>>TARGET`, which is equivalent to
`>> TARGET 2>&1`.

!!! info "important"
    This syntax is deprecated and should not be
    used. See the page about [obsolete and deprecated
    syntax](../scripting/obsolete.md).

## Appending redirected output and error output

To append the cumulative redirection of `stdout` and `stderr` to a file
you simply do

    >> FILE 2>&1

    &>> FILE

## Transporting stdout and stderr through a pipe

    COMMAND1 2>&1 | COMMAND2

    COMMAND1 |& COMMAND2

## Redirecting input

    N < SOURCE

The input descriptor `N` uses `SOURCE` as its data source. If `N` is
omitted, filedescriptor 0 (`stdin`) is assumed.

## Here documents

<BOOKMARK:tag_heredoc>

    <<TAG
    ...
    TAG

    <<-TAG
    ...
    TAG

A here-document is an input redirection using source data specified
directly at the command line (or in the script), no "external" source.
The redirection-operator `<<` is used together with a tag `TAG` that's
used to mark the end of input later:

    # display help

    cat <<EOF
    Sorry...
    No help available yet for $PROGRAM.
    Hehe...
    EOF

As you see, substitutions are possible. To be precise, the following
substitutions and expansions are performed in the here-document data:

-   [Parameter expansion](../syntax/pe.md)
-   [Command substitution](../syntax/expansion/cmdsubst.md)
-   [Arithmetic expansion](../syntax/expansion/arith.md)

You can avoid that by quoting the tag:

    cat <<"EOF"
    This won't be expanded: $PATH
    EOF

Last but not least, if the redirection operator `<<` is followed by a
`-` (dash), all **leading TAB** from the document data will be ignored.
This might be useful to have optical nice code also when using
here-documents.

The tag you use **must** be the only word in the line, to be recognized
as end-of-here-document marker.

!!! info "info"
    It seems that here-documents (tested on versions
    `1.14.7`, `2.05b` and `3.1.17`) are correctly terminated when there is
    an EOF before the end-of-here-document tag. The reason is unknown, but
    it seems to be done on purpose. Bash 4 introduced a warning message when
    end-of-file is seen before the tag is reached.

## Here strings

    <<< WORD

The here-strings are a variation of the here-documents. The word `WORD`
is taken for the input redirection:

    cat <<< "Hello world... $NAME is here..."

Just beware to quote the `WORD` if it contains spaces. Otherwise the
rest will be given as normal parameters.

The here-string will append a newline (`\n`) to the data.

## Multiple redirections

More redirection operations can occur in a line of course. The order is
**important**! They're evaluated from **left to right**. If you want to
redirect both, `stderr` and `stdout` to the same file (like `/dev/null`,
to hide it), this is **the wrong way**:

``` bash
# { echo OUTPUT; echo ERRORS >&2; } is to simulate something that outputs to STDOUT and STDERR
# you can test with it
{ echo OUTPUT; echo ERRORS >&2; } 2>&1 1>/dev/null
```

Why? Relatively easy:

-   initially, `stdout` points to your terminal (you read it)
-   same applies to `stderr`, it's connected to your terminal
-   `2>&1` redirects `stderr` away from the terminal to the target for
    `stdout`: **the terminal** (again...)
-   `1>/dev/null` redirects `stdout` away from your terminal to the file
    `/dev/null`

What remains? `stdout` goes to `/dev/null`, `stderr` still (or better:
"again") goes to the terminal. You have to swap the order to make it
do what you want:

``` bash
{ echo OUTPUT; echo ERRORS >&2; } 1>/dev/null 2>&1
```

## Examples

How to make a program quiet (assuming all output goes to `STDOUT` and
`STDERR`?

    command >/dev/null 2>&1

## See also

-   Internal: [Illustrated Redirection
    Tutorial](../howto/redirection_tutorial.md)
-   Internal: [The noclobber
    option](../commands/builtin/set.md#tag_noclobber)
-   Internal: [The exec builtin command](../commands/builtin/exec.md)
-   Internal: [Simple commands parsing and
    execution](../syntax/grammar/parser_exec.md)
-   Internal: [Process substitution
    syntax](../syntax/expansion/proc_subst.md)
-   Internal: [Obsolete and deprecated syntax](../scripting/obsolete.md)
-   Internal: [Nonportable syntax and command
    uses](../scripting/nonportable.md)