1.\" Copyright (c) 2016 The FreeBSD Foundation, Inc. 2.\" 3.\" This documentation was written by 4.\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship 5.\" from the FreeBSD Foundation. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.Dd May 5, 2020 29.Dt THR_SUSPEND 2 30.Os 31.Sh NAME 32.Nm thr_suspend 33.Nd suspend the calling thread 34.Sh LIBRARY 35.Lb libc 36.Sh SYNOPSIS 37.In sys/thr.h 38.Ft int 39.Fn thr_suspend "struct timespec *timeout" 40.Sh DESCRIPTION 41.Bf -symbolic 42This function is intended for implementing threading. 43Normal applications should use 44.Xr pthread_cond_timedwait 3 45together with 46.Xr pthread_cond_broadcast 3 47for typical safe suspension with cooperation of the thread 48being suspended, or 49.Xr pthread_suspend_np 3 50and 51.Xr pthread_resume_np 3 52in some specific situations, instead. 53.Ef 54.Pp 55The 56.Fn thr_suspend 57system call puts the calling thread in a suspended state, where it is 58not eligible for CPU time. 59This state is exited by another thread calling 60.Xr thr_wake 2 , 61when the time interval specified by 62.Fa timeout 63has elapsed, 64or by the delivery of a signal to the suspended thread. 65.Pp 66If the 67.Fa timeout 68argument is 69.Dv NULL , 70the suspended state can be only terminated by explicit 71.Fn thr_wake 72or signal. 73.Pp 74If a wake from 75.Xr thr_wake 2 76was delivered before the 77.Nm 78call, the thread is not put into a suspended state. 79Instead, the call 80returns immediately without an error. 81.Pp 82If a thread previously called 83.Xr thr_wake 2 84with its own thread identifier, which resulted in setting the internal kernel 85flag to immediately abort interruptible sleeps with an 86.Er EINTR 87error 88.Po 89see 90.Xr thr_wake 2 91.Pc , 92the flag is cleared. 93As with 94.Xr thr_wake 2 95called from another thread, the next 96.Nm 97call does not result in suspension. 98.Sh RETURN VALUES 99.Rv -std thr_suspend 100.Sh ERRORS 101The 102.Fn thr_suspend 103operation returns the following errors: 104.Bl -tag -width Er 105.It Bq Er EFAULT 106The memory pointed to by the 107.Fa timeout 108argument is not valid. 109.It Bq Er ETIMEDOUT 110The specified timeout expired. 111.It Bq Er ETIMEDOUT 112The 113.Fa timeout 114argument specified a zero time interval. 115.It Bq Er EINTR 116The sleep was interrupted by a signal. 117.El 118.Sh SEE ALSO 119.Xr ps 1 , 120.Xr thr_wake 2 , 121.Xr pthread_resume_np 3 , 122.Xr pthread_suspend_np 3 123.Sh STANDARDS 124The 125.Fn thr_suspend 126system call is non-standard. 127.Sh HISTORY 128The 129.Fn thr_suspend 130system call first appeared in 131.Fx 5.2 . 132