Some languages offer features to allow exception management, or exception handling. Here by exception I mean an exceptional event which should not happen in the normal flow of an algorithm. C does not provide such a feature. Wouldn't it be nice to have such a feature in C too ?

Why use exception management ?

The only mention of 'exceptional' and 'normal' in the sentence above should trigger a red alarm in every one's head. What's exceptional ? What's normal ? It surely depends on the context of every project. If you're writing a software for a satellite in outer space, or a software running in a cosy environment like your bedroom, a bit flip due to radiation surely doesn't look the same to you. And there you have again some egg's war about what's an exception and how you should care about. So disclaimer, I don't mean to say with this article what should be considered an exception, neither that you have to do exception management, neither that if you do you have to do it the way I introduce here. It's really just about introducing a method which you could use if you think it fits your needs.

The way I've been taught to handle exceptions in C was to return an error code from the function susceptible to encounter an exception (like printf returning a negative value if an output error occured). If the function already has to return a value, it may use the same 'channel', like again printf whose returned value is the number of characters printed if no error occured. If the returned value's type does not allow to use the same channel, a global variable can be used instead (like errno when fopen fails), or a reference to a variable can be passed in argument and this variable is set as needed.

So, if there is already a way to manage exception, why bother looking for another one ? I think these methods are unsastifying because they are inconsistent while representing the same concept, and they put the exception at the place of something conceptually different: the input or the output of the function. In other word they pollute the interface of the function. A more elegant way would be to have a dedicated third channel for the exception. Moreover, a key component of an exception management system is the interruption of the flow of the algorithm implemented by the function. This component is left unaddressed by the methods above.

These considerations define the specification of the exception management solution I was hoping for in C: not cluttering the input/output interface of the function, not cluttering the code of the 'normal' algorithm of the function, and allowing interruption of the normal flow of the algorithm when an exception occurs.

How to implement an exception management in standard C.

The base idea to implement exception management in C is to use the setjmp/longjmp instructions. The idea is not new, Peter Van Der Linden speaks about it in his book "Expert C Programming" in 1994, and others, EmptyQ for example, did it before. The setjmp/longjmp instructions allow to 'bookmark' a point in time in the execution of a program and come back to it later. Yes, "Back to the Future" in C, sounds great no ? At first it looks like a goto, but it's a bit different. A goto can only move the execution pointer to somewhere in the same scope. longjmp can instead jump anywhere that has been passed through since the beginning of the execution. The code below gives a simple example of how to use setjmp and longjmp.

