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.