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 USAGE
  35 -----
  36
  37 Set 'LD_PRELOAD' to include the _absolute_ path to `libcoloredstderr.so`:
  38
  39     LD_PRELOAD=/absolute/path/to/libcoloredstderr.so
  40
  41 The 'COLORED_STDERR_FDS' environment variable must be set to the file
  42 descriptors which should be colored (comma separated list). Normally this is
  43 just 2 (stderr):
  44
  45     COLORED_STDERR_FDS=2,
  46
  47 The trailing comma is important!
  48
  49
  50 A default setup could look like this:
  51
  52     LD_PRELOAD="$HOME/bin/libcoloredstderr.so"
  53     COLORED_STDERR_FDS=2,
  54     export LD_PRELOAD COLORED_STDERR_FDS
  55
  56
  57 The following additional environment variables are available:
  58
  59 - 'COLORED_STDERR_PRE'
  60   String to write before each write to stderr, defaults to "\033[91m" (bright
  61   red).
  62 - 'COLORED_STDERR_POST'
  63   String to write after each write to stderr, defaults to "\033[0m" (reset
  64   color).
  65 - 'COLORED_STDERR_FORCE_WRITE'
  66   If set to an non-empty value add pre/post strings even when not writing to a
  67   terminal, e.g. when writing to a file. By default, only writes to a terminal
  68   are colored.
  69
  70
  71 DEBUG
  72 -----
  73
  74 To enable debug mode, configure coloredstderr with '--enable-debug'.
  75
  76 Debug mode is slower than normal mode. To log only warnings without the
  77 overhead of debug mode use '--enable-warnings'.
  78
  79 Debug messages are written to the file `colored_stderr_debug_log.txt` in the
  80 current working directory _if_ it exists. If it exists debug messages are
  81 appended. Be careful, this file might grow very quickly.
  82
  83 *Important:* Warnings are written to `$HOME/colored_stderr_warning_log.txt`
  84 even if it _does not_ exist (only if debug or warning mode is enabled)! If it
  85 doesn't exist it's created. An existing file isn't overwritten, but the
  86 warnings are appended at the end.
  87
  88
  89 BUGS
  90 ----
  91
  92 If you find any bugs not mentioned in this document please report them to
  93 <simon@ruderich.org> with coloredstderr in the subject.
  94
  95
  96 AUTHORS
  97 -------
  98
  99 Written by Simon Ruderich <simon@ruderich.org>.
 100
 101
 102 LICENSE
 103 -------
 104
 105 coloredstderr is licensed under GPL version 3 or later.
 106
 107 Copyright (C) 2013  Simon Ruderich
 108
 109 This program is free software: you can redistribute it and/or modify
 110 it under the terms of the GNU General Public License as published by
 111 the Free Software Foundation, either version 3 of the License, or
 112 (at your option) any later version.
 113
 114 This program is distributed in the hope that it will be useful,
 115 but WITHOUT ANY WARRANTY; without even the implied warranty of
 116 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 117 GNU General Public License for more details.
 118
 119 You should have received a copy of the GNU General Public License
 120 along with this program.  If not, see <http://www.gnu.org/licenses/>.