We often want to output multiple lines of text from a script, for instance to provide detailed instructions to the user. The output below is a real example from a script that generates random passphrases.

===========================================================================
If no one can see your computer screen right now, you may use one of the
suggested passphrases about to be displayed.  Otherwise, make up one of
your own consisting of three words separated by random characters and
modified with a random capital letters or other characters inserted.
===========================================================================
        

We could output this text using six printf commands or one printf and six string constants. This would be messy, though, and would require quotes around each line of text. We could also store it in a separate file and display it with the cat command, but this would mean more files to maintain.

A here document, or heredoc for short, is another form of redirection that is typically only used in scripts. It essentially redirects the standard input from a portion of the script itself. The general form is as follows:

command << end-of-document-marker

Content of the heredoc

end-of-document-marker
        

The content can contain anything except the marker. End-of-document-marker can be any arbitrary text of your choosing. You simply must choose a marker that is not in the text you want to display. Common markers are EOM (end of message) or EOF (end of file).

Heredocs can be used with any Unix command that reads from standard input, but are most often used with the cat or more command:

#!/bin/sh -e

cat << EOM
===========================================================================
If no one can see your computer screen right now, you may use one of the
suggested passphrases about to be displayed.  Otherwise, make up one of
your own consisting of three words separated by random characters and
modified with a random capital letters or other characters inserted.
===========================================================================
EOM
        

If the heredoc text may be more than one screen long, then use more instead of cat.

Heredocs can also be used to create files from a template that uses shell or environment variables. Any variable references and command output capture that appear within the text of a heredoc will be expanded. The output of any command reading from a heredoc can, of course, be redirected to a file or other device.

#!/bin/csh -ef

# Generate a series of test input files with different ending values
# and tolerances
foreach end_value (10 100 1000 10000)
    foreach tolerance (0.0001 0.0005 0.001)
        cat << EOM > test-input-$end_value-$tolerance.txt
start_value=1
end_value=$end_value
tolerance=$tolerance
EOM
    end
end