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