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.

DEBIAN                                          Debian Utilities                              ANNOTATE-OUTPUT(1)