1.\" $NetBSD: thrd.3,v 1.3 2019/04/27 10:57:11 wiz Exp $ 2.\" 3.\" Copyright (c) 2016 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Kamil Rytarowski. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd October 16, 2016 31.Dt THRD 3 32.Os 33.Sh NAME 34.Nm thrd 35.Nd thread functions 36.Sh LIBRARY 37.Lb libpthread 38.Sh SYNOPSIS 39.In threads.h 40.Vt typedef "int" "(*thrd_start_t)" "(void *)" 41.Ft int 42.Fn thrd_create "thrd_t *thr" "thrd_start_t func" "void *arg" 43.Ft thrd_t 44.Fn thrd_current "void" 45.Ft int 46.Fn thrd_detach "thrd_t thr" 47.Ft int 48.Fn thrd_equal "thrd_t t1" "thrd_t t2" 49.Ft _Noreturn void 50.Fn thrd_exit "int res" 51.Ft int 52.Fn thrd_join "thrd_t thr" "int *res" 53.Ft int 54.Fn thrd_sleep "const struct timespec *duration" "struct timespec *remaining" 55.Ft void 56.Fn thrd_yield "void" 57.Sh DESCRIPTION 58The 59.Nm 60interface operates over opaque objects of the 61.Dv thrd_t 62type. 63.Pp 64The 65.Fn thrd_create 66function is used to create a new thread, calling 67.Fa func 68with the 69.Fa arg 70parameter. 71This function initializes the 72.Fa thr 73object with the identifier of the newly created thread. 74The completion of 75.Fn thrd_create 76is synchronized with the start of the newly produced thread. 77It is possible to reuse the 78.Fa thr 79object once the thread has terminated either by joining another thread 80operation or been detached. 81.Pp 82The 83.Fn thrd_current 84function returns the thread identifier of the current thread. 85.Pp 86The 87.Fn thrd_detach 88function is used to indicate that storage for the 89.Fa thr 90object can be reclaimed on the thread's termination. 91The 92.Fa thr 93object cannot be already detached or joined. 94.Pp 95The 96.Fn thrd_equal 97function is used to check whether two 98.Fa t1 99and 100.Fa t2 101objects refer to the same thread. 102.Pp 103The 104.Fn thrd_exit 105function terminates the calling thread and passes the 106.Fa res 107value that might be read by the 108.Fn thrd_join 109function. 110The program terminates once all threads have been terminated with 111an exit code equivalent to calling the 112.Xr exit 3 113function with the 114.Dv EXIT_SUCCESS 115status. 116The 117.Fn thrd_join 118function joins the 119.Fa thr 120thread, waiting and blocking until it has terminated. 121The 122.Fa res 123parameter points to a variable that will store the status passed from the 124joined function. 125If 126.Fa res 127is 128.Dv NULL 129then the status from the 130.Fn thrd_exit 131function is ignored. 132.Pp 133The 134.Fn thrd_sleep 135function suspends execution of the calling thread until either 136a signal is received or the interval specified in the 137.Fa duration 138argument has been passed. 139The 140.Fa remaining 141parameter stores requested timeout reduced with the time actually suspended. 142This argument is used when 143.Fn thrd_sleep 144has been interrupted. 145It is valid code to point both arguments 146.Fa duration 147and 148.Fa remaining 149to the same object. 150It is not guaranteed that sleep will not take longer than specified in 151.Fa duration , 152however unless interrupted with a signal it will not take shorter 153than the specified interval. 154.Pp 155The 156.Fn thrd_yield 157function yields a process voluntarily and gives other threads a chance to run 158without waiting for any involuntary preemptive switch. 159.Sh RETURN VALUES 160The 161.Fn thrd_create 162function returns 163.Dv thrd_success 164on success, otherwise 165.Dv thrd_nomem 166if not sufficient memory could be allocated, or 167.Dv thrd_error 168on other errors. 169.Pp 170The 171.Fn thrd_current 172function returns the identifier of the calling thread. 173.Pp 174The 175.Fn thrd_detach 176function returns 177.Dv thrd_current 178on success or 179.Dv thrd_error 180on failure. 181.Pp 182The 183.Fn thrd_equal 184function returns zero if 185.Fa t0 186and 187.Fa t1 188refer to the different threads, 189otherwise it will return non-zero. 190.Pp 191The 192.Fn thrd_exit 193function does not return. 194.Pp 195The 196.Fn thrd_join 197function returns 198.Dv thrd_success 199on success or 200.Dv thrd_error 201on failure. 202.Pp 203The 204.Fn thrd_sleep 205function returns 0 on success (as the requested time has elapsed), 206\-1 once the function was interrupted by a signal, 207or a negative value to indicate error. 208The 209.Nx 210implementation returns \-2 on error. 211.Pp 212The 213.Fn thrd_yield 214function returns no value. 215.Sh SEE ALSO 216.Xr nanosleep 2 , 217.Xr pthread_create 3 , 218.Xr pthread_detach 3 , 219.Xr pthread_equal 3 , 220.Xr pthread_exit 3 , 221.Xr pthread_join 3 , 222.Xr pthread_self 3 , 223.Xr sched 3 , 224.Xr threads 3 225.Sh STANDARDS 226The 227.Nm 228interface conforms to 229.St -isoC-2011 . 230.Sh HISTORY 231This interface first appeared in 232.Nx 9 . 233.Sh AUTHORS 234.An Kamil Rytarowski Aq Mt kamil@NetBSD.org 235