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).
#include <pthread.h> void *work(void *arg) { return NULL; } pthread_t t; pthread_create(&t, NULL, work, NULL); pthread_join(t, NULL);
Try it
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.
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
#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
argpointer 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
mainends the whole process, killing all threads. Callpthread_exitinmainor 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 *withintptr_tworks on common platforms but is implementation-defined; a pointer to a struct is the portable way. - Thread identifiers (
pthread_t) are opaque. Compare them withpthread_equal, and never print them as numbers if you want portable or repeatable output. pthread_detachmakes 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_rvariants. - C11 offers
<threads.h>(thrd_create,thrd_join), a smaller portable alternative; see threads.h.
Related
- pthread_mutex, pthread_cond, threads.h, stdatomic.h
- Tutorial: Threads