On Wed, Jul 27, 2022 at 07:31:11AM +0100, Jason McIntyre wrote: > On Tue, Jul 26, 2022 at 09:18:47PM -0500, Scott Cheloha wrote: > > A few improvements I want to make to the sleep(1) manpage. > > > > DESCRIPTION > > > > - "for a minimum of" is better said "for at least". > > > > hi. > > i can;t really distinguish between one form being better than the other. > "until at least" is the posix wording; "for a minimum" the text in > net/free/open etc.
I am confident "until at least" sounds more natural than "for a minimum of". > > > - 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? > > > > i suppose the dominance of sh has led to examples getting written in this > style. but that doesn;t mean we have to rewrite all csh examples. i > think we usually use sh for script examples, but try to make sure that > all examples work regardless of the user shell. > > you're right that the current section is a bit wordy though. Alright, I'm leaving it out then. > > - 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). > > > > normally we'd try to avoid sending the reader of section1 pages to > sections 2/3/9. but if there's stuff there that will help the user (not > code writer) then it'd make sense. is there? Nope, removed. > > - Add echo(1) and ls(1) from the EXAMPLES. > > > > that's not needed. we don;t add every command listed in the page to SEE > ALSO. just really pages we think will help people better understand the > subject they're reading about. so echo(1) does not really help you > understand sleep(1). however you should leave the reference to at(1) - > in this case it shows you how to do something like sleep, but better > suited to some specific tasks. Okay, I have dropped echo(1) and ls(1) and restored at(1). > > ... 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. > > > > again, i think that's outside the scope of sleep(1). We explicitly mention that sleep(1) has non-standard behavior when receiving SIGALRM. It's a feature. You can use it to, for example, manually intervene and abbreviate a long delay in a script. ... should I cook up an example with kill(1)? -- Here's an updated diff. I have also noted in History that sleep(1) was rewritten for 4.4BSD (to avoid issues with the AT&T copyright, I assume). Keith Bostic committed it, but I don't know if he actually rewrote it. 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 18:35:02 -0000 @@ -45,58 +45,27 @@ .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): +Wait five seconds before running a command: .Pp -.Dl (sleep 1800; sh command_file >& errors)& +.Dl $ sleep 5 ; echo Hello, World! .Pp -To repetitively run a command (with -.Xr csh 1 ) : +List a file twice per second: .Bd -literal -offset indent -while (! -r zzz.rawdata) - sleep 300 -end -foreach i (*.rawdata) - sleep 70 - awk -f collapse_data $i >> results -end -.Ed -.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. -.Pp -To monitor the growth of a file without consuming too many resources: -.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 @@ -108,10 +77,16 @@ 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 . +.Pp +This implementation of +.Nm +first appeared in +.Bx 4.4 .
