A few improvements I want to make to the sleep(1) manpage. DESCRIPTION
- "for a minimum of" is better said "for at least". - The seconds argument can be zero, so say "non-negative". - Specify that the number (the whole thing) is decimal to exclude e.g. hex numbers. It then follows that the optional fraction must also be decimal. - I don't think we need to inspire the reader to use sleep(1) in any particular way. We can just demonstrate these patterns in the Examples provided later. ASYNCHRONOUS EVENTS - Note that SIGALRM wakes sleep(1) up "early". EXAMPLES - Simplify the first example. I think parenthetically pointing the reader to at(1) muddies what ought to be the simplest possible example. Scheduling jobs is a way more advanced topic, sleep(1) is more like a shell primitive. - Shorten the interval in the first example. A half hour is not interactive. - Get rid of the entire csh(1) example. It's extremely complex and the bulk of the text is spent explaining things that aren't about sleep(1) at all. Maybe also of note is that very few other manpages offer csh(1) examples. Is there a rule about that? - Tweak the third example to show the reader that you can sleep for a fraction of a second, as mentioned in the Description. STANDARDS - Prefer active voice. "The handling of fractional arguments" is better said "Support for fractional seconds". Shorten "is provided as" to "is". SEE ALSO - Seems logical to point back to nanosleep(2) and sleep(3). - Add echo(1) and ls(1) from the EXAMPLES. ... unsure if we actually need to reference these or if it's a distraction. The existing examples make use of awk(1) but do not Xr it in this section, unsure if there is a rule about this. - Add signal(3) because we talk about SIGALRM. HISTORY - Not merely "appeared": "first appeared". -- Tweaks? ok? Index: sleep.1 =================================================================== RCS file: /cvs/src/bin/sleep/sleep.1,v retrieving revision 1.22 diff -u -p -r1.22 sleep.1 --- sleep.1 16 Aug 2016 18:51:25 -0000 1.22 +++ sleep.1 27 Jul 2022 02:16:18 -0000 @@ -45,62 +45,35 @@ .Sh DESCRIPTION The .Nm -utility -suspends execution for a minimum of the specified number of -.Ar seconds . -This number must be positive and may contain a decimal fraction. -.Nm -is commonly used to schedule the execution of other commands (see below). +utility suspends execution until at least the given number of +.Ar seconds +have elapsed. +.Ar seconds +must be a non-negative decimal value and may contain a fraction. .Sh ASYNCHRONOUS EVENTS .Bl -tag -width "SIGALRMXXX" .It Dv SIGALRM -Terminate normally, with a zero exit status. +Terminate early, with a zero exit status. .El .Sh EXIT STATUS .Ex -std sleep .Sh EXAMPLES -Wait a half hour before running the script -.Pa command_file -(see also the -.Xr at 1 -utility): -.Pp -.Dl (sleep 1800; sh command_file >& errors)& -.Pp -To repetitively run a command (with -.Xr csh 1 ) : -.Bd -literal -offset indent -while (! -r zzz.rawdata) - sleep 300 -end -foreach i (*.rawdata) - sleep 70 - awk -f collapse_data $i >> results -end -.Ed +Wait five seconds before running a command: .Pp -The scenario for such a script might be: a program currently -running is taking longer than expected to process a series of -files, and it would be nice to have another program start -processing the files created by the first program as soon as it is finished -(when -.Pa zzz.rawdata -is created). -The script checks every five minutes for this file. -When it is found, processing is done in several steps -by sleeping 70 seconds between each -.Xr awk 1 -job. +.Dl $ sleep 5 ; echo Hello, World! .Pp -To monitor the growth of a file without consuming too many resources: +List a file twice per second: .Bd -literal -offset indent -while true; do - ls -l file - sleep 5 +while ls -l file; do + sleep 0.5 done .Ed .Sh SEE ALSO -.Xr at 1 +.Xr echo 1 , +.Xr ls 1 , +.Xr nanosleep 2 , +.Xr signal 3 , +.Xr sleep 3 .Sh STANDARDS The .Nm @@ -108,10 +81,11 @@ utility is compliant with the .St -p1003.1-2008 specification. .Pp -The handling of fractional arguments is provided as an extension to that -specification. +Support for fractional +.Ar seconds +is an extension to that specification. .Sh HISTORY A .Nm -utility appeared in +utility first appeared in .At v4 .