// Include stdio.h for printf #include <stdio.h> // Include setjmp.h for setjmp and longjmp #include <setjmp.h> // Some declarations void BackToTheFuture(void); struct Doc; void Year1955(volatile struct Doc* doc); void Year1985(volatile struct Doc* doc); // Main function int main() { // Popcorn's ready ? Let's go ! BackToTheFuture(); return 0; } // Structure to memorise some infos about Doc enum docStatus { dead, alive }; enum blouseStatus { notBulletProof, bulletProof }; struct Doc { enum docStatus status; enum blouseStatus blouse; }; // Some macros to define points in time #define YEAR_1955 -1 #define START 0 #define YEAR_1985 1 // This is the variable to memorise the execution environment used by setjmp // and longjmp jmp_buf env; // The movie void BackToTheFuture(void) { // Create the Doc, as it will be modified between the successive jump // we need to declare it as 'volatile' volatile struct Doc doc = {.status = alive, .blouse = notBulletProof}; // Memorise the current execution environment to come back to it later. // setjmp returns 0 or the value sent by longjmp (which must be different // from 0) int when = setjmp(env); // Call the appropriate function depending on 'when' we are in time. // The first time we pass here it will be START, then we'll come back here // and 'when' will be equal to YEAR_1955, and finally once again with 'when' // equals to YEAR_1985 if (when == YEAR_1955) Year1955(&doc); if (when == START || when == YEAR_1985) Year1985(&doc); // End of the movie printf("That's the power of love !\n"); } // What happens in 1985 void Year1985(volatile struct Doc* doc) { // Print some info about what's happening printf("Marty meets Doc\n"); char* strStatus[2] = {"dead", "alive"}; printf("Doc is %s\n", strStatus[doc->status]); printf("Terrorists kill Doc\n"); // The first time we'll pass here doc->blouse is equal to notBulletProof, // the second time it will be bulletProof because it will have been // updated in Year1955() if (doc->blouse != bulletProof) doc->status = dead; printf("Doc is %s\n", strStatus[doc->status]); if (doc->status == dead) { printf("Marty jumps to 1955\n"); // Jump back to the setjmp instruction in BackToTheFuture(), then 'when' // will be equal to YEAR_1955. A call to BackToTheFuture() instead would // jump at the beginning of this function, resetting 'status' in the Doc // structure and creating an infinite loop. Note also that it isn't // possible to use 'goto' here. longjmp(env, YEAR_1955); // The execution will never reach here. } } // What happens in 1955 void Year1955(volatile struct Doc* doc) { // Back in 1955 Doc is alive, update the structure doc->status = alive; // Print some info about what's happening printf("Marty arrives in 1955\n"); printf("Doc is alive\n"); printf("Marty gives a letter to Doc\n"); doc->blouse = bulletProof; printf("Marty goes back to 1985\n"); // Jump back to the setjmp instruction in BackToTheFuture(), then 'when' // will be equal to YEAR_1985. A call to BackToTheFuture() instead would // jump at the beginning of this function, resetting 'blouse' in the Doc // structure and creating an infinite loop. Note also that it isn't // possible to use 'goto' here. longjmp(env, YEAR_1985); // The execution will never reach here. } /* compiles without warning using: gcc -std=c18 -Wall -Wextra -o main main.c outputs: Marty meets doc Doc is alive Terrorists kill Doc Doc is dead Marty jumps to 1955 Marty arrives in 1955 Doc is alive Marty gives a letter to Doc Marty goes back to 1985 Marty meets Doc Doc is alive Terrorists kill Doc Doc is alive That's the power of love ! */

Even on a small example like this, it's already become spaghetti code, so I hope you agree it should be avoided or used with great care. Embedded in the exception management framework introduced here, it's constrained to a safe usage, with the only trap being not declaring the necessary variables as volatile, but this is warned by the compiler so you're safe.

Then, how does it fit the requirements ? To identify the exception we can use the value passed by longjmp, and leave the input/output of the functions clean. The interruption of the flow of the algorithm is fulfilled by longjmp jumping back to setjmp. And the processing of the exception is done in separate blocks of code, those called by setjmp according to the value sent by longjmp. That's a perfect match ! It gives something like this:

... switch(setjmp(env)) { case 0: // Start of the block of code corresponding to the 'normal' flow you // want to guard against exceptions ... // If something 'exceptional' happens during the normal flow, interrupt // it and switch to the block of code dedicated to it's management. These // interruption could even emanate from inside function called from this // block of code if (...) longjmp(env, exceptionA); ... if (...) longjmp(env, exceptionB); ... // End of the block of code you want to guard against exceptions break; case exceptionA: // Block of code to manage exceptionA ... break; case exceptionB: // Block of code to manage exceptionB ... break; } ...

Now we can make it look prettier thanks to our good friend the precompiler:

(in a previous version of this article I was using raise() instead of raiseExc(), this was conflicting the raise() function defined in signal.h, hence the correction)

#define try switch(setjmp(env)) { case 0: #define raiseExc(exc) longjmp(env, exc) #define catch(exc) break;case exc: ... try { // Start of the block of code corresponding to the 'normal' flow ... // Switching to exception management if needed if (...) raiseExc(exceptionA); ... if (...) raiseExc(exceptionB); ... // End of the block of code } catch(exceptionA) { // Block of code to manage exceptionA ... } catch(exceptionB) { // Block of code to manage exceptionB ... } ...

And with a little more macros we can easily add a default block to manage all exceptions without their own management block, and share blocks between several exceptions:

#define try switch(setjmp(env)) { case 0: #define raiseExc(exc) longjmp(env, exc) #define catch(exc) break;case exc: #define catchAlso(exc) case exc: #define catchDefault break;default: ... try { // Start of the block of code corresponding to the 'normal' flow ... // Switching to exception management if needed if (...) raiseExc(exceptionA); ... if (...) raiseExc(exceptionB); ... // End of the block of code } catch(exceptionA) { // Block of code to manage exceptionA ... } catch(exceptionB) catchAlso(exceptionC) { // Block of code to manage exceptionB and exceptionC ... } catchDefault { // Block of code to manage any exception other than exceptionA, // exceptionB and exceptionC ... } ...

Finally, to allow try/catch blocks inside other try/catch blocks, we need several env variables. This can be done with an array of jmp_buf and a variable to keep track of the current depth in the try/catch blocks:

jmp_buf envs[depthMaxTryCatch]; int tryCatchDepth = 0; #define try switch(setjmp(envs[tryCatchDepth++])) { case 0: #define raiseExc(exc) longjmp(envs[tryCatchDepth-1], exc) #define catch(exc) break;case exc: #define catchAlso(exc) case exc: #define catchDefault break;default: #define endCatch --tryCatchDepth ... try { // Start of the block of code corresponding to the 'normal' flow ... // Switching to exception management if needed if (...) raiseExc(exceptionA); ... if (...) raiseExc(exceptionB); ... // End of the block of code } catch(exceptionA) { // Block of code to manage exceptionA ... } catch(exceptionB) catchAlso(exceptionC) { // Block of code to manage exceptionB and exceptionC ... } catchDefault { // Block of code to manage any exception other than exceptionA, // exceptionB and exceptionC ... } endCatch; ...

And here we are. With a few more security and conveniences (conversion from exception ID to string; exception forwarding; ...) which I won't detailed here (because I've already did here) you have a complete, clean, safe and easy to use exception management framework in plain standard C.

