NAME¶

annotate-output - annotate program output with time and stream

SYNOPSIS¶

annotate-output [options ...] [--] program [args ...]

DESCRIPTION¶

annotate-output executes program with args as arguments and prepends printed lines with a format string followed by an indicator for the stream on which the line was printed followed by a colon and a single space.
The stream indicators are I for information from annotate-output as well as O for STDOUT and E for STDERR from program.

OPTIONS¶

+FORMAT

A format string that may use the conversion specifiers from the date(1)-utility. The printed string is separated from the following stream indicator by a single space. May be overridden by later options that specify the format string.
Defaults to "%H:%M:%S".

--raw-date-format FORMAT

A format string that may use the conversion specifiers from the date(1)-utility. There is no separator between the printed string and the following stream indicator. May be overridden by later options that specify the format string.

--

Ends option parsing (unless it is itself an argument to an option).

-h, --help

Display a help message.

EXIT STATUS¶

If program is invoked, the exit status of annotate-output shall be the exit status of program; otherwise, annotate-output shall exit with one of the following values:

0

-h or --help was used.

125

An error occurred in annotate-output.

126

program was found but could not be invoked.

127

program could not be found or was not specified.

EXAMPLE¶

$ annotate-output make
21:41:21 I: Started make
21:41:21 O: gcc -Wall program.c
21:43:18 E: program.c: Couldn't compile, and took me ages to find out
21:43:19 E: collect2: ld returned 1 exit status
21:43:19 E: make: *** [all] Error 1
21:43:19 I: Finished with exitcode 2

CAVEATS AND BUGS¶

Since STDOUT and STDERR are processed in parallel, it can happen that some lines received on STDOUT will show up before later-printed STDERR lines (and vice-versa).
This is unfortunately very hard to fix with the current annotation strategy. A fix would involve switching to PTRACE'ing the process. Giving nice a (much) higher priority over program could however cause this behaviour to show up less frequently.

annotate-output expects program to output (text) lines (as specified by POSIX) to STDOUT and STDERR.
In particular, it leads to undefined behaviour when lines are printed that contain NUL bytes. It further may lead to undefined behaviour when lines are printed that contain bytes that do not form valid characters in the current locale.

When an interactive program asks for input, the question might not be shown until after you have answered it. This will give the impression that program has hung, while it has not.

annotate-output is implemented as a script in the Shell Command Language. Shells typically set various (shell) variables when started and may set the `export` attribute on some of them. They further initialise (shell) variables from their own environment (as set by the caller of the shell respectively the caller of annotate-output) and set the `export` attribute on them.
It follows from this, that when the caller of annotate-output wants to set the environment (variables) of program, they may get overridden or additional ones may get added by the shell.
Further, environment variables are in principle allowed to have names (for example `.`) that are not valid shell variable names. POSIX does not specify whether or not such environment variables are exported to programs invoked from the shell. No assumptions can thus be made on whether such environment variables will be exported correctly or at all to program.

SEE ALSO¶

date(1)

SUPPORT¶

annotate-output is community-supported (meaning: you'll need to fix it yourself). Patches are however appreciated, as is any feedback (positive or negative).

AUTHOR¶

This manual page was written by Jeroen van Wolffelaar <jeroen@wolffelaar.nl> and can be redistributed under the terms of the GPL version 2. The annotate-output script itself was re-written by Johannes Schauer Marin Rodrigues <josch@debian.org> and can be redistributed under the terms of the Expat license.