Page MenuHomeFreeBSD

Update shm_open.2
ClosedPublic

Authored by wblock on Jan 6 2017, 5:16 PM.

Details

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.

Diff Detail

Repository
rS FreeBSD src repository - subversion
Lint
Automatic diff as part of commit; lint not applicable.
Unit
Automatic diff as part of commit; unit tests not applicable.

Event Timeline

wblock retitled this revision from to Update sh_open.2.
wblock updated this object.
wblock edited the test plan for this revision. (Show Details)
wblock added a reviewer: rwatson.
wblock set the repository for this revision to rS FreeBSD src repository - subversion.
rwatson edited edge metadata.

Seems reasonable to me!

This revision is now accepted and ready to land.Jan 6 2017, 6:46 PM
jilles requested changes to this revision.Jan 6 2017, 7:38 PM
jilles added a reviewer: jilles.
jilles added a subscriber: jilles.
jilles added inline comments.
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.

This revision now requires changes to proceed.Jan 6 2017, 7:38 PM
pluknet added inline comments.
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:
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 edited edge metadata.
wblock removed rS FreeBSD src repository - subversion as the repository for this revision.

Updated for feedback.

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 retitled this revision from Update sh_open.2 to Update shm_open.2.
wblock edited edge metadata.

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.

jilles edited edge metadata.
This revision is now accepted and ready to land.Jan 13 2017, 7:28 PM
This revision was automatically updated to reflect the committed changes.