man pages: add missing commas between subordinate and main clauses

jmc@ dislikes a comma before "then" in a conditional, so leave those
untouched.

ok jmc@

tsleep_nsec(9): add MAXTSLP macro, the maximum sleep duration

This macro will be useful for truncating durations below INFSLP
(UINT64_MAX) when converting from a timespec or timeval to a count
of nanoseconds before calling tsleep_nsec(9), msleep_nsec(9), or
rwsleep_nsec(9).

A relative timespec can hold many more nanoseconds than a uint64_t
can. TIMESPEC_TO_NSEC() and TIMEVAL_TO_NSEC() check for overflow,
returning UINT64_MAX if the conversion would overflow a uint64_t.

Thus, MAXTSLP will make it easy to avoid inadvertently passing INFSLP
to tsleep_nsec(9) et al. when the caller intended to set a timeout.

The code in such a case might look something like this:

uint64_t nsecs = MIN(TIMESPEC_TO_NSEC(&ts), MAXTSLP);

The macro may also be useful for rejecting intervals that are "too large",
e.g. for sockets with timeouts, if the timeout duration is to be stored
as a uint64_t in an object in the kernel. The code in such a case might
look something like this:

case SIOCTIMEOUT:
{
struct timeval *tv = (struct timeval *)data;
uint64_t nsecs;

if (tv->tv_sec < 0 || !timerisvalid(tv))
return EINVAL;

nsecs = TIMEVAL_TO_NSEC(tv);
if (nsecs > MAXTSLP)
return EOVERFLOW;

obj.timeout = nsecs;
break;
}

Idea suggested by visa@.

ok visa@

*sleep_nsec(9): sleep *at least* the given number of nanoseconds

The *sleep(9) interfaces are challenging to use when one needs to sleep
for a given minimum duration: the programmer needs to account for both
the current tick and any integer division when converting an interval
to a count of ticks. This sort of input conversion is complicated and
ugly at best and error-prone at worst.

This patch consolidates this conversion logic into the *sleep_nsec(9)
functions themselves. This will allow us to use the functions at the
syscall layer and elsewhere in the kernel where guaranteeing a minimum
sleep duration is of vital importance.

With input from bluhm@, guenther@, ratchov@, tedu@, and kettenis@.

Requested by mpi@ and kettenis@.

Conversion algorithm from mpi@.

ok mpi@, kettenis@, deraadt@

Add tsleep_nsec(9), msleep_nsec(9), and rwsleep_nsec(9).

Equivalent to their unsuffixed counterparts except that (a) they take
a timeout in terms of nanoseconds, and (b) INFSLP, aka UINT64_MAX (not
zero) indicates that a timeout should not be set.

For now, zero nanoseconds is not a strictly valid invocation: we log a
warning on DIAGNOSTIC kernels if we see such a call. We still sleep
until the next tick in such a case, however. In the future this could
become some sort of poll... TBD.

To facilitate conversions to these interfaces: add inline conversion
functions to sys/time.h for turning your timeout into nanoseconds.

Also do a few easy conversions for warmup and to demonstrate how
further conversions should be done.

Lots of input from mpi@ and ratchov@. Additional input from tedu@,
deraadt@, mortimer@, millert@, and claudio@.

Partly inspired by FreeBSD r247787.

positive feedback from deraadt@, ok mpi@

rwsleep: generalize to support both read- and write-locks.

Wanted for tentative clock_nanosleep(2) diff, but maybe useful
elsewhere in the future.

ok mpi@

Introduce rwsleep(9), an equivalent to msleep(9) but for code protected
by a write lock.

ok guenther@, vgross@

Remove useless quoting from .Fo and .Fn function names, to prevent
development of a cargo cult in case people look at existing files
for examples. This achieves a consistent .Fo and .Fn quoting style
across the whole tree.

- add wakep_{n,one} to NAME and more fully into DESCRIPTION
- zap eol whitespace

wakeup_n and wakeup_one blurbs

Replace old-fashioned .Fd by new-fangled .In for #include lines.
Diff from Jan Klemkow <j dot klemkow at wemelug dot de> on tech@.
No objection from jmc@ against this type of change.

these functions are in systm.h now, reminded by kettenis

First pass at removing clauses 3 and 4 from NetBSD licenses.

Not sure what's more surprising: how long it took for NetBSD to
catch up to the rest of the BSDs (including UCB), or the amount of
code that NetBSD has claimed for itself without attributing to the
actual authors.

OK deraadt@

Correct a typo:
tsleep -> msleep

from Paul de Weerd, Thanks!

- better integrate msleep() into this page
- art says bpendsleep has been removed, so kill it

ok art

<oga> art write me a manpage
<art> What? Write it yourself.
<oga> sudo art write me a manpage.
<art> ok

Document msleep(9).

