xref: /netbsd-src/bin/sleep/sleep.1 (revision a525a2707f14231df8c323f499f088fd72499a1b)
1.\"	$NetBSD: sleep.1,v 1.28 2023/02/19 10:54:35 uwe Exp $
2.\"
3.\" Copyright (c) 1990, 1993, 1994
4.\"	The Regents of the University of California.  All rights reserved.
5.\"
6.\" This code is derived from software contributed to Berkeley by
7.\" the Institute of Electrical and Electronics Engineers, Inc.
8.\"
9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions
11.\" are met:
12.\" 1. Redistributions of source code must retain the above copyright
13.\"    notice, this list of conditions and the following disclaimer.
14.\" 2. Redistributions in binary form must reproduce the above copyright
15.\"    notice, this list of conditions and the following disclaimer in the
16.\"    documentation and/or other materials provided with the distribution.
17.\" 3. Neither the name of the University nor the names of its contributors
18.\"    may be used to endorse or promote products derived from this software
19.\"    without specific prior written permission.
20.\"
21.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
22.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
23.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
24.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
25.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
26.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
27.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
28.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
29.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
30.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
31.\" SUCH DAMAGE.
32.\"
33.\"	@(#)sleep.1	8.3 (Berkeley) 4/18/94
34.\"
35.Dd January 26, 2019
36.Dt SLEEP 1
37.Os
38.Sh NAME
39.Nm sleep
40.Nd suspend execution for an interval of time
41.Sh SYNOPSIS
42.Nm
43.Ar seconds
44.Sh DESCRIPTION
45The
46.Nm
47utility suspends execution for a minimum of
48.Ar seconds
49seconds, then exits.
50It is usually used to schedule the execution of other commands
51.Po
52see
53.Sx EXAMPLES
54below
55.Pc .
56.Pp
57.Em Note :
58The
59.Nx
60.Nm
61command will accept and honor a non-integer number of specified seconds.
62Note however, that if the request is for much more than 2.5 hours,
63any fractional seconds will be ignored.
64Permitting non-integral delays is a
65.Em non-portable
66extension, and its use will decrease the probability that a shell
67script will execute properly on another system.
68.Pp
69When the
70.Dv SIGINFO
71signal is received, an estimate of the number of seconds remaining to
72sleep is printed on the standard output.
73.Sh EXIT STATUS
74The
75.Nm
76utility exits with one of the following values:
77.Bl -tag -width flag
78.It Li \&0
79On successful completion, or if the signal
80.Dv SIGALRM
81was received.
82.It Li \&>0
83An error occurred.
84.El
85.Sh EXAMPLES
86To schedule the execution of a command for 1800 seconds later:
87.Pp
88.Dl (sleep 1800; sh command_file >errors 2>&1)&
89.Pp
90This incantation would wait half an hour before
91running the script
92.Ar command_file .
93.Po
94See the
95.Xr at 1
96utility
97.Pc .
98.Pp
99To repeatedly run a command (using
100.Xr csh 1 ) :
101.Pp
102.Bd -literal -offset indent -compact
103while (1)
104	if (! -r zzz.rawdata) then
105		sleep 300
106	else
107		foreach i (*.rawdata)
108			sleep 70
109			awk -f collapse_data $i >> results
110		end
111		break
112	endif
113end
114.Ed
115.Pp
116The scenario for a script such as this might be: a program currently
117running is taking longer than expected to process a series of
118files, and it would be nice to have
119another program start processing the files created by the first
120program as soon as it is finished
121.Po
122when
123.Li zzz.rawdata
124is created
125.Pc .
126The script checks every five minutes for the file
127.Li zzz.rawdata .
128When the file is found, processing the generated files
129.Pq Li *.rawdata
130is done courteously by sleeping for 70 seconds in between each
131awk job.
132.Pp
133To wait until a particular time, the following,
134with some error checking added, might be used
135.Po
136using
137.Xr sh 1
138on
139.Nx
140.Pc :
141.Bd -literal -offset indent
142END=$(( $( date -d "$1" +%s ) - START_TIME ))
143while [ "${SECONDS}" -lt "${END}" ]
144do
145	sleep "$((END - SECONDS))"
146done
147.Ed
148.Pp
149where the argument
150.Ql $1
151specifies the desired date and time in any format the
152.Fl d
153option to the
154.Xr date 1
155command accepts.
156.Sh SEE ALSO
157.Xr at 1 ,
158.Xr csh 1 ,
159.Xr date 1 ,
160.Xr sh 1 ,
161.Xr nanosleep 2 ,
162.Xr sleep 3
163.Sh STANDARDS
164The
165.Nm
166command is expected to be
167.St -p1003.2
168compatible.
169.Sh HISTORY
170A
171.Nm
172utility appeared in
173.At v4 .
174Processing fractional seconds, and processing the
175.Ar seconds
176argument respecting the current locale, was added in
177.Nx 1.3 .
178The ability to sleep for extended periods appeared in
179.Nx 9.0 .
180.Sh BUGS
181This
182.Nm
183command cannot handle requests for durations
184much longer than about 250 billion years.
185Any such attempt will result in an error,
186and immediate termination.
187It is suggested that when there is a need
188for sleeps exceeding this period, the
189.Nm
190command be executed in a loop, with each
191individual
192.Nm
193invocation limited to 200 billion years
194approximately.
195