120 lines
4.5 KiB
Groff
120 lines
4.5 KiB
Groff
.TH ANNOTATE-OUTPUT 1 "Debian Utilities" "DEBIAN" \" -*- nroff -*-
|
|
.SH NAME
|
|
annotate-output \- annotate program output with time and stream
|
|
.SH SYNOPSIS
|
|
\fBannotate\-output\fR [\fIoptions\fR ...] [--] \fIprogram\fR [\fIargs\fR ...]
|
|
.SH DESCRIPTION
|
|
\fBannotate\-output\fR executes \fIprogram\fR with \fIargs\fR 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.
|
|
.br
|
|
The stream indicators are \fBI\fR for information from
|
|
\fBannotate\-output\fR as well as \fBO\fR for STDOUT and \fBE\fR for STDERR
|
|
from \fIprogram\fR.
|
|
|
|
|
|
.SH OPTIONS
|
|
.TP
|
|
\fB+FORMAT\fR
|
|
A format string that may use the conversion specifiers from the
|
|
\fBdate\fR(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.
|
|
.br
|
|
Defaults to "%H:%M:%S".
|
|
.TP
|
|
\fB--raw-date-format\fR \fIFORMAT\fR
|
|
A format string that may use the conversion specifiers from the
|
|
\fBdate\fR(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.
|
|
.TP
|
|
\fB--\fR
|
|
Ends option parsing (unless it is itself an argument to an option).
|
|
.TP
|
|
\fB\-h\fR, \fB\-\-help\fR
|
|
Display a help message.
|
|
|
|
.SH EXIT STATUS
|
|
If \fIprogram\fR is invoked, the exit status of \fBannotate\-output\fR
|
|
shall be the exit status of \fIprogram\fR; otherwise,
|
|
\fBannotate\-output\fR shall exit with one of the following values:
|
|
.TP
|
|
0
|
|
\fB\-h\fR or \fB\-\-help\fR was used.
|
|
.TP
|
|
125
|
|
An error occurred in \fBannotate\-output\fR.
|
|
.TP
|
|
126
|
|
\fIprogram\fR was found but could not be invoked.
|
|
.TP
|
|
127
|
|
\fIprogram\fR could not be found or was not specified.
|
|
|
|
.SH EXAMPLE
|
|
|
|
.nf
|
|
$ 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
|
|
.fi
|
|
|
|
.SH 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).
|
|
.br
|
|
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 \fIprogram\fR could
|
|
however cause this behaviour to show up less frequently.
|
|
|
|
\fBannotate\-output\fR expects \fIprogram\fR to output (text) lines (as
|
|
specified by POSIX) to STDOUT and STDERR.
|
|
.br
|
|
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 \fIprogram\fR asks for input, the question might not be
|
|
shown until after you have answered it. This will give the impression that
|
|
\fIprogram\fR has hung, while it has not.
|
|
|
|
\fBannotate\-output\fR 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 \fBannotate\-output\fR) and set the
|
|
`export` attribute on them.
|
|
.br
|
|
It follows from this, that when the caller of \fBannotate\-output\fR wants
|
|
to set the environment (variables) of \fIprogram\fR, they may get
|
|
overridden or additional ones may get added by the shell.
|
|
.br
|
|
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 \fIprogram\fR.
|
|
|
|
.SH "SEE ALSO"
|
|
\fBdate\fR(1)
|
|
|
|
.SH SUPPORT
|
|
\fBannotate\-output\fR is community-supported (meaning: you'll need to fix
|
|
it yourself). Patches are however appreciated, as is any feedback
|
|
(positive or negative).
|
|
|
|
.SH 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 \fBannotate-output\fR script itself was re-written by Johannes Schauer
|
|
Marin Rodrigues <josch@debian.org> and can be redistributed under the terms
|
|
of the Expat license.
|