X-Git-Url: https://ruderich.org/simon/gitweb/?p=coloredstderr%2Fcoloredstderr.git;a=blobdiff_plain;f=README;h=3416100224af7572702f2981119692f5eddeecde;hp=e00fdfaf2be4186fa4cafdabed62511049ecf06c;hb=8793959e82e055ca063fb1d724eb12eec0afd701;hpb=b24bd8dc4367f3adc443e4acb954326f38098c53 diff --git a/README b/README index e00fdfa..3416100 100644 --- a/README +++ b/README @@ -1,11 +1,15 @@ 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 (requires /proc). 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') @@ -21,14 +25,43 @@ 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. + +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 +------------ + + ./configure && make && make check + +Then either install the library with `make install` or just copy it from +`src/.libs/` to wherever you want to install it: + + rm -f /destination/path/for/library/libcoloredstderr.so + cp -L src/.libs/libcoloredstderr.so /destination/path/for/library/ + +*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 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 +the library. Just remove the file first and then copy it. `make install` +handles the install in this way and is therefore not affected. + +As a simple safeguard, `make` builds and installs the `libcoloredstderr.so` +file non-writable to prevent accidental overwrites. Even if the overwrite is +forced with `cp -f`, the file is unlinked and recreated by `cp` because the +file is non-writable, preventing the problem. USAGE @@ -57,8 +90,7 @@ A default setup could look like this: 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). @@ -66,6 +98,35 @@ The following additional environment variables are available: 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. + +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 +and Zsh: + + export COLORED_STDERR_PRE=$'\033[91m' # bright red + export COLORED_STDERR_POST=$'\033[0m' # default + +Or to be more compatible you can use the following which should work in any +Bourne shell: + + esc=`printf '\033'` + 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 @@ -73,12 +134,16 @@ DEBUG To enable debug mode, configure coloredstderr with '--enable-debug'. +*Important:* Debug mode enables `assert()`s in the code which might abort the +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'. +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 @@ -86,6 +151,20 @@ doesn't exist it's created. An existing file isn't overwritten, but the 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 the `/proc` file system. + Suggestions welcome. +- Output of `strace` is not always colored correctly as the output from + `coloredstderr` is traced and displayed as well. + + BUGS ----