PTHREAD_CREATE(3)          POSIX Programmer's Manual         PTHREAD_CREATE(3)



PPRROOLLOOGG
       This manual page is part of the POSIX Programmer's Manual.  The OS
       implementation of this interface may differ (consult the corresponding
       OS manual page for details of OS behavior), or the interface may not be
       implemented on OS.

NNAAMMEE
       pthread_create -- thread creation

SSYYNNOOPPSSIISS
       #include <pthread.h>

       int pthread_create(pthread_t *restrict _t_h_r_e_a_d,
           const pthread_attr_t *restrict _a_t_t_r,
           void *(*_s_t_a_r_t___r_o_u_t_i_n_e)(void*), void *restrict _a_r_g);

DDEESSCCRRIIPPTTIIOONN
       The _p_t_h_r_e_a_d___c_r_e_a_t_e() function shall create a new thread, with
       attributes specified by _a_t_t_r, within a process. If _a_t_t_r is NULL, the
       default attributes shall be used. If the attributes specified by _a_t_t_r
       are modified later, the thread's attributes shall not be affected.
       Upon successful completion, _p_t_h_r_e_a_d___c_r_e_a_t_e() shall store the ID of the
       created thread in the location referenced by _t_h_r_e_a_d.

       The thread is created executing _s_t_a_r_t___r_o_u_t_i_n_e with _a_r_g as its sole
       argument. If the _s_t_a_r_t___r_o_u_t_i_n_e returns, the effect shall be as if there
       was an implicit call to _p_t_h_r_e_a_d___e_x_i_t() using the return value of
       _s_t_a_r_t___r_o_u_t_i_n_e as the exit status. Note that the thread in which _m_a_i_n()
       was originally invoked differs from this. When it returns from _m_a_i_n(),
       the effect shall be as if there was an implicit call to _e_x_i_t() using
       the return value of _m_a_i_n() as the exit status.

       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.

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

       If _p_t_h_r_e_a_d___c_r_e_a_t_e() fails, no new thread is created and the contents of
       the location referenced by _t_h_r_e_a_d 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 _a_t_t_r argument
       to _p_t_h_r_e_a_d___c_r_e_a_t_e() does not refer to an initialized thread attributes
       object.

RREETTUURRNN VVAALLUUEE
       If successful, the _p_t_h_r_e_a_d___c_r_e_a_t_e() function shall return zero;
       otherwise, an error number shall be returned to indicate the error.

EERRRROORRSS
       The _p_t_h_r_e_a_d___c_r_e_a_t_e() function shall fail if:

       EEAAGGAAIINN 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.

       EEPPEERRMM  The caller does not have appropriate privileges to set the
              required scheduling parameters or scheduling policy.

       The _p_t_h_r_e_a_d___c_r_e_a_t_e() function shall not return an error code of
       [[EEIINNTTRR]].

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

EEXXAAMMPPLLEESS
       None.

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       There is no requirement on the implementation that the ID of the
       created thread be available before the newly created thread starts
       executing. The calling thread can obtain the ID of the created thread
       through the _t_h_r_e_a_d argument of the _p_t_h_r_e_a_d___c_r_e_a_t_e() function, and the
       newly created thread can obtain its ID by a call to _p_t_h_r_e_a_d___s_e_l_f().

RRAATTIIOONNAALLEE
       A suggested alternative to _p_t_h_r_e_a_d___c_r_e_a_t_e() 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''.

       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 _s_t_a_r_t___r_o_u_t_i_n_e() 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 _s_t_a_r_t___r_o_u_t_i_n_e() 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.

       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.

        *  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.

       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.

       If an implementation detects that the value specified by the _a_t_t_r
       argument to _p_t_h_r_e_a_d___c_r_e_a_t_e() does not refer to an initialized thread
       attributes object, it is recommended that the function should fail and
       report an [[EEIINNVVAALL]] error.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _f_o_r_k(), _p_t_h_r_e_a_d___e_x_i_t(), _p_t_h_r_e_a_d___j_o_i_n()

       The Base Definitions volume of POSIX.1-2017, _S_e_c_t_i_o_n _4_._1_2, _M_e_m_o_r_y
       _S_y_n_c_h_r_o_n_i_z_a_t_i_o_n, <<pptthhrreeaadd..hh>>

CCOOPPYYRRIIGGHHTT
       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 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 .



IEEE/The Open Group                  2017                    PTHREAD_CREATE(3)
