C Interfaces and Implementations

David R. Hanson

Mentioned 14

C Interfaces and Implementations describes how to use interface-based design in the C programming language, and it illustrates this approach by describing 24 interfaces and their implementations in detail. The source code in the book is interleaved with its explanation in an order that best suits understanding the code.

More on Amazon.com

Mentioned in questions and answers.

My question is unfortunately badly formed as I'm not entirely certain to call what I'm trying to do. My apologies for that.

It came up since I'm trying to code a really basic browser that I want to implement in C and I was thinking about how best to go about it. The basic idea being something like libcurl (for network interaction) -> libxml2 (parse HTML) -> UI and then some manner of getting libcurl to accept GET or POST requests from the UI (haven't gotten to this point yet).

However, this approuch is severely limited, if I say want to check whether it's a PDF and then send it off to libpoppler before handing it to libxml2 I'll have to recode my entire program flow. Further, if I want to use parts of my program (say, the libcurl -> pdftohtml -> libxml2 part) and send it off to another program (for example w3m instead of my UI), I again don't see how I will manage that.

I could instead simply write a Perl or Python wrapper for curl, libxml2, etc, or do something along the lines of "curl example.com | parser | UI". However doing it in Perl or Python still seems like I'll have to recode my program logic every time I want to do something new, and piping everything seems inelegant. I would also like to do this in C if possible.

So my question is; what do one call this idea? I've been driving myself crazy trying to figure out how to search for a solution for a problem that I can't name. I know it has something to do with modularity, however I don't know what specifically and modularity is a very broad term. Secondly and optionally if anybody could point me in the direction of a solution I would appreciate that as well although it's not as important as what it's called.

Thanks to all who read this. :)

First I suggest you take a look at http://www.amazon.com/Interfaces-Implementations-Techniques-Creating-Reusable/dp/0201498413. Second most browsers are asynchronous so you are going to need a event library like libuv or libev. Also most modern websites require javascript to function properly, but adding a javascript engine to your browser would greatly complicate the project. I also don't see any mention of how you plan on parsing the http being sent to and from your browser, I suggest https://github.com/joyent/http-parser.

As for your question on control flow, I would have a function that parse's the response from the server and use's switch() to handle the various types of data being sent to your browser. There is a field in the http header which explains the content type and that way your browser should be able to call different functions based of what the content type is.

Also take a look at function pointers, both here Polymorphism (in C) and here How do function pointers in C work? . Function pointers would/could be a more eloquent way to solve your problem instead having large switch statements through out your code. With function pointers you can have one function that when called in your program behaves differently.

I will try to explain below with a browser as an example.

So lets say your browser just got back a http response from some server. The http response looks something like this in C.

struct http_res
{
    struct http_header *header;
    struct http_body *body

    int (*decode_body)(char **);
};

So first your http parser will parse the http header and figure out if it's a valid response and if there's content, etc, etc. If there is content the parser will check the type and based off, if it's html, javascript, css, or whatever the parser will set the function pointer to point at the right function to decode the http body.

static int decode_javascript(char **body)
{
    /* Whatever it takes to parse javascript from http. */
    return 0;
}

static int decode_html(char **body)
{
    /* Whatever it takes to parse html from http. */
    return 0;
}

static int decode_css(char **body)
{
    /* Whatever it takes to parse css from http. */
    return 0;
}

int parse_http_header(struct http_res *http)
{
    /* ... lots of other code to figure out content type. ... */

    switch(body_content_type)
    {
        case BCT_JAVASCRIPT:
          http->decode_body = &decode_javascript;
          break;

        case BCT_HTML:
          http->decode_body = &decode_html;
          break;

        case BCT_CSS:
          http->decode_body = &decode_css;
          break;

        default:
          printf("Error can't parse body type.\n");
          return -1;
    }
    return 0;
}

Now when we pass the http request to another part of the browser that function can call decode_body() in the http response object and it will end up with a decoded body it can understand, with out knowing what it's decoding.

