I, too, found it INCREDIBLY difficult to read. Perhaps because I don't have much understanding of random-number generators, but I had to re-read the first handful of entries about 3 times before I could catch on. I think a big part of it was my tendency to read the BOLD statements as the facts. Then when it said FACT beneath it, I had to start all over again.

Or better use getentropy(2)/getrandom(2) when it is possible.

arc4random and arc4random_buf are probably better still.

Please don't use arc4random* for cryptographic purposes. RC4 is broken -- there are practical attacks against it. It's fine for non-secure purposes though (eg. monte carlo simulation).

The 'arc4' no longer refers to RC4 on macOS/iOS and OpenBSD. On those systems 'arc4random' is playfully a bacronym for "A Replacement Call for Random". The new arc4random* implementation will now be replaced as cryptographic techniques advance.

It appears the Apple and OpenBSD implementations use the getentropy syscall and then add additional entropy mixing.

Yup, OpenBSD have even changed calls to other entropy sources to returning strong random by default from arc4random.

http://marc.info/?l=openbsd-cvs&m=141807513728073&w=2

libbsd is also using getentropy: https://cgit.freedesktop.org/libbsd/tree/src/arc4random.c

arc4random uses chacha20 on openBSD now, has for several years, OSX and FreeBSD are yet to update...

The macOS Sierra man page says it uses the NIST-approved AES cipher and will be replaced as the techniques advance.

True, but never pass GRND_RANDOM or GRND_NONBLOCK.

NONBLOCK just returns an error code instead of blocking. No harm in that, AFIAK.

Just wait until people start using the EAGAIN value in keys.

Why do these flags exist if they should never be used?

There are probably good uses for them.

But unless you are doing something very tightly integrated with Linux, you should just ignore them.