Example of use.

To conclude I'll give an example of how to use it and how it can make the code cleaner. I'll consider here the loading of a CSV file. I think it's a good example because it uses memory allocation and input/output operation, which, in case of failure, could probably be considered as exceptional relatively to the loading algorithm itself (again, it really depends on the context). I'll use LibCapy for the implementation of the try/catch framework, and make some shortcuts to simplify the example.

#include <LibCapy/capy.h> // Structure to memorise the CSV struct CSV { char* filename; FILE* fp; int nbCol; int nbRow; int** data; }; // Load the CSV void LoadCSV(struct CSV* const that); // Display the content of the loaded CSV void DisplayCSV(struct CSV const* const that); // Free the memory used by a struct CSV void CSVFree(struct CSV* const that); // Main function // Expect one argument: the path to the csv file int main( int argc, char** argv) { // Exception to manage the wrong number of arguments // User defined exception can be added to manage the special cases // of the application #define excWrongArguments 1000 // Create the CSV instance struct CSV csv = \ { .filename = argv[1], .fp = NULL, .nbCol = 0, .nbRow = 0, .data = NULL }; // Try to load and display the CSV try { // If the user gave no path in argument, raise an exception // The processing of this special case is done in its own block and // doesn't pollute the 'normal' flow if (argc != 2) raiseExc(excWrongArguments); // Load the CSV. // No need to worry about what can go wrong here, if there is a // a problem the exception management framework will take care of it LoadCSV(&csv); // Display the CSV // If the loading as failed the execution has been rerouted toward // the exception management block, no need to worry about failure // here too DisplayCSV(&csv); // Code dedicated to the management of exceptions in their own blocks } catch(excWrongArguments) { println("Usage: main <path to the csv file>."); } catchDefault { println("Failed to load and display the CSV."); } endCatch; // Free memory CSVFree(&csv); return EXIT_SUCCESS; } // Load the CSV void LoadCSV( struct CSV* const that) { try { // Open the file // If the file can't be open the execution will be rerouted toward // the exception management block, then there is no need to worry // here about failure and the code can be kept simple that->fp = safeFOpen( that->filename, "r"); // Read the number of columns and rows // Same as above, no need to worry about the failure of reading, // and so on for the following code safeFScanf( that->fp, "%d,%d\n", &(that->nbRow), &(that->nbCol)); // Allocate memory for the rows safeMalloc( that->data, that->nbRow * sizeof(int*)); loop(iRow, that->nbRow) that->data[iRow] = NULL; // Loop on the rows loop(iRow, that->nbRow) { // Allocate memory for the values in the row safeMalloc( that->data[iRow], that->nbCol * sizeof(int)); // Variable to memorise the separator char sep = ','; // Loop on the column loop(iCol, that->nbCol) { // If it's the last column, update the separator if (iCol == that->nbCol - 1) sep = '\n'; // Scan the value in the column safeFScanf( that->fp, "%d", that->data[iRow] + iCol); // Skip the separator char c; safeFScanf( that->fp, "%c", &c); if (c != sep) raiseExc(CapyExc_StreamReadError); } } } catch(CapyExc_StreamOpenError) { println("Failed to open the file"); } catch(CapyExc_StreamReadError) { println("Failed to read the data"); // Data may have been partially read, avoid leaving inconsistent // data by cleaning it here CSVFree(that); } endCatch; // Close the file if it has been opened if (that->fp != NULL) fclose(that->fp); // Forward the exception if any // If there has been a problem, let the calling function know about it // and it will decide what to do CapyForwardExc(); } // Display the content of the loaded CSV void DisplayCSV( struct CSV const* const that) { // Loop on the rows loop(iRow, that->nbRow) { // Column separator char sep = ','; // Loop on the column loop(iCol, that->nbCol) { // If it's the last column, update the separator if (iCol == that->nbCol - 1) sep = '\n'; // Print the column value and its separator printf( "%d%c", that->data[iRow][iCol], sep); } } } // Free the memory used by a struct CSV void CSVFree( struct CSV* const that) { // If the rows have been allocated if (that->data != NULL) { // Loop on the rows, if the row has been allocated, free it loop(iRow, that->nbRow) if (that->data[iRow] != NULL) free(that->data[iRow]); // Free the rows free(that->data); that->data = NULL; } // Reset the dimension of the array that->nbRow = 0; that->nbCol = 0; } /* Compiles without warning using (or -O0): gcc -O3 -std=c18 -Wall -Wextra -o main main.c -lcapy test1.csv: 3,2 1,2 3,4 5,6 `main test1.csv` outputs: 1,2 3,4 5,6 test2.csv: 2,3 1,2 3,4,5 `main test2.csv` outputs: Failed to read the data Failed to load and display the CSV. test3.csv: 3,2 1,2 3,4 `main test3.csv` outputs: Failed to read the data Failed to load and display the CSV. `main` outputs: Usage: main <path to the csv file>. `main missingFile.csv` outputs: Failed to open the file Failed to load and display the CSV. Each example also passes valgrind without error. */

