horok/devscripts
1
0
Fork 0
Code Activity

Adding upstream version 2.25.15.

Browse source 
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
This commit is contained in:
Daniel Baumann 2025-06-21 11:04:07 +02:00
parent 10737b110a
commit b543f2e88d
Signed by: daniel.baumann
GPG key ID: BCC918A2ABD66424
485 changed files with 191459 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

120
scripts/annotate-output.1 Normal file
View file

@ -0,0 +1,120 @@
.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.