jcs.org
jcs's openbsd hax
openbsd
1.\" $OpenBSD: pthread_create.3,v 1.17 2025/06/07 00:16:52 schwarze Exp $
2.\"
3.\" Copyright (c) 1996 John Birrell <jb@cimlogic.com.au>.
4.\" All rights reserved.
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright
10.\" notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\" notice, this list of conditions and the following disclaimer in the
13.\" documentation and/or other materials provided with the distribution.
14.\" 3. All advertising materials mentioning features or use of this software
15.\" must display the following acknowledgement:
16.\" This product includes software developed by John Birrell.
17.\" 4. Neither the name of the author nor the names of any co-contributors
18.\" may be used to endorse or promote products derived from this software
19.\" without specific prior written permission.
20.\"
21.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL AND CONTRIBUTORS ``AS IS'' AND
22.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
23.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
24.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
25.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
26.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
27.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
28.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
29.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
30.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
31.\" SUCH DAMAGE.
32.\"
33.\" $FreeBSD: pthread_create.3,v 1.8 1999/08/28 00:03:04 peter Exp $
34.\"
35.Dd $Mdocdate: June 7 2025 $
36.Dt PTHREAD_CREATE 3
37.Os
38.Sh NAME
39.Nm pthread_create
40.Nd create a new thread
41.Sh SYNOPSIS
42.Lb libpthread
43.In pthread.h
44.Ft int
45.Fn pthread_create "pthread_t *thread" "const pthread_attr_t *attr" "void *(*start_routine)(void *)" "void *arg"
46.Sh DESCRIPTION
47The
48.Fn pthread_create
49function is used to create a new thread, with attributes specified by
50.Fa attr ,
51within a process.
52If
53.Fa attr
54is NULL, the default attributes are used.
55If the attributes specified by
56.Fa attr
57are modified later, the thread's attributes are not affected.
58Upon successful completion
59.Fn pthread_create
60will store the ID of the created thread in the location specified by
61.Fa thread .
62.Pp
63The thread is created executing
64.Fa start_routine
65with
66.Fa arg
67as its sole argument.
68If the
69.Fa start_routine
70returns, the effect is as if there was an implicit call to
71.Fn pthread_exit
72using the return value of
73.Fa start_routine
74as the exit status.
75Note that the thread in which
76.Fn main
77was originally invoked differs from this.
78When it returns from
79.Fn main ,
80the effect is as if there was an implicit call to
81.Fn exit
82using the return value of
83.Fn main
84as the exit status.
85.Pp
86The signal state of the new thread is initialized as:
87.Bl -bullet -offset indent
88.It
89The signal mask is inherited from the creating thread.
90.It
91The set of signals pending for the new thread is empty.
92.El
93.Sh RETURN VALUES
94If successful, the
95.Fn pthread_create
96function will return zero.
97Otherwise an error number will be returned to indicate the error.
98.Sh ERRORS
99.Fn pthread_create
100will fail if:
101.Bl -tag -width Er
102.It Bq Er EAGAIN
103The system lacked the necessary resources to create another thread, or
104the system-imposed limit on the total number of threads in a process
105[PTHREAD_THREADS_MAX] would be exceeded.
106.It Bq Er EINVAL
107The value specified by
108.Fa attr
109is invalid.
110.El
111.Sh SEE ALSO
112.Xr __tfork 3 ,
113.Xr pthread_attr_init 3 ,
114.Xr pthread_attr_setdetachstate 3 ,
115.Xr pthread_attr_setguardsize 3 ,
116.Xr pthread_attr_setstack 3 ,
117.Xr pthread_attr_setstackaddr 3 ,
118.Xr pthread_attr_setstacksize 3 ,
119.Xr pthread_cleanup_pop 3 ,
120.Xr pthread_cleanup_push 3 ,
121.Xr pthread_exit 3 ,
122.Xr pthread_join 3
123.Sh STANDARDS
124.Fn pthread_create
125conforms to
126.St -p1003.1-96 .