int next_function(struct http_res * res)
{
    char *decoded_body;
    int rtrn;

    /* Now we can decode the http body with out knowing anything about
    it. We just call decode_body() and end up with a buffer with the
    decoded data in it. */
    rtrn = res->decode_body(&decoded_body);
    if(rtrn < 0)
    {
        printf("Can't decode body.\n");
        return -1;
    }

    return 0;
}

To make your program really modular at least in C, you would stick the various parts of your browser in different shared libraries, like the HTTP parser, event library, Javascript engine, html parser, etc, etc. Then you would create interfaces between each library and you would be able to swap out each library with a different one with having to change your program, you would link a different library at run time. Take a look at Dr Robert martin(uncle bob) he talks about this extensively. This talk is good but it lacks slides https://www.youtube.com/watch?v=asLUTiJJqdE , starts at 8:20. This one is also interesting, and it has slides: https://www.youtube.com/watch?v=WpkDN78P884 .

And finally nothing about C, perl or python means you will have to recode your program logic. You will have to design your program so that each module does not know about each other. The module knows about the interface and if you connect two modules that both "speak" the same interface you will have created a modular system. It's just like how the internet works the various computers on the internet do not need to know what the other computer is, or what it's doing, or it's operating system, all they need to know is TCP/IP and they can communicate with all the other devices on the internet.

What is the best place or a link to learn algorithms in C? How do you know when and where to use the implementation of algorithms by just looking into the problems?

Algorithms in C by Sedgewick is a great place to start the investigation. Once you are familiar with what algorithms are available and what the performance characteristics of each are, you'll be able to see where to use each of them.

Algorithms aren't necessarily tied to a specific language, just to clarify, so any algorithms book will work great as long as you can understand the concept being the data structure/algorithm.

That said, this seems like a good choice: Algorithms in C. I have the C++ equivalent on my shelf.

