Fcntl: add module documentation

[mauke]

No description provided.

[jkeenan]

I'm glad that you took the time to write this documentation. However, it's such an extensive re-write that I question whether it should go into blead so soon before a production release.

[mauke]

Yes, it is a lot. But I'd argue this is only because the module barely had any documentation before and the little it had was partially inaccurate:

• By default your system's F_* and O_* constants (eg, F_DUPFD and O_CREAT) and the FD_CLOEXEC constant are exported into your namespace.

  Not true; e.g. O_NOATIME or F_GETSIG are not exported by default.

• See perlopentut to learn about the uses of the O_* constants with sysopen().

  That hasn't been the case since 2013; commit b25a8b1 removed all the sysopen bits from perlopentut.

• In multiple places, "the S_I* constants" are mentioned, but some of the S_I* symbols aren't constants; they're one-argument functions (e.g. S_ISREG, S_ISDIR) and, deviating from the C macros, S_IFMT can be used both with and without an argument.

All in all, I think my patch is a massive improvement over the status quo.

---

That said, it is a pure documentation patch. None of the code is changed, so I don't see how this could break anything. Documentation updates are explicitly allowed under the "blead freeze".

What is the risk that you're seeing?