1. What is Thread-Local Storage (TLS)?

2. The __thread Specifier — Syntax and Rules

The syntax is simple: add __thread to the declaration of a global or static variable:

/* ===== TLS Variable Declarations ===== */

/* Simple TLS variable — each thread has its own copy, initialized to 0 */
static __thread int per_thread_counter;

/* TLS buffer — each thread has its own 256-byte buffer */
static __thread char per_thread_buf[256];

/* TLS with initializer — each thread starts with value 42 */
static __thread int magic = 42;

/* Global TLS (visible across translation units) */
__thread long global_per_thread_value;

/* With extern */
extern __thread int some_per_thread_var;

Important rules for __thread:

• The __thread keyword must immediately follow the static or extern storage class specifier, if one is used. Example: static __thread int x; is correct. __thread static int x; is wrong.
• TLS variables can have initializers, just like normal global or static variables: static __thread int x = 10;. The initializer must be a constant expression.
• You can take the address of a TLS variable using the & operator: int *p = &per_thread_counter;. However, the address is only valid while the thread is alive — do not store it somewhere another thread might use after this thread exits.
• __thread can only be applied to global or static variables — not to local (auto) variables, because local variables are already per-thread by nature (they live on the stack).

3. Platform and Compiler Requirements

Thread-Local Storage is not part of the POSIX standard — it is a non-standard extension. However, it is widely available on most major UNIX/Linux platforms. On Linux, TLS requires all three of:

4. Thread-Safe strerror() Using TLS

Compare this to the TSD version from File 4. The logic is identical, but notice how much simpler the implementation is — no keys, no key creation, no pthread_once(), no malloc(), no destructor, no pthread_setspecific/getspecific. The __thread keyword does all the work.

/* ===== Listing 31-4: Thread-safe strerror() using TLS — THE SIMPLE WAY ===== */
/* File: strerror_tls.c */

#define _GNU_SOURCE
#include <stdio.h>
#include <string.h>
#include <pthread.h>

#define MAX_ERROR_LEN 256

/* THE KEY LINE: __thread makes this a per-thread variable.
   Each thread automatically gets its own 256-byte buf.
   No API calls needed. No malloc. No destructor.
   Storage is freed automatically when the thread exits. */
static __thread char buf[MAX_ERROR_LEN];

char *strerror(int err)
{
    /* 'buf' here refers to THIS THREAD's own copy — no sharing possible */
    if (err < 0 || err >= _sys_nerr || _sys_errlist[err] == NULL) {
        snprintf(buf, MAX_ERROR_LEN, "Unknown error %d", err);
    } else {
        strncpy(buf, _sys_errlist[err], MAX_ERROR_LEN - 1);
        buf[MAX_ERROR_LEN - 1] = '\0';
    }
    return buf;   /* Returns pointer to THIS THREAD's private buf — safe! */
}

/* === Test === */
static void *threadFunc(void *arg)
{
    char *str = strerror(EPERM);
    printf("Other thread: str (%p) = %s\n", str, str);
    return NULL;
}

int main(void)
{
    pthread_t t;
    char *str;

    str = strerror(EINVAL);
    printf("Main thread has called strerror()\n");

    pthread_create(&t, NULL, threadFunc, NULL);
    pthread_join(t, NULL);

    printf("Main thread: str (%p) = %s\n", str, str);
    return 0;
}

/* Expected output:
   Main thread has called strerror()
   Other thread: str (0x40376ab0) = Operation not permitted
   Main thread:  str (0x40175080) = Invalid argument
                      ^^^^^^^^^^^      ^^^^^^^^^^^^^^^^
                      Different addresses! Each thread has its own buf. */

5. TSD vs TLS — Detailed Comparison

6. More TLS Examples

/* ===== EXAMPLE: Various uses of __thread ===== */

#include <stdio.h>
#include <pthread.h>

/* Per-thread call counter — each thread counts its own calls independently */
static __thread unsigned long call_count = 0;

/* Per-thread error accumulator */
static __thread int last_errno = 0;

/* Per-thread scratch buffer */
static __thread char scratch[512];

/* Per-thread "initialized" flag */
static __thread int thread_initialized = 0;

void do_work(int value)
{
    call_count++;   /* Increments THIS thread's counter — no mutex needed! */

    if (!thread_initialized) {
        /* First-call-from-this-thread initialization */
        snprintf(scratch, sizeof(scratch), "Thread scratch initialized");
        thread_initialized = 1;
    }

    /* Use scratch buffer — it's per-thread, no races */
    snprintf(scratch, sizeof(scratch), "Processing value %d (call #%lu)",
             value, call_count);
    printf("%s\n", scratch);
}

static void *worker(void *arg)
{
    int id = *(int *)arg;
    int i;
    for (i = 0; i < 3; i++) {
        do_work(id * 10 + i);
    }
    /* call_count here shows only THIS thread's calls — no shared state */
    printf("Thread %d total calls: %lu\n", id, call_count);
    return NULL;
}

int main(void)
{
    pthread_t t1, t2;
    int id1 = 1, id2 = 2;

    pthread_create(&t1, NULL, worker, &id1);
    pthread_create(&t2, NULL, worker, &id2);
    pthread_join(t1, NULL);
    pthread_join(t2, NULL);

    /* Main thread's call_count is still 0 — it never called do_work() */
    printf("Main thread calls: %lu\n", call_count);
    return 0;
}

/* Important: Taking the address of a TLS variable */
void demonstrate_tls_address(void)
{
    /* Valid: &call_count gives the address of THIS thread's copy */
    unsigned long *p = &call_count;
    (*p)++;   /* Increments this thread's call_count */

    /* WARNING: Do NOT store this address and use it from another thread!
       After this thread exits, the address becomes invalid. */
}

7. Chapter 31 Summary