version 1.3

exceptions4c Reference Documentation

sheep_064.png

exceptions4c

Version:
1.3
Author:
Copyright (c) 2010 Guillermo Calvo
See also:
http://code.google.com/p/exceptions4c/

An exception handling framework for C

Bring the power of exceptions to your C applications with this tiny, portable exception handling framework for C!

This library provides you a simple set of keywords (macros, actually) which map the semantics of exception handling you're probably already used to:

You can write try/catch/finally blocks just as if you were coding in Java:

 int foo;
 void * buffer = malloc(1024);
  
 try{
     foo = bar(buffer);
 }catch(BadUserInputException){
     foo = 123;
 }finally{
     free(buffer);
 }
 

This way you will never have to deal again with boring error codes, or check return values every time you call a function.

Dispose Pattern

There are other keywords related to resource handling:

They allow you to use the Dispose Pattern in your code:

 FILE * file;
 usingFile(file, "log.txt", "a"){
     fputs("hello, world!\n", file);
 }
  
 Foo foo;
 with(foo, disposeFoo) foo = acquireFoo(bar, foobar); use fooSomething(foo);
  
 Bar bar;
 using(Bar, bar, ("BAR", 123) ){
     barSomething(bar);
 }
 

This is a clean and terse way to handle all kinds of resources with implicit acquisition and automatic disposal.

Signal Handling

In addition, signals (such as SIGHUP, SIGFPE and SIGSEGV) can be handled in an exceptional way. Forget about scary segmentation faults, all you need is to catch BadPointerException:

 int * pointer = NULL;
  
 try{
     int oops = *pointer;
 }catch(BadPointerException){
     printf("No problem ;-)");
 }
 

Multithreading

If you are using threads in your program, you must enable the thread-safe version of the library by defining E4C_THREAD_SAFE at compiler level.

The usage of the framework does not vary between single and multithreaded programs. The same semantics apply. The only caveat is that the behaviour of signal handling is undefined in a multithreaded program so use this feature with caution.

Portability

This library should compile in any good old C compiler. It uses nothing but standard C functions. In order to use exceptions4c you have to drop the two files (except4c.h and except4c.c) in your project and remember to include the header file from your code.

In case your application uses threads, exceptions4c relies on pthreads, the POSIX application programming interface for writing multithreaded applications. This API is available for most operating systems and platforms.

License

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

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


exceptions4c version 1.3
Copyright 2010 Guillermo Calvo.

Generated on 24 Jan 2010 by doxygen 1.6.2