Update shm_open.2

[wblock]

Summary

From https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=215612

Remove obsolete notes about using read(2) and write(2) with shared memory objects.

Add note about the requirement of using ftruncate(2) before writing to a shared memory object.

Test Plan

Throw myself on the mercy of reviewers.

[rwatson]

Seems reasonable to me!

[jilles]

lib/libc/sys/shm_open.2

183 ↗

(On Diff #23658)

The above two sentences describe what POSIX specifies and I think they should be kept (but perhaps reformulated such that they clearly describe POSIX requirements).

191 ↗

(On Diff #23658)

The part about persistence across reboots remains valid.

[pluknet]

lib/libc/sys/shm_open.2

176 ↗

(On Diff #23658)

From my POV, this is already documented there:

Newly created objects start off with a size of zero. <..> The size of the object can be adjusted via ftruncate(2)

If ever retain this chunk, I'd rather move it into EXAMPLES or so.

197 ↗

(On Diff #23658)

This is usually written in this form:

The
.Fn shm_open
system call will fail if:

[jilles]

lib/libc/sys/shm_open.2

176 ↗

(On Diff #23658)

The point here is that a write(2) will not extend the object. That is only documented in the cited parts by omission, and I think that is insufficiently clear.

[wblock]

Updated for feedback.

[jilles]

lib/libc/sys/shm_open.2

174 ↗

(On Diff #23967)

Nitpick: .Tn POSIX

191–193 ↗

(On Diff #23967)

It may be clearer here to say something like

Since writes do not extend a shared memory object,
.Xr ftruncate 2
needs to be called before any data can be written.

On another note, the usual spelling seems to be "shared memory object", not "shared-memory object" (ignoring usual spelling rules but looking at the existing documentation and the POSIX specification).

[wblock]

Update for feedback and move examples section before errors section in an unsuccessful attempt to get mandoc to not complain about it. But it's closer than it was.