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