xref: /dragonfly/lib/libc/sys/nanosleep.2 (revision 86ccdacb) 
1.\" $FreeBSD: src/lib/libc/sys/nanosleep.2,v 1.8.2.5 2002/12/20 18:39:35 ceri Exp $
2.\"	$OpenBSD: nanosleep.2,v 1.1 1997/04/20 20:56:20 tholo Exp $
3.\"	$NetBSD: nanosleep.2,v 1.1 1997/04/17 18:12:02 jtc Exp $
4.\"
5.\" Copyright (c) 1986, 1991, 1993
6.\"	The Regents of the University of California.  All rights reserved.
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.\" 3. Neither the name of the University nor the names of its contributors
17.\"    may be used to endorse or promote products derived from this software
18.\"    without specific prior written permission.
19.\"
20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.\"     @(#)sleep.3	8.1 (Berkeley) 6/4/93
33.\"
34.Dd January 17, 2021
35.Dt NANOSLEEP 2
36.Os
37.Sh NAME
38.Nm nanosleep
39.Nd high resolution sleep
40.Sh LIBRARY
41.Lb libc
42.Sh SYNOPSIS
43.In time.h
44.Ft int
45.Fo nanosleep
46.Fa "const struct timespec *rqtp"
47.Fa "struct timespec *rmtp"
48.Fc
49.Ft int
50.Fo clock_nanosleep
51.Fa "clockid_t clock_id"
52.Fa "int flags"
53.Fa "const struct timespec *rqtp"
54.Fa "struct timespec *rmtp"
55.Fc
56.Sh DESCRIPTION
57Both
58.Fn nanosleep
59and
60.Fn clock_nanosleep
61allow to suspend the calling thread for an interval
62measured in nanoseconds.
63Compared to
64.Fn nanosleep ,
65.Fn clock_nanosleep
66further allows the caller to select the clock against which
67the suspension interval is to be measured,
68and allows the suspension interval to be specified as either a relative
69or an absolute value.
70.Pp
71If the
72.Fa flags
73argument is 0 (i.e., the
74.Dv TIMER_ABSTIME
75flag is not set),
76the value specified in the
77.Fa rqtp
78argument is interpreted as an interval relative to the current time
79measured in the clock specified by the
80.Fa clock_id
81argument.
82Then
83.Fn clock_nanosleep
84suspends execution of the calling thread until either the
85time interval specified by the
86.Fa rqtp
87argument has elapsed,
88or a signal is delivered to the calling process and its
89action is to invoke a signal-catching function or to terminate the
90process.
91.Pp
92If the
93.Fa flags
94argument is
95.Dv TIMER_ABSTIME ,
96the value specified in the
97.Fa rqtp
98argument is interpreted as an absolute time measured by the
99.Fa clock_id
100clock.
101Then
102.Fn clock_nanosleep
103suspends execution of the calling thread until either the
104value of the clock specified by the
105.Fa clock_id
106argument reaches the absolute time specified by the
107.Fa rqtp
108argument,
109or a signal is delivered to the calling process and its
110action is to invoke a signal-catching function or to terminate the
111process.
112If, at the time of the call, the time value specified by
113.Fa rqtp
114is less than or equal to the time value of the specified clock, then
115.Fn clock_nanosleep
116returns immediately and the calling thread is not suspended.
117.Pp
118The suspension time may be longer than requested due to the
119scheduling of other activity by the system.
120An unmasked signal will terminate the sleep early, regardless of the
121.Dv SA_RESTART
122value on the interrupting signal.
123The
124.Fa rqtp
125and
126.Fa rmtp
127arguments can point to the same object.
128.Pp
129The following
130.Fa clock_id
131values (see
132.Xr clock_gettime 2
133for their meanings) are supported:
134.Pp
135.Bl -item -compact -offset indent
136.It
137CLOCK_MONOTONIC
138.It
139CLOCK_MONOTONIC_FAST
140.It
141CLOCK_MONOTONIC_PRECISE
142.It
143CLOCK_REALTIME
144.It
145CLOCK_REALTIME_FAST
146.It
147CLOCK_REALTIME_PRECISE
148.It
149CLOCK_SECOND
150.It
151CLOCK_UPTIME
152.It
153CLOCK_UPTIME_FAST
154.It
155CLOCK_UPTIME_PRECISE
156.El
157.Pp
158The
159.Fn nanosleep
160function behaves like
161.Fn clock_nanosleep
162with a
163.Fa clock_id
164argument of
165.Dv CLOCK_REALTIME
166and without the
167.Dv TIMER_ABSTIME
168flag in the
169.Fa flags
170argument.
171.Pp
172The use of these functions has no effect on the action or blockage of any signal.
173.Sh RETURN VALUES
174These functions return zero when the requested time has elapsed.
175.Pp
176If these functions return for any other reason, then
177.Fn clock_nanosleep
178will directly return the error number, and
179.Fn nanosleep
180will return \-1 with the global variable
181.Va errno
182set to indicate the error.
183If a relative sleep is interrupted by a signal and
184.Fa rmtp
185is
186.Pf non- Dv NULL ,
187the timespec structure it references is updated to contain the
188unslept amount (the request time minus the time actually slept).
189.Sh ERRORS
190These functions can fail with the following errors:
191.Bl -tag -width Er
192.It Bq Er EFAULT
193Either
194.Fa rqtp
195or
196.Fa rmtp
197points to memory that is not a valid part of the process
198address space.
199.It Bq Er EINTR
200The function was interrupted by the delivery of a signal.
201.It Bq Er EINVAL
202The
203.Fa rqtp
204argument specified a nanosecond value less than zero
205or greater than or equal to 1000 million.
206.It Bq Er EINVAL
207The
208.Fa flags
209argument contained an invalid flag.
210.It Bq Er EINVAL
211The
212.Fa clock_id
213argument was
214.Dv CLOCK_THREAD_CPUTIME_ID
215or an unrecognized value.
216.It Bq Er ENOTSUP
217The
218.Fa clock_id
219argument was valid but not supported by this implementation of
220.Fn clock_nanosleep .
221.El
222.Sh SEE ALSO
223.Xr clock_gettime 2 ,
224.Xr sigaction 2 ,
225.Xr sleep 3
226.Sh STANDARDS
227The
228.Fn nanosleep
229function conforms to
230.St -p1003.1b-93 .
231The
232.Fn clock_nanosleep
233function conforms to
234.St -p1003.1-2008 .
235