2 .\" Copyright 2000 Massachusetts Institute of Technology
4 .\" Permission to use, copy, modify, and distribute this software and
5 .\" its documentation for any purpose and without fee is hereby
6 .\" granted, provided that both the above copyright notice and this
7 .\" permission notice appear in all copies, that both the above
8 .\" copyright notice and this permission notice appear in all
9 .\" supporting documentation, and that the name of M.I.T. not be used
10 .\" in advertising or publicity pertaining to distribution of the
11 .\" software without specific, written prior permission. M.I.T. makes
12 .\" no representations about the suitability of this software for any
13 .\" purpose. It is provided "as is" without express or implied
16 .\" THIS SOFTWARE IS PROVIDED BY M.I.T. ``AS IS''. M.I.T. DISCLAIMS
17 .\" ALL EXPRESS OR IMPLIED WARRANTIES WITH REGARD TO THIS SOFTWARE,
18 .\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
19 .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT
20 .\" SHALL M.I.T. BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
21 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
22 .\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
23 .\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
24 .\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
25 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
26 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
35 .Nm shm_open , shm_unlink
36 .Nd "shared memory object operations"
44 .Fn shm_open "const char *path" "int flags" "mode_t mode"
46 .Fn shm_unlink "const char *path"
50 system call opens (or optionally creates) a
52 shared memory object named
56 argument contains a subset of the flags used by
58 An access mode of either
69 may also be specified.
74 then a new shared memory object named
76 will be created if it does not exist.
78 the shared memory object is created with mode
80 subject to the process' umask value.
85 flags are specified and a shared memory object named
93 Newly created objects start off with a size of zero.
94 If an existing shared memory object is opened with
99 then the shared memory object will be truncated to a size of zero.
100 The size of the object can be adjusted via
105 The new descriptor is set to close during
113 As a FreeBSD extension,
120 In this case, an anonymous, unnamed shared memory object is created.
121 Since the object has no name,
122 it cannot be removed via a subsequent call to
125 the shared memory object will be garbage collected when the last reference to
126 the shared memory object is removed.
127 The shared memory object may be shared with other processes by sharing the
132 Attempting to open an anonymous shared memory object with
136 All other flags are ignored.
140 system call removes a shared memory object named
145 returns a non-negative integer,
149 Both functions return -1 on failure, and set
151 to indicate the error.
155 argument does not necessarily represent a pathname (although it does in
156 most other implementations).
157 Two processes opening the same
159 are guaranteed to access the same shared memory object if and only if
172 flags may be used in portable programs.
175 specifications state that the result of using
180 on a shared memory object, or on the descriptor returned by
185 kernel implementation explicitly includes support for
191 also supports zero-copy transmission of data from shared memory
195 Neither shared memory objects nor their contents persist across reboots.
197 Writes do not extend shared memory objects, so
199 must be called before any data can be written.
203 This example fails without the call to
205 .Bd -literal -compact
207 uint8_t buffer[getpagesize()];
211 fd = shm_open(SHM_ANON, O_RDWR | O_CREAT, 0600);
213 err(EX_OSERR, "%s: shm_open", __func__);
214 if (ftruncate(fd, getpagesize()) < 0)
215 err(EX_IOERR, "%s: ftruncate", __func__);
216 len = pwrite(fd, buffer, getpagesize(), 0);
218 err(EX_IOERR, "%s: pwrite", __func__);
219 if (len != getpagesize())
220 errx(EX_IOERR, "%s: pwrite length mismatch", __func__);
224 fails with these error codes for these conditions:
237 The process has already reached its limit for open file descriptors.
239 The system file table is full.
242 was specified while creating an anonymous shared memory object via
247 argument points outside the process' allocated address space.
248 .It Bq Er ENAMETOOLONG
249 The entire pathname exceeded 1023 characters.
253 does not begin with a slash
258 is specified and the named shared memory object does not exist.
263 are specified and the named shared memory object does exist.
265 The required permissions (for reading or reading and writing) are denied.
269 fails with these error codes for these conditions:
274 argument points outside the process' allocated address space.
275 .It Bq Er ENAMETOOLONG
276 The entire pathname exceeded 1023 characters.
278 The named shared memory object does not exist.
280 The required permissions are denied.
282 requires write permission to the shared memory object.
296 functions are believed to conform to
303 functions first appeared in
305 The functions were reimplemented as system calls using shared memory objects
306 directly rather than files in
309 .An Garrett A. Wollman Aq Mt wollman@FreeBSD.org
310 (C library support and this manual page)
312 .An Matthew Dillon Aq Mt dillon@FreeBSD.org