1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
|
<table class="head">
<tr>
<td class="head-ltitle">PTHREAD_CREATE(3)</td>
<td class="head-vol">Library Functions Manual</td>
<td class="head-rtitle">PTHREAD_CREATE(3)</td>
</tr>
</table>
<div class="manual-text">
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<p class="Pp"><code class="Nm">pthread_create</code> —
<span class="Nd">create a new thread</span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="LIBRARY"><a class="permalink" href="#LIBRARY">LIBRARY</a></h1>
<p class="Pp"><span class="Lb">POSIX Threads Library (libpthread,
-lpthread)</span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
<p class="Pp"><code class="In">#include
<<a class="In">pthread.h</a>></code></p>
<p class="Pp"><var class="Ft">int</var>
<br/>
<code class="Fn">pthread_create</code>(<var class="Fa" style="white-space: nowrap;">pthread_t
*restrict thread</var>, <var class="Fa" style="white-space: nowrap;">const
pthread_attr_t *restrict attr</var>,
<var class="Fa" style="white-space: nowrap;">void *(*start_routine)(void
*)</var>, <var class="Fa" style="white-space: nowrap;">void *restrict
arg</var>);</p>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
<p class="Pp">The
<a class="permalink" href="#pthread_create"><code class="Fn" id="pthread_create">pthread_create</code></a>()
function is used to create a new thread, with attributes specified by
<var class="Fa">attr</var>, within a process. If <var class="Fa">attr</var>
is <code class="Dv">NULL</code>, the default attributes are used. If the
attributes specified by <var class="Fa">attr</var> are modified later, the
thread's attributes are not affected. Upon successful completion
<code class="Fn">pthread_create</code>() will store the ID of the created
thread in the location specified by <var class="Fa">thread</var>.</p>
<p class="Pp" id="pthread_exit">The thread is created executing
<var class="Fa">start_routine</var> with <var class="Fa">arg</var> as its
sole argument. If the <var class="Fa">start_routine</var> returns, the
effect is as if there was an implicit call to
<a class="permalink" href="#pthread_exit"><code class="Fn">pthread_exit</code></a>()
using the return value of <var class="Fa">start_routine</var> as the exit
status. Note that the thread in which
<a class="permalink" href="#main"><code class="Fn" id="main">main</code></a>()
was originally invoked differs from this. When it returns from
<code class="Fn">main</code>(), the effect is as if there was an implicit
call to
<a class="permalink" href="#exit"><code class="Fn" id="exit">exit</code></a>()
using the return value of <code class="Fn">main</code>() as the exit
status.</p>
<p class="Pp">The signal state of the new thread is initialized as:</p>
<ul class="Bl-bullet Bd-indent">
<li>The signal mask is inherited from the creating thread.</li>
<li>The set of signals pending for the new thread is empty.</li>
</ul>
</section>
<section class="Sh">
<h1 class="Sh" id="RETURN_VALUES"><a class="permalink" href="#RETURN_VALUES">RETURN
VALUES</a></h1>
<p class="Pp">If successful, the <code class="Fn">pthread_create</code>()
function will return zero. Otherwise an error number will be returned to
indicate the error.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="ERRORS"><a class="permalink" href="#ERRORS">ERRORS</a></h1>
<p class="Pp">The <code class="Fn">pthread_create</code>() function can return
any of the following errors:</p>
<dl class="Bl-tag">
<dt id="ENOMEM">[<a class="permalink" href="#ENOMEM"><code class="Er">ENOMEM</code></a>]</dt>
<dd>The system lacked the necessary resources to create another thread.</dd>
<dt id="EAGAIN">[<a class="permalink" href="#EAGAIN"><code class="Er">EAGAIN</code></a>]</dt>
<dd>The system-imposed limit on the total number of threads in a process
<code class="Dv">[PTHREAD_THREADS_MAX]</code> would be exceeded.</dd>
<dt id="EAGAIN~2">[<a class="permalink" href="#EAGAIN~2"><code class="Er">EAGAIN</code></a>]</dt>
<dd>The <code class="Dv">RACCT_NTHR</code> limit would be exceeded; see
<a class="Xr">racct(2)</a>.</dd>
<dt id="EPERM">[<a class="permalink" href="#EPERM"><code class="Er">EPERM</code></a>]</dt>
<dd>The caller does not have permission to set the scheduling parameters or
scheduling policy.</dd>
<dt id="EINVAL">[<a class="permalink" href="#EINVAL"><code class="Er">EINVAL</code></a>]</dt>
<dd>A value specified by <var class="Fa">attr</var> is invalid.</dd>
<dt id="EDEADLK">[<a class="permalink" href="#EDEADLK"><code class="Er">EDEADLK</code></a>]</dt>
<dd>The CPU set specified by <var class="Fa">attr</var> would prevent the
thread from running on any CPU.</dd>
<dt id="EFAULT">[<a class="permalink" href="#EFAULT"><code class="Er">EFAULT</code></a>]</dt>
<dd>The stack base specified by <var class="Fa">attr</var> is invalid, or the
kernel was unable to put required initial data on the stack.</dd>
</dl>
</section>
<section class="Sh">
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
ALSO</a></h1>
<p class="Pp"><a class="Xr">cpuset_setaffinity(2)</a>,
<a class="Xr">fork(2)</a>, <a class="Xr">racct(2)</a>,
<a class="Xr">thr_new(2)</a>, <a class="Xr">pthread_attr(3)</a>,
<a class="Xr">pthread_cancel(3)</a>,
<a class="Xr">pthread_cleanup_pop(3)</a>,
<a class="Xr">pthread_cleanup_push(3)</a>,
<a class="Xr">pthread_exit(3)</a>, <a class="Xr">pthread_join(3)</a></p>
</section>
<section class="Sh">
<h1 class="Sh" id="STANDARDS"><a class="permalink" href="#STANDARDS">STANDARDS</a></h1>
<p class="Pp">The <code class="Fn">pthread_create</code>() function conforms to
<span class="St">ISO/IEC 9945-1:1996 (“POSIX.1”)</span>.</p>
</section>
</div>
<table class="foot">
<tr>
<td class="foot-date">August 17, 2018</td>
<td class="foot-os">FreeBSD 15.0</td>
</tr>
</table>
|
