shm: Document shm_create_largepage()

[markj]

Summary

While here, move notes about FreeBSD-specific functionality to the
COMPATIBILITY section, and document the ECAPMODE error for shm_open().

[markj]

• Add an MLINK.
• Fix some lint warnings.

[kib]

lib/libc/sys/shm_open.2

193

Perhaps mention munmap(2) as well.

212

213

Might be mention ftruncate(2) again?

217

If the wait-less allocation. I understand that there is no such word. Might be, say 'if system has suitable physical memory immediately available'?

234

or a non-blocked signal is delivered to the thread

262

Might be, mention that the initial shm obj parameters are set by FIOSSHMLPGCNF during shm_create_largepage(). This is useful to know to read truss/ktrace output.

[markj]

• Take kib's suggestions.

[markj]

lib/libc/sys/shm_open.2

217

I wrote "non-blocking".

[pauamma_gundo.com]

lib/libc/sys/shm_open.2

181

Or maybe "of mappings"

184

For consistency with

This ensures that the object can be mapped using so-called
.Dq superpages ,

190–191

Same as above

220

240–241

Is the kernel able to detect that and give up? Or would the thread just lock up in the kernel? (In the latter case, maybe suggest a reasonable value for calling alarm() or some other way to recover.)

269–270

[markj]

lib/libc/sys/shm_open.2

184

Here I'm referring to a physical page size, whereas a "superpage" usually refers to the size of a virtual mapping. I think the suggested change is a bit confusing and not really consistent with the rest of the text.

240–241

The previous sentence mentions that a signal can interrupt the allocation, which seems like enough of a hint to me? I don't really want to be prescriptive here, if only to discourage the use of this policy.

[markj]

• Address some review feedback.