exceptions4c   version 3.0
An exception handling framework for C
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
e4c_st_g.h File Reference

exceptions4c gcc stack trace header file More...

#include "e4c.h"

Functions

void e4c_stack_trace_print_exception (const e4c_exception *exception)
 Prints a fatal error message and backtrace regarding the uncaught exception. More...
 
void * e4c_stack_trace_initialize (const e4c_exception *exception)
 Initializes the backtrace of a newly created exception. More...
 
void e4c_stack_trace_finalize (void *custom_data)
 Finalizes the backtrace of an exception which is about to be destroyed. More...
 

Detailed Description

exceptions4c gcc stack trace header file

Version
2.0
Author
Copyright (c) 2012 Guillermo Calvo

exceptions4c gcc stack trace header file

This extension allows exceptions4c to print a trace stack regarding an uncaught exception:

Uncaught RuntimeException: He who foos last, foos best.
thrown at thud (foobar.c:9)
from xyzzy (foobar.c:20)
from plugh (foobar.c:25)
from fred (foobar.c:30)
from waldo (foobar.c:35)
from garply (foobar.c:40)
from grault (foobar.c:45)
from corge (foobar.c:50)
from quux (foobar.c:55)
from qux (foobar.c:63)
from baz (foobar.c:68)
from bar (foobar.c:75)
from foo (foobar.c:84)
from main (foobar.c:96)

You need to set up the provided exception context handlers through the function e4c_context_set_handlers:

int main(int argc, char *argv[]){
e4c_context_set_handlers(
e4c_stack_trace_print_exception,
argv[0],
e4c_stack_trace_initialize,
e4c_stack_trace_finalize
);
// ...
}
}

This module needs to be compiled with GCC (the GNU Compiler Collection). It depends on the GCC Function Instrumentation and Generate debugging information functionality. They can be enabled by using the compiler parameters:

  • -finstrument-functions
  • -g3

License

This is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This software 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 Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this software. If not, see http://www.gnu.org/licenses/.

Function Documentation

void e4c_stack_trace_finalize ( void *  custom_data)

Finalizes the backtrace of an exception which is about to be destroyed.

Parameters
custom_dataThe backtrace to be finalized

This function disposes of the call stack captured at the moment the exception was thrown.

It must be passed to e4c_context_set_handlers as the handler for finalizing the custom data of an exception, along with e4c_stack_trace_initialize and e4c_stack_trace_print_exception.

See Also
e4c_context_set_handlers
e4c_stack_trace_initialize
e4c_stack_trace_print_exception
e4c_initialize_handler
e4c_finalize_handler
e4c_uncaught_handler
void* e4c_stack_trace_initialize ( const e4c_exception exception)

Initializes the backtrace of a newly created exception.

Parameters
exceptionThe newly created exception
Returns
The backtrace to be assigned to the exception

This function captures the call stack at the moment the exception is being thrown. It expects that the initial value of the custom data is a text string containing the path to the executing program.

It must be passed to e4c_context_set_handlers as the handler for initializing the custom data of an exception, along with e4c_stack_trace_finalize and e4c_stack_trace_print_exception.

See Also
e4c_context_set_handlers
e4c_stack_trace_finalize
e4c_stack_trace_print_exception
e4c_initialize_handler
e4c_finalize_handler
e4c_uncaught_handler
void e4c_stack_trace_print_exception ( const e4c_exception exception)

Prints a fatal error message and backtrace regarding the uncaught exception.

Parameters
exceptionThe uncaught exception

This function prints the exception and its backtrace to the standard error output. The stack trace represents the reverse path of execution at the moment the exception was thrown.

It must be passed to e4c_context_set_handlers as the handler for uncaught exceptions, along with e4c_stack_trace_initialize and e4c_stack_trace_finalize.

See Also
e4c_context_set_handlers
e4c_stack_trace_initialize
e4c_stack_trace_finalize
e4c_initialize_handler
e4c_finalize_handler
e4c_uncaught_handler