PTHREAD(3)

📦 version 15.1, in freebsd 14.5, freebsd 15.1, nixpkgs unstable

💅 PTHREAD(3) — POSIX thread functions, but make it make sense 💅

Okay bestie, this is the PTHREAD(3) page from the Library Functions Manual, and it’s all about the POSIX Threads Library (libpthread, -lpthread). This is part 1, so buckle up. 🎀

🌸 NAME 🌸

pthread — POSIX thread functions. That’s the name, bestie. Periodt. 💅

📚 LIBRARY 📚

POSIX Threads Library (libpthread, -lpthread) — yes, that’s the one you link with. ✨

🧚 SYNOPSIS 🧚

#include <pthread.h>

✨ DESCRIPTION ✨

Okay so POSIX threads are a set of functions that support applications with requirements for multiple flows of control, called threads, within a process. Multithreading is used to improve the performance of a program. That’s the whole vibe: multiple little flows of control doing their thing inside one process, and multithreading can make your program perform better. 🦋

The POSIX thread functions are summarized in this section in the following groups:

  • Thread Routines
  • Attribute Object Routines
  • Mutex Routines
  • Condition Variable Routines
  • Read/Write Lock Routines
  • Per-Thread Context Routines
  • Cleanup Routines

FreeBSD extensions to the POSIX thread functions are summarized in pthread_np(3). Go check that one if you need the FreeBSD-specific extras, iykyk. 👑

🧵 Thread Routines 🧵

  • int pthread_create(pthread_t *thread, const pthread_attr_t *attr, void *(*start_routine)(void *), void *arg) — Creates a new thread of execution. New main character just dropped. ✨
  • int pthread_cancel(pthread_t thread) — Cancels execution of a thread. Sorry bestie, it’s giving cancel culture. 😭
  • int pthread_detach(pthread_t thread) — Marks a thread for deletion. Not me setting it free. 🦋
  • int pthread_equal(pthread_t t1, pthread_t t2) — Compares two thread IDs. Are they the same? Let’s find out. 💅
  • void pthread_exit(void *value_ptr) — Terminates the calling thread. Bye from the thread itself. 👋
  • int pthread_join(pthread_t thread, void **value_ptr) — Causes the calling thread to wait for the termination of the specified thread. It’s literally waiting for its friend to finish. 🫶
  • int pthread_kill(pthread_t thread, int sig) — Delivers a signal to a specified thread. A little signal delivery, very demure. 💌
  • int pthread_once(pthread_once_t *once_control, void (*init_routine)(void)) — Calls an initialization routine once. Once. Not twice. Once. 💀
  • pthread_t pthread_self(void) — Returns the thread ID of the calling thread. Hi, it’s me. 🙈
  • int pthread_setcancelstate(int state, int *oldstate) — Sets the current thread’s cancelability state. Setting the vibe for cancellation. ✨
  • int pthread_setcanceltype(int type, int *oldtype) — Sets the current thread’s cancelability type. The type of cancellation energy, if you will. 💅
  • void pthread_testcancel(void) — Creates a cancellation point in the calling thread. A little checkpoint, bestie. 🎀
  • void pthread_yield(void) — Allows the scheduler to run another thread instead of the current one. Sharing is caring, fr fr. 🌈

🪄 Attribute Object Routines 🪄

  • int pthread_attr_destroy(pthread_attr_t *attr) — Destroy a thread attributes object. Cleanup era. 🧹
  • int pthread_attr_getinheritsched(const pthread_attr_t *attr, int *inheritsched) — Get the inherit scheduling attribute from a thread attributes object. Reading the scheduling tea. 🍵
  • int pthread_attr_getschedparam(const pthread_attr_t *attr, struct sched_param *param) — Get the scheduling parameter attribute from a thread attributes object. Parameter peek. 👀
  • int pthread_attr_getschedpolicy(const pthread_attr_t *attr, int *policy) — Get the scheduling policy attribute from a thread attributes object. Policy check. 💅
  • int pthread_attr_getscope(const pthread_attr_t *attr, int *contentionscope) — Get the contention scope attribute from a thread attributes object. Scope it out. 🔭
  • int pthread_attr_getstacksize(const pthread_attr_t *attr, size_t *stacksize) — Get the stack size attribute from a thread attributes object. How big is the stack? Asking for a friend. 🍓
  • int pthread_attr_getstackaddr(const pthread_attr_t *attr, void **stackaddr) — Get the stack address attribute from a thread attributes object. Address acquired. 📬
  • int pthread_attr_getdetachstate(const pthread_attr_t *attr, int *detachstate) — Get the detach state attribute from a thread attributes object. Detach state check, no cap. 💀
  • int pthread_attr_init(pthread_attr_t *attr) — Initialize a thread attributes object with default values. Fresh start, default settings. ✨
  • int pthread_attr_setinheritsched(pthread_attr_t *attr, int inheritsched) — Set the inherit scheduling attribute in a thread attributes object. Setting the inheritance vibe. 🧬
  • int pthread_attr_setschedparam(pthread_attr_t *attr, const struct sched_param *param) — Set the scheduling parameter attribute in a thread attributes object. Parameter, but make it set. 💅
  • int pthread_attr_setschedpolicy(pthread_attr_t *attr, int policy) — Set the scheduling policy attribute in a thread attributes object. Policy is now set. 👑
  • int pthread_attr_setscope(pthread_attr_t *attr, int contentionscope) — Set the contention scope attribute in a thread attributes object. Scope: set. 🔭
  • int pthread_attr_setstacksize(pthread_attr_t *attr, size_t stacksize) — Set the stack size attribute in a thread attributes object. Stack size, your call. 🍓
  • int pthread_attr_setstackaddr(pthread_attr_t *attr, void *stackaddr) — Set the stack address attribute in a thread attributes object. Address, but make it set. 📬
  • int pthread_attr_setdetachstate(pthread_attr_t *attr, int detachstate) — Set the detach state in a thread attributes object. Detach state: handled. 💅

