Skip to content
Tutorials Center
My learning

Topics

C Reference ยท POSIX and Systems

C pthread_create() and pthread_join() functions

Reference for pthread_create(), pthread_join(), pthread_exit() and pthread_detach(): start threads, pass arguments, return results, and avoid common lifetime bugs.

pthread_create() starts a new thread of execution inside the current process. The thread runs a function you supply, shares all global memory and open files with the other threads, and has its own stack. pthread_join() waits for a thread to finish and collects the void * it returned.

Threads are cheaper than processes and communicate through shared memory, which is also the danger: unsynchronized access to shared data is a data race and undefined behavior. Protect shared state with a mutex and signal changes with a condition variable. Compile and link with -pthread (our editor does this for you).

C
#include <pthread.h>

void *work(void *arg) { return NULL; }

pthread_t t;
pthread_create(&t, NULL, work, NULL);
pthread_join(t, NULL);

Try it

C Threads that return results

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.

C Passing integers and exiting a thread early

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.

Syntax

C
#include <pthread.h>

int pthread_create(pthread_t *restrict thread, const pthread_attr_t *restrict attr,
                   void *(*start_routine)(void *), void *restrict arg);
int pthread_join(pthread_t thread, void **retval);
void pthread_exit(void *retval);
int pthread_detach(pthread_t thread);
pthread_t pthread_self(void);
int pthread_equal(pthread_t t1, pthread_t t2);
Name Description
thread Where to store the new thread's identifier.
attr Attributes (stack size, detached state), or NULL for defaults.
start_routine Function the thread runs. It takes and returns a void *.
arg The single argument handed to start_routine.
retval (pthread_join) Where to store the thread's return value, or NULL.

Returns: 0 on success. On failure, a positive error number (EAGAIN out of resources or thread limit, EINVAL, ESRCH no such thread, EDEADLK joining yourself). The pthread functions do not set errno; compare the return value, and use strerror(rc) for a message.

Usage notes

  • Order is not guaranteed. Threads run when the scheduler decides. Output that must be in a fixed order should be printed after the joins, from data the threads stored, as the examples do.
  • Join every joinable thread exactly once, or detach it. An unjoined thread leaks resources until the process exits.
  • Lifetime of the argument: the arg pointer must stay valid while the thread uses it. Never pass the address of a loop variable or a local that goes out of scope; give each thread its own element of an array that outlives the joins.
  • Returning from main ends the whole process, killing all threads. Call pthread_exit in main or join first.
  • Returning from the start routine is equivalent to pthread_exit(retval). Do not return a pointer to a local variable of the thread: its stack is gone after exit.
  • Passing an integer through void * with intptr_t works on common platforms but is implementation-defined; a pointer to a struct is the portable way.
  • Thread identifiers (pthread_t) are opaque. Compare them with pthread_equal, and never print them as numbers if you want portable or repeatable output.
  • pthread_detach makes a thread clean up after itself; you can then no longer join it. Joining a detached thread is undefined behavior.
  • Most of the standard library is thread-safe, but functions that return pointers to static storage (strtok, localtime, rand) are not; use their _r variants.
  • C11 offers <threads.h> (thrd_create, thrd_join), a smaller portable alternative; see threads.h.