Output and evaluation

This topic gathers the small, sharp commands that scripts are built from: the ones that print something, that read or set the environment, that evaluate an expression or a condition, and that simply succeed or fail.

The commands #

Producing text

The environment

Numbers

Evaluating

Exit status

A note on exit status #

Several commands here exist to be used for their exit status rather than their output. Every command, when it finishes, leaves behind a number: 0 means success, anything else means a kind of failure. A shell's if, &&, and || all act on that number.

test is the clearest case — it prints nothing and exists only to set an exit status from a condition. true and false are the most minimal: fixed success and fixed failure. Where this topic's pages give an exit-status table, that number is often the whole point of the command.

Where to start #

For everyday printing, echo; for anything that needs columns, padding, or precise formatting, printf.

echo prints its arguments, separated by single spaces, followed by a newline.

echo [options] [string...]

$ echo Hello, Peios
Hello, Peios

It is the simplest way to put a line of text on standard output — printing a message, or feeding a fixed string into a pipe.

Options #

Escape sequences #

With -e, echo recognises these backslash sequences and prints the character they stand for:

echo and printf #

echo is fixed: arguments, spaces, a newline. The moment you need control over the output — columns, padding, a number formatted a particular way, output with no spaces between pieces — use printf instead. printf is also more predictable across environments, since echo's handling of escapes and -n varies.

A note on shells #

Many command shells provide their own built-in echo, and the shell's version is what runs when you type echo at a prompt. Built-in versions vary — especially in how they treat -n, -e, and escape sequences — so their behaviour may differ from what is described here. To be certain you are running this command rather than the shell built-in, invoke it by its full path.

Exit status #

printf prints text built from a format string. The format string is printed literally, except that escape sequences become characters and substitution fields are replaced by the arguments that follow.

printf format [argument...]

$ printf 'the letter %X comes before %X\n' 10 11
the letter A comes before B

Where echo prints arguments as-is, printf gives you control: padding, column widths, number bases, fixed decimal places. It is the command for output that has to line up or be exact.

printf writes only what the format string says — there is no automatic trailing newline. Include \n yourself where you want one.

Escape sequences #

The format string interprets these backslash sequences:

Substitution fields #

A field begins with % and is replaced by the next argument, formatted accordingly.

Width and precision #

Between the % and the field letter you may put two numbers — %[width][.precision]field:

• width — the minimum number of columns. Output narrower than this is padded with leading spaces; a negative width pads on the right instead.
• precision — after a .; its meaning depends on the field. For a string it is a maximum length; for an integer, a minimum digit count (zero-padded); for a float, the number of decimal places.

$ printf '%-10s %5.2f\n' apples 3.1
apples         3.10

Reusing the format string #

If more arguments are supplied than the format string has fields, printf repeats the format string until the arguments run out. If there are too few, the leftover fields default to an empty string (or 0 for a number).

$ printf '%s: %d\n' alpha 1 beta 2 gamma 3
alpha: 1
beta: 2
gamma: 3

Exit status #

yes prints a line over and over, without stopping.

yes [string...]

$ yes
y
y
y
...

With no argument it prints y forever. Given arguments, it prints them — joined by spaces — as the repeated line instead.

$ yes retry
retry
retry
...

yes never stops on its own. It ends when something downstream closes the pipe, or when you interrupt it with Ctrl-C.

What it is for #

yes exists to answer prompts. An older interactive command that asks "are you sure? [y/n]" again and again can be fed a stream of confirmations:

$ yes | slow-interactive-command

Most modern commands have a proper option for this — rm -f, and similar — and that is the better way when it exists. yes is the fallback for a command that offers no such option. It is also a quick way to generate an endless stream of identical lines for a test.

Exit status #

seq prints a sequence of numbers, one per line.

seq [options] last
seq [options] first last
seq [options] first increment last

$ seq 3
1
2
3
$ seq 2 2 10
2
4
6
8
10

The three forms control where the sequence starts and how it steps:

• seq last — count from 1 up to last.
• seq first last — count from first up to last.
• seq first increment last — count from first to last, stepping by increment.

The increment may be negative, to count down, and the numbers may be fractional. seq is most often used to drive a loop a fixed number of times.

Options #

$ seq -s , 1 5
1,2,3,4,5
$ seq -w 8 10
08
09
10

