1SHM_OPEN(3P) POSIX Programmer's Manual SHM_OPEN(3P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
13 shm_open — open a shared memory object (REALTIME)
14
16 #include <sys/mman.h>
17 int shm_open(const char *name, int oflag, mode_t mode);
19
21 The shm_open() function shall establish a connection between a shared
22 memory object and a file descriptor. It shall create an open file
23 description that refers to the shared memory object and a file descrip‐
24 tor that refers to that open file description. The file descriptor is
25 used by other functions to refer to that shared memory object. The name
26 argument points to a string naming a shared memory object. It is
27 unspecified whether the name appears in the file system and is visible
28 to other functions that take pathnames as arguments. The name argument
29 conforms to the construction rules for a pathname, except that the
30 interpretation of <slash> characters other than the leading <slash>
31 character in name is implementation-defined, and that the length limits
32 for the name argument are implementation-defined and need not be the
33 same as the pathname limits {PATH_MAX} and {NAME_MAX}. If name begins
34 with the <slash> character, then processes calling shm_open() with the
35 same value of name refer to the same shared memory object, as long as
36 that name has not been removed. If name does not begin with the <slash>
37 character, the effect is implementation-defined.
38 If successful, shm_open() shall return a file descriptor for the shared
40 memory object that is the lowest numbered file descriptor not currently
41 open for that process. The open file description is new, and therefore
42 the file descriptor does not share it with any other processes. It is
43 unspecified whether the file offset is set. The FD_CLOEXEC file
44 descriptor flag associated with the new file descriptor is set.
45 The file status flags and file access modes of the open file descrip‐
47 tion are according to the value of oflag. The oflag argument is the
48 bitwise-inclusive OR of the following flags defined in the <fcntl.h>
49 header. Applications specify exactly one of the first two values
50 (access modes) below in the value of oflag:
51 O_RDONLY Open for read access only.
53 O_RDWR Open for read or write access.
55 Any combination of the remaining flags may be specified in the value of
57 oflag:
58 O_CREAT If the shared memory object exists, this flag has no
60 effect, except as noted under O_EXCL below. Otherwise, the
61 shared memory object is created. The user ID of the shared
62 memory object shall be set to the effective user ID of the
63 process. The group ID of the shared memory object shall be
64 set to the effective group ID of the process; however, if
65 the name argument is visible in the file system, the group
66 ID may be set to the group ID of the containing directory.
67 The permission bits of the shared memory object shall be
68 set to the value of the mode argument except those set in
69 the file mode creation mask of the process. When bits in
70 mode other than the file permission bits are set, the
71 effect is unspecified. The mode argument does not affect
72 whether the shared memory object is opened for reading, for
73 writing, or for both. The shared memory object has a size
74 of zero.
75 O_EXCL If O_EXCL and O_CREAT are set, shm_open() fails if the
77 shared memory object exists. The check for the existence of
78 the shared memory object and the creation of the object if
79 it does not exist is atomic with respect to other processes
80 executing shm_open() naming the same shared memory object
81 with O_EXCL and O_CREAT set. If O_EXCL is set and O_CREAT
82 is not set, the result is undefined.
83 O_TRUNC If the shared memory object exists, and it is successfully
85 opened O_RDWR, the object shall be truncated to zero length
86 and the mode and owner shall be unchanged by this function
87 call. The result of using O_TRUNC with O_RDONLY is unde‐
88 fined.
89 When a shared memory object is created, the state of the shared memory
91 object, including all data associated with the shared memory object,
92 persists until the shared memory object is unlinked and all other ref‐
93 erences are gone. It is unspecified whether the name and shared memory
94 object state remain valid after a system reboot.
95
97 Upon successful completion, the shm_open() function shall return a non-
98 negative integer representing the lowest numbered unused file descrip‐
99 tor. Otherwise, it shall return −1 and set errno to indicate the error.
100
102 The shm_open() function shall fail if:
103 EACCES The shared memory object exists and the permissions specified by
105 oflag are denied, or the shared memory object does not exist and
106 permission to create the shared memory object is denied, or
107 O_TRUNC is specified and write permission is denied.
108 EEXIST O_CREAT and O_EXCL are set and the named shared memory object
110 already exists.
111 EINTR The shm_open() operation was interrupted by a signal.
113 EINVAL The shm_open() operation is not supported for the given name.
115 EMFILE All file descriptors available to the process are currently
117 open.
118 ENFILE Too many shared memory objects are currently open in the system.
120 ENOENT O_CREAT is not set and the named shared memory object does not
122 exist.
123 ENOSPC There is insufficient space for the creation of the new shared
125 memory object.
126 The shm_open() function may fail if:
128 ENAMETOOLONG
130 The length of the name argument exceeds {_POSIX_PATH_MAX} on
131 systems that do not support the XSI option or exceeds
132 {_XOPEN_PATH_MAX} on XSI systems, or has a pathname component
133 that is longer than {_POSIX_NAME_MAX} on systems that do not
134 support the XSI option or longer than {_XOPEN_NAME_MAX} on XSI
135 systems.
136 The following sections are informative.
138
140 Creating and Mapping a Shared Memory Object
141 The following code segment demonstrates the use of shm_open() to create
142 a shared memory object which is then sized using ftruncate() before
143 being mapped into the process address space using mmap():
144 #include <unistd.h>
146 #include <sys/mman.h>
147 ...
148 #define MAX_LEN 10000
150 struct region { /* Defines "structure" of shared memory */
151 int len;
152 char buf[MAX_LEN];
153 };
154 struct region *rptr;
155 int fd;
156 /* Create shared memory object and set its size */
158 fd = shm_open("/myregion", O_CREAT | O_RDWR, S_IRUSR | S_IWUSR);
160 if (fd == −1)
161 /* Handle error */;
162 if (ftruncate(fd, sizeof(struct region)) == −1)
164 /* Handle error */;
165 /* Map shared memory object */
167 rptr = mmap(NULL, sizeof(struct region),
169 PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0);
170 if (rptr == MAP_FAILED)
171 /* Handle error */;
172 /* Now we can refer to mapped region using fields of rptr;
174 for example, rptr->len */
175 ...
176
178 None.
179
181 When the Memory Mapped Files option is supported, the normal open()
182 call is used to obtain a descriptor to a file to be mapped according to
183 existing practice with mmap(). When the Shared Memory Objects option
184 is supported, the shm_open() function shall obtain a descriptor to the
185 shared memory object to be mapped.
186 There is ample precedent for having a file descriptor represent several
188 types of objects. In the POSIX.1‐1990 standard, a file descriptor can
189 represent a file, a pipe, a FIFO, a tty, or a directory. Many implemen‐
190 tations simply have an operations vector, which is indexed by the file
191 descriptor type and does very different operations. Note that in some
192 cases the file descriptor passed to generic operations on file descrip‐
193 tors is returned by open() or creat() and in some cases returned by
194 alternate functions, such as pipe(). The latter technique is used by
195 shm_open().
196 Note that such shared memory objects can actually be implemented as
198 mapped files. In both cases, the size can be set after the open using
199 ftruncate(). The shm_open() function itself does not create a shared
200 object of a specified size because this would duplicate an extant func‐
201 tion that set the size of an object referenced by a file descriptor.
202 On implementations where memory objects are implemented using the
204 existing file system, the shm_open() function may be implemented using
205 a macro that invokes open(), and the shm_unlink() function may be
206 implemented using a macro that invokes unlink().
207 For implementations without a permanent file system, the definition of
209 the name of the memory objects is allowed not to survive a system
210 reboot. Note that this allows systems with a permanent file system to
211 implement memory objects as data structures internal to the implementa‐
212 tion as well.
213 On implementations that choose to implement memory objects using memory
215 directly, a shm_open() followed by an ftruncate() and close() can be
216 used to preallocate a shared memory area and to set the size of that
217 preallocation. This may be necessary for systems without virtual memory
218 hardware support in order to ensure that the memory is contiguous.
219 The set of valid open flags to shm_open() was restricted to O_RDONLY,
221 O_RDWR, O_CREAT, and O_TRUNC because these could be easily implemented
222 on most memory mapping systems. This volume of POSIX.1‐2008 is silent
223 on the results if the implementation cannot supply the requested file
224 access because of implementation-defined reasons, including hardware
225 ones.
226 The error conditions [EACCES] and [ENOTSUP] are provided to inform the
228 application that the implementation cannot complete a request.
229 [EACCES] indicates for implementation-defined reasons, probably hard‐
231 ware-related, that the implementation cannot comply with a requested
232 mode because it conflicts with another requested mode. An example might
233 be that an application desires to open a memory object two times, map‐
234 ping different areas with different access modes. If the implementation
235 cannot map a single area into a process space in two places, which
236 would be required if different access modes were required for the two
237 areas, then the implementation may inform the application at the time
238 of the second open.
239 [ENOTSUP] indicates for implementation-defined reasons, probably hard‐
241 ware-related, that the implementation cannot comply with a requested
242 mode at all. An example would be that the hardware of the implementa‐
243 tion cannot support write-only shared memory areas.
244 On all implementations, it may be desirable to restrict the location of
246 the memory objects to specific file systems for performance (such as a
247 RAM disk) or implementation-defined reasons (shared memory supported
248 directly only on certain file systems). The shm_open() function may be
249 used to enforce these restrictions. There are a number of methods
250 available to the application to determine an appropriate name of the
251 file or the location of an appropriate directory. One way is from the
252 environment via getenv(). Another would be from a configuration file.
253 This volume of POSIX.1‐2008 specifies that memory objects have initial
255 contents of zero when created. This is consistent with current behavior
256 for both files and newly allocated memory. For those implementations
257 that use physical memory, it would be possible that such implementa‐
258 tions could simply use available memory and give it to the process
259 uninitialized. This, however, is not consistent with standard behavior
260 for the uninitialized data area, the stack, and of course, files.
261 Finally, it is highly desirable to set the allocated memory to zero for
262 security reasons. Thus, initializing memory objects to zero is
263 required.
264
266 A future version might require the shm_open() and shm_unlink() func‐
267 tions to have semantics similar to normal file system operations.
268
270 close(), dup(), exec, fcntl(), mmap(), shmat(), shmctl(), shmdt(),
271 shm_unlink(), umask()
272 The Base Definitions volume of POSIX.1‐2008, <fcntl.h>, <sys_mman.h>
274
276 Portions of this text are reprinted and reproduced in electronic form
277 from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
278 -- Portable Operating System Interface (POSIX), The Open Group Base
279 Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
280 cal and Electronics Engineers, Inc and The Open Group. (This is
281 POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
282 event of any discrepancy between this version and the original IEEE and
283 The Open Group Standard, the original IEEE and The Open Group Standard
284 is the referee document. The original Standard can be obtained online
285 at http://www.unix.org/online.html .
286 Any typographical or formatting errors that appear in this page are
288 most likely to have been introduced during the conversion of the source
289 files to man page format. To report such errors, see https://www.ker‐
290 nel.org/doc/man-pages/reporting_bugs.html .
291IEEE/The Open Group 2013 SHM_OPEN(3P)