Function signature changes for forward-compatible interfaces

c, libraries, macros

Solution

Pass a pointer to a structure...

typedef struct
{
    int value;
} typeStructure;

void foo(const typeStructure * const pTypeStructure);

Should `typeStructure` be expanded, older versions of `foo` will simply ignore new fields.

Problem

Is there a common practice how to extend a C API while staying forward compatible? Suppose I want to provide a function foo in a c library: ``` foo(int value); ``` Now in a later version I would like to extend foo to allow another parameter. ``` foo(int value, const char *description_may_be_NULL); ``` To ensure forward-compatibility I would have to name the new one differently, e.g. `foo2`. Would it be clever to provide a macro such that: ``` #define MYLIB_API 2 #include <mylib.h> /* the header will #define foo foo2 */ ``` That would avoid using nasty names in practice. Are there any common practices how to handle the conflicting forward compatibility and elegant code for future versions? Any examples of how popular C APIs have handled that in the past would be appreciated. Edit: Unfortunately I didn't clearly mention this: The `foo(int)` signature is already set, so introducing varargs/struct parameters would also be an incompatible API change. It is not actually probable that many functions will change over time, but some will eventually. Paying ahead for all functions with an uncommon signature seems a high price to me.

Original source