sleep(9) was removed aeons ago according to miod, so remove references
to it. Because man pages are named after functions (at least they
should be) and sleep(9) doesn't exist anymore, sleep.9 is renamed to
tsleep.9.

Input and reminders from jmc and ratchov.

tsleep_nsec(9): add MAXTSLP macro, the maximum sleep duration

This macro will be useful for truncating durations below INFSLP
(UINT64_MAX) when converting from a timespec or timeval to a count
of nanoseconds before calling tsleep_nsec(9), msleep_nsec(9), or
rwsleep_nsec(9).

A relative timespec can hold many more nanoseconds than a uint64_t
can. TIMESPEC_TO_NSEC() and TIMEVAL_TO_NSEC() check for overflow,
returning UINT64_MAX if the conversion would overflow a uint64_t.

Thus, MAXTSLP will make it easy to avoid inadvertently passing INFSLP
to tsleep_nsec(9) et al. when the caller intended to set a timeout.

The code in such a case might look something like this:

uint64_t nsecs = MIN(TIMESPEC_TO_NSEC(&ts), MAXTSLP);

The macro may also be useful for rejecting intervals that are "too large",
e.g. for sockets with timeouts, if the timeout duration is to be stored
as a uint64_t in an object in the kernel. The code in such a case might
look something like this:

case SIOCTIMEOUT:
{
struct timeval *tv = (struct timeval *)data;
uint64_t nsecs;

if (tv->tv_sec < 0 || !timerisvalid(tv))
return EINVAL;

nsecs = TIMEVAL_TO_NSEC(tv);
if (nsecs > MAXTSLP)
return EOVERFLOW;

obj.timeout = nsecs;
break;
}

Idea suggested by visa@.

ok visa@

*sleep_nsec(9): sleep *at least* the given number of nanoseconds

The *sleep(9) interfaces are challenging to use when one needs to sleep
for a given minimum duration: the programmer needs to account for both
the current tick and any integer division when converting an interval
to a count of ticks. This sort of input conversion is complicated and
ugly at best and error-prone at worst.

This patch consolidates this conversion logic into the *sleep_nsec(9)
functions themselves. This will allow us to use the functions at the
syscall layer and elsewhere in the kernel where guaranteeing a minimum
sleep duration is of vital importance.

With input from bluhm@, guenther@, ratchov@, tedu@, and kettenis@.

Requested by mpi@ and kettenis@.

Conversion algorithm from mpi@.

ok mpi@, kettenis@, deraadt@

Add tsleep_nsec(9), msleep_nsec(9), and rwsleep_nsec(9).

Equivalent to their unsuffixed counterparts except that (a) they take
a timeout in terms of nanoseconds, and (b) INFSLP, aka UINT64_MAX (not
zero) indicates that a timeout should not be set.

For now, zero nanoseconds is not a strictly valid invocation: we log a
warning on DIAGNOSTIC kernels if we see such a call. We still sleep
until the next tick in such a case, however. In the future this could
become some sort of poll... TBD.

To facilitate conversions to these interfaces: add inline conversion
functions to sys/time.h for turning your timeout into nanoseconds.

Also do a few easy conversions for warmup and to demonstrate how
further conversions should be done.

Lots of input from mpi@ and ratchov@. Additional input from tedu@,
deraadt@, mortimer@, millert@, and claudio@.

Partly inspired by FreeBSD r247787.

positive feedback from deraadt@, ok mpi@

rwsleep: generalize to support both read- and write-locks.

Wanted for tentative clock_nanosleep(2) diff, but maybe useful
elsewhere in the future.

ok mpi@

Introduce rwsleep(9), an equivalent to msleep(9) but for code protected
by a write lock.

ok guenther@, vgross@

Remove useless quoting from .Fo and .Fn function names, to prevent
development of a cargo cult in case people look at existing files
for examples. This achieves a consistent .Fo and .Fn quoting style
across the whole tree.

- add wakep_{n,one} to NAME and more fully into DESCRIPTION
- zap eol whitespace

wakeup_n and wakeup_one blurbs

Replace old-fashioned .Fd by new-fangled .In for #include lines.
Diff from Jan Klemkow <j dot klemkow at wemelug dot de> on tech@.
No objection from jmc@ against this type of change.

these functions are in systm.h now, reminded by kettenis

First pass at removing clauses 3 and 4 from NetBSD licenses.

Not sure what's more surprising: how long it took for NetBSD to
catch up to the rest of the BSDs (including UCB), or the amount of
code that NetBSD has claimed for itself without attributing to the
actual authors.

OK deraadt@

Correct a typo:
tsleep -> msleep

from Paul de Weerd, Thanks!

- better integrate msleep() into this page
- art says bpendsleep has been removed, so kill it

ok art

<oga> art write me a manpage
<art> What? Write it yourself.
<oga> sudo art write me a manpage.
<art> ok

