4 coloredstderr is a small library which uses 'LD_PRELOAD' to color stderr. It
5 ``follows'' dups, has minimal performance overhead and can ignore certain
6 binaries (requires /proc).
8 Like all solutions using 'LD_PRELOAD' it only works with dynamically linked
9 binaries. Statically linked binaries, for example valgrind, are not supported.
10 setuid binaries are also not supported ('LD_PRELOAD' disabled for security
13 It was inspired by stderred [2]. Similar solutions (using 'LD_PRELOAD')
16 - stderred [1], but doesn't `follow' dups (I somehow missed it when looking
17 for existing implementations)
18 - stderred [2], but only hooks `write()`
20 [1]: https://github.com/sickill/stderred
21 [2]: https://github.com/trapd00r/stderred
23 Most other existing solutions use a second process which colors its input and
24 pipe stderr to it. However this creates different runtime behaviour resulting
25 in a different ordering of the output. Partial lines (no newline) also often
26 cause problems. coloredstderr handles these cases correctly (but has other
27 possible issues, see below).
29 coloredstderr is licensed under GPL 3 (or later).
35 - C99 compiler (variable length arrays)
36 - dynamic linker/loader which supports 'LD_PRELOAD' (e.g. GNU/Linux's or
43 ./configure && make && make check
45 Then either install the library with `make install` or just copy it from
46 `src/.libs/` to wherever you want to install it:
48 rm -f /destination/path/for/library/libcoloredstderr.so
49 cp -L src/.libs/libcoloredstderr.so /destination/path/for/library/
51 *Important:* If you install `libcoloredstderr.so` manually, make sure _not_ to
52 use plain `cp` to overwrite an existing `libcoloredstderr.so` file which is in
53 use! Doing so will crash most processes which were started with 'LD_PRELOAD'
54 set to this file. This is not a bug in coloredstderr, but a general problem.
55 `cp` truncates the file which causes the `mmap()` ed library to be in an
56 inconsistent state causing a segmentation fault when using any functions of
57 the library. Just remove the file first and then copy it. `make install`
58 handles the install in this way and is therefore not affected.
60 As a simple safeguard, `make` builds and installs the `libcoloredstderr.so`
61 file non-writable to prevent accidental overwrites. Even if the overwrite is
62 forced with `cp -f`, the file is unlinked and recreated by `cp` because the
63 file is non-writable, preventing the problem.
69 Set 'LD_PRELOAD' to include the _absolute_ path to `libcoloredstderr.so`:
71 LD_PRELOAD=/absolute/path/to/libcoloredstderr.so
73 The 'COLORED_STDERR_FDS' environment variable must be set to the file
74 descriptors which should be colored (comma separated list). Normally this is
79 The trailing comma is important!
82 A default setup could look like this:
84 LD_PRELOAD="$HOME/bin/libcoloredstderr.so"
86 export LD_PRELOAD COLORED_STDERR_FDS
89 The following additional environment variables are available:
91 - 'COLORED_STDERR_PRE'
92 String to write before each write to stderr, defaults to "\033[31m" (red).
93 - 'COLORED_STDERR_POST'
94 String to write after each write to stderr, defaults to "\033[0m" (reset
96 - 'COLORED_STDERR_FORCE_WRITE'
97 If set to an non-empty value add pre/post strings even when not writing to a
98 terminal, e.g. when writing to a file. By default, only writes to a terminal
100 - 'COLORED_STDERR_IGNORED_BINARIES'
101 Comma separated list of binary names/paths which should not be tracked
102 (including their children). Useful for `reset` which writes to the terminal,
103 but fails to work if the output is colored. See below for an example.
105 All environment variables starting with 'COLORED_STDERR_PRIVATE_*' are
106 internal variables used by the implementation and should not be set manually.
107 See the source for details.
110 To set custom colors as pre/post strings you can use the `$''` feature of Bash
113 export COLORED_STDERR_PRE=$'\033[91m' # bright red
114 export COLORED_STDERR_POST=$'\033[0m' # default
116 Or to be more compatible you can use the following which should work in any
120 COLORED_STDERR_PRE="${esc}[91m" # bright red
121 COLORED_STDERR_POST="${esc}[0m" # default
122 export COLORED_STDERR_PRE COLORED_STDERR_POST
124 Fix `reset`; its writes to the terminal must be unaltered. `reset` is a
125 symbolic-link to `tset` on some systems, adapt as necessary:
127 COLORED_STDERR_IGNORED_BINARIES=/usr/bin/tset
128 export COLORED_STDERR_IGNORED_BINARIES
134 To enable debug mode, configure coloredstderr with '--enable-debug'.
136 *Important:* Debug mode enables `assert()`s in the code which might abort the
137 process using 'LD_PRELOAD' if an error condition is detected!
139 Debug mode is slower than normal mode. To log only warnings without the
140 overhead of debug mode use '--enable-warnings'. `assert()`s are not enabled
141 with '--enable-warnings', so it's safe to use.
143 Debug messages are appended to the file `colored_stderr_debug_log.txt` in the
144 current working directory _if_ it exists. Be careful, this file might grow
147 *Important:* Warnings are written to `$HOME/colored_stderr_warning_log.txt`
148 even if it _does not_ exist (only if debug or warning mode is enabled)! If it
149 doesn't exist it's created. An existing file isn't overwritten, but the
150 warnings are appended at the end.
156 - `{fputc,putc,putchar}_unlocked()` are not hooked with glibc when writing to
157 stdout (which might be redirected to stderr). Can't be fixed as the compiler
158 inlines the code into the program without calling any function.
159 - Test `test_stdio.sh` fails on FreeBSD, because FreeBSD does handle the above
160 correctly (no inlining), but the test is designed for GNU/Linux.
161 - 'COLORED_STDERR_IGNORED_BINARIES' requires the `/proc` file system.
163 - Output of `strace` is not always colored correctly as the output from
164 `coloredstderr` is traced and displayed as well. Suggestions welcome.
170 If you find any bugs not mentioned in this document please report them to
171 <simon@ruderich.org> with coloredstderr in the subject.
177 Written by Simon Ruderich <simon@ruderich.org>.
183 coloredstderr is licensed under GPL version 3 or later.
185 Copyright (C) 2013-2014 Simon Ruderich
187 This program is free software: you can redistribute it and/or modify
188 it under the terms of the GNU General Public License as published by
189 the Free Software Foundation, either version 3 of the License, or
190 (at your option) any later version.
192 This program is distributed in the hope that it will be useful,
193 but WITHOUT ANY WARRANTY; without even the implied warranty of
194 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
195 GNU General Public License for more details.
197 You should have received a copy of the GNU General Public License
198 along with this program. If not, see <http://www.gnu.org/licenses/>.