pthread_create

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



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


NAME
       pthread_create — thread creation

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
       The pthread_create() function shall create a new thread, with attributes
       specified by attr, within a process. If attr is NULL, the default
       attributes shall be used. If the attributes specified by attr are
       modified later, the thread's attributes shall not be affected.  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. If the 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. 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.

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

RETURN VALUE
       If successful, the pthread_create() function shall return zero;
       otherwise, an error number shall be returned to indicate the error.

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.

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

       The pthread_create() function shall not return an error code of [EINTR].

       The following sections are informative.

EXAMPLES
       None.

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. The
       calling thread can obtain the ID of the created thread through the return
       value of the pthread_create() function, and the newly created thread can
       obtain its ID by a call to pthread_self().

RATIONALE
       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''.

       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.

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

FUTURE DIRECTIONS
       None.

SEE ALSO
       fork(), pthread_exit(), pthread_join()

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

COPYRIGHT
       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electrical
       and Electronics Engineers, Inc and The Open Group.  (This is POSIX.1-2008
       with the 2013 Technical Corrigendum 1 applied.) 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.unix.org/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                   2013                PTHREAD_CREATE(3POSIX)