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