-f takes a single floating-point conversion — see printf for the format syntax — and cannot be combined with -w.

Exit status #

env runs a command with a changed environment — the set of NAME=VALUE variables a process inherits. Run with no command, it prints the current environment instead.

env [options] [NAME=VALUE]... [command [arg]...]

$ env LANG=C TZ=UTC my-program
$ env
PATH=/bin
HOME=/home/jack
...

How it works #

You give env a list of NAME=VALUE assignments, then a command. env applies the assignments to its own environment and then runs the command, which inherits the result. The assignments affect only that one run — your shell's environment is untouched.

This is the clean way to run something with a particular variable set, without changing it for everything else, and the standard way to run a command with one variable temporarily different.

With no command, env simply prints the environment it would have used — which, with no options, is the current one.

Building the environment #

The order is: start (inherited, or empty with -i), apply --file, apply --unset, apply the NAME=VALUE arguments.

Running the command #

Signal handling #

env can adjust how the command treats signals before launching it:

Other options #

Exit status #

When env runs a command, it exits with that command's status. The exception is a failure in env itself:

printenv prints environment variables.

printenv [options] [variable...]

Name one or more variables and printenv prints the value of each. Name none and it prints the whole environment, one NAME=VALUE pair per line.

$ printenv HOME
/home/jack
$ printenv
PATH=/bin
HOME=/home/jack
...

Options #

printenv and env #

Both can print the environment. printenv is the one built for reading it — it can pick out a single variable by name. env prints the environment too, but its real job is running a command with a modified one. Use printenv to look something up; use env to change something for a command.

Exit status #

numfmt converts numbers between plain digits and human-readable forms — turning 1500000 into 1.5M, or 1.5M back into 1500000.

numfmt [options] [number...]

$ numfmt --to=si 1500000
1.5M
$ numfmt --from=si 1.5M
1500000

numfmt takes numbers as arguments, or — with none — reads them from standard input, which lets it rescale a column of numbers flowing through a pipe.

The direction of conversion #

A UNIT is one of:

Working on fields #

By default numfmt converts the whole input line. To convert numbers sitting in a column of wider text, name the field:

Shaping the output #

Other options #

Exit status #

expr evaluates a single expression and prints its value.

expr expression

$ expr 6 + 7
13
$ expr length "Peios"
5

Each part of the expression — every number, operator, and keyword — is a separate argument. That is why the spaces matter: expr 6+7 is one argument and not an expression, while expr 6 + 7 is three.

Arithmetic #

Comparison #

A comparison yields 1 for true and 0 for false. It is arithmetic when both sides are numbers, and lexical otherwise.

Logic #

String operations #

