4 coloredstderr is a small library which uses 'LD_PRELOAD' to color stderr.
7 Like all solutions using 'LD_PRELOAD' it only works with dynamically linked
8 binaries. Statically linked binaries, for example valgrind, are not supported.
11 It was inspired by stderred [2]. Similar solutions (using 'LD_PRELOAD')
14 - stderred [1], but doesn't `follow' dups (I somehow missed it when looking
15 for existing implementations)
16 - stderred [2], but only hooks `write()`
18 [1]: https://github.com/sickill/stderred
19 [2]: https://github.com/trapd00r/stderred
21 Most other existing solutions use a second process which colors its input and
22 pipe stderr to it. However this creates different runtime behaviour resulting
23 in a different ordering of the output. Partial lines (no newline) also often
30 - C99 compiler (variable length arrays)
31 - dynamic linker/loader which supports 'LD_PRELOAD' (e.g. GNU/Linux's ld.so)
37 ./configure && make && make check
39 Then either install the library with `make install` or just copy it from
40 `src/.libs/` to wherever you want to install it:
42 rm -f /destination/path/for/library/libcoloredstderr.so
43 cp -L src/.libs/libcoloredstderr.so /destination/path/for/library/
45 *Important:* If you install `libcoloredstderr.so` manually, make sure _not_ to
46 use plain `cp` to overwrite an existing `libcoloredstderr.so` file which is in
47 use! Doing so will crash all processes which were started with 'LD_PRELOAD'
48 set to this file. This is not a bug in coloredstderr, but a general problem.
49 `cp` truncates the file which causes the `mmap()` ed library to be in an
50 inconsistent state causing a segmentation fault when using any functions of
51 the library. Just remove the file first and then copy it. `make install`
52 handles the install in this way and is therefore not affected.
54 As a simple safeguard, `make` builds and installs the `libcoloredstderr.so`
55 file non-writable to prevent accidental overwrites. Even if the overwrite is
56 forced with `cp -f`, the file is unlinked and recreated by `cp` because the
57 file is non-writable, preventing the problem.
63 Set 'LD_PRELOAD' to include the _absolute_ path to `libcoloredstderr.so`:
65 LD_PRELOAD=/absolute/path/to/libcoloredstderr.so
67 The 'COLORED_STDERR_FDS' environment variable must be set to the file
68 descriptors which should be colored (comma separated list). Normally this is
73 The trailing comma is important!
76 A default setup could look like this:
78 LD_PRELOAD="$HOME/bin/libcoloredstderr.so"
80 export LD_PRELOAD COLORED_STDERR_FDS
83 The following additional environment variables are available:
85 - 'COLORED_STDERR_PRE'
86 String to write before each write to stderr, defaults to "\033[91m" (bright
88 - 'COLORED_STDERR_POST'
89 String to write after each write to stderr, defaults to "\033[0m" (reset
91 - 'COLORED_STDERR_FORCE_WRITE'
92 If set to an non-empty value add pre/post strings even when not writing to a
93 terminal, e.g. when writing to a file. By default, only writes to a terminal
97 To set custom colors as pre/post strings you can use the `$''` feature of Bash
100 export COLORED_STDERR_PRE=$'\033[91m' # bright red
101 export COLORED_STDERR_POST=$'\033[0m' # default
103 Or to be more compatible you can use the following which should work in any
107 COLORED_STDERR_PRE="${esc}[91m" # red
108 COLORED_STDERR_POST="${esc}[0m" # default
109 export COLORED_STDERR_PRE COLORED_STDERR_POST
115 To enable debug mode, configure coloredstderr with '--enable-debug'.
117 *Important:* Debug mode enables `assert()`s in the code which might abort the
118 process if an error condition is detected!
120 Debug mode is slower than normal mode. To log only warnings without the
121 overhead of debug mode use '--enable-warnings'. `assert()`s are not enabled
122 with '--enable-warnings', so it's safe to use.
124 Debug messages are written to the file `colored_stderr_debug_log.txt` in the
125 current working directory _if_ it exists. If it exists debug messages are
126 appended. Be careful, this file might grow very quickly.
128 *Important:* Warnings are written to `$HOME/colored_stderr_warning_log.txt`
129 even if it _does not_ exist (only if debug or warning mode is enabled)! If it
130 doesn't exist it's created. An existing file isn't overwritten, but the
131 warnings are appended at the end.
137 If you find any bugs not mentioned in this document please report them to
138 <simon@ruderich.org> with coloredstderr in the subject.
144 Written by Simon Ruderich <simon@ruderich.org>.
150 coloredstderr is licensed under GPL version 3 or later.
152 Copyright (C) 2013 Simon Ruderich
154 This program is free software: you can redistribute it and/or modify
155 it under the terms of the GNU General Public License as published by
156 the Free Software Foundation, either version 3 of the License, or
157 (at your option) any later version.
159 This program is distributed in the hope that it will be useful,
160 but WITHOUT ANY WARRANTY; without even the implied warranty of
161 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
162 GNU General Public License for more details.
164 You should have received a copy of the GNU General Public License
165 along with this program. If not, see <http://www.gnu.org/licenses/>.