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
12 shm_open — open a shared memory object (REALTIME)
13
15 #include <sys/mman.h>
16 int shm_open(const char *name, int oflag, mode_t mode);
18
20 The shm_open() function shall establish a connection between a shared
21 memory object and a file descriptor. It shall create an open file
22 description that refers to the shared memory object and a file descrip‐
23 tor that refers to that open file description. The file descriptor
24 shall be allocated as described in Section 2.14, File Descriptor Allo‐
25 cation, and can be used by other functions to refer to that shared mem‐
26 ory object. The name argument points to a string naming a shared mem‐
27 ory object. It is unspecified whether the name appears in the file sys‐
28 tem and is visible to other functions that take pathnames as arguments.
29 The name argument conforms to the construction rules for a pathname,
30 except that the interpretation of <slash> characters other than the
31 leading <slash> character in name is implementation-defined, and that
32 the length limits for the name argument are implementation-defined and
33 need not be the same as the pathname limits {PATH_MAX} and {NAME_MAX}.
34 If name begins with the <slash> character, then processes calling
35 shm_open() with the same value of name refer to the same shared memory
36 object, as long as that name has not been removed. If name does not
37 begin with the <slash> character, the effect is implementation-defined.
38 If successful, shm_open() shall return a file descriptor for the shared
40 memory object. The open file description is new, and therefore the
41 file descriptor does not share it with any other processes. It is
42 unspecified whether the file offset is set. The FD_CLOEXEC file
43 descriptor flag associated with the new file descriptor is set.
44 The file status flags and file access modes of the open file descrip‐
46 tion are according to the value of oflag. The oflag argument is the
47 bitwise-inclusive OR of the following flags defined in the <fcntl.h>
48 header. Applications specify exactly one of the first two values
49 (access modes) below in the value of oflag:
50 O_RDONLY Open for read access only.
52 O_RDWR Open for read or write access.
54 Any combination of the remaining flags may be specified in the value of
56 oflag:
57 O_CREAT If the shared memory object exists, this flag has no
59 effect, except as noted under O_EXCL below. Otherwise, the
60 shared memory object is created. The user ID of the shared
61 memory object shall be set to the effective user ID of the
62 process. The group ID of the shared memory object shall be
63 set to the effective group ID of the process; however, if
64 the name argument is visible in the file system, the group
65 ID may be set to the group ID of the containing directory.
66 The permission bits of the shared memory object shall be
67 set to the value of the mode argument except those set in
68 the file mode creation mask of the process. When bits in
69 mode other than the file permission bits are set, the
70 effect is unspecified. The mode argument does not affect
71 whether the shared memory object is opened for reading, for
72 writing, or for both. The shared memory object has a size
73 of zero.
74 O_EXCL If O_EXCL and O_CREAT are set, shm_open() fails if the
76 shared memory object exists. The check for the existence of
77 the shared memory object and the creation of the object if
78 it does not exist is atomic with respect to other processes
79 executing shm_open() naming the same shared memory object
80 with O_EXCL and O_CREAT set. If O_EXCL is set and O_CREAT
81 is not set, the result is undefined.
82 O_TRUNC If the shared memory object exists, and it is successfully
84 opened O_RDWR, the object shall be truncated to zero length
85 and the mode and owner shall be unchanged by this function
86 call. The result of using O_TRUNC with O_RDONLY is unde‐
87 fined.
88 When a shared memory object is created, the state of the shared memory
90 object, including all data associated with the shared memory object,
91 persists until the shared memory object is unlinked and all other ref‐
92 erences are gone. It is unspecified whether the name and shared memory
93 object state remain valid after a system reboot.
94
96 Upon successful completion, the shm_open() function shall return a non-
97 negative integer representing the file descriptor. Otherwise, it shall
98 return -1 and set errno to indicate the error.
99
101 The shm_open() function shall fail if:
102 EACCES The shared memory object exists and the permissions specified by
104 oflag are denied, or the shared memory object does not exist and
105 permission to create the shared memory object is denied, or
106 O_TRUNC is specified and write permission is denied.
107 EEXIST O_CREAT and O_EXCL are set and the named shared memory object
109 already exists.
110 EINTR The shm_open() operation was interrupted by a signal.
112 EINVAL The shm_open() operation is not supported for the given name.
114 EMFILE All file descriptors available to the process are currently
116 open.
117 ENFILE Too many shared memory objects are currently open in the system.
119 ENOENT O_CREAT is not set and the named shared memory object does not
121 exist.
122 ENOSPC There is insufficient space for the creation of the new shared
124 memory object.
125 The shm_open() function may fail if:
127 ENAMETOOLONG
129 The length of the name argument exceeds {_POSIX_PATH_MAX} on
130 systems that do not support the XSI option or exceeds
131 {_XOPEN_PATH_MAX} on XSI systems, or has a pathname component
132 that is longer than {_POSIX_NAME_MAX} on systems that do not
133 support the XSI option or longer than {_XOPEN_NAME_MAX} on XSI
134 systems.
135 The following sections are informative.
137
139 Creating and Mapping a Shared Memory Object
140 The following code segment demonstrates the use of shm_open() to create
141 a shared memory object which is then sized using ftruncate() before
142 being mapped into the process address space using mmap():
143 #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‐2017 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‐2017 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 Section 2.14, File Descriptor Allocation, close(), dup(), exec,
271 fcntl(), mmap(), shmat(), shmctl(), shmdt(), shm_unlink(), umask()
272 The Base Definitions volume of POSIX.1‐2017, <fcntl.h>, <sys_mman.h>
274
276 Portions of this text are reprinted and reproduced in electronic form
277 from IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
278 table Operating System Interface (POSIX), The Open Group Base Specifi‐
279 cations Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of
280 Electrical and Electronics Engineers, Inc and The Open Group. In the
281 event of any discrepancy between this version and the original IEEE and
282 The Open Group Standard, the original IEEE and The Open Group Standard
283 is the referee document. The original Standard can be obtained online
284 at http://www.opengroup.org/unix/online.html .
285 Any typographical or formatting errors that appear in this page are
287 most likely to have been introduced during the conversion of the source
288 files to man page format. To report such errors, see https://www.ker‐
289 nel.org/doc/man-pages/reporting_bugs.html .
290IEEE/The Open Group 2017 SHM_OPEN(3P)