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