🔒 Mutex Routines 🔒

  • int pthread_mutexattr_destroy(pthread_mutexattr_t *attr) — Destroy a mutex attributes object. Mutex attributes? Gone. 🧹
  • int pthread_mutexattr_getprioceiling(const pthread_mutexattr_t *restrict attr, int *restrict ceiling) — Obtain priority ceiling attribute of mutex attribute object. Priority ceiling tea. 🍵
  • int pthread_mutexattr_getprotocol(const pthread_mutexattr_t *restrict attr, int *restrict protocol) — Obtain protocol attribute of mutex attribute object. Protocol received. 📡
  • int pthread_mutexattr_gettype(const pthread_mutexattr_t *restrict attr, int *restrict type) — Obtain the mutex type attribute in the specified mutex attributes object. Type check. 💅
  • int pthread_mutexattr_init(pthread_mutexattr_t *attr) — Initialize a mutex attributes object with default values. Defaults, but for mutex attributes. ✨
  • int pthread_mutexattr_setprioceiling(pthread_mutexattr_t *attr, int ceiling) — Set priority ceiling attribute of mutex attribute object. Ceiling: set. 🏠
  • int pthread_mutexattr_setprotocol(pthread_mutexattr_t *attr, int protocol) — Set protocol attribute of mutex attribute object. Protocol: set. 📡
  • int pthread_mutexattr_settype(pthread_mutexattr_t *attr, int type) — Set the mutex type attribute that is used when a mutex is created. This is the type that gets used when a mutex is created, bestie. 💅
  • int pthread_mutex_destroy(pthread_mutex_t *mutex) — Destroy a mutex. Mutex deleted. 💀
  • int pthread_mutex_init(pthread_mutex_t *mutex, const pthread_mutexattr_t *attr) — Initialize a mutex with specified attributes. Mutex debut. ✨
  • int pthread_mutex_lock(pthread_mutex_t *mutex) — Lock a mutex and block until it becomes available. Locked and waiting. 🔒
  • int pthread_mutex_timedlock(pthread_mutex_t *mutex, const struct timespec *abstime) — Lock a mutex and block until it becomes available or until the timeout expires. Locked, but with a timer. ⏰
  • int pthread_mutex_trylock(pthread_mutex_t *mutex) — Try to lock a mutex, but do not block if the mutex is locked by another thread, including the current thread. It won’t block if the mutex is locked by another thread — including the current thread. Yes, even you, bestie. 💀
  • int pthread_mutex_unlock(pthread_mutex_t *mutex) — Unlock a mutex. Release the lock, release the drama. 🕊️

🫧 Condition Variable Routines 🫧

  • int pthread_condattr_destroy(pthread_condattr_t *attr) — Destroy a condition variable attributes object. Cond attr: destroyed. 🧹
  • int pthread_condattr_init(pthread_condattr_t *attr) — Initialize a condition variable attributes object with default values. Fresh cond attr, default values. ✨
  • int pthread_cond_broadcast(pthread_cond_t *cond) — Unblock all threads currently blocked on the specified condition variable. Everybody up, it’s a broadcast. 📢
  • int pthread_cond_destroy(pthread_cond_t *cond) — Destroy a condition variable. Condition variable: deleted. 💀
  • int pthread_cond_init(pthread_cond_t *cond, const pthread_condattr_t *attr) — Initialize a condition variable with specified attributes. Condition variable debut. 🎀
  • int pthread_cond_signal(pthread_cond_t *cond) — Unblock at least one of the threads blocked on the specified condition variable. Wake at least one bestie. 🫶
  • int pthread_cond_timedwait(pthread_cond_t *cond, pthread_mutex_t *mutex, const struct timespec *abstime) — Unlock the specified mutex, wait no longer than the specified time for a condition, and then relock the mutex. Unlock, wait with a time limit, relock. The full little routine. ⏳
  • int pthread_cond_wait(pthread_cond_t *, pthread_mutex_t *mutex) — Unlock the specified mutex, wait for a condition, and relock the mutex. Unlock, wait, relock. Periodt. 💅

