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