xref: /dragonfly/lib/libc/sys/nanosleep.2 (revision b827281d) 
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.Nm clock_nanosleep
40.Nd high resolution sleep
41.Sh LIBRARY
42.Lb libc
43.Sh SYNOPSIS
44.In time.h
45.Ft int
46.Fo nanosleep
47.Fa "const struct timespec *rqtp"
48.Fa "struct timespec *rmtp"
49.Fc
50.Ft int
51.Fo clock_nanosleep
52.Fa "clockid_t clock_id"
53.Fa "int flags"
54.Fa "const struct timespec *rqtp"
55.Fa "struct timespec *rmtp"
56.Fc
57.Sh DESCRIPTION
58Both
59.Fn nanosleep
60and
61.Fn clock_nanosleep
62allow to suspend the calling thread for an interval
63measured in nanoseconds.
64Compared to
65.Fn nanosleep ,
66.Fn clock_nanosleep
67further allows the caller to select the clock against which
68the suspension interval is to be measured,
69and allows the suspension interval to be specified as either a relative
70or an absolute value.
71.Pp
72If the
73.Fa flags
74argument is 0 (i.e., the
75.Dv TIMER_ABSTIME
76flag is not set),
77the value specified in the
78.Fa rqtp
79argument is interpreted as an interval relative to the current time
80measured in the clock specified by the
81.Fa clock_id
82argument.
83Then
84.Fn clock_nanosleep
85suspends execution of the calling thread until either the
86time interval specified by the
87.Fa rqtp
88argument has elapsed,
89or a signal is delivered to the calling process and its
90action is to invoke a signal-catching function or to terminate the
91process.
92.Pp
93If the
94.Fa flags
95argument is
96.Dv TIMER_ABSTIME ,
97the value specified in the
98.Fa rqtp
99argument is interpreted as an absolute time measured by the
100.Fa clock_id
101clock.
102Then
103.Fn clock_nanosleep
104suspends execution of the calling thread until either the
105value of the clock specified by the
106.Fa clock_id
107argument reaches the absolute time specified by the
108.Fa rqtp
109argument,
110or a signal is delivered to the calling process and its
111action is to invoke a signal-catching function or to terminate the
112process.
113If, at the time of the call, the time value specified by
114.Fa rqtp
115is less than or equal to the time value of the specified clock, then
116.Fn clock_nanosleep
117returns immediately and the calling thread is not suspended.
118.Pp
119The suspension time may be longer than requested due to the
120scheduling of other activity by the system.
121An unmasked signal will terminate the sleep early, regardless of the
122.Dv SA_RESTART
123value on the interrupting signal.
124The
125.Fa rqtp
126and
127.Fa rmtp
128arguments can point to the same object.
129.Pp
130The following
131.Fa clock_id
132values (see
133.Xr clock_gettime 2
134for their meanings) are supported:
135.Pp
136.Bl -item -compact -offset indent
137.It
138CLOCK_MONOTONIC
139.It
140CLOCK_MONOTONIC_FAST
141.It
142CLOCK_MONOTONIC_PRECISE
143.It
144CLOCK_REALTIME
145.It
146CLOCK_REALTIME_FAST
147.It
148CLOCK_REALTIME_PRECISE
149.It
150CLOCK_SECOND
151.It
152CLOCK_UPTIME
153.It
154CLOCK_UPTIME_FAST
155.It
156CLOCK_UPTIME_PRECISE
157.El
158.Pp
159The
160.Fn nanosleep
161function behaves like
162.Fn clock_nanosleep
163with a
164.Fa clock_id
165argument of
166.Dv CLOCK_REALTIME
167and without the
168.Dv TIMER_ABSTIME
169flag in the
170.Fa flags
171argument.
172.Pp
173The use of these functions has no effect on the action or blockage of any signal.
174.Sh RETURN VALUES
175These functions return zero when the requested time has elapsed.
176.Pp
177If these functions return for any other reason, then
178.Fn clock_nanosleep
179will directly return the error number, and
180.Fn nanosleep
181will return \-1 with the global variable
182.Va errno
183set to indicate the error.
184If a relative sleep is interrupted by a signal and
185.Fa rmtp
186is
187.Pf non- Dv NULL ,
188the timespec structure it references is updated to contain the
189unslept amount (the request time minus the time actually slept).
190.Sh ERRORS
191These functions can fail with the following errors:
192.Bl -tag -width Er
193.It Bq Er EFAULT
194Either
195.Fa rqtp
196or
197.Fa rmtp
198points to memory that is not a valid part of the process
199address space.
200.It Bq Er EINTR
201The function was interrupted by the delivery of a signal.
202.It Bq Er EINVAL
203The
204.Fa rqtp
205argument specified a nanosecond value less than zero
206or greater than or equal to 1000 million.
207.It Bq Er EINVAL
208The
209.Fa flags
210argument contained an invalid flag.
211.It Bq Er EINVAL
212The
213.Fa clock_id
214argument was
215.Dv CLOCK_THREAD_CPUTIME_ID
216or an unrecognized value.
217.It Bq Er ENOTSUP
218The
219.Fa clock_id
220argument was valid but not supported by this implementation of
221.Fn clock_nanosleep .
222.El
223.Sh SEE ALSO
224.Xr clock_gettime 2 ,
225.Xr sigaction 2 ,
226.Xr sleep 3
227.Sh STANDARDS
228The
229.Fn nanosleep
230function conforms to
231.St -p1003.1b-93 .
232The
233.Fn clock_nanosleep
234function conforms to
235.St -p1003.1-2008 .
236