pthread_create.3p (8493B)
- '\" et
- .TH PTHREAD_CREATE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
- .\"
- .SH 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.
- .\"
- .SH NAME
- pthread_create
- \(em thread creation
- .SH SYNOPSIS
- .LP
- .nf
- #include <pthread.h>
- .P
- int pthread_create(pthread_t *restrict \fIthread\fP,
- const pthread_attr_t *restrict \fIattr\fP,
- void *(*\fIstart_routine\fP)(void*), void *restrict \fIarg\fP);
- .fi
- .SH DESCRIPTION
- The
- \fIpthread_create\fR()
- function shall create a new thread, with attributes specified by
- .IR attr ,
- within a process. If
- .IR attr
- is NULL, the default attributes shall be used. If the attributes
- specified by
- .IR attr
- are modified later, the thread's attributes shall not be affected.
- Upon successful completion,
- \fIpthread_create\fR()
- shall store the ID of the created thread in the location referenced by
- .IR thread .
- .P
- The thread is created executing
- .IR start_routine
- with
- .IR arg
- as its sole argument. If the
- .IR start_routine
- returns, the effect shall be as if there was an implicit call to
- \fIpthread_exit\fR()
- using the return value of
- .IR start_routine
- as the exit status. Note that the thread in which
- \fImain\fR()
- was originally invoked differs from this. When it returns from
- \fImain\fR(),
- the effect shall be as if there was an implicit call to
- \fIexit\fR()
- using the return value of
- \fImain\fR()
- as the exit status.
- .P
- The signal state of the new thread shall be initialized as follows:
- .IP " *" 4
- The signal mask shall be inherited from the creating thread.
- .IP " *" 4
- The set of signals pending for the new thread shall be empty.
- .P
- The thread-local current locale
- and the alternate stack
- shall not be inherited.
- .P
- The floating-point environment shall be inherited from the creating
- thread.
- .P
- If
- \fIpthread_create\fR()
- fails, no new thread is created and the contents of the location
- referenced by
- .IR thread
- are undefined.
- .P
- 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.
- .P
- The behavior is undefined if the value specified by the
- .IR attr
- argument to
- \fIpthread_create\fR()
- does not refer to an initialized thread attributes object.
- .SH "RETURN VALUE"
- If successful, the
- \fIpthread_create\fR()
- function shall return zero; otherwise, an error number shall be
- returned to indicate the error.
- .SH ERRORS
- The
- \fIpthread_create\fR()
- function shall fail if:
- .TP
- .BR 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.
- .TP
- .BR EPERM
- The caller does not have appropriate privileges to set the required
- scheduling parameters or scheduling policy.
- .P
- The
- \fIpthread_create\fR()
- function shall not return an error code of
- .BR [EINTR] .
- .LP
- .IR "The following sections are informative."
- .SH EXAMPLES
- None.
- .SH "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
- .IR thread
- argument of the
- \fIpthread_create\fR()
- function, and the newly created thread can obtain its ID by a call to
- \fIpthread_self\fR().
- .SH RATIONALE
- A suggested alternative to
- \fIpthread_create\fR()
- 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''.
- .P
- Splitting the operation was rejected by the standard developers for
- many reasons:
- .IP " *" 4
- 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.
- .IP " *" 4
- 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.
- .IP " *" 4
- For those applications that require such behavior, it is possible to
- simulate the two separate steps with the facilities that are currently
- provided. The
- \fIstart_routine\fR()
- can synchronize by waiting on a condition variable that is signaled by
- the start operation.
- .P
- 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
- \fIstart_routine\fR()
- 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.
- .P
- 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:
- .IP " *" 4
- 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.
- .IP " *" 4
- 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.
- .IP " *" 4
- The ability for applications to segregate threads by class would be
- lost.
- .P
- 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:
- .IP " *" 4
- 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.
- .IP " *" 4
- 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.
- .P
- If an implementation detects that the value specified by the
- .IR attr
- argument to
- \fIpthread_create\fR()
- does not refer to an initialized thread attributes object, it is
- recommended that the function should fail and report an
- .BR [EINVAL]
- error.
- .SH "FUTURE DIRECTIONS"
- None.
- .SH "SEE ALSO"
- .IR "\fIfork\fR\^(\|)",
- .IR "\fIpthread_exit\fR\^(\|)",
- .IR "\fIpthread_join\fR\^(\|)"
- .P
- The Base Definitions volume of POSIX.1\(hy2017,
- .IR "Section 4.12" ", " "Memory Synchronization",
- .IR "\fB<pthread.h>\fP"
- .\"
- .SH 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 Standard can be obtained online at
- http://www.opengroup.org/unix/online.html .
- .PP
- 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 .