There is also a book that seems language agnostic (correct me if I'm wrong) called Data Structures & Algorithm's, though I hear it's a bit dated, so you'll miss out on more recent structures.

Don't forget the internet has a plethora of information available to you. However, books are usually better for these sorts of things. This is because internet resources tend to focus on one thing at a time. For example, you need to understand what Big-O notation is before you can understand what it means when we say a List has O(1) [constant time] removal.

A book will cover these things in the correct order, but an internet resource will focus on either Big-O notation or data structures, but often won't easily connect the two.


When it comes to using it, you'll mostly make the connection when it comes to what you'll be doing with the data.

For example, you might want a vector (array) if you just need ordered elements, but if you need ordered elements and removal from any place (but can sacrifice random access), then a list would be more appropriate, due to it's constant-time removal.

I read Pointers on C by Kenneth Reek recently. I thought I was pretty well versed in C, but this book gave me a few epiphanies, despite being aimed at beginners. The code examples are things of beauty (but not the fastest code on a x86-like CPU). It provide good implementations of many of the most common algorithms and data-structures that are in use, with excellent explanations about why they are implemented as they are (and sometimes code or suggestions for alternative implementations).

On the same page as your question: patterns for creating reusable code in C (that is what we all want, isn't it?), C Interfaces and Implementations: Techniques for Creating Reusable Software, by David R. Hanson. It has been a few years since I read it, and I don't have a copy to verify what I recall is correct, but if I remember correctly it deals with how to create good C API:s to data structures and algorithms, as well as giving example implementations of some of the most common algorithms.

Of topic: As I have mostly written throw-away programs in C for private use, this one helped me get rid of some bad coding habits as well as being an excellent C reference: C: A reference Manual. Reminds me that I ought to buy that one.

Can a string be used as array index in C?

Ex: String Corresponding value "ONE" 1 "TWO" 2 "FIVE" 5 "TEN" 10

When a string in the above list is passed to the function, the function must return the corresponding value indicated above. Can this be achieved by declaring a constant array with string as index

int *x;
x["ONE"]  = 1;
x["TWO"]  = 2;
x["FIVE"] = 5;
x["TEN"]  = 5;

return x["string received by the function"];

The above logic does not work as expected; is there a workaround to implement the above logic in order to have a string-indexed array?

As already indicated, you need an associative array or hash map or equivalent. One possible source for such code is Hanson's "C Interfaces and Implementations" (code at Google Code - double check licencing terms etc before using it.)

I'm working on a large project in C, and I want to organize it using interface (.h) and implementation (.c) files, similar to many object-oriented languages such as Objective-C or Java. I am familiar with creating static libraries in C, but I think that doing so for my project is unnecessarily complex. How can I implement an interface/implementation paradigm in ANSI C? I'm primarily using GCC for compilation, but I'm aiming for strict adherence to ANSI C and cross-compiler compatibility. Thanks!

Please do yourself a favor and read C Interfaces and Implementations: Techniques for Creating Reusable Software

Here is a repository of mine that holds some libs written in C using the pattern of interfaces & implementation described in the book.

Can anyone point me to a source code file or to a package that has a good, reusable implementation of sprintf() in C which I can customize as per my own need?

An explanation on why I need it: Strings are not null terminated in my code (binary compatible). Therefore sprintf("%s") is useless unless I fix the code to understand how to render string.

Thanks to quinmars for pointing out that there is way to print string through %s without it being null terminated. Though it solves the requriement right now, I shall eventually need the sprintf (or snprintf) implementation for higher level functions which use variants. Out of other mentioned till now, it seems to me that SQLite implementation is the best. Thanks Doug Currie for pointing it out.

Look at Hanson's C Interfaces: Implementations and Techniques. It is an interesting book in that it is written using Knuth's Literate Programming techniques, and it specifically includes an extensible formatted I/O interface based on snprintf().

I am looking for some resources that speak about managing large C projects using make, header files, building configure files etc.

What resources are used by the community? Any good ones for beginners?

What are some clever (not ordinary) ways of implementing data structures in C, and what are some data structures that should be used more often?

For example, what is the most effective way (generating minimal overhead) to implement a directed and cyclic graph with weighted edges in C?
I know that we can store the distances in an array as is done here, but what other ways are there to implement this kind of a graph?

Answering your first question, I recommend to encapsulate your structures using opaque pointers (a.k.a Handles).

For example, you may declare a handle to a linked list (here MS-like naming):

typedef struct linked_list_t* HLINKEDLIST;

We assume that linked_list_t is a generic one (composed of void pointers).

This way you can hide what a "handle" to a linked list is, or in what form is implemented (information hiding):

HLINKEDLIST LinkedListCreate();
LinkedListAdd(LLELEMENT v);
LinkedListCopy(HLINKEDLIST dst, const HLINKEDLIST src);

Handle subtypes are also commonly defined, such as PHLINKEDLIST (pointer to a linked list handle).

Related types can also be defined for convenience (and to use the limited information hiding available in C). e.g: the linked list element type can be defined as

typedef void* LLELEMENT;

There are good books on Data Structures in C to check. This is good: http://www.amazon.com/Interfaces-Implementations-Techniques-Creating-Reusable/dp/0201498413

Also note that LLELEMENT is actually compatible with void* so if you are defining other type def as:

typedef void* SYSTEMDATA;

SYSTEMDATA is compatible with LLELEMENT, so the compiler won't complain on:

int QuerySystemData(SYSTEMDATA* sd);

and calling:

QuerySystemData(lle);

where lle is of type LLELEMENT.

This type checking can be enforced encapsulating simple members in structs. If I don't remember bad, declaring STRICT in a program using windows.h causes handles to be type-safer (incompatible between). Definitions like the following are common:

typedef struct __HWND 
{ 
int __handle; 
} __HWND; 

typedef __HWND* HWND; 

If the simpler definitions were:

typedef int HWND;
typedef int HBITMAP;

The two handles would be type compatible and interchangeable on functions expecting to work with windows and functions expecting to work with bitmaps (potential horrible bugs).

I am trying to use some old C libraries in some new C++.

The library's header files use D. Hanson's "C Interfaces and Implementations" implementation-hiding idiom of:

#define T MyAST 

typedef struct T *T;

Near as I can tell, this compiles with C because in C struct names and typedef names are in different namespaces but it does not compile with C++ (extern "C" { #include "MyAST.h" }) evidently because typedef and struct names are in the same namespace.

conflicting declaration 'typedef struct MyAST* MyAST'

I think I'm doomed to move the struct def into the headers and give up using the technique but I really don't want to (this idiom is used in a lot of code, some mine, some not) and thought I'd check here to see if anyone has any insight.

PS: If you don't know the idiom, it lets you keep the struct definition in the implementing C file and then users of the interface (MyAST.h) can't reach into the struct, they must use your functions in the implementation.

Honestly if the only purpose here is to use some old libraries (which we'll presume won't be updated), I'd create a glue layer between your C++ and the old libraries. Just write a small amount of wrapper code that's compiled in C to use the old libraries, and provide a C interface that compiles in C++ to your new C++ code.

Having the same name mean two different things can only cause confusion among future maintainers, so I would try to isolate the interface code to a few source files.

Finally, while I can appreciate wanting to separate the interface from the implementation at some point you have to trust your code users to not flagrantly violate the conditions of the library and just code it in an obvious way rather than going to paranoid lengths to hide struct definitions away.

I am trying to write a function to clean up the hash table that is generated by this code

/*
* Markov chain random text generator.
*/

#include <string.h>
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include <time.h>
#include "eprintf.h"

enum {
NPREF   = 2,    /* number of prefix words */
NHASH   = 4093, /* size of state hash table array */
MAXGEN  = 10000 /* maximum words generated */
};

typedef struct State State;
typedef struct Suffix Suffix;

struct State {  /* prefix + suffix list */
char*   pref[NPREF];    /* prefix words */
Suffix* suf;            /* list of suffixes */
State*  next;           /* next in hash table */
};

struct Suffix { /* list of suffixes */
char*   word;           /* suffix */
Suffix* next;           /* next in list of suffixes */
};

State* lookup(char *prefix[], int create);
void build(char *prefix[], FILE*);
void generate(int nwords);
void add(char *prefix[], char *word);

State* statetab[NHASH]; /* hash table of states */

char NONWORD[] = "\n";  /* cannot appear as real word */

/* markov main: markov-chain random text generation */
int main(void)
{
int i, nwords = MAXGEN;
char *prefix[NPREF];        /* current input prefix */

int c;
long seed;

setProgName("markov");
seed = time(NULL);

srand(seed);
for (i = 0; i < NPREF; i++) /* set up initial prefix */
    prefix[i] = NONWORD;
build(prefix, stdin);
add(prefix, NONWORD);
generate(nwords);
return 0;
}

const int MULTIPLIER = 31;  /* for hash() */

/* hash: compute hash value for array of NPREF strings */
unsigned int hash(char* s[NPREF])
{
unsigned int h;
unsigned char *p;
int i;

h = 0;
for (i = 0; i < NPREF; i++)
    for (p = (unsigned char *) s[i]; *p != '\0'; p++)
        h = MULTIPLIER * h + *p;
return h % NHASH;
}


/* lookup: search for prefix; create if requested. */
/*  returns pointer if present or created; NULL if not. */
/*  creation doesn't strdup so strings mustn't change later. */
State* lookup(char *prefix[NPREF], int create)
{
int i, h;
State *sp;

h = hash(prefix);
for (sp = statetab[h]; sp != NULL; sp = sp->next) {
    for (i = 0; i < NPREF; i++)
        if (strcmp(prefix[i], sp->pref[i]) != 0)
            break;
    if (i == NPREF)     /* found it */
        return sp;
}
if (create) {
    sp = (State *) emalloc(sizeof(State));
    for (i = 0; i < NPREF; i++)
        sp->pref[i] = prefix[i];
    sp->suf = NULL;
    sp->next = statetab[h];
    statetab[h] = sp;
}
return sp;
}

/* addsuffix: add to state. suffix must not change later */
void addsuffix(State *sp, char *suffix)
{
Suffix *suf;

suf = (Suffix *) emalloc(sizeof(Suffix));
suf->word = suffix;
suf->next = sp->suf;
sp->suf = suf;
}

/* add: add word to suffix list, update prefix */
void add(char *prefix[NPREF], char *suffix)
{
State *sp;

sp = lookup(prefix, 1);  /* create if not found */
addsuffix(sp, suffix);
/* move the words down the prefix */
memmove(prefix, prefix+1, (NPREF-1)*sizeof(prefix[0]));
prefix[NPREF-1] = suffix;
}

/* build: read input, build prefix table */
void build(char *prefix[NPREF], FILE *f)
{
char buf[100], fmt[10];

/* create a format string; %s could overflow buf */
sprintf(fmt, "%%%ds", sizeof(buf)-1);
while (fscanf(f, fmt, buf) != EOF)
    add(prefix, estrdup(buf));
}

/* generate: produce output, one word per line */
void generate(int nwords)
{
State *sp;
Suffix *suf;
char *prefix[NPREF], *w;
int i, nmatch;

for (i = 0; i < NPREF; i++) /* reset initial prefix */
    prefix[i] = NONWORD;

for (i = 0; i < nwords; i++) {
    sp = lookup(prefix, 0);
    if (sp == NULL)
        eprintf("internal error: lookup failed");
    nmatch = 0;
    for (suf = sp->suf; suf != NULL; suf = suf->next)
        if (rand() % ++nmatch == 0) /* prob = 1/nmatch */
            w = suf->word;
    if (nmatch == 0)
        eprintf("internal error: no suffix %d %s", i, prefix[0]);
    if (strcmp(w, NONWORD) == 0)
        break;
    printf("%s\n", w);
    memmove(prefix, prefix+1, (NPREF-1)*sizeof(prefix[0]));
    prefix[NPREF-1] = w;
}
}

Here is what I have so far for my clean function

/*Clean Function*/
void clean_up(State *sp)
{
State *temp;
Suffix *temp2, temp3;

for(int h = 0; h < NHASH; h++)
{
    for (sp = statetab[h]; sp != NULL; sp = sp->next)
    {
        while(sp->suf != NULL) 
        {
            temp2= sp->suf;
            temp3= *temp2->next;
            free(temp2);
            sp->suf= &temp3;
        }

    }
}
}

I think im on the right track, I'm going through each index in the hash table, then going from state to state and freeing the suffixes. I'm not sure what to do about the prefixes, because I have to free them before I can free each state. Any help would be greatly appreciated.

The example code is derived from the Markov program in The Practice of Programming by Kernighan and Pike, a most excellent book.

Given that you are trying to clean up the statetab, the main clean-up function doesn't need any argument. You do have to be careful not to free the states directly in statetab, but you do need to release auxilliary states chained off statetab[i].next.

typedef struct State State;
typedef struct Suffix Suffix;

struct State {  /* prefix + suffix list */
char*   pref[NPREF];    /* prefix words */
Suffix* suf;            /* list of suffixes */
State*  next;           /* next in hash table */
};

struct Suffix { /* list of suffixes */
char*   word;           /* suffix */
Suffix* next;           /* next in list of suffixes */
};

State* statetab[NHASH]; /* hash table of states */

static void free_state(State *state);
static void free_suffix(Suffix *suffix);

static void cleanup(void)
{
   for (int i = 0; i < NHASH; i++)
      free_state(statetab[i]);
}

static void free_state(State *state)
{
    if (state != 0)
    {
        for (int i = 0; i < NPREF; i++)
            free(state->pref[i]);
        free_suffix(state->suf);
        if (state->next != 0)
        {
            free_state(state->next);
            free(state->next);
        }
    }
}

static void free_suffix(Suffix *suffix)
{
    if (suffix != 0)
    {
        free(suffix->word);
        free_suffix(suffix->next);
        free(suffix);
    }
}

Do you see how I've designed the free_xxxx() code based on the design of the xxxx structure?

Caveat Lector: uncompiled code, much less tested code.


I dug up the code from the TPOP site, and tried to apply it. I made some fixes to the freeing code above (syntax error fixed, the null checks in free_state() and free_suffix()), but the code as a whole was not designed to allow the data to be freed.

There are a couple of problems. First, a few of the prefixes are not allocated (NONWORD). It might be possible to avoid releasing those by testing whether a prefix is NONWORD, but that's nasty. It might be possible to allocate those prefixes too (replace NONWORD by estrdup(NONWORD)). I think there's another place, somewhere, that a non-allocated pointer is being stashed in a prefix in the state table; I'm getting crashes in malloc() complaining of 'freeing non-allocated memory' (which is distinct from 'double freeing allocated memory', I believe), but I've not managed to resolve that.

However, that then changes to another problem; the prefixes are reused. That is, almost every prefix in the system is used as the the second word of one prefix, then as the first word of the next prefix. Thus, you can't readily free the prefixes.

If you were to design this so that the memory could be released, then you'd probably design it so that there was a system of 'atoms' (immutable strings) such that each word was allocated once and reused as often as necessary (see C Interfaces and Implementations: Techniques for Creating Reusable Code by D Hanson for the source of the term). The code freeing the state table would then concentrate only on the non-word data. There'd be code to release the complete set of atoms as well.

I ran the Markov program under valgrind without the cleanup; there are no memory access problems and no leaked data; it is all still accessible at program exit. I was using a data file of about 15,000 words (and about 2900 distinct words), and the statistics were:

==9610== HEAP SUMMARY:
==9610==     in use at exit: 695,269 bytes in 39,567 blocks
==9610==   total heap usage: 39,567 allocs, 0 frees, 695,269 bytes allocated
==9610== 
==9610== LEAK SUMMARY:
==9610==    definitely lost: 0 bytes in 0 blocks
==9610==    indirectly lost: 0 bytes in 0 blocks
==9610==      possibly lost: 0 bytes in 0 blocks
==9610==    still reachable: 695,269 bytes in 39,567 blocks

So, you set yourself an interesting exercise. However, I think it is not achievable without reworking some of the memory allocation mechanism so that the data can be freed cleanly.

(On BSD, and hence on Mac OS X too, there are a pair of functions in <stdlib.h> called setprogname() and getprogname(). On BSD, setprogname() is called automatically before the main() gets going (with argv[0], I believe). The declaration in eprintf.h conflicts with the declaration in <stdlib.h>, which may be why the code in the question uses setProgName() instead of the original setprogname(). I chose to fix setprogname() in eprintf.h so that it took a const char * argument and therefore matched the declaration in <stdlib.h>.)


TPOP was previously at http://plan9.bell-labs.com/cm/cs/tpop and http://cm.bell-labs.com/cm/cs/tpop but both are now (2015-08-10) broken. See also Wikipedia on TPOP.

I'm about to design a C api for some functionality and I would like to make it asynchronous as the exposed functionality may take some time. Using a blocking api is probably not a good idea as the user of the api will need to make many simultaneous calls.

What is the right way to design the interface so that I can notify the user that the asynchronous operation has completed?

I can think of several different approaches, but I can't say that I am aware of the best practices for this. Does anyone have any experiences with similar API:s?

In this example, the intention is to return an int containing an answer.

Callback function:

typedef void (*callback_function)(int, void *);

/* Calls the callback function with the answer and cookie when done */
error_code DoSomething(callback_function, void *cookie);

Polling:

error_code DoSomething(void *cookie);

/* Blocks until any call has completed, then returns the answer and cookie */
error_code WaitForSomething(int *answer, void **cookie);

Platform specific event queue

/* Windows version, the api calls PostQueuedCompletionStatus when done */
error_code DoSomething( HANDLE hIoCompletionPort,
                        ULONG_PTR dwCompletionKey,
                        LPOVERLAPPED lpOverlapped );

Users of this API will typically be event-driven, so designs like the below are probably not going to be a good idea.

Futures:

/* External dummy definition for a future */
struct Future_Impl {
    int unused;
};
typedef Future_Impl *Future;

/* Initializes a future, so that it can be waited on later */
error_code DoSomething(Future *future);

/* Blocks until the result is available */
error_code WaitForSomething(Future future, int *answer);

Platform specific "futures"/events:

/* Windows version, the api signals the event when done */
error_code DoSomething( HANDLE hEvent, int *answer );

/* Can be waited on using WaitForMultipleObjects,
   but that has a limit on how many events that can be used */

I realize you've asked for a specific scenario, but as far as designing C interfaces go, I've heard immensely positive reviews about this book and usually hear it recommended first to questions similar to yours: C Interfaces and Implementations: Techniques for Creating Reusable Software

Are there any tips which we should follow for good design when we are considering the 'C' as the implementation language.

I want tips which should be considered because we are using 'C' as the implementation language and not related to the functionality.

C Interfaces and Implementations is a great book on the subject

"C Interfaces and Implementations" shows some interesting usage patterns for data structures, but I am sure there are others out there.

http://www.amazon.com/Interfaces-Implementations-Techniques-Addison-Wesley-Professional/dp/0201498413

Look at the Goddard Space Flight Center (NASA) C coding standard (at this URL). It has some good and interesting guidelines.

One specific guideline, which I've adopted for my own code, is that headers should be self-contained. That is, you should be able to write:

#include "header.h"

and the code should compile correctly, with any other necessary headers included, regardless of what has gone before. The simple way to ensure this is to include the header in the implementation source -- as the first header. If that compiles, the header is self-contained. If it doesn't compile, fix things so that it does. Of course, this also requires you to ensure that headers are idempotent - work the same regardless of how often they are included. There's a standard idiom for that, too:

#ifndef HEADER_H_INCLUDED
#define HEADER_H_INCLUDED
...operational body of header.h...
#endif /* HEADER_H_INCLUDED */

It is imperative, of course, to have the #define at the top of the file, not at the bottom. Otherwise, if a header included by this also includes header.h, then you end up with an infinite loop - not healthy. Even if you decide to go with a strategy of:

#ifndef HEADER_H_INCLUDED
#include "header.h"
#endif /* HEADER_H_INCLUDED */

in the code that include the header - a practice which is not recommended - it is important to include the guards in the header itself too.


Update 2011-05-01

The GSFC URL above no longer works. You can find more information in the answers for the question Should I use #include in headers, which also contains a cross-reference to this question.

Update 2012-03-24

The referenced NASA C coding standard can be accessed and downloaded via the Internet archive:

http://web.archive.org/web/20090412090730/http://software.gsfc.nasa.gov/assetsbytype.cfm?TypeAsset=Standard

How does one construct and access a set of key-value pairs in C? To use a silly simple example, let's say I want to create a table which translates between an integer and its square root.

If I were writing javascript, I could just do this:

var squareRoots = {
   4: 2,
   9: 3,
   16: 4,
   25: 5
}

and then access them like:

var squareRootOf25 = squareRoots[5]

What's the prettiest way to do this in C? What if I want to use one type of enum as the key and another type of enum as the value?

There is no built-in way to do this unless you count initializing an array like this in C99:

double squareRoots[] =
{
     [4] = 2.0,
     [9] = 3.0,
    [16] = 4.0,
    [25] = 5.0,
};

However, this allocates 26 elements in the array; the other values are all zeroes.

Assuming you didn't mean this, then look at C Interfaces and Implementations by D R Hanson; it shows a way of implementing associative arrays (aka hashes or dictionaries).

I have a C program in which I need to create a whole family of functions which have the same signatures and bodies, and differ only in their types. What I would like to do is define a macro which generates all of those functions for me, as otherwise I will spend a long time copying and modifying the original functions. As an example, one of the functions I need to generate looks like this:

int copy_key__sint_(void *key, void **args, int argc, void **out {
if ((*out = malloc(sizeof(int))) {
return 1;
}

**((_int_ **) out) = *((_int_ *) key);  
return 0;  

}

The idea is that I could call a macro, GENERATE_FUNCTIONS("int", "sint") or something like this, and have it generate this function. The italicized parts are what need to be plugged in.

Is this possible?

Try something like this (I just tested the compilation, but not the result in an executed program):

 #include "memory.h"

   #define COPY_KEY(type, name)                                 \
   type name(void *key, void **args, int argc, void **out) { \
      if (*out = malloc(sizeof(type))) {                     \
         return 1;                                           \
      }                                                      \
   **((type **) out) = *((type *) key);                      \
   return 0;                                                 \
   }                                                         \

COPY_KEY(int, copy_key_sint)

For more on the subject of generic programming in C, read this blog wich contains a few examples and also this book which contains interesting solutions to the problem for basic data structures and algorithm.