1. Understanding Version Numbers

A shared library real name follows this format:

2. The Three Conditions for Compatibility

A library change is compatible (minor version bump only) if and only if all three of these conditions are met:

3. Compatible vs Incompatible — Quick Reference

Code Example 1 — A Compatible Change (Minor Version Bump)

In version 1.0.1 of libdemo, add_numbers takes two ints. In 1.0.2 we fix a bug and add a new function multiply_numbers. This is compatible — no existing caller breaks.

/* ===== libdemo version 1.0.1 ===== */
/* mod1.c */
int add_numbers(int a, int b) {
    return a + b;   /* original */
}

void hello_from_mod1(void) {
    printf("libdemo v1.0.1\n");
}

/* ===== libdemo version 1.0.2 — COMPATIBLE CHANGE ===== */
/* mod1.c */
#include <stdio.h>

/* Same function, same signature — bug fix inside */
int add_numbers(int a, int b) {
    /* Fixed: previously had off-by-one in some edge case */
    return a + b;
}

/* NEW function added — does NOT break existing callers */
int multiply_numbers(int a, int b) {
    return a * b;
}

void hello_from_mod1(void) {
    printf("libdemo v1.0.2 (bug fixed)\n");
}

/* demo.h — updated public header for v1.0.2 */
#ifndef DEMO_H
#define DEMO_H

/* Existing functions — unchanged */
int  add_numbers(int a, int b);
void hello_from_mod1(void);
void hello_from_mod2(void);

/* New function — safely added */
int  multiply_numbers(int a, int b);

#endif

# Build version 1.0.2 — SAME soname (libdemo.so.1) because compatible
gcc -g -c -fPIC -Wall mod1.c mod2.c

gcc -g -shared -Wl,-soname,libdemo.so.1 \
    -o libdemo.so.1.0.2 \
    mod1.o mod2.o

# Install and run ldconfig
sudo mv libdemo.so.1.0.2 /usr/local/lib/
sudo ldconfig -v | grep libdemo
# libdemo.so.1 -> libdemo.so.1.0.2   (changed — soname now points to 1.0.2)

# Old programs still work — they load libdemo.so.1 -> libdemo.so.1.0.2
# They call add_numbers(), which still exists with same signature → OK
# They never call multiply_numbers() — they don't know it exists → no problem

Code Example 2 — An Incompatible Change (New Major Version)

In version 2.0.0, we change add_numbers to take a third parameter and remove hello_from_mod2. Old programs that call these functions will break — so we need a new major version.

/* ===== libdemo version 2.0.0 — INCOMPATIBLE CHANGE ===== */
/* mod1.c */
#include <stdio.h>

/* CHANGED: third parameter added — breaks all old callers! */
int add_numbers(int a, int b, int c) {
    return a + b + c;
}

/* CHANGED: return type changed from void to int — breaks old callers! */
int hello_from_mod1(void) {
    printf("libdemo v2.0.0\n");
    return 0;
}

/* hello_from_mod2 REMOVED — old programs calling it will crash at link time */

/* demo.h — v2 header: INCOMPATIBLE with v1 */
#ifndef DEMO_H
#define DEMO_H

/* Changed signature */
int add_numbers(int a, int b, int c);

/* Changed return type */
int hello_from_mod1(void);

/* hello_from_mod2 removed */

#endif

# Build version 2.0.0 — NEW soname (libdemo.so.2) — DIFFERENT from v1!
gcc -g -c -fPIC -Wall mod1.c

# NOTE: soname is now libdemo.so.2
gcc -g -shared -Wl,-soname,libdemo.so.2 \
    -o libdemo.so.2.0.0 \
    mod1.o

# Install
sudo mv libdemo.so.2.0.0 /usr/local/lib/
sudo ldconfig -v | grep libdemo
# libdemo.so.1 -> libdemo.so.1.0.2   (v1 still present, untouched)
# libdemo.so.2 -> libdemo.so.2.0.0   (new v2 soname created)