More about the volatile qualifier

Lets consider the following trivial example. We have a function which open a file, do something on it which may raise an exception, then we use try/catch to ensure the file is closed wether or not an exception occured:

void f() { FILE* fp = NULL; try { fp = fopen("test", "r"); raiseExc(CapyExc_MallocFailed); } catchDefault { println("exception caught"); } endCatch; if (fp != NULL) fclose(fp); }

The file pointer is not declared volatile and can be modified inside and outside the try/catch blocks. Then the compiler raises correctly the warning variable ‘fp’ might be clobbered by ‘longjmp’ or ‘vfork’. According to what I wrote in this article the solution would be to use the volatile qualifier, as follow:

void f() { volatile FILE* fp = NULL; try { fp = fopen("test", "r"); raiseExc(CapyExc_MallocFailed); } catchDefault { println("exception caught"); } endCatch; if (fp != NULL) fclose(fp); }

Unfortunately this doesn't work in this case because the qualifier doesn't match the interface of fclose, then the compiler raises the warning passing argument 1 of ‘fclose’ discards ‘volatile’ qualifier from pointer target type. The solution I found is to use a structure instead of the qualifier to store all the necessary volatile variables:

void f() { struct {FILE* fp;} volatileVars = {.fp = NULL}; try { volatileVars.fp = fopen("test", "r"); raiseExc(CapyExc_MallocFailed); } catchDefault { println("exception caught"); } endCatch; if (volatileVars.fp != NULL) fclose(volatileVars.fp); }

This compiles without warning (whatever the optimization level), and works as expected (confirmed by checking with valgrind). My understanding (not 100% sure) is as follow. volatile will avoid the optimization to move the value of the variable to some register where it will get clobbered cause it is part of what's restored during the longjmp. By putting the variable into a structure, which isn't optimised to a register cause it's not a basic type, it prevents it the same way to be itself put into a register for optimization, without the trouble of qualifying its type. If you're more savvy and can confirm/disprove me I'd like to hear about you !