Deprecate Code in C

In software development, managing a large codebase frequently requires updating APIs, swapping out outdated functions, or eliminating unsafe code. However, simply removing legacy functions can introduce compatibility issues for existing applications that still depend on them. A safer approach is to flag such code as deprecated - keeping it available while signaling that it should no longer be used and will likely be removed in the future. This tutorial demonstrates how to deprecate code in C.

Unlike C++, the C language does not provide a universally supported deprecation mechanism across compilers, so many projects rely on compiler-specific extensions. These can be wrapped in macros to provide a consistent and portable way to mark code as deprecated.

Mark as deprecated

The following example demonstrates how to mark a function as deprecated using compiler-specific extensions:

#include <stdio.h>

#if defined(__GNUC__)
#define DEPRECATED __attribute__((deprecated))
#elif defined(_MSC_VER)
#define DEPRECATED __declspec(deprecated)
#else
#define DEPRECATED
#endif

DEPRECATED void test() {
    printf("Test function\n");
}

int main() {
    test();

    return 0;
}

This code still builds successfully, but a warning is emitted indicating that the function is deprecated. GCC output example:

main.c: In function ‘main’:
main.c:16:5: warning: ‘test’ is deprecated [-Wdeprecated-declarations]
   16 |     test();
      |     ^~~~
main.c:11:17: note: declared here
   11 | DEPRECATED void test() {
      |                 ^~~~

Mark as deprecated with message

A more informative approach is to attach a message explaining the preferred alternative. This helps guide developers toward the updated function.

#include <stdio.h>

#if defined(__GNUC__)
#define DEPRECATED(msg) __attribute__((deprecated(msg)))
#elif defined(_MSC_VER)
#define DEPRECATED(msg) __declspec(deprecated(msg))
#else
#define DEPRECATED(msg)
#endif

DEPRECATED("Use test2 instead.") void test1() {
    printf("Test1 function\n");
}

void test2() {
    printf("Test2 function\n");
}

int main() {
    test1();

    return 0;
}

Compiler output now includes the custom message:

main.c: In function ‘main’:
main.c:20:5: warning: ‘test1’ is deprecated: Use test2 instead. [-Wdeprecated-declarations]
   20 |     test1();
      |     ^~~~~
main.c:11:39: note: declared here
   11 | DEPRECATED("Use test2 instead.") void test1() {
      |                                       ^~~~~