# Create linker name pointing to v2
sudo ln -sf libdemo.so.2 /usr/local/lib/libdemo.so

# -------------------------------------------------------
# Old program compiled against v1:
ldd old_program
# libdemo.so.1 => /usr/local/lib/libdemo.so.1.0.2  ← still gets v1! WORKS.

# New program compiled against v2:
gcc -o new_program new_main.c -ldemo -L/usr/local/lib
ldd new_program
# libdemo.so.2 => /usr/local/lib/libdemo.so.2.0.0  ← gets v2. WORKS.

Code Example 3 — The Struct Padding Technique

Library designers sometimes reserve space in exported structs for future use, allowing fields to be added without breaking the ABI. This is a common technique for stable library ABIs.

/* ===== demo.h — v1.0.x with reserved padding ===== */
#ifndef DEMO_H
#define DEMO_H

/* 
 * The struct has 'reserved' fields to allow future additions
 * WITHOUT changing the struct's total size.
 * This is the "padding for future use" technique.
 */
typedef struct {
    int  id;            /* offset 0 */
    int  value;         /* offset 4 */
    char name[64];      /* offset 8 */
    int  flags;         /* offset 72 */

    /* Reserved fields — currently unused, set to 0 */
    int  _reserved1;   /* offset 76 — for future use */
    int  _reserved2;   /* offset 80 — for future use */
    void *_reserved3;  /* offset 84 — for future use */
} DemoRecord;

DemoRecord *demo_create(int id, int value, const char *name);
void        demo_destroy(DemoRecord *rec);
void        demo_print(const DemoRecord *rec);

#endif

/* mod_record.c — implementation */
#include <stdlib.h>
#include <string.h>
#include <stdio.h>
#include "demo.h"

DemoRecord *demo_create(int id, int value, const char *name) {
    DemoRecord *rec = calloc(1, sizeof(DemoRecord)); /* calloc zeros all reserved fields */
    if (!rec) return NULL;
    rec->id    = id;
    rec->value = value;
    strncpy(rec->name, name, sizeof(rec->name) - 1);
    return rec;
}

void demo_destroy(DemoRecord *rec) {
    free(rec);
}

void demo_print(const DemoRecord *rec) {
    printf("id=%d value=%d name=%s flags=%d\n",
           rec->id, rec->value, rec->name, rec->flags);
}

/* ===== Later: v1.1.0 — USE one reserved field, NO ABI break ===== */
/* New demo.h: _reserved1 is now 'priority', struct SIZE is same */

typedef struct {
    int  id;
    int  value;
    char name[64];
    int  flags;

    /* _reserved1 is now officially 'priority' */
    int  priority;     /* offset 76 — newly defined field */
    int  _reserved2;
    void *_reserved3;
} DemoRecord;

/* Add new function that uses priority */
void demo_set_priority(DemoRecord *rec, int pri);

/* 
 * Why is this still compatible?
 *
 * Old programs allocate DemoRecord — size is still the same (reserved space holds it).
 * Old programs never set 'priority' — it stays 0 (calloc initializes to 0).
 * Old programs call demo_create/demo_destroy/demo_print — all still exist, same signature.
 * Only NEW programs can use demo_set_priority — old programs simply don't call it.
 *
 * Result: minor version bump to 1.1.0, same soname libdemo.so.1 — COMPATIBLE.
 */

# Build v1.1.0 — still soname libdemo.so.1
gcc -g -shared -Wl,-soname,libdemo.so.1 \
    -o libdemo.so.1.1.0 \
    mod_record.o

sudo mv libdemo.so.1.1.0 /usr/local/lib/
sudo ldconfig -v | grep libdemo
# libdemo.so.1 -> libdemo.so.1.1.0   (changed, still v1 soname)

4. Version Decision Guide

Use this decision table when making a library change:

Interview Questions & Answers