README
======
-coloredstderr is a small library which uses 'LD_PRELOAD' to color stderr.
-
+coloredstderr is a small library which uses 'LD_PRELOAD' to color stderr. It
+``follows'' dups, has minimal performance overhead and can ignore certain
+binaries.
Like all solutions using 'LD_PRELOAD' it only works with dynamically linked
binaries. Statically linked binaries, for example valgrind, are not supported.
setuid binaries are also not supported ('LD_PRELOAD' disabled for security
reasons).
-
It was inspired by stderred [2]. Similar solutions (using 'LD_PRELOAD')
include:
Most other existing solutions use a second process which colors its input and
pipe stderr to it. However this creates different runtime behaviour resulting
in a different ordering of the output. Partial lines (no newline) also often
-cause problems.
+cause problems. coloredstderr handles these cases correctly (but has other
+possible issues, see below).
+
+coloredstderr is licensed under GPL 3 (or later).
DEPENDENCIES
------------
- C99 compiler (variable length arrays)
-- dynamic linker/loader which supports 'LD_PRELOAD' (e.g. GNU/Linux's ld.so)
+- dynamic linker/loader which supports 'LD_PRELOAD' (e.g. GNU/Linux's or
+ FreeBSD's ld.so)
INSTALLATION
------------
+If you're using the Git version, run `autoreconf -fsi` first to generate
+`configure`.
+
./configure && make && make check
Then either install the library with `make install` or just copy it from
*Important:* If you install `libcoloredstderr.so` manually, make sure _not_ to
use plain `cp` to overwrite an existing `libcoloredstderr.so` file which is in
-use! Doing so will crash all processes which were started with 'LD_PRELOAD'
+use! Doing so will crash most processes which were started with 'LD_PRELOAD'
set to this file. This is not a bug in coloredstderr, but a general problem.
`cp` truncates the file which causes the `mmap()` ed library to be in an
inconsistent state causing a segmentation fault when using any functions of
COLORED_STDERR_FDS=2,
export LD_PRELOAD COLORED_STDERR_FDS
+To use coloredstderr with multi-lib (multiple architectures on the same
+system, e.g. i386 and amd64), your system must support the '$LIB' variable in
+'LD_PRELOAD'. Then you can build coloredstderr for all architectures and use
+'$LIB' in 'LD_PRELOAD'. The following should work for Debian-based systems
+with this directory structure:
+
+ dir
+ `-- lib
+ |-- i386-linux-gnu
+ | `-- libcoloredstderr.so
+ `-- x86_64-linux-gnu
+ `-- libcoloredstderr.so
+
+Now set 'LD_PRELOAD'. `lib/` is included in '$LIB'!
+
+ LD_PRELOAD='/absolute/path/to/dir/$LIB/libcoloredstderr.so'
+
+The single quotes are important. '$LIB' is not evaluated by the shell, but by
+the loader (`man ld.so`). Now both i386 and amd64 binaries automatically use
+coloredstderr.
+
The following additional environment variables are available:
- 'COLORED_STDERR_PRE'
- String to write before each write to stderr, defaults to "\033[91m" (bright
- red).
+ String to write before each write to stderr, defaults to "\033[31m" (red).
- 'COLORED_STDERR_POST'
String to write after each write to stderr, defaults to "\033[0m" (reset
color).
If set to an non-empty value add pre/post strings even when not writing to a
terminal, e.g. when writing to a file. By default, only writes to a terminal
are colored.
+- 'COLORED_STDERR_IGNORED_BINARIES'
+ Comma separated list of binary names/paths which should not be tracked
+ (including their children). Useful for `reset` which writes to the terminal,
+ but fails to work if the output is colored. See below for an example.
+ Requires `/proc/self/exe`.
+
+All environment variables starting with 'COLORED_STDERR_PRIVATE_*' are
+internal variables used by the implementation and should not be set manually.
+See the source for details.
To set custom colors as pre/post strings you can use the `$''` feature of Bash
Bourne shell:
esc=`printf '\033'`
- COLORED_STDERR_PRE="${esc}[91m" # red
+ COLORED_STDERR_PRE="${esc}[91m" # bright red
COLORED_STDERR_POST="${esc}[0m" # default
export COLORED_STDERR_PRE COLORED_STDERR_POST
+Fix `reset`; its writes to the terminal must be unaltered. `reset` is a
+symbolic-link to `tset` on some systems, adapt as necessary:
+
+ COLORED_STDERR_IGNORED_BINARIES=/usr/bin/tset
+ export COLORED_STDERR_IGNORED_BINARIES
+
DEBUG
-----
To enable debug mode, configure coloredstderr with '--enable-debug'.
*Important:* Debug mode enables `assert()`s in the code which might abort the
-process if an error condition is detected!
+process using 'LD_PRELOAD' if an error condition is detected!
Debug mode is slower than normal mode. To log only warnings without the
overhead of debug mode use '--enable-warnings'. `assert()`s are not enabled
with '--enable-warnings', so it's safe to use.
-Debug messages are written to the file `colored_stderr_debug_log.txt` in the
-current working directory _if_ it exists. If it exists debug messages are
-appended. Be careful, this file might grow very quickly.
+Debug messages are appended to the file `colored_stderr_debug_log.txt` in the
+current working directory _if_ it exists. Be careful, this file might grow
+very quickly.
*Important:* Warnings are written to `$HOME/colored_stderr_warning_log.txt`
even if it _does not_ exist (only if debug or warning mode is enabled)! If it
warnings are appended at the end.
+KNOWN ISSUES
+------------
+
+- `{fputc,putc,putchar}_unlocked()` are not hooked with glibc when writing to
+ stdout (which might be redirected to stderr). Can't be fixed as the compiler
+ inlines the code into the program without calling any function.
+- Test `test_stdio.sh` fails on FreeBSD, because FreeBSD does handle the above
+ correctly (no inlining), but the test is designed for GNU/Linux.
+- 'COLORED_STDERR_IGNORED_BINARIES' requires `/proc/self/exe`. Suggestions
+ welcome.
+- Output of `strace` is not always colored correctly as the output from
+ `coloredstderr` is traced and displayed as well. Suggestions welcome.
+
+
BUGS
----
coloredstderr is licensed under GPL version 3 or later.
-Copyright (C) 2013 Simon Ruderich
+Copyright (C) 2013-2014 Simon Ruderich
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
ruderich.org/simon / coloredstderr / coloredstderr.git / blobdiff