colorredstderr-mirror/README

README
======

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:

- 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. 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 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
`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
-----

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

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[31m" (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.
- '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
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
-----

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'. `assert()`s are not enabled
with '--enable-warnings', so it's safe to use.

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
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 `/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
----

If you find any bugs not mentioned in this document please report them to
<simon@ruderich.org> with coloredstderr in the subject.


AUTHORS
-------

Written by Simon Ruderich <simon@ruderich.org>.


LICENSE
-------

coloredstderr is licensed under GPL version 3 or later.

Copyright (C) 2013-2018  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 <http://www.gnu.org/licenses/>.