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