Many of these operators — *, <, |, ( — are also meaningful to a shell, so quote or escape them so they reach expr intact.

Exit status #

expr's exit status reports on the value it computed:

factor prints the prime factors of a number.

factor [options] [number...]

$ factor 360
360: 2 2 2 3 3 5

Each line of output is the original number, a colon, and its prime factors in increasing order, repeated as often as they divide in. Give several numbers and factor factors each; give none and it reads numbers from standard input.

Options #

$ factor -h 360
360: 2^3 3^2 5

Exit status #

test evaluates a single condition and reports whether it is true or false. It prints nothing — the answer is its exit status: 0 for true, 1 for false. That makes it the command a shell's if, while, &&, and || are built on.

test expression
[ expression ]

The two forms are the same command. [ is test under another name; when invoked as [, it requires a closing ] as its last argument. [ -f notes.txt ] and test -f notes.txt are identical.

$ test -f notes.txt && echo "the file exists"

File tests #

Existence and type #

Access #

These three tests ask whether you may actually use the file:

On Peios these are real access checks. test asks the kernel whether your token is granted the right in question — a live check against the file's security descriptor, the same decision any actual read, write, or execute would face. The answer is therefore honest: test -w FILE is true exactly when a write would be permitted.

-x on a regular file means "you are permitted to execute it" — which is a different question from whether the file is an executable. A file can be runnable code and still fail -x for you, and the two are decided separately; see Access decisions.

Comparing two files #

Other file tests #

The last two rows probe decorative inode fields. The Peios access model does not consult them — they are stored on the inode and reported for completeness, but they carry no authority. For a true picture of what may be done to a file, use the access tests -r, -w, -x above, not -O, -g, or -u.

String tests #

Integer comparisons #

Combining conditions #

-a and -o are genuinely ambiguous to parse and are best avoided. Combine separate test calls with the shell's own && and || instead:

test -f notes.txt && test -r notes.txt

A note on shells #

Many command shells provide their own built-in test and [, and the shell's version is what runs when you type test at a prompt or in a script. A built-in may not behave as described here — in particular, the access tests -r, -w, and -x are the real access checks described above only when this command runs. To be certain you are running this command rather than the shell built-in, invoke it by its full path.

Exit status #

true and false do nothing at all. Their only product is an exit status: true always succeeds, false always fails.

true
false

$ true ; echo $?
0
$ false ; echo $?
1

true exits 0. false exits 1. They take no arguments that matter, produce no output, and have no effect on anything.

What they are for #

A command that is only an exit status is useful as a fixed value in places that expect a command:

• An always-true or always-false loop. while true is the standard way to write a loop that runs until something inside it breaks out.
• A deliberate placeholder. Setting a configurable command to true makes that step do nothing and "succeed"; false makes it a step that always fails.
• A known result in a test. When a script or a condition needs a guaranteed pass or fail to check against, true and false provide it.

They are the simplest commands there are — and the overview's note on exit status is the whole idea behind them.

Exit status #

tee reads standard input and writes it, unchanged, to standard output and to each file you name. It is the T-junction of a pipeline: the data keeps flowing down the pipe while a copy is also captured on disk.

tee [options] [file...]

$ echo saved | tee note.txt
saved
$ cat note.txt
saved

The name is the shape of the letter T — one stream in, the same stream out two ways. That makes tee the tool for the moment you want to both see (or keep piping) some data and keep it at the same time.

Writing to several places at once #

Every byte that arrives on standard input is written to standard output and to each named file. Name more than one file and each one receives a full, identical copy:

$ producer | tee a.log b.log c.log | consumer

Here producer's output reaches consumer down the pipe exactly as if tee were not there, and a.log, b.log, and c.log each end up holding the same complete copy of it. With no files named, tee copies input straight to standard output and nothing else — a plain pass-through.

tee does not buffer between reads: it writes each chunk out as it is read, so a file being written by tee fills up as the data flows, rather than all at once when the input ends.

Overwrite or append #

By default, each named file is truncated — opened fresh, so any existing contents are discarded before the new data is written. A file that does not exist is created.

With -a (--append), tee appends to each named file instead: existing contents are kept and the new data is added to the end. A file that does not exist is still created.

$ echo first  | tee log.txt        # log.txt now holds "first"
$ echo second | tee -a log.txt     # log.txt now holds "first" then "second"

Creating a file inherits a security descriptor #

When tee creates a new output file — a named file that did not already exist — that file needs a security descriptor, and it inherits one from the directory it is created in. This is the same creation-inherits-a-descriptor rule that governs every file-creating tool on Peios; see Files and directories for the shared model.

With -a, when the named file already exists, tee opens that existing file to append and creates nothing, so no new descriptor is involved. Whether opening a file to write succeeds — whether creating a new one or writing an existing one — is decided by the normal access check against the relevant directory or file. tee reports a file it cannot open and, by default, carries on with the outputs it can write.

Files named - #

tee gives no special meaning to -. A file argument of - refers to a file literally named - in the current directory; it is opened, created, and written exactly like any other named file. It is not a stand-in for standard output — standard output is always written and needs no naming.

Ignoring interrupts #

With -i (--ignore-interrupts), tee ignores the interrupt signal (the one a terminal sends on Ctrl-C). This lets tee keep copying to its files even as an interrupt tears down the rest of a pipeline, so the capture is not cut short.

Behaviour on write errors #

By default, if a write to one output fails, tee reports it and stops writing to that output, but keeps writing to the others; a broken-pipe error on standard output is treated quietly. Two options change this policy.

-p sets write-error behaviour so that errors on a pipe (a downstream reader that has gone away) are ignored while other write errors are still reported.

--output-error[=MODE] sets the policy explicitly. Given on its own, with no =MODE, it selects warn-nopipe. The modes are:

Options #

Exit status #