[src/trunk]: src/share/man/man4 Tighten language so it fits in one paragraph ...

[riastradh <riastradh%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/6e23d00ceed2
branches:  trunk
changeset: 932181:6e23d00ceed2
user:      riastradh <riastradh%NetBSD.org@localhost>
date:      Fri May 01 19:54:37 2020 +0000

description:
Tighten language so it fits in one paragraph again.

This way the first two paragraphs have parallel structure:

- _Applications_ should read from /dev/urandom or sysctl kern.arandom...
- _Systems_ should be engineered to read once from /dev/random...

diffstat:

 share/man/man4/rnd.4 |  42 +++++++++++++++++++-----------------------
 1 files changed, 19 insertions(+), 23 deletions(-)

diffs (60 lines):

diff -r 2bcf58090570 -r 6e23d00ceed2 share/man/man4/rnd.4
--- a/share/man/man4/rnd.4      Fri May 01 19:53:17 2020 +0000
+++ b/share/man/man4/rnd.4      Fri May 01 19:54:37 2020 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: rnd.4,v 1.31 2020/05/01 12:43:33 nia Exp $
+.\"    $NetBSD: rnd.4,v 1.32 2020/05/01 19:54:37 riastradh Exp $
 .\"
 .\" Copyright (c) 2014-2020 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -51,32 +51,28 @@
 predictable.
 .El
 .Pp
-Applications can read from
-.Pa /dev/urandom
+Applications should read from
+.Pa /dev/urandom ,
+or the
+.Xr sysctl 7
+variable
+.Li kern.arandom ,
 when they need randomly generated data, e.g. key material for
-cryptography or seeds for simulations, and the device is known
-to be available.
-.Pp
-A
+cryptography or seeds for simulations.
+(The
 .Xr sysctl 7
-variable,
-.Li kern.arandom ,
-provides equivalent functionality to
+variable
+.Li kern.arandom
+is limited to 256 bytes per read, but is otherwise equivalent to
+reading from
 .Pa /dev/urandom
-and will never block.  However, it only returns up to 256 bytes per call.
-This is expected to be enough for seeding most cryptographically secure
-random number generators and ciphers, and if more data is required the
-variable can be queried again.
-.Pp
-Applications should read from the sysctl variable when a high level of
-reliability is required, or the runtime environment cannot be predicted,
-e.g. in a library.  It is possible that
-.Pa /dev/urandom
-is unavailable due to the application being in a
+and always works even in a
 .Xr chroot 8
-environment, or when other restrictions such as those enforced by
-.Xr setrlimit 2
-apply.
+environment without requiring a populated
+.Pa /dev
+tree and without opening a file descriptor, so
+.Li kern.arandom
+may be preferable to use in libraries.)
 .Pp
 Systems should be engineered to judiciously read at least once from
 .Pa /dev/random