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

exceptions4c Reference Documentation

exceptions4c

exceptions4c

Version
3.0
Author
Copyright (c) 2013 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!

This library provides you with 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.

Exception Hierarchies

The possible exceptions in a program are organized in a pseudo-hierarchy of exceptions. RuntimeException is the root of the exceptions pseudo-hierarchy. Any exception can be handled by a code block introduced by catch(RuntimeException), except for AssertionException.

When an exception is thrown, control is transferred to the nearest dynamically-enclosing catch code block that handles the exception. Whether a particular catch block handles an exception is found out by comparing the type (and supertypes) of the actual thrown exception against the specified exception type in the catch clause.

A catch block is given an exception type as a parameter. This parameter determines the set of exceptions that can be handled by the code block. A block handles an actual exception that was thrown if the specified type parameter is either:

  • the same type of that exception.
  • the same type of any of the supertypes of that exception.

If you write a catch block that handles an exception with no defined subtypes, it will only handle that very specific exception. By grouping exceptions into hierarchies, you can design generic catch blocks that deal with several exceptions.

Dispose Pattern

There are other keywords related to resource handling:

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

FOO foo;
with(foo, dispose_FOO) foo = acquire_FOO(bar, foobar); use do_something(foo);
...
BAR bar;
using(BAR, bar, ("BAR", 123) ){
do_something_else(bar);
}
...
FILE * file;
e4c_using_file(file, "log.txt", "a"){
fputs("hello, world!\n", file);
}

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 to do is 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 switch on the thread-safe version of the library by defining E4C_THREADSAFE at compiler level.

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

Integration

Whether you are developing a standalone application, or an external library that provides services to independent programs, you can integrate exceptions4c in your code very easily.

The system provides a mechanism for implicit initialization and finalization of the exception framework, so that it is safe to use try, catch, throw, etc. from any external function, even if the rest of the program does not leverage the exception system at all.

Portability

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

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.

Software 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/.

Required:
  • License and copyright notice: Include a copy of the license and copyright notice with the code.
  • Library usage: The library may be used within a non-open-source application.
  • Disclose Source: Source code for this library must be made available when distributing the software.
Permitted:
  • Commercial Use: This software and derivatives may be used for commercial purposes.
  • Modification: This software may be modified.
  • Distribution: You may distribute this software.
  • Sublicensing: You may grant a sublicense to modify and distribute this software to third parties not included in the license.
  • Patent Grant: This license provides an express grant of patent rights from the contributor to the recipient.
Forbidden:
  • Hold Liable: Software is provided without warranty and the software author/license owner cannot be held liable for damages.

Documentation License

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts and no Back-Cover Texts. See the GNU Free Documentation License for more details.