README: Update.

[coloredstderr/coloredstderr.git] / README

diff --git a/README b/README
index a99edfa3f2952a79f07a2dc519de87c57055f7d7..3416100224af7572702f2981119692f5eddeecde 100644 (file)
--- a/README
+++ b/README
@@ -1,7 +1,9 @@
 README
 ======
 
 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
 
 
 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
 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)
 
 
 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
 
 
 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
 
 *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
 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.
   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.
 
 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'`
 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
 
     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
 -----
 
 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
 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 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
 
 *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
 ------------
 
 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.
   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
 
 
 BUGS