From b24bd8dc4367f3adc443e4acb954326f38098c53 Mon Sep 17 00:00:00 2001 From: Simon Ruderich Date: Mon, 10 Jun 2013 22:33:59 +0200 Subject: [PATCH] README: Add. --- README | 120 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 120 insertions(+) create mode 100644 README diff --git a/README b/README new file mode 100644 index 0000000..e00fdfa --- /dev/null +++ b/README @@ -0,0 +1,120 @@ +README +====== + +coloredstderr is a small library which uses 'LD_PRELOAD' to color stderr. + + +Like all solutions using 'LD_PRELOAD' it only works with dynamically linked +binaries. Statically linked binaries, for example valgrind, are not supported. + + +It was inspired by stderred [2]. Similar solutions (using 'LD_PRELOAD') +include: + +- stderred [1], but doesn't `follow' dups (I somehow missed it when looking + for existing implementations) +- stderred [2], but only hooks `write()` + +[1]: https://github.com/sickill/stderred +[2]: https://github.com/trapd00r/stderred + +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. + + +DEPENDENCIES +------------ + +- C99 compiler (variable length arrays) +- dynamic linker/loader which supports 'LD_PRELOAD' (e.g. GNU/Linux's ld.so) + + +USAGE +----- + +Set 'LD_PRELOAD' to include the _absolute_ path to `libcoloredstderr.so`: + + LD_PRELOAD=/absolute/path/to/libcoloredstderr.so + +The 'COLORED_STDERR_FDS' environment variable must be set to the file +descriptors which should be colored (comma separated list). Normally this is +just 2 (stderr): + + COLORED_STDERR_FDS=2, + +The trailing comma is important! + + +A default setup could look like this: + + LD_PRELOAD="$HOME/bin/libcoloredstderr.so" + COLORED_STDERR_FDS=2, + export LD_PRELOAD COLORED_STDERR_FDS + + +The following additional environment variables are available: + +- 'COLORED_STDERR_PRE' + String to write before each write to stderr, defaults to "\033[91m" (bright + red). +- 'COLORED_STDERR_POST' + String to write after each write to stderr, defaults to "\033[0m" (reset + color). +- 'COLORED_STDERR_FORCE_WRITE' + 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. + + +DEBUG +----- + +To enable debug mode, configure coloredstderr with '--enable-debug'. + +Debug mode is slower than normal mode. To log only warnings without the +overhead of debug mode use '--enable-warnings'. + +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. + +*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 +doesn't exist it's created. An existing file isn't overwritten, but the +warnings are appended at the end. + + +BUGS +---- + +If you find any bugs not mentioned in this document please report them to + with coloredstderr in the subject. + + +AUTHORS +------- + +Written by Simon Ruderich . + + +LICENSE +------- + +coloredstderr is licensed under GPL version 3 or later. + +Copyright (C) 2013 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 +the Free Software Foundation, either version 3 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program. If not, see . -- 2.43.2