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
  92 The following additional environment variables are available:
  93
  94 - 'COLORED_STDERR_PRE'
  95   String to write before each write to stderr, defaults to "\033[31m" (red).
  96 - 'COLORED_STDERR_POST'
  97   String to write after each write to stderr, defaults to "\033[0m" (reset
  98   color).
  99 - 'COLORED_STDERR_FORCE_WRITE'
 100   If set to an non-empty value add pre/post strings even when not writing to a
 101   terminal, e.g. when writing to a file. By default, only writes to a terminal
 102   are colored.
 103 - 'COLORED_STDERR_IGNORED_BINARIES'
 104   Comma separated list of binary names/paths which should not be tracked
 105   (including their children). Useful for `reset` which writes to the terminal,
 106   but fails to work if the output is colored. See below for an example.
 107   Requires `/proc/self/exe`.
 108
 109 All environment variables starting with 'COLORED_STDERR_PRIVATE_*' are
 110 internal variables used by the implementation and should not be set manually.
 111 See the source for details.
 112
 113
 114 To set custom colors as pre/post strings you can use the `$''` feature of Bash
 115 and Zsh:
 116
 117     export COLORED_STDERR_PRE=$'\033[91m' # bright red
 118     export COLORED_STDERR_POST=$'\033[0m' # default
 119
 120 Or to be more compatible you can use the following which should work in any
 121 Bourne shell:
 122
 123     esc=`printf '\033'`
 124     COLORED_STDERR_PRE="${esc}[91m" # bright red
 125     COLORED_STDERR_POST="${esc}[0m" # default
 126     export COLORED_STDERR_PRE COLORED_STDERR_POST
 127
 128 Fix `reset`; its writes to the terminal must be unaltered. `reset` is a
 129 symbolic-link to `tset` on some systems, adapt as necessary:
 130
 131     COLORED_STDERR_IGNORED_BINARIES=/usr/bin/tset
 132     export COLORED_STDERR_IGNORED_BINARIES
 133
 134
 135 DEBUG
 136 -----
 137
 138 To enable debug mode, configure coloredstderr with '--enable-debug'.
 139
 140 *Important:* Debug mode enables `assert()`s in the code which might abort the
 141 process using 'LD_PRELOAD' if an error condition is detected!
 142
 143 Debug mode is slower than normal mode. To log only warnings without the
 144 overhead of debug mode use '--enable-warnings'. `assert()`s are not enabled
 145 with '--enable-warnings', so it's safe to use.
 146
 147 Debug messages are appended to the file `colored_stderr_debug_log.txt` in the
 148 current working directory _if_ it exists. Be careful, this file might grow
 149 very quickly.
 150
 151 *Important:* Warnings are written to `$HOME/colored_stderr_warning_log.txt`
 152 even if it _does not_ exist (only if debug or warning mode is enabled)! If it
 153 doesn't exist it's created. An existing file isn't overwritten, but the
 154 warnings are appended at the end.
 155
 156
 157 KNOWN ISSUES
 158 ------------
 159
 160 - `{fputc,putc,putchar}_unlocked()` are not hooked with glibc when writing to
 161   stdout (which might be redirected to stderr). Can't be fixed as the compiler
 162   inlines the code into the program without calling any function.
 163 - Test `test_stdio.sh` fails on FreeBSD, because FreeBSD does handle the above
 164   correctly (no inlining), but the test is designed for GNU/Linux.
 165 - 'COLORED_STDERR_IGNORED_BINARIES' requires `/proc/self/exe`. Suggestions
 166   welcome.
 167 - Output of `strace` is not always colored correctly as the output from
 168   `coloredstderr` is traced and displayed as well. Suggestions welcome.
 169
 170
 171 BUGS
 172 ----
 173
 174 If you find any bugs not mentioned in this document please report them to
 175 <simon@ruderich.org> with coloredstderr in the subject.
 176
 177
 178 AUTHORS
 179 -------
 180
 181 Written by Simon Ruderich <simon@ruderich.org>.
 182
 183
 184 LICENSE
 185 -------
 186
 187 coloredstderr is licensed under GPL version 3 or later.
 188
 189 Copyright (C) 2013-2014  Simon Ruderich
 190
 191 This program is free software: you can redistribute it and/or modify
 192 it under the terms of the GNU General Public License as published by
 193 the Free Software Foundation, either version 3 of the License, or
 194 (at your option) any later version.
 195
 196 This program is distributed in the hope that it will be useful,
 197 but WITHOUT ANY WARRANTY; without even the implied warranty of
 198 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 199 GNU General Public License for more details.
 200
 201 You should have received a copy of the GNU General Public License
 202 along with this program.  If not, see <http://www.gnu.org/licenses/>.