README
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Contents
========

        1. Description of Stacktrace
        2. Quick build
        3. Using it
        4. License of Stacktrace


1. Description of Stacktrace
============================

  Stacktrace is a little utility library, that permits to print the contenst of
  the stack in a readable manner, when some event is received or when program
  decides to print it (for debugging purpouses, maybe).

  The look'n'feel of the printed stacktrace is similar to java's stacktrace,
  but symbol names are fetch from the binary ELF structures.

  If you have any idea or suggestion, or if you think you have found a bug, you
  can contact me at
  
    Gerardo García Peña <gerardo@kung-foo.net>


2. Quick build
==============

  Stacktrace have not yet a installer program or procedure. Perhaps next version.

  The result of compiling Stacktrace is three library files:

    - stacktrace.so    - A dynamic library prepared for use with LD_PRELOAD.
    - libstacktrace.so - A dynamic library useful if you want to include an
                         stacktrace feature in your program.
    - libstacktrace.a  - A static library useful if you want to include an
                         stacktrace feature in your program.

  For building these files go to a temporary directory (in this example we will
  use /var/tmp) and uncompress Stacktrace distribution there.

    $ cd /var/tmp/
    $ zcat <your stacktrace-1.2.0.tar.gz dist file> | tar xvf -
    $ cd stacktrace-1.2.0

  Once configured, build the package:

    $ make

  And if you want to install it in your system:

    $ make install

  If you want to check the installation procedure before installing (to see
  what is installed and where), use:

    $ make -n install

  And if you want to change destination directories, edit the Makefile and
  change the configuration variables BINDIR, DOCDIR, INCDIR and LIBDIR.


3. Using Stacktrace
===================

  Dynamic preload library
  -----------------------

  To use the dynamic library as LD_PRELOAD library you only have to call your
  program in this way:

    $ LD_PRELOAD=./stacktrace.so ./your_program

  Or using the wrapper provided in this package:

    $ stacktrace /bin/ls ~/*

  The 'stacktrace.so' dynamic shared object (dynamic library) will be loaded
  and initialized before your program starts (main). This library routes most
  signals to itself, to be able to catch any of them before your program
  crashes or finishes, and then print an stacktrace.

  Static library
  --------------

  Stacktrace can be linked against your program. Stacktrace offers two
  functions:

    void stacktrace_init(int signal_hook);

      This function initializes the Stacktrace engine.

      It receives only one boolean parameter. If this parameter is a non-zero
      integer, the initialization routine will route most signals to the
      stacktrace library. Otherwise signals will be left untouched.

    void stacktrace(void);

      Prints a nice stacktrace on stderr.

  Dynamic library
  ---------------

  It can be used in the same way that the static library, but you also can load
  it dinamically in your program, making 'stacktrace' a soft dependency only
  used if available in the system.

  Example:

    (1) add a new global var - it will contain the handler
        that references the stacktrace library loaded at runtime.

          void *lst = NULL;

    (2) loading stacktrace at runtime - following code snipet
        should be included in your program initialization.

          if((lst = dlopen("libstacktrace.so", RTLD_LAZY)) != NULL)
          {
            void (*stacktrace_init)(int) = dlsym(lst, "stacktrace_init");
            int  (*stacktrace_version_check)(int, int, int) = dlsym(lst, "stacktrace_version_check");

            if(!dlerror() && stacktrace_version_check(1, 2, 0))
            {
              stacktrace_init(1); /* enable signal hooking */
            } else {
              dlclose(lst);
              lst = NULL;
            }
          } else
            printf("! stacktrace not installed\n"
                   "- You should consider installing it, it's really useful!\n");

    (2) using it in your program - whenever you need to print
        a nice stacktrace, you only need to copy following
        lines:

          if(lst)
          {
            void *(*stacktrace)(void) = dlsym(lst, "stacktrace");
            stacktrace();
          } else
            printf("! stacktrace library not available.
                   "- I warned you that you'll need it in the future!");


4. Other thoughts
=================

  If you compile your programs with the GNU C flag -rdynamic all symbols will
  be exported, not only used symbols, making backtrace(3) functionalities
  similar to stacktrace. The main difference between backtrace(3) and
  stacktrace resides on that it is not necessary to rebuild your programs to
  get a decent stack backtrace information in case of problems.


5. License of Stacktrace
========================

  All Stacktrace files are governed by the GPL license (GNU General Public License,
  see file `COPYING' in this directory),


-----
Stacktrace - Stacktrace printer.
  (C) 2008-2010 Gerardo García Peña <gerardo@kung-foo.net>

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 2 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, write to the Free Software Foundation, Inc., 51 Franklin
Street, Fifth Floor, Boston, MA  02110-1301  USA