POSIX Threads

01 Introduction

The previous four lessons in this unit have been largely conceptual: what threads are, where they can live in the system, how the kernel schedules them, and what happens to a program when several of them run at once. This lesson is the practical counterpart. It introduces the POSIX threads API — commonly called pthreads — which is the standard interface for creating and managing threads in C on any UNIX-like system.

The pthreads standard was formalised in IEEE 1003.1c (1995) and is now part of POSIX.1. It is available on Linux (via glibc's Native POSIX Thread Library, examined in Lesson 4.3), on macOS, on the BSDs, and on Solaris. It is the API you will use for every laboratory and assignment in this course that involves threads. Learning it well is not just a matter of memorising a few function names — the pthread programming model has its own conventions for error handling, resource management, and thread lifecycle, and getting those conventions right is the difference between code that works and code that works reliably.

The lesson covers the five core functions (pthread_create, pthread_join, pthread_detach, pthread_exit, and the attribute machinery), the thread lifecycle from creation to completion, the standard compilation conventions, and the pitfalls — including a few that are specific to Linux and glibc. It closes with a complete working program that illustrates everything discussed, and prepares you for the thread-management work in Lab 3.

02 Learning objectives

This lesson contributes to U4.4, U4.5, and to course learning outcomes CLO2, CLO6, and CLO8.

03 Required reading

• OSTEP — Chapter 27, Interlude: Thread API. A concise introduction to the POSIX threads interface with example code.
• Operating System Concepts — Chapter 4, Section 4.4, Thread Libraries, and the Pthreads examples throughout Chapter 4.
• Butenhof, D. R. — Programming with POSIX Threads, Chapters 1–3. The classical reference for the pthreads programming model. Chapter 1 gives the philosophy, Chapter 2 covers thread creation and termination, and Chapter 3 covers attributes.
• Linux man pages: man 7 pthreads, man 3 pthread_create, man 3 pthread_join, man 3 pthread_detach, man 3 pthread_exit, man 3 pthread_attr_init, man 3 pthread_attr_setdetachstate, man 3 pthread_attr_setstacksize, man 3 pthread_self, man 3 pthread_equal.

04 Core content

4.1 The pthread API in one page

The pthreads API is larger than it first appears, but the subset you will use in this course is small. Six functions cover almost every case.

All of them return an integer error code, discussed in section 4.7. All of them are declared in the header <pthread.h>. And all of them follow the conventions that POSIX established for the whole threading interface.

4.2 Creating a thread: pthread_create

The signature is:

#include <pthread.h>

int pthread_create(pthread_t *thread,
                   const pthread_attr_t *attr,
                   void *(*start_routine)(void *),
                   void *arg);

The four arguments have specific roles.

• thread is a pointer to a pthread_t variable, which the function fills in with the new thread's identifier. This identifier is what you pass to pthread_join or pthread_detach later.
• attr is a pointer to a pthread_attr_t structure describing thread attributes, or NULL to accept the defaults. The default attributes are almost always what you want; section 4.6 discusses when to override them.
• start_routine is a function pointer to the thread's entry point. The function must have the exact signature void *(*)(void *) — it takes one void * argument and returns void *.
• arg is the argument passed to start_routine. If you need to pass multiple values, wrap them in a struct and pass a pointer to it.

The function returns 0 on success or an error number on failure — not the convention of setting errno and returning −1 that the rest of POSIX uses. This inconsistency is important enough that section 4.7 is devoted to it.

A minimal creation call:

pthread_t t;
int err = pthread_create(&t, NULL, worker, NULL);
if (err != 0) {
    fprintf(stderr, "pthread_create: %s\n", strerror(err));
    exit(1);
}

4.3 The thread start routine

The start routine is an ordinary function, but its signature is fixed by the API. The most common form takes a pointer to a struct that holds the arguments:

struct args {
    int       id;
    double   *data;
    size_t    n;
    double    result;
};

void *worker(void *p) {
    struct args *a = p;
    double sum = 0.0;
    for (size_t i = 0; i < a->n; i++) sum += a->data[i];
    a->result = sum;
    return NULL;
}

The void * return value is the thread's exit value, which pthread_join can retrieve. A thread that has nothing to return can return NULL (or, equivalently, call pthread_exit(NULL)).

void *worker(void *p) {
    int result = 42;
    return &result;   /* WRONG — the variable is gone on return */
}

4.4 Waiting for threads: pthread_join

Threads are analogous to processes in that a thread may be joinable or detached. A joinable thread is one whose resources are not reclaimed by the system until another thread calls pthread_join on its identifier. A detached thread's resources are reclaimed automatically when it terminates, with no join required.

By default, pthread_create creates joinable threads. The signature of pthread_join is:

int pthread_join(pthread_t thread, void **retval);

The function blocks the calling thread until the target thread terminates. If retval is not NULL, the target thread's return value (the pointer it returned from its start routine, or the argument to pthread_exit) is stored at *retval. Once a thread has been joined, its resources are fully reclaimed and its identifier may be reused.

The essential rule for joinable threads: every thread that is created must eventually be joined or detached. A joinable thread that is never joined is a resource leak — its kernel task structure and stack remain allocated until the process terminates. This is the threading analogue of the zombie-process problem from Unit 3.

A joining pattern for multiple threads:

pthread_t t[N];
for (int i = 0; i < N; i++)
    pthread_create(&t[i], NULL, worker, &args[i]);

for (int i = 0; i < N; i++)
    pthread_join(t[i], NULL);

Note that the joins are in a separate loop from the creations. Creating all threads first and then joining them lets the threads run in parallel. If the create-then-join were done in one loop, each thread would be created and immediately joined, serialising the whole computation.

4.5 Detached threads: pthread_detach

Not every thread needs to be joined. A fire-and-forget thread — one whose result no one will ever collect — should be detached so that its resources are reclaimed on exit. There are two ways to create a detached thread.

The first is to call pthread_detach after creation:

pthread_t t;
pthread_create(&t, NULL, worker, NULL);
pthread_detach(t);

The second is to set the detach state in the attributes structure before calling pthread_create, which avoids the race between thread creation and the detach call:

pthread_attr_t attr;
pthread_attr_init(&attr);
pthread_attr_setdetachstate(&attr,
                            PTHREAD_CREATE_DETACHED);
pthread_create(&t, &attr, worker, NULL);
pthread_attr_destroy(&attr);

The race matters when the thread might terminate before pthread_detach is called on its identifier. If the thread has already terminated, its identifier may no longer refer to it, and the detach call may fail. Setting the attribute before creation eliminates the race entirely.

4.6 Thread attributes

The pthread_attr_t structure is an opaque type that describes the initial configuration of a new thread. Using it has three steps: initialise, set the values you care about, and destroy it after creating the thread.

pthread_attr_t attr;
pthread_attr_init(&attr);

/* ... pthread_attr_set... calls ... */

pthread_create(&t, &attr, worker, NULL);

pthread_attr_destroy(&attr);

The attributes you will most often set are:

Detach state

PTHREAD_CREATE_JOINABLE (the default) or PTHREAD_CREATE_DETACHED. Set with pthread_attr_setdetachstate.

Stack size

The size of the thread's user-space stack. The default on Linux is typically 8 MB, which is generous for ordinary threads but wasteful when creating thousands of them. Set with pthread_attr_setstacksize.

Stack address

The base address of the thread's stack. Rarely used; some applications pass a pre-allocated stack so they can control its placement, for example to keep thread stacks within a single NUMA node.

Scheduling policy and priority

SCHED_OTHER, SCHED_FIFO, or SCHED_RR with an associated priority. Real-time policies require privileges and are discussed in Unit 5.

Guard size

A region of protected memory placed after the thread's stack so that a stack overflow triggers a fault rather than silently corrupting adjacent memory. Default is one page.

4.7 Error handling and the -pthread flag

The pthreads functions return an integer error code and do not use errno. This is a deliberate design choice from POSIX 1003.1c: because errno is a per-thread variable on a modern system, but was not when pthreads was standardised, the interface opted to return errors directly and avoid any shared or thread-local state ambiguity.

The correct pattern is:

int err = pthread_create(&t, NULL, worker, NULL);
if (err != 0) {
    fprintf(stderr, "pthread_create failed: %s\n", strerror(err));
    return 1;
}

Never use perror with a pthreads error code: perror reads from errno, which the pthreads functions do not set. The result is a misleading message about a completely different error.

The other convention specific to pthreads is the compiler and linker flag -pthread. On modern glibc this flag both defines the preprocessor macro _REENTRANT (which enables thread-safe variants of some library functions) and links the program against the threading library. Without -pthread, the program may compile but produce incorrect behaviour under concurrency, or fail to link at all.

gcc -Wall -Wextra -g -O2 -pthread -o program program.c

On macOS and the BSDs, the same flag works, though modern versions of these systems often provide threading in the base C library. On Linux, the flag is mandatory.

4.8 The thread lifecycle

Bringing the functions together, a thread passes through a sequence of states that mirrors the process lifecycle from Unit 3 but is specific to the pthreads model.

4.9 Thread-local storage

In Lesson 4.1 we saw that each thread has its own errno even though errno looks like a global variable. This is an example of thread-local storage (TLS): a variable that appears to each thread to be private, even though it is declared at file scope.

Thread-local storage is useful whenever a thread needs to maintain state across calls to library functions without passing that state explicitly. The POSIX interface has two forms.

The compiler-based form uses the _Thread_local storage-class specifier (C11; __thread in GCC and Clang). Each thread sees its own copy of the variable:

_Thread_local int counter = 0;

void bump(void) {
    counter++;      /* each thread increments its own copy */
}

The POSIX form uses pthread_key_create and pthread_setspecific to associate a value with a key that is unique to the calling thread. This is the older, more portable interface and is what the C library uses internally for errno:

pthread_key_t key;

void init(void) {
    pthread_key_create(&key, NULL);
}

void set(int value) {
    pthread_setspecific(key, (void *)(long)value);
}

int get(void) {
    return (int)(long)pthread_getspecific(key);
}

TLS is a small but important part of the pthreads programming model. It gives you a way to have per-thread state without passing it through every function call, and it is what makes the C library safe to use from multiple threads at once. We will return to it in Unit 6, when we discuss how synchronization primitives are themselves implemented using per-thread state.

4.10 Common pitfalls

The pthread API is small, but its programming model has a set of pitfalls that beginners reliably encounter. Most of them are consequences of the shared-address-space design from Lesson 4.1.

4.11 A note on pthread_cancel

POSIX provides pthread_cancel, which requests that another thread be cancelled. The mechanism is subtle: a cancel request is not a command that terminates the target immediately. The target thread will be terminated only when it next reaches a cancellation point — one of a defined set of functions, including read, write, sleep, wait, pthread_join, and pthread_cond_wait. Between cancellation points, the thread continues to run.

Cancellation also has two modes — deferred (the default) and asynchronous — and the state can be disabled entirely. Because correct cancellation requires the target thread to handle a signal-like event and clean up after itself (using pthread_cleanup_push and pthread_cleanup_pop), the mechanism is more complex than it first appears.

In this course, you will not need to use pthread_cancel. When a thread must be asked to stop, the conventional pattern is a shared flag that the thread checks periodically — a form of cooperative cancellation that is simpler and more predictable than the POSIX mechanism. We will use this pattern in the threading laboratory.

05 Worked example

To make the API concrete, walk through a complete program that uses every function discussed. It creates a fixed number of worker threads, each of which computes a partial result; the main thread joins them all and combines the results.

#include <stdio.h>
#include <stdlib.h>
#include <pthread.h>
#include <string.h>
#include <time.h>

#define N        400000000L
#define WORKERS  4

static long  data[N];
static long  partial[WORKERS];

struct args {
    int    id;         /* thread index */
    size_t start;
    size_t end;
};

static void *sum_worker(void *p) {
    struct args *a = p;
    long s = 0;
    for (size_t i = a->start; i < a->end; i++) s += data[i];
    partial[a->id] = s;
    printf("thread %d: pid=%d, sum=%ld\n",
           a->id, (int)getpid(), s);
    return NULL;
}

static double now(void) {
    struct timespec ts;
    clock_gettime(CLOCK_MONOTONIC, &ts);
    return ts.tv_sec + ts.tv_nsec / 1e9;
}

int main(void) {
    for (long i = 0; i < N; i++) data[i] = 1;

    /* Argument structs must persist until each thread is joined,
       so they live in the main thread's stack. */
    struct args args[WORKERS];
    pthread_t   tids[WORKERS];

    size_t per = N / WORKERS;

    double t0 = now();

    for (int w = 0; w < WORKERS; w++) {
        args[w].id    = w;
        args[w].start = w * per;
        args[w].end   = (w == WORKERS - 1) ? N : (w + 1) * per;

        int err = pthread_create(&tids[w], NULL, sum_worker, &args[w]);
        if (err != 0) {
            fprintf(stderr, "pthread_create: %s\n", strerror(err));
            exit(1);
        }
    }

    for (int w = 0; w < WORKERS; w++) {
        int err = pthread_join(tids[w], NULL);
        if (err != 0) {
            fprintf(stderr, "pthread_join: %s\n", strerror(err));
            exit(1);
        }
    }

    long total = 0;
    for (int w = 0; w < WORKERS; w++) total += partial[w];

    double t1 = now();
    printf("total = %ld\n", total);
    printf("elapsed = %.3f s\n", t1 - t0);
    return 0;
}

gcc -Wall -Wextra -g -O2 -pthread -o psum psum.c
./psum

thread 0: pid=1234, sum=100000000
thread 2: pid=1234, sum=100000000
thread 1: pid=1234, sum=100000000
thread 3: pid=1234, sum=100000000
total = 400000000
elapsed = 0.28 s

pthread_attr_t attr;
int err = pthread_attr_init(&attr);
if (err != 0) { /* handle */ }

/* 1 MB stack instead of the default 8 MB */
err = pthread_attr_setstacksize(&attr, 1 << 20);
if (err != 0) { /* handle */ }

/* Detached: the workers have nothing to return */
err = pthread_attr_setdetachstate(&attr,
                                  PTHREAD_CREATE_DETACHED);
if (err != 0) { /* handle */ }

for (int w = 0; w < WORKERS; w++) {
    err = pthread_create(&tids[w], &attr, sum_worker, &args[w]);
    if (err != 0) { /* handle */ }
}

pthread_attr_destroy(&attr);

/* Nothing to join — the workers are detached */

Kernel-thread switch (measured on a modern x86-64 VM):
    Cost per switch:      ~170 ns

User-thread switch (measured in Lesson 4.2):
    Cost per switch:      ~70 ns

06 Interactive activity

07 Knowledge check

08 Unit discussion

09 Practice exercise

10 Summary

• POSIX Threads (pthreads) is the standard C interface for threading on UNIX-like systems, including Linux, macOS, and the BSDs.
• The core functions are pthread_create (create a thread), pthread_join (wait for a joinable thread), pthread_detach (mark a thread as detached), and pthread_exit (terminate the calling thread).
• A thread's start routine has the fixed signature void *(*)(void *). Arguments and return values pass through void * pointers, usually to a struct that holds multiple values.
• Every thread is either joinable (its resources are reclaimed by pthread_join) or detached (its resources are reclaimed automatically on exit). A joinable thread that is never joined leaks its resources.
• The pthread_attr_t structure configures a thread's initial state: detach state, stack size, stack address, scheduling policy, and guard size. Set attributes before calling pthread_create to avoid races.
• Pthreads functions return error codes directly; they do not set errno. Use strerror(err), not perror.
• Always compile pthread programs with -pthread, which enables thread-safe library variants and links the threading implementation.
• Thread-local storage (via _Thread_local or the pthread_key_create API) gives each thread a private copy of a variable that appears at file scope. It is what makes the C library safe under concurrency.
• Common pitfalls: forgetting -pthread, using errno for pthreads errors, returning pointers to thread-local variables, passing the address of a loop variable, never joining joinable threads, sharing data without synchronization, assuming scheduling order, and calling exit instead of pthread_exit.

11 References

• Arpaci-Dusseau, R. H., & Arpaci-Dusseau, A. C. Operating Systems: Three Easy Pieces, Chapter 27. Available online at ostep.org.
• Silberschatz, A., Galvin, P. B., & Gagne, G. Operating System Concepts, 10th ed., Chapter 4, Section 4.4.
• Butenhof, D. R. Programming with POSIX Threads, Chapters 1–3. Addison-Wesley, 1997.
• Drepper, U., & Molnar, I. The Native POSIX Thread Library for Linux. Red Hat, 2003.
• Linux man-pages: man 7 pthreads, man 3 pthread_create, man 3 pthread_join, man 3 pthread_detach, man 3 pthread_exit, man 3 pthread_attr_init, man 3 pthread_key_create, man 3 pthread_self, man 3 pthread_equal.
• POSIX.1-2017 / IEEE Std 1003.1, Standard for Information Technology — Portable Operating System Interface (POSIX), Section on Threads.