Bug 215612
| Summary: | shm_open.2 man page does not accurately describe support for read(2)/write(2) on POSIX shared-memory objects | ||
|---|---|---|---|
| Product: | Documentation | Reporter: | Robert Watson <rwatson> |
| Component: | Books & Articles | Assignee: | freebsd-doc (Nobody) <doc> |
| Status: | Closed FIXED | ||
| Severity: | Affects Only Me | CC: | jau, wblock |
| Priority: | --- | ||
| Version: | Latest | ||
| Hardware: | Any | ||
| OS: | Any | ||
Review https://reviews.freebsd.org/D9066 created. A commit references this bug: Author: wblock Date: Fri Jan 13 19:41:02 UTC 2017 New revision: 312083 URL: https://svnweb.freebsd.org/changeset/base/312083 Log: Update the shm_open.2 man page to reflect objective reality. PR: 215612 Submitted by: rwatson MFC after: 1 week Differential Revision: https://reviews.freebsd.org/D9066 Changes: head/lib/libc/sys/shm_open.2 |
The shm_open(2) man page states the following about POSIX shared-memory objects: The result of using open(2), read(2), or write(2) on a shared memory object, or on the descriptor returned by shm_open(), is undefined. It is also undefined whether the shared memory object itself, or its contents, persist across reboots. In FreeBSD, read(2) and write(2) on a shared memory object will fail with EOPNOTSUPP and neither shared memory objects nor their contents persist across reboots. However, this is no longer up-to-date: the kernel implementation explicitly includes support for read(2)/write(2). This documentation also does not mention the confusing property that ftruncate(2) must be called to extend a shared-memory object before it can be written to. I.e., the following does require a call to ftruncate(2): uint8_t buffer[getpagesize()]; ssize_t len; int fd; fd = shm_open(SHM_ANON, O_RDWR | O_CREAT, 0600); if (fd < 0) err(EX_OSERR, "%s: shm_open", __func__); if (ftruncate(fd, getpagesize()) < 0) err(EX_IOERR, "%s: ftruncate", __func__); len = pwrite(fd, buffer, getpagesize(), 0); if (len < 0) err(EX_IOERR, "%s: pwrite", __func__); if (len != getpagesize()) errx(EX_IOERR, "%s: pwrite length mismatch", __func__); If the truncate is missing, then pwrite(2) will return 0 bytes written (EOF). It is not clear that this is a bug, but it probably deserves mention.