PTHREAD_CREATE(3P)

💖 PROLOG 💖

okay so first thing bestie, this page is part of the POSIX Programmer's Manual. the Linux implementation of this interface may differ (so go check the corresponding Linux manual page for the deets on Linux behavior), or honestly the interface might not even be implemented on Linux at all. 🙈

---

✨ NAME ✨

pthread_create — thread creation 💅 (yes we're making a whole new thread, we're literally birthing a lil worker, iconic)

---

🦋 SYNOPSIS 🦋

#include <pthread.h>

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

---

🌸 DESCRIPTION 🌸

so pthread_create() shall create a new thread, with attributes specified by attr, within a process. if attr is NULL, the default attributes shall be used, no thoughts head empty, defaults it is. and listen — if the attributes specified by attr get modified later, the thread's attributes shall not be affected. once it's locked in, it's locked in fr. 💜 upon successful completion, pthread_create() shall store the ID of the created thread in the location referenced by thread.

the thread is created executing start_routine with arg as its sole argument. and if start_routine returns? the effect shall be as if there was an implicit call to pthread_exit() using the return value of start_routine as the exit status. periodt. but note that the thread in which main() was originally invoked differs from this — when it returns from main(), the effect shall be as if there was an implicit call to exit() using the return value of main() as the exit status. yes bestie, main character energy really does get different rules. 👑

the signal state of the new thread shall be initialized as follows:

• the signal mask shall be inherited from the creating thread.
• the set of signals pending for the new thread shall be empty.

the thread-local current locale and the alternate stack shall not be inherited. (not me passing down zero trauma, growth 🌱)

the floating-point environment shall be inherited from the creating thread.

if pthread_create() fails, no new thread is created and the contents of the location referenced by thread are undefined. 💀

if _POSIX_THREAD_CPUTIME is defined, the new thread shall have a CPU-time clock accessible, and the initial value of this clock shall be set to zero.

the behavior is undefined if the value specified by the attr argument to pthread_create() does not refer to an initialized thread attributes object. like, undefined undefined. don't do it. 🚨

---

⭐ RETURN VALUE ⭐

if successful, the pthread_create() function shall return zero; otherwise, an error number shall be returned to indicate the error. (yes, it returns the error number directly, it does not set errno, we love a function that just tells you straight 🫶)

---

🔥 ERRORS 🔥

the pthread_create() function shall fail if:

• EAGAIN — the system lacked the necessary resources to create another thread, or the system-imposed limit on the total number of threads in a process {PTHREAD_THREADS_MAX} would be exceeded. basically the thread party is full. 😭
• EPERM — the caller does not have appropriate privileges to set the required scheduling parameters or scheduling policy. no permission bestie, sorry.

and importantly: the pthread_create() function shall not return an error code of [EINTR]. not a thing here.

the following sections are informative. (translation: the actual normative stuff is done, everything after this is ✨lore✨)

---

🎀 EXAMPLES 🎀

None.

(yeah. nothing. the vibes are the example. 😌)

---

🌈 APPLICATION USAGE 🌈

there is no requirement on the implementation that the ID of the created thread be available before the newly created thread starts executing. so don't come for the implementation about it. 🙅

the calling thread can obtain the ID of the created thread through the thread argument of the pthread_create() function, and the newly created thread can obtain its ID by a call to pthread_self(). that's the whole plan, that's the whole system. 💫

---

🧚 RATIONALE 🧚

(okay this is the gossip section, the "why is it like this" section, and it is long but it's giving lore so we're reading all of it)

a suggested alternative to pthread_create() would be to define two separate operations: create and start. some applications would find such behavior more natural. Ada, in particular, separates the "creation" of a task from its "activation". very demure, very mindful.

splitting the operation was rejected by the standard developers for many reasons:

• the number of calls required to start a thread would increase from one to two and thus place an additional burden on applications that do not require the additional synchronization. the second call, however, could be avoided by the additional complication of a start-up state attribute.
• an extra state would be introduced: "created but not started". this would require the standard to specify the behavior of the thread operations when the target has not yet started executing.
• for those applications that require such behavior, it is possible to simulate the two separate steps with the facilities that are currently provided. the start_routine() can synchronize by waiting on a condition variable that is signaled by the start operation.

an Ada implementor can choose to create the thread at either of two points in the Ada program: when the task object is created, or when the task is activated (generally at a "begin"). if the first approach is adopted, the start_routine() needs to wait on a condition variable to receive the order to begin "activation". the second approach requires no such condition variable or extra synchronization. in either approach, a separate Ada task control block would need to be created when the task object is created to hold rendezvous queues, and so on. (iykyk 🫡)

an extension of the preceding model would be to allow the state of the thread to be modified between the create and start. this would allow the thread attributes object to be eliminated. this has been rejected because:

• all state in the thread attributes object has to be able to be set for the thread. this would require the definition of functions to modify thread attributes. there would be no reduction in the number of function calls required to set up the thread. in fact, for an application that creates all threads using identical attributes, the number of function calls required to set up the threads would be dramatically increased. use of a thread attributes object permits the application to make one set of attribute setting function calls. otherwise, the set of attribute setting function calls needs to be made for each thread creation. (imagine. the inefficiency. no thanks 💀)
• depending on the implementation architecture, functions to set thread state would require kernel calls, or for other implementation reasons would not be able to be implemented as macros, thereby increasing the cost of thread creation.
• the ability for applications to segregate threads by class would be lost. rip.

another suggested alternative uses a model similar to that for process creation, such as "thread fork". the fork semantics would provide more flexibility and the "create" function can be implemented simply by doing a thread fork followed immediately by a call to the desired "start routine" for the thread. this alternative has these problems:

• for many implementations, the entire stack of the calling thread would need to be duplicated, since in many architectures there is no way to determine the size of the calling frame.
• efficiency is reduced since at least some part of the stack has to be copied, even though in most cases the thread never needs the copied context, since it merely calls the desired start routine.

and finally, the recommendation part: if an implementation detects that the value specified by the attr argument to pthread_create() does not refer to an initialized thread attributes object, it is recommended that the function should fail and report an [EINVAL] error. 👀 (remember the undefined behavior from earlier? yeah. this is the polite suggestion about it.)

---

🦄 FUTURE DIRECTIONS 🦄

None.

(we're not going anywhere, we're staying exactly like this 💅)

---

💫 SEE ALSO 💫

• fork()
• pthread_exit()
• pthread_join()

The Base Definitions volume of POSIX.1‐2017, Section 4.12, Memory Synchronization, <pthread.h>

---

👑 COPYRIGHT 👑

portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1-2017, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group.

in the event of any discrepancy between this version and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. (the original ate, this one is the understudy 🫶) the original Standard can be obtained online at http://www.opengroup.org/unix/online.html .

any typographical or formatting errors that appear in this page are most likely to have been introduced during the conversion of the source files to man page format. to report such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .

---

and that's the whole page bestie!! brought to you by IEEE/The Open Group, 2017 — that's the source and the year, we're crediting them properly, no plagiarism in this group chat — for PTHREAD_CREATE(3P). now go make some threads. slay. 🧵✨💖