README

   1 README
   2 ======
   3
   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.
   7
   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
  11 reasons).
  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. coloredstderr handles these cases correctly (but has other
  27 possible issues, see below).
  28
  29 coloredstderr is licensed under GPL 3 (or later).
  30
  31
  32 DEPENDENCIES
  33 ------------
  34
  35 - C99 compiler (variable length arrays)
  36 - dynamic linker/loader which supports 'LD_PRELOAD' (e.g. GNU/Linux's or
  37   FreeBSD's ld.so)
  38
  39
  40 INSTALLATION
  41 ------------
  42
  43 If you're using the Git version, run `autoreconf -fsi` first to generate
  44 `configure`.
  45
  46     ./configure && make && make check
  47
  48 Then either install the library with `make install` or just copy it from
  49 `src/.libs/` to wherever you want to install it:
  50
  51     rm -f /destination/path/for/library/libcoloredstderr.so
  52     cp -L src/.libs/libcoloredstderr.so /destination/path/for/library/
  53
  54 *Important:* If you install `libcoloredstderr.so` manually, make sure _not_ to
  55 use plain `cp` to overwrite an existing `libcoloredstderr.so` file which is in
  56 use! Doing so will crash most processes which were started with 'LD_PRELOAD'
  57 set to this file. This is not a bug in coloredstderr, but a general problem.
  58 `cp` truncates the file which causes the `mmap()` ed library to be in an
  59 inconsistent state causing a segmentation fault when using any functions of
  60 the library. Just remove the file first and then copy it. `make install`
  61 handles the install in this way and is therefore not affected.
  62
  63 As a simple safeguard, `make` builds and installs the `libcoloredstderr.so`
  64 file non-writable to prevent accidental overwrites. Even if the overwrite is
  65 forced with `cp -f`, the file is unlinked and recreated by `cp` because the
  66 file is non-writable, preventing the problem.
  67
  68
  69 USAGE
  70 -----
  71
  72 Set 'LD_PRELOAD' to include the _absolute_ path to `libcoloredstderr.so`:
  73
  74     LD_PRELOAD=/absolute/path/to/libcoloredstderr.so
  75
  76 The 'COLORED_STDERR_FDS' environment variable must be set to the file
  77 descriptors which should be colored (comma separated list). Normally this is
  78 just 2 (stderr):
  79
  80     COLORED_STDERR_FDS=2,
  81
  82 The trailing comma is important!
  83
  84
  85 A default setup could look like this:
  86
  87     LD_PRELOAD="$HOME/bin/libcoloredstderr.so"
  88     COLORED_STDERR_FDS=2,
  89     export LD_PRELOAD COLORED_STDERR_FDS
  90
  91 To use coloredstderr with multi-lib (multiple architectures on the same
  92 system, e.g. i386 and amd64), your system must support the '$LIB' variable in
  93 'LD_PRELOAD'. Then you can build coloredstderr for all architectures and use
  94 '$LIB' in 'LD_PRELOAD'. The following should work for Debian-based systems
  95 with this directory structure:
  96
  97     dir
  98     `-- lib
  99         |-- i386-linux-gnu
 100         |   `-- libcoloredstderr.so
 101         `-- x86_64-linux-gnu
 102             `-- libcoloredstderr.so
 103
 104 Now set 'LD_PRELOAD'. `lib/` is included in '$LIB'!
 105
 106     LD_PRELOAD='/absolute/path/to/dir/$LIB/libcoloredstderr.so'
 107
 108 The single quotes are important. '$LIB' is not evaluated by the shell, but by
 109 the loader (`man ld.so`). Now both i386 and amd64 binaries automatically use
 110 coloredstderr.
 111
 112
 113 The following additional environment variables are available:
 114
 115 - 'COLORED_STDERR_PRE'
 116   String to write before each write to stderr, defaults to "\033[31m" (red).
 117 - 'COLORED_STDERR_POST'
 118   String to write after each write to stderr, defaults to "\033[0m" (reset
 119   color).
 120 - 'COLORED_STDERR_FORCE_WRITE'
 121   If set to an non-empty value add pre/post strings even when not writing to a
 122   terminal, e.g. when writing to a file. By default, only writes to a terminal
 123   are colored.
 124 - 'COLORED_STDERR_IGNORED_BINARIES'
 125   Comma separated list of binary names/paths which should not be tracked
 126   (including their children). Useful for `reset` which writes to the terminal,
 127   but fails to work if the output is colored. See below for an example.
 128   Requires `/proc/self/exe`.
 129
 130 All environment variables starting with 'COLORED_STDERR_PRIVATE_*' are
 131 internal variables used by the implementation and should not be set manually.
 132 See the source for details.
 133
 134
 135 To set custom colors as pre/post strings you can use the `$''` feature of Bash
 136 and Zsh:
 137
 138     export COLORED_STDERR_PRE=$'\033[91m' # bright red
 139     export COLORED_STDERR_POST=$'\033[0m' # default
 140
 141 Or to be more compatible you can use the following which should work in any
 142 Bourne shell:
 143
 144     esc=`printf '\033'`
 145     COLORED_STDERR_PRE="${esc}[91m" # bright red
 146     COLORED_STDERR_POST="${esc}[0m" # default
 147     export COLORED_STDERR_PRE COLORED_STDERR_POST
 148
 149 Fix `reset`; its writes to the terminal must be unaltered. `reset` is a
 150 symbolic-link to `tset` on some systems, adapt as necessary:
 151
 152     COLORED_STDERR_IGNORED_BINARIES=/usr/bin/tset
 153     export COLORED_STDERR_IGNORED_BINARIES
 154
 155
 156 DEBUG
 157 -----
 158
 159 To enable debug mode, configure coloredstderr with '--enable-debug'.
 160
 161 *Important:* Debug mode enables `assert()`s in the code which might abort the
 162 process using 'LD_PRELOAD' if an error condition is detected!
 163
 164 Debug mode is slower than normal mode. To log only warnings without the
 165 overhead of debug mode use '--enable-warnings'. `assert()`s are not enabled
 166 with '--enable-warnings', so it's safe to use.
 167
 168 Debug messages are appended to the file `colored_stderr_debug_log.txt` in the
 169 current working directory _if_ it exists. Be careful, this file might grow
 170 very quickly.
 171
 172 *Important:* Warnings are written to `$HOME/colored_stderr_warning_log.txt`
 173 even if it _does not_ exist (only if debug or warning mode is enabled)! If it
 174 doesn't exist it's created. An existing file isn't overwritten, but the
 175 warnings are appended at the end.
 176
 177
 178 KNOWN ISSUES
 179 ------------
 180
 181 - `{fputc,putc,putchar}_unlocked()` are not hooked with glibc when writing to
 182   stdout (which might be redirected to stderr). Can't be fixed as the compiler
 183   inlines the code into the program without calling any function.
 184 - Test `test_stdio.sh` fails on FreeBSD, because FreeBSD does handle the above
 185   correctly (no inlining), but the test is designed for GNU/Linux.
 186 - 'COLORED_STDERR_IGNORED_BINARIES' requires `/proc/self/exe`. Suggestions
 187   welcome.
 188 - Output of `strace` is not always colored correctly as the output from
 189   `coloredstderr` is traced and displayed as well. Suggestions welcome.
 190
 191
 192 BUGS
 193 ----
 194
 195 If you find any bugs not mentioned in this document please report them to
 196 <simon@ruderich.org> with coloredstderr in the subject.
 197
 198
 199 AUTHORS
 200 -------
 201
 202 Written by Simon Ruderich <simon@ruderich.org>.
 203
 204
 205 LICENSE
 206 -------
 207
 208 coloredstderr is licensed under GPL version 3 or later.
 209
 210 Copyright (C) 2013-2018  Simon Ruderich
 211
 212 This program is free software: you can redistribute it and/or modify
 213 it under the terms of the GNU General Public License as published by
 214 the Free Software Foundation, either version 3 of the License, or
 215 (at your option) any later version.
 216
 217 This program is distributed in the hope that it will be useful,
 218 but WITHOUT ANY WARRANTY; without even the implied warranty of
 219 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 220 GNU General Public License for more details.
 221
 222 You should have received a copy of the GNU General Public License
 223 along with this program.  If not, see <http://www.gnu.org/licenses/>.