plucky (1) annotate-output.1.gz

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.