🔐 Read/Write Lock Routines 🔐

  • int pthread_rwlock_destroy(pthread_rwlock_t *lock) — Destroy a read/write lock object. RW lock: destroyed. 🧹
  • int pthread_rwlock_init(pthread_rwlock_t *lock, const pthread_rwlockattr_t *attr) — Initialize a read/write lock object. RW lock debut. ✨
  • int pthread_rwlock_rdlock(pthread_rwlock_t *lock) — Lock a read/write lock for reading, blocking until the lock can be acquired. Reading lock, and it will wait until it can get it. 📖
  • int pthread_rwlock_tryrdlock(pthread_rwlock_t *lock) — Attempt to lock a read/write lock for reading, without blocking if the lock is unavailable. Try to read-lock, but no blocking if it’s unavailable. 🙅‍♀️
  • int pthread_rwlock_trywrlock(pthread_rwlock_t *lock) — Attempt to lock a read/write lock for writing, without blocking if the lock is unavailable. Try to write-lock, no blocking if it’s unavailable. ✍️
  • int pthread_rwlock_unlock(pthread_rwlock_t *lock) — Unlock a read/write lock. Unlocked, bestie. 🔓
  • int pthread_rwlock_wrlock(pthread_rwlock_t *lock) — Lock a read/write lock for writing, blocking until the lock can be acquired. Writing lock, and it will wait until it can get it. ✍️
  • int pthread_rwlockattr_destroy(pthread_rwlockattr_t *attr) — Destroy a read/write lock attribute object. RW lock attr: destroyed. 🧹
  • int pthread_rwlockattr_getpshared(const pthread_rwlockattr_t *attr, int *pshared) — Retrieve the process shared setting for the read/write lock attribute object. Getting the process shared setting. 🫱
  • int pthread_rwlockattr_init(pthread_rwlockattr_t *attr) — Initialize a read/write lock attribute object. RW lock attr debut. ✨
  • int pthread_rwlockattr_setpshared(pthread_rwlockattr_t *attr, int pshared) — Set the process shared setting for the read/write lock attribute object. Process shared setting: set. 💅

🧺 Per-Thread Context Routines 🧺

  • int pthread_key_create(pthread_key_t *key, void (*routine)(void *)) — Create a thread-specific data key. A key, just for your thread. 🔑
  • int pthread_key_delete(pthread_key_t key) — Delete a thread-specific data key. Key deleted. 🗑️
  • void * pthread_getspecific(pthread_key_t key) — Get the thread-specific value for the specified key. Getting your thread-specific value. 🎁
  • int pthread_setspecific(pthread_key_t key, const void *value_ptr) — Set the thread-specific value for the specified key. Setting your thread-specific value. 💅

🧼 Cleanup Routines 🧼

  • int pthread_atfork(void (*prepare)(void), void (*parent)(void), void (*child)(void)) — Register fork handlers. Fork handlers: registered. 🍴
  • void pthread_cleanup_pop(int execute) — Remove the routine at the top of the calling thread’s cancellation cleanup stack and optionally invoke it. Pops the cleanup routine and can optionally invoke it. 🫧
  • void pthread_cleanup_push(void (*routine)(void *), void *routine_arg) — Push the specified cancellation cleanup handler onto the calling thread’s cancellation stack. Pushes a cleanup handler onto the calling thread’s cancellation stack. 🧚

💅 IMPLEMENTATION NOTES (the tea ☕)

Okay so real talk about how this actually works on your machine, bestie:

The current FreeBSD POSIX thread implementation is literally built into the 1:1 Threading Library, aka libthr, aka -lthr when you're linking. Iconic. ✨

It contains thread-safe versions of the Standard C Library (libc, -lc) functions and the thread functions, so you're not out here writing wrappers like a clown. 🫶

Threaded applications are linked with this library, periodt. So if your app is doing the multithreaded thing, that's the vibe you're linking against. 🧚

🌈 SEE ALSO (your reading list, bestie 📚)

Like, go read these next, no cap — they're all (3) manpages and they're all gonna eat:

That's the whole squad, fr fr. 🎀

👑 STANDARDS (the receipts 🧾)

So here's how you know who's official and who's just vibing:

The functions with the pthread_ prefix and not the _np suffix or the pthread_rwlock prefix conform to ISO/IEC 9945-1:1996 (“POSIX.1”). Those are the certified good girls — fully standard, fully iconic. ✨

The functions with the pthread_ prefix and the _np suffix are non-portable extensions to POSIX threads. _np literally stands for "not portable," so like… don't be shocked when they don't exist everywhere, babe. 🙈

The functions with the pthread_rwlock prefix are extensions created by The Open Group as part of the Version 2 of the Single UNIX Specification (“SUSv2”). Fancy committee energy, but we respect it. 💜

💀 tiny reminder bestie: _np = not portable. If you ship it, that's a choice, and the consequences are yours. Slay responsibly.

And that's the whole page, periodt! 🍓 This one's from the Debian crew, dated October 12, 2021, and it's the PTHREAD(3) page — go forth and thread safely, my love. 🦋💖

📦 where this page comes from