Document msleep(9).

sleep(9) was removed aeons ago according to miod, so remove references
to it. Because man pages are named after functions (at least they
should be) and sleep(9) doesn't exist anymore, sleep.9 is renamed to
tsleep.9.

Input and reminders from jmc and ratchov.

*sleep_nsec(9): sleep *at least* the given number of nanoseconds

The *sleep(9) interfaces are challenging to use when one needs to sleep
for a given minimum duration: the programmer needs to account for both
the current tick and any integer division when converting an interval
to a count of ticks. This sort of input conversion is complicated and
ugly at best and error-prone at worst.

This patch consolidates this conversion logic into the *sleep_nsec(9)
functions themselves. This will allow us to use the functions at the
syscall layer and elsewhere in the kernel where guaranteeing a minimum
sleep duration is of vital importance.

With input from bluhm@, guenther@, ratchov@, tedu@, and kettenis@.

Requested by mpi@ and kettenis@.

Conversion algorithm from mpi@.

ok mpi@, kettenis@, deraadt@

Add tsleep_nsec(9), msleep_nsec(9), and rwsleep_nsec(9).

Equivalent to their unsuffixed counterparts except that (a) they take
a timeout in terms of nanoseconds, and (b) INFSLP, aka UINT64_MAX (not
zero) indicates that a timeout should not be set.

For now, zero nanoseconds is not a strictly valid invocation: we log a
warning on DIAGNOSTIC kernels if we see such a call. We still sleep
until the next tick in such a case, however. In the future this could
become some sort of poll... TBD.

To facilitate conversions to these interfaces: add inline conversion
functions to sys/time.h for turning your timeout into nanoseconds.

Also do a few easy conversions for warmup and to demonstrate how
further conversions should be done.

Lots of input from mpi@ and ratchov@. Additional input from tedu@,
deraadt@, mortimer@, millert@, and claudio@.

Partly inspired by FreeBSD r247787.

positive feedback from deraadt@, ok mpi@

rwsleep: generalize to support both read- and write-locks.

Wanted for tentative clock_nanosleep(2) diff, but maybe useful
elsewhere in the future.

ok mpi@

Introduce rwsleep(9), an equivalent to msleep(9) but for code protected
by a write lock.

ok guenther@, vgross@

Remove useless quoting from .Fo and .Fn function names, to prevent
development of a cargo cult in case people look at existing files
for examples. This achieves a consistent .Fo and .Fn quoting style
across the whole tree.

- add wakep_{n,one} to NAME and more fully into DESCRIPTION
- zap eol whitespace

wakeup_n and wakeup_one blurbs

Replace old-fashioned .Fd by new-fangled .In for #include lines.
Diff from Jan Klemkow <j dot klemkow at wemelug dot de> on tech@.
No objection from jmc@ against this type of change.

these functions are in systm.h now, reminded by kettenis

First pass at removing clauses 3 and 4 from NetBSD licenses.

Not sure what's more surprising: how long it took for NetBSD to
catch up to the rest of the BSDs (including UCB), or the amount of
code that NetBSD has claimed for itself without attributing to the
actual authors.

OK deraadt@

Correct a typo:
tsleep -> msleep

from Paul de Weerd, Thanks!

- better integrate msleep() into this page
- art says bpendsleep has been removed, so kill it

ok art

<oga> art write me a manpage
<art> What? Write it yourself.
<oga> sudo art write me a manpage.
<art> ok

Document msleep(9).

sleep(9) was removed aeons ago according to miod, so remove references
to it. Because man pages are named after functions (at least they
should be) and sleep(9) doesn't exist anymore, sleep.9 is renamed to
tsleep.9.

Input and reminders from jmc and ratchov.

Add tsleep_nsec(9), msleep_nsec(9), and rwsleep_nsec(9).

Equivalent to their unsuffixed counterparts except that (a) they take
a timeout in terms of nanoseconds, and (b) INFSLP, aka UINT64_MAX (not
zero) indicates that a timeout should not be set.

For now, zero nanoseconds is not a strictly valid invocation: we log a
warning on DIAGNOSTIC kernels if we see such a call. We still sleep
until the next tick in such a case, however. In the future this could
become some sort of poll... TBD.

To facilitate conversions to these interfaces: add inline conversion
functions to sys/time.h for turning your timeout into nanoseconds.

Also do a few easy conversions for warmup and to demonstrate how
further conversions should be done.

Lots of input from mpi@ and ratchov@. Additional input from tedu@,
deraadt@, mortimer@, millert@, and claudio@.

Partly inspired by FreeBSD r247787.

positive feedback from deraadt@, ok mpi@

rwsleep: generalize to support both read- and write-locks.

Wanted for tentative clock_nanosleep(2) diff, but maybe useful
elsewhere in the future.

ok mpi@

