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