1SHM_OPEN(3P)               POSIX Programmer's Manual              SHM_OPEN(3P)
2
3
4

PROLOG

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

NAME

12       shm_open — open a shared memory object (REALTIME)
13

SYNOPSIS

15       #include <sys/mman.h>
16
17       int shm_open(const char *name, int oflag, mode_t mode);
18

DESCRIPTION

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
39       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
45       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
51       O_RDONLY    Open for read access only.
52
53       O_RDWR      Open for read or write access.
54
55       Any combination of the remaining flags may be specified in the value of
56       oflag:
57
58       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
75       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
83       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
89       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

RETURN VALUE

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

ERRORS

101       The shm_open() function shall fail if:
102
103       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
108       EEXIST O_CREAT and O_EXCL are set and the named  shared  memory  object
109              already exists.
110
111       EINTR  The shm_open() operation was interrupted by a signal.
112
113       EINVAL The shm_open() operation is not supported for the given name.
114
115       EMFILE All  file  descriptors  available  to  the process are currently
116              open.
117
118       ENFILE Too many shared memory objects are currently open in the system.
119
120       ENOENT O_CREAT is not set and the named shared memory object  does  not
121              exist.
122
123       ENOSPC There  is  insufficient space for the creation of the new shared
124              memory object.
125
126       The shm_open() function may fail if:
127
128       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
136       The following sections are informative.
137

EXAMPLES

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
144
145           #include <unistd.h>
146           #include <sys/mman.h>
147           ...
148
149           #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
157           /* Create shared memory object and set its size */
158
159           fd = shm_open("/myregion", O_CREAT | O_RDWR, S_IRUSR | S_IWUSR);
160           if (fd == -1)
161               /* Handle error */;
162
163           if (ftruncate(fd, sizeof(struct region)) == -1)
164               /* Handle error */;
165
166           /* Map shared memory object */
167
168           rptr = mmap(NULL, sizeof(struct region),
169                  PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0);
170           if (rptr == MAP_FAILED)
171               /* Handle error */;
172
173           /* Now we can refer to mapped region using fields of rptr;
174              for example, rptr->len */
175           ...
176

APPLICATION USAGE

178       None.
179

RATIONALE

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
187       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
197       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
203       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
208       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
214       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
220       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
227       The  error conditions [EACCES] and [ENOTSUP] are provided to inform the
228       application that the implementation cannot complete a request.
229
230       [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
240       [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
245       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
254       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

FUTURE DIRECTIONS

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

SEE ALSO

270       Section  2.14,  File  Descriptor  Allocation,  close(),  dup(),   exec,
271       fcntl(), mmap(), shmat(), shmctl(), shmdt(), shm_unlink(), umask()
272
273       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
286       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 .
290
291
292
293IEEE/The Open Group                  2017                         SHM_OPEN(3P)
Impressum