]> ruderich.org/simon Gitweb - coloredstderr/coloredstderr.git/blob - README
79a40843429a4c66f346cf893be42c29f4834cb3
[coloredstderr/coloredstderr.git] / README
1 README
2 ======
3
4 coloredstderr is a small library which uses 'LD_PRELOAD' to color stderr.
5
6
7 Like all solutions using 'LD_PRELOAD' it only works with dynamically linked
8 binaries. Statically linked binaries, for example valgrind, are not supported.
9 setuid binaries are also not supported ('LD_PRELOAD' disabled for security
10 reasons).
11
12
13 It was inspired by stderred [2]. Similar solutions (using 'LD_PRELOAD')
14 include:
15
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()`
19
20 [1]: https://github.com/sickill/stderred
21 [2]: https://github.com/trapd00r/stderred
22
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.
27
28
29 DEPENDENCIES
30 ------------
31
32 - C99 compiler (variable length arrays)
33 - dynamic linker/loader which supports 'LD_PRELOAD' (e.g. GNU/Linux's ld.so)
34
35
36 INSTALLATION
37 ------------
38
39     ./configure && make && make check
40
41 Then either install the library with `make install` or just copy it from
42 `src/.libs/` to wherever you want to install it:
43
44     rm -f /destination/path/for/library/libcoloredstderr.so
45     cp -L src/.libs/libcoloredstderr.so /destination/path/for/library/
46
47 *Important:* If you install `libcoloredstderr.so` manually, make sure _not_ to
48 use plain `cp` to overwrite an existing `libcoloredstderr.so` file which is in
49 use! Doing so will crash all processes which were started with 'LD_PRELOAD'
50 set to this file. This is not a bug in coloredstderr, but a general problem.
51 `cp` truncates the file which causes the `mmap()` ed library to be in an
52 inconsistent state causing a segmentation fault when using any functions of
53 the library. Just remove the file first and then copy it. `make install`
54 handles the install in this way and is therefore not affected.
55
56 As a simple safeguard, `make` builds and installs the `libcoloredstderr.so`
57 file non-writable to prevent accidental overwrites. Even if the overwrite is
58 forced with `cp -f`, the file is unlinked and recreated by `cp` because the
59 file is non-writable, preventing the problem.
60
61
62 USAGE
63 -----
64
65 Set 'LD_PRELOAD' to include the _absolute_ path to `libcoloredstderr.so`:
66
67     LD_PRELOAD=/absolute/path/to/libcoloredstderr.so
68
69 The 'COLORED_STDERR_FDS' environment variable must be set to the file
70 descriptors which should be colored (comma separated list). Normally this is
71 just 2 (stderr):
72
73     COLORED_STDERR_FDS=2,
74
75 The trailing comma is important!
76
77
78 A default setup could look like this:
79
80     LD_PRELOAD="$HOME/bin/libcoloredstderr.so"
81     COLORED_STDERR_FDS=2,
82     export LD_PRELOAD COLORED_STDERR_FDS
83
84
85 The following additional environment variables are available:
86
87 - 'COLORED_STDERR_PRE'
88   String to write before each write to stderr, defaults to "\033[91m" (bright
89   red).
90 - 'COLORED_STDERR_POST'
91   String to write after each write to stderr, defaults to "\033[0m" (reset
92   color).
93 - 'COLORED_STDERR_FORCE_WRITE'
94   If set to an non-empty value add pre/post strings even when not writing to a
95   terminal, e.g. when writing to a file. By default, only writes to a terminal
96   are colored.
97
98 All environment variables starting with 'COLORED_STDERR_PRIVATE_*' are
99 internal variables used by the implementation and should not be set manually.
100 See the source for details.
101
102
103 To set custom colors as pre/post strings you can use the `$''` feature of Bash
104 and Zsh:
105
106     export COLORED_STDERR_PRE=$'\033[91m' # bright red
107     export COLORED_STDERR_POST=$'\033[0m' # default
108
109 Or to be more compatible you can use the following which should work in any
110 Bourne shell:
111
112     esc=`printf '\033'`
113     COLORED_STDERR_PRE="${esc}[91m" # red
114     COLORED_STDERR_POST="${esc}[0m" # default
115     export COLORED_STDERR_PRE COLORED_STDERR_POST
116
117
118 DEBUG
119 -----
120
121 To enable debug mode, configure coloredstderr with '--enable-debug'.
122
123 *Important:* Debug mode enables `assert()`s in the code which might abort the
124 process if an error condition is detected!
125
126 Debug mode is slower than normal mode. To log only warnings without the
127 overhead of debug mode use '--enable-warnings'. `assert()`s are not enabled
128 with '--enable-warnings', so it's safe to use.
129
130 Debug messages are written to the file `colored_stderr_debug_log.txt` in the
131 current working directory _if_ it exists. If it exists debug messages are
132 appended. Be careful, this file might grow very quickly.
133
134 *Important:* Warnings are written to `$HOME/colored_stderr_warning_log.txt`
135 even if it _does not_ exist (only if debug or warning mode is enabled)! If it
136 doesn't exist it's created. An existing file isn't overwritten, but the
137 warnings are appended at the end.
138
139
140 BUGS
141 ----
142
143 If you find any bugs not mentioned in this document please report them to
144 <simon@ruderich.org> with coloredstderr in the subject.
145
146
147 AUTHORS
148 -------
149
150 Written by Simon Ruderich <simon@ruderich.org>.
151
152
153 LICENSE
154 -------
155
156 coloredstderr is licensed under GPL version 3 or later.
157
158 Copyright (C) 2013  Simon Ruderich
159
160 This program is free software: you can redistribute it and/or modify
161 it under the terms of the GNU General Public License as published by
162 the Free Software Foundation, either version 3 of the License, or
163 (at your option) any later version.
164
165 This program is distributed in the hope that it will be useful,
166 but WITHOUT ANY WARRANTY; without even the implied warranty of
167 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
168 GNU General Public License for more details.
169
170 You should have received a copy of the GNU General Public License
171 along with this program.  If not, see <http://www.gnu.org/licenses/>.