]>
Commit | Line | Data |
---|---|---|
c11b1abf | 1 | .\" Copyright (C) 2002 Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 2 | .\" |
93015253 | 3 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
4 | .\" Permission is granted to make and distribute verbatim copies of this |
5 | .\" manual provided the copyright notice and this permission notice are | |
6 | .\" preserved on all copies. | |
7 | .\" | |
8 | .\" Permission is granted to copy and distribute modified versions of this | |
9 | .\" manual under the conditions for verbatim copying, provided that the | |
10 | .\" entire resulting derived work is distributed under the terms of a | |
11 | .\" permission notice identical to this one. | |
c13182ef | 12 | .\" |
fea681da MK |
13 | .\" Since the Linux kernel and libraries are constantly changing, this |
14 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
15 | .\" responsibility for errors or omissions, or for damages resulting from | |
10d76543 MK |
16 | .\" the use of the information contained herein. The author(s) may not |
17 | .\" have taken the same level of care in the production of this manual, | |
18 | .\" which is licensed free of charge, as they might when working | |
19 | .\" professionally. | |
c13182ef | 20 | .\" |
fea681da MK |
21 | .\" Formatted or processed versions of this manual, if unaccompanied by |
22 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 23 | .\" %%%LICENSE_END |
fea681da | 24 | .\" |
df18528c | 25 | .\" FIXME . Add an example to this page |
4b8c67d9 | 26 | .TH SHM_OPEN 3 2017-09-15 "Linux" "Linux Programmer's Manual" |
fea681da | 27 | .SH NAME |
f68512e9 | 28 | shm_open, shm_unlink \- create/open or unlink POSIX shared memory objects |
fea681da | 29 | .SH SYNOPSIS |
fea681da | 30 | .B #include <sys/mman.h> |
e03e2055 | 31 | .br |
84c517a4 | 32 | .BR "#include <sys/stat.h>" " /* For mode constants */" |
87d17de4 | 33 | .br |
e03e2055 | 34 | .BR "#include <fcntl.h>" " /* For O_* constants */" |
68e4db0a | 35 | .PP |
fea681da | 36 | .BI "int shm_open(const char *" name ", int " oflag ", mode_t " mode ); |
68e4db0a | 37 | .PP |
fea681da | 38 | .BI "int shm_unlink(const char *" name ); |
68e4db0a | 39 | .PP |
20c58d70 | 40 | Link with \fI\-lrt\fP. |
fea681da | 41 | .SH DESCRIPTION |
bf0cac28 | 42 | .BR shm_open () |
fea681da MK |
43 | creates and opens a new, or opens an existing, POSIX shared memory object. |
44 | A POSIX shared memory object is in effect a handle which can | |
c13182ef | 45 | be used by unrelated processes to |
fea681da | 46 | .BR mmap (2) |
c13182ef MK |
47 | the same region of shared memory. |
48 | The | |
bf0cac28 | 49 | .BR shm_unlink () |
c13182ef | 50 | function performs the converse operation, |
fea681da | 51 | removing an object previously created by |
bf0cac28 | 52 | .BR shm_open (). |
dd3568a1 | 53 | .PP |
fea681da | 54 | The operation of |
bf0cac28 | 55 | .BR shm_open () |
fea681da MK |
56 | is analogous to that of |
57 | .BR open (2). | |
58 | .I name | |
c13182ef MK |
59 | specifies the shared memory object to be created or opened. |
60 | For portable use, | |
8e984751 MK |
61 | a shared memory object should be identified by a name of the form |
62 | .IR /somename ; | |
63 | that is, a null-terminated string of up to | |
bd838488 MK |
64 | .BI NAME_MAX |
65 | (i.e., 255) characters consisting of an initial slash, | |
8e984751 MK |
66 | .\" glibc allows the initial slash to be omitted, and makes |
67 | .\" multiple initial slashes equivalent to a single slash. | |
68 | .\" This differs from the implementation of POSIX message queues. | |
69 | followed by one or more characters, none of which are slashes. | |
70 | .\" glibc allows subdirectory components in the name, in which | |
71 | .\" case the subdirectory must exist under /dev/shm, and allow the | |
72 | .\" required permissions if a user wants to create a shared memory | |
73 | .\" object in that subdirectory. | |
dd3568a1 | 74 | .PP |
fea681da MK |
75 | .I oflag |
76 | is a bit mask created by ORing together exactly one of | |
c13182ef | 77 | .B O_RDONLY |
fea681da | 78 | or |
2d5e8aeb | 79 | .B O_RDWR |
fea681da MK |
80 | and any of the other flags listed here: |
81 | .TP 1.1i | |
82 | .B O_RDONLY | |
83 | Open the object for read access. | |
33a0ccb2 | 84 | A shared memory object opened in this way can be |
c13182ef | 85 | .BR mmap (2)ed |
c9942389 MK |
86 | only for read |
87 | .RB ( PROT_READ ) | |
88 | access. | |
fea681da MK |
89 | .TP |
90 | .B O_RDWR | |
91 | Open the object for read-write access. | |
92 | .TP | |
93 | .B O_CREAT | |
c13182ef | 94 | Create the shared memory object if it does not exist. |
bf0cac28 MK |
95 | The user and group ownership of the object are taken |
96 | from the corresponding effective IDs of the calling process, | |
9ee4a2b6 | 97 | .\" In truth it is actually the filesystem IDs on Linux, but these |
bf0cac28 | 98 | .\" are nearly always the same as the effective IDs. (MTK, Jul 05) |
fea681da | 99 | and the object's |
c13182ef | 100 | permission bits are set according to the low-order 9 bits of |
fea681da MK |
101 | .IR mode , |
102 | except that those bits set in the process file mode | |
103 | creation mask (see | |
104 | .BR umask (2)) | |
105 | are cleared for the new object. | |
bf0cac28 | 106 | A set of macro constants which can be used to define |
fea681da | 107 | .I mode |
c13182ef | 108 | is listed in |
bf0cac28 | 109 | .BR open (2). |
87d17de4 MK |
110 | (Symbolic definitions of these constants can be obtained by including |
111 | .IR <sys/stat.h> .) | |
bdd915e2 | 112 | .IP |
5503c85e | 113 | A new shared memory object initially has zero length\(emthe size of the |
fea681da MK |
114 | object can be set using |
115 | .BR ftruncate (2). | |
bf0cac28 | 116 | The newly allocated bytes of a shared memory |
d9bfdb9c | 117 | object are automatically initialized to 0. |
c13182ef | 118 | .TP |
fea681da | 119 | .B O_EXCL |
c13182ef | 120 | If |
fea681da | 121 | .B O_CREAT |
bf0cac28 | 122 | was also specified, and a shared memory object with the given |
c13182ef | 123 | .I name |
fea681da | 124 | already exists, return an error. |
c13182ef | 125 | The check for the existence of the object, and its creation if it |
fea681da MK |
126 | does not exist, are performed atomically. |
127 | .TP | |
128 | .B O_TRUNC | |
129 | If the shared memory object already exists, truncate it to zero bytes. | |
dd3568a1 | 130 | .PP |
87d17de4 MK |
131 | Definitions of these flag values can be obtained by including |
132 | .IR <fcntl.h> . | |
dd3568a1 | 133 | .PP |
fea681da | 134 | On successful completion |
bf0cac28 | 135 | .BR shm_open () |
fea681da MK |
136 | returns a new file descriptor referring to the shared memory object. |
137 | This file descriptor is guaranteed to be the lowest-numbered file descriptor | |
c13182ef | 138 | not previously opened within the process. |
fea681da MK |
139 | The |
140 | .B FD_CLOEXEC | |
c13182ef | 141 | flag (see |
fea681da MK |
142 | .BR fcntl (2)) |
143 | is set for the file descriptor. | |
847e0d88 | 144 | .PP |
c13182ef MK |
145 | The file descriptor is normally used in subsequent calls |
146 | to | |
fea681da | 147 | .BR ftruncate (2) |
bf0cac28 | 148 | (for a newly created object) and |
fea681da MK |
149 | .BR mmap (2). |
150 | After a call to | |
151 | .BR mmap (2) | |
152 | the file descriptor may be closed without affecting the memory mapping. | |
847e0d88 | 153 | .PP |
fea681da | 154 | The operation |
c13182ef | 155 | of |
bf0cac28 | 156 | .BR shm_unlink () |
fea681da MK |
157 | is analogous to |
158 | .BR unlink (2): | |
159 | it removes a shared memory object name, and, once all processes | |
c13182ef | 160 | have unmapped the object, de-allocates and |
fea681da | 161 | destroys the contents of the associated memory region. |
c13182ef | 162 | After a successful |
bf0cac28 | 163 | .BR shm_unlink (), |
c13182ef | 164 | attempts to |
bf0cac28 | 165 | .BR shm_open () |
c13182ef | 166 | an object with the same |
fea681da | 167 | .I name |
26cd31fd | 168 | fail (unless |
fea681da MK |
169 | .B O_CREAT |
170 | was specified, in which case a new, distinct object is created). | |
47297adb | 171 | .SH RETURN VALUE |
fea681da | 172 | On success, |
bf0cac28 | 173 | .BR shm_open () |
2fda57bd | 174 | returns a nonnegative file descriptor. |
c13182ef | 175 | On failure, |
bf0cac28 | 176 | .BR shm_open () |
fea681da | 177 | returns \-1. |
bf0cac28 | 178 | .BR shm_unlink () |
fea681da MK |
179 | returns 0 on success, or \-1 on error. |
180 | .SH ERRORS | |
181 | On failure, | |
182 | .I errno | |
c13182ef MK |
183 | is set to indicate the cause of the error. |
184 | Values which may appear in | |
fea681da MK |
185 | .I errno |
186 | include the following: | |
c13182ef | 187 | .TP |
fea681da MK |
188 | .B EACCES |
189 | Permission to | |
bf0cac28 | 190 | .BR shm_unlink () |
fea681da MK |
191 | the shared memory object was denied. |
192 | .TP | |
193 | .B EACCES | |
c13182ef | 194 | Permission was denied to |
bf0cac28 | 195 | .BR shm_open () |
fea681da MK |
196 | .I name |
197 | in the specified | |
bf0cac28 | 198 | .IR mode , |
c13182ef | 199 | or |
fea681da MK |
200 | .B O_TRUNC |
201 | was specified and the caller does not have write permission on the object. | |
c13182ef | 202 | .TP |
fea681da MK |
203 | .B EEXIST |
204 | Both | |
205 | .B O_CREAT | |
206 | and | |
c13182ef | 207 | .B O_EXCL |
fea681da | 208 | were specified to |
bf0cac28 | 209 | .BR shm_open () |
fea681da MK |
210 | and the shared memory object specified by |
211 | .I name | |
212 | already exists. | |
213 | .TP | |
214 | .B EINVAL | |
215 | The | |
216 | .I name | |
c13182ef | 217 | argument to |
bf0cac28 | 218 | .BR shm_open () |
fea681da MK |
219 | was invalid. |
220 | .TP | |
221 | .B EMFILE | |
26c32fab | 222 | The per-process limit on the number of open file descriptors has been reached. |
fea681da MK |
223 | .TP |
224 | .B ENAMETOOLONG | |
c13182ef | 225 | The length of |
fea681da | 226 | .I name |
c13182ef | 227 | exceeds |
fea681da MK |
228 | .BR PATH_MAX . |
229 | .TP | |
230 | .B ENFILE | |
e258766b | 231 | The system-wide limit on the total number of open files has been reached. |
fea681da MK |
232 | .TP |
233 | .B ENOENT | |
234 | An attempt was made to | |
bf0cac28 | 235 | .BR shm_open () |
c13182ef MK |
236 | a |
237 | .I name | |
fea681da MK |
238 | that did not exist, and |
239 | .B O_CREAT | |
240 | was not specified. | |
241 | .TP | |
242 | .B ENOENT | |
243 | An attempt was to made to | |
bf0cac28 | 244 | .BR shm_unlink () |
c13182ef MK |
245 | a |
246 | .I name | |
fea681da | 247 | that does not exist. |
67ff1512 MK |
248 | .SH VERSIONS |
249 | These functions are provided in glibc 2.2 and later. | |
be409be4 ZL |
250 | .SH ATTRIBUTES |
251 | For an explanation of the terms used in this section, see | |
252 | .BR attributes (7). | |
253 | .TS | |
254 | allbox; | |
255 | lbw24 lb lb | |
256 | l l l. | |
257 | Interface Attribute Value | |
258 | T{ | |
259 | .BR shm_open (), | |
260 | .BR shm_unlink () | |
261 | T} Thread safety MT-Safe locale | |
262 | .TE | |
847e0d88 | 263 | .sp 1 |
47297adb | 264 | .SH CONFORMING TO |
abb4b5b5 | 265 | POSIX.1-2001, POSIX.1-2008. |
dd3568a1 | 266 | .PP |
2b2581ee MK |
267 | POSIX.1-2001 says that the group ownership of a newly created shared |
268 | memory object is set to either the calling process's effective group ID | |
44a2c328 | 269 | or "a system default group ID". |
f71eeb14 MK |
270 | POSIX.1-2008 says that the group ownership |
271 | may be set to either the calling process's effective group ID | |
272 | or, if the object is visible in the filesystem, | |
273 | the group ID of the parent directory. | |
47297adb | 274 | .SH NOTES |
dd3568a1 | 275 | .PP |
c13182ef | 276 | POSIX leaves the behavior of the combination of |
fea681da MK |
277 | .B O_RDONLY |
278 | and | |
279 | .B O_TRUNC | |
c13182ef MK |
280 | unspecified. |
281 | On Linux, this will successfully truncate an existing | |
5503c85e | 282 | shared memory object\(emthis may not be so on other UNIX systems. |
dd3568a1 | 283 | .PP |
547afefe MK |
284 | The POSIX shared memory object implementation on Linux makes use |
285 | of a dedicated | |
286 | .BR tmpfs (5) | |
3a9a2ecb | 287 | filesystem that is normally mounted under |
bf0cac28 | 288 | .IR /dev/shm . |
47297adb | 289 | .SH SEE ALSO |
fea681da MK |
290 | .BR close (2), |
291 | .BR fchmod (2), | |
292 | .BR fchown (2), | |
293 | .BR fcntl (2), | |
294 | .BR fstat (2), | |
295 | .BR ftruncate (2), | |
c4d76cd9 | 296 | .BR memfd_create (2), |
fea681da MK |
297 | .BR mmap (2), |
298 | .BR open (2), | |
f93af9c6 MK |
299 | .BR umask (2), |
300 | .BR shm_overview (7) |