X-Git-Url: https://ruderich.org/simon/gitweb/?p=coloredstderr%2Fcoloredstderr.git;a=blobdiff_plain;f=README;h=3416100224af7572702f2981119692f5eddeecde;hp=a99edfa3f2952a79f07a2dc519de87c57055f7d7;hb=8793959e82e055ca063fb1d724eb12eec0afd701;hpb=d08a5128063fd06ea80915d38cc29ac07015ff0e

diff --git a/README b/README
index a99edfa..3416100 100644
--- a/README
+++ b/README
@@ -1,7 +1,9 @@
 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
@@ -23,14 +25,17 @@ 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
@@ -46,7 +51,7 @@ 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
@@ -93,6 +98,10 @@ 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.
@@ -109,10 +118,16 @@ 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" # 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
 -----
@@ -120,15 +135,15 @@ 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
@@ -139,9 +154,15 @@ warnings are appended at the end.
 KNOWN ISSUES
 ------------
 
-- `{fputc,putc,putchar}_unlocked()` are not hooked when writing to stdout
-  (which might be redirected to stderr). Can't be fixed as the compiler
+- `{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