Added a note about the return value. Its been so long I can't

remember who suggested the 'caveat' section.  Sorry.

1 files changed, 19 insertions, 0 deletions

diff --git a/lib/libc/gen/sleep.3 b/lib/libc/gen/sleep.3
index a56a80e..1016a3d 100644
--- a/lib/libc/gen/sleep.3
+++ b/lib/libc/gen/sleep.3
@@ -72,10 +72,29 @@ such a function would not restart after signals, but would not interfere
 with other uses of
 .Xr setitimer 2 .
 .Sh RETURN VALUES
+The
+.Fn sleep
+function returns the number of seconds remaining to complete the operation. If
+sleep is interrupted or cannot allocate a timer it may will return the value
+needed to be passed to a subsequent sleep to complete the necessary delay.
+.Fn sleep
+repeatedly until it returns zero may busy-wait until a timer
+is available.
 .Sh SEE ALSO
 .Xr setitimer 2 ,
 .Xr sigpause 2 ,
 .Xr usleep 3
+.Sh CAVEAT
+In practice the FreeBSD implementation will not be interrupted: it will
+always return the original argument or zero. Code that depends on
+sleep being interrupted (using it as a timed pause, for example) needs
+to be recoded to use
+.Xr select 2
+or some other delay mechanism. Code that
+calls
+.Fn sleep
+repeatedly until it returns zero may busy-wait until a timer
+is available.
 .Sh HISTORY
 A
 .Fn sleep