Introduce rwsleep(9), an equivalent to msleep(9) but for code protected
by a write lock.

ok guenther@, vgross@

Remove useless quoting from .Fo and .Fn function names, to prevent
development of a cargo cult in case people look at existing files
for examples. This achieves a consistent .Fo and .Fn quoting style
across the whole tree.

- add wakep_{n,one} to NAME and more fully into DESCRIPTION
- zap eol whitespace

wakeup_n and wakeup_one blurbs

Replace old-fashioned .Fd by new-fangled .In for #include lines.
Diff from Jan Klemkow <j dot klemkow at wemelug dot de> on tech@.
No objection from jmc@ against this type of change.

these functions are in systm.h now, reminded by kettenis

First pass at removing clauses 3 and 4 from NetBSD licenses.

Not sure what's more surprising: how long it took for NetBSD to
catch up to the rest of the BSDs (including UCB), or the amount of
code that NetBSD has claimed for itself without attributing to the
actual authors.

OK deraadt@

Correct a typo:
tsleep -> msleep

from Paul de Weerd, Thanks!

- better integrate msleep() into this page
- art says bpendsleep has been removed, so kill it

ok art

<oga> art write me a manpage
<art> What? Write it yourself.
<oga> sudo art write me a manpage.
<art> ok

Document msleep(9).

sleep(9) was removed aeons ago according to miod, so remove references
to it. Because man pages are named after functions (at least they
should be) and sleep(9) doesn't exist anymore, sleep.9 is renamed to
tsleep.9.

Input and reminders from jmc and ratchov.

rwsleep: generalize to support both read- and write-locks.

Wanted for tentative clock_nanosleep(2) diff, but maybe useful
elsewhere in the future.

ok mpi@

Introduce rwsleep(9), an equivalent to msleep(9) but for code protected
by a write lock.

ok guenther@, vgross@

Remove useless quoting from .Fo and .Fn function names, to prevent
development of a cargo cult in case people look at existing files
for examples. This achieves a consistent .Fo and .Fn quoting style
across the whole tree.

- add wakep_{n,one} to NAME and more fully into DESCRIPTION
- zap eol whitespace

wakeup_n and wakeup_one blurbs

Replace old-fashioned .Fd by new-fangled .In for #include lines.
Diff from Jan Klemkow <j dot klemkow at wemelug dot de> on tech@.
No objection from jmc@ against this type of change.

these functions are in systm.h now, reminded by kettenis

First pass at removing clauses 3 and 4 from NetBSD licenses.

Not sure what's more surprising: how long it took for NetBSD to
catch up to the rest of the BSDs (including UCB), or the amount of
code that NetBSD has claimed for itself without attributing to the
actual authors.

OK deraadt@

Correct a typo:
tsleep -> msleep

from Paul de Weerd, Thanks!

- better integrate msleep() into this page
- art says bpendsleep has been removed, so kill it

ok art

<oga> art write me a manpage
<art> What? Write it yourself.
<oga> sudo art write me a manpage.
<art> ok

Document msleep(9).

sleep(9) was removed aeons ago according to miod, so remove references
to it. Because man pages are named after functions (at least they
should be) and sleep(9) doesn't exist anymore, sleep.9 is renamed to
tsleep.9.

Input and reminders from jmc and ratchov.

Introduce rwsleep(9), an equivalent to msleep(9) but for code protected
by a write lock.

ok guenther@, vgross@

Remove useless quoting from .Fo and .Fn function names, to prevent
development of a cargo cult in case people look at existing files
for examples. This achieves a consistent .Fo and .Fn quoting style
across the whole tree.

- add wakep_{n,one} to NAME and more fully into DESCRIPTION
- zap eol whitespace

wakeup_n and wakeup_one blurbs

Replace old-fashioned .Fd by new-fangled .In for #include lines.
Diff from Jan Klemkow <j dot klemkow at wemelug dot de> on tech@.
No objection from jmc@ against this type of change.

these functions are in systm.h now, reminded by kettenis

First pass at removing clauses 3 and 4 from NetBSD licenses.

Not sure what's more surprising: how long it took for NetBSD to
catch up to the rest of the BSDs (including UCB), or the amount of
code that NetBSD has claimed for itself without attributing to the
actual authors.

OK deraadt@

Correct a typo:
tsleep -> msleep

from Paul de Weerd, Thanks!

- better integrate msleep() into this page
- art says bpendsleep has been removed, so kill it

ok art

<oga> art write me a manpage
<art> What? Write it yourself.
<oga> sudo art write me a manpage.
<art> ok

Document msleep(9).

sleep(9) was removed aeons ago according to miod, so remove references
to it. Because man pages are named after functions (at least they
should be) and sleep(9) doesn't exist anymore, sleep.9 is renamed to
tsleep.9.

Input and reminders from jmc and ratchov.