]>
Commit | Line | Data |
---|---|---|
c11b1abf | 1 | .\" Copyright (C) 2002 Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 2 | .\" |
4b72fb64 | 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 |
bd838488 | 26 | .TH SHM_OPEN 3 2009-02-25 "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 */" |
fea681da MK |
35 | .sp |
36 | .BI "int shm_open(const char *" name ", int " oflag ", mode_t " mode ); | |
37 | .sp | |
38 | .BI "int shm_unlink(const char *" name ); | |
67ff1512 | 39 | .sp |
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 (). |
fea681da MK |
53 | .LP |
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. | |
fea681da MK |
74 | .LP |
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. | |
c13182ef MK |
84 | A shared memory object opened in this way can only be |
85 | .BR mmap (2)ed | |
fea681da MK |
86 | for read (\fBPROT_READ\fP) access. |
87 | .TP | |
88 | .B O_RDWR | |
89 | Open the object for read-write access. | |
90 | .TP | |
91 | .B O_CREAT | |
c13182ef | 92 | Create the shared memory object if it does not exist. |
bf0cac28 MK |
93 | The user and group ownership of the object are taken |
94 | from the corresponding effective IDs of the calling process, | |
95 | .\" In truth it is actually the file system IDs on Linux, but these | |
96 | .\" are nearly always the same as the effective IDs. (MTK, Jul 05) | |
fea681da | 97 | and the object's |
c13182ef | 98 | permission bits are set according to the low-order 9 bits of |
fea681da MK |
99 | .IR mode , |
100 | except that those bits set in the process file mode | |
101 | creation mask (see | |
102 | .BR umask (2)) | |
103 | are cleared for the new object. | |
bf0cac28 | 104 | A set of macro constants which can be used to define |
fea681da | 105 | .I mode |
c13182ef | 106 | is listed in |
bf0cac28 | 107 | .BR open (2). |
87d17de4 MK |
108 | (Symbolic definitions of these constants can be obtained by including |
109 | .IR <sys/stat.h> .) | |
fea681da | 110 | .sp |
5503c85e | 111 | A new shared memory object initially has zero length\(emthe size of the |
fea681da MK |
112 | object can be set using |
113 | .BR ftruncate (2). | |
bf0cac28 | 114 | The newly allocated bytes of a shared memory |
d9bfdb9c | 115 | object are automatically initialized to 0. |
c13182ef | 116 | .TP |
fea681da | 117 | .B O_EXCL |
c13182ef | 118 | If |
fea681da | 119 | .B O_CREAT |
bf0cac28 | 120 | was also specified, and a shared memory object with the given |
c13182ef | 121 | .I name |
fea681da | 122 | already exists, return an error. |
c13182ef | 123 | The check for the existence of the object, and its creation if it |
fea681da MK |
124 | does not exist, are performed atomically. |
125 | .TP | |
126 | .B O_TRUNC | |
127 | If the shared memory object already exists, truncate it to zero bytes. | |
128 | .LP | |
87d17de4 MK |
129 | Definitions of these flag values can be obtained by including |
130 | .IR <fcntl.h> . | |
131 | .LP | |
fea681da | 132 | On successful completion |
bf0cac28 | 133 | .BR shm_open () |
fea681da MK |
134 | returns a new file descriptor referring to the shared memory object. |
135 | This file descriptor is guaranteed to be the lowest-numbered file descriptor | |
c13182ef | 136 | not previously opened within the process. |
fea681da MK |
137 | The |
138 | .B FD_CLOEXEC | |
c13182ef | 139 | flag (see |
fea681da MK |
140 | .BR fcntl (2)) |
141 | is set for the file descriptor. | |
142 | ||
c13182ef MK |
143 | The file descriptor is normally used in subsequent calls |
144 | to | |
fea681da | 145 | .BR ftruncate (2) |
bf0cac28 | 146 | (for a newly created object) and |
fea681da MK |
147 | .BR mmap (2). |
148 | After a call to | |
149 | .BR mmap (2) | |
150 | the file descriptor may be closed without affecting the memory mapping. | |
151 | ||
152 | The operation | |
c13182ef | 153 | of |
bf0cac28 | 154 | .BR shm_unlink () |
fea681da MK |
155 | is analogous to |
156 | .BR unlink (2): | |
157 | it removes a shared memory object name, and, once all processes | |
c13182ef | 158 | have unmapped the object, de-allocates and |
fea681da | 159 | destroys the contents of the associated memory region. |
c13182ef | 160 | After a successful |
bf0cac28 | 161 | .BR shm_unlink (), |
c13182ef | 162 | attempts to |
bf0cac28 | 163 | .BR shm_open () |
c13182ef | 164 | an object with the same |
fea681da MK |
165 | .I name |
166 | will fail (unless | |
167 | .B O_CREAT | |
168 | was specified, in which case a new, distinct object is created). | |
47297adb | 169 | .SH RETURN VALUE |
fea681da | 170 | On success, |
bf0cac28 | 171 | .BR shm_open () |
2fda57bd | 172 | returns a nonnegative file descriptor. |
c13182ef | 173 | On failure, |
bf0cac28 | 174 | .BR shm_open () |
fea681da | 175 | returns \-1. |
bf0cac28 | 176 | .BR shm_unlink () |
fea681da MK |
177 | returns 0 on success, or \-1 on error. |
178 | .SH ERRORS | |
179 | On failure, | |
180 | .I errno | |
c13182ef MK |
181 | is set to indicate the cause of the error. |
182 | Values which may appear in | |
fea681da MK |
183 | .I errno |
184 | include the following: | |
c13182ef | 185 | .TP |
fea681da MK |
186 | .B EACCES |
187 | Permission to | |
bf0cac28 | 188 | .BR shm_unlink () |
fea681da MK |
189 | the shared memory object was denied. |
190 | .TP | |
191 | .B EACCES | |
c13182ef | 192 | Permission was denied to |
bf0cac28 | 193 | .BR shm_open () |
fea681da MK |
194 | .I name |
195 | in the specified | |
bf0cac28 | 196 | .IR mode , |
c13182ef | 197 | or |
fea681da MK |
198 | .B O_TRUNC |
199 | was specified and the caller does not have write permission on the object. | |
c13182ef | 200 | .TP |
fea681da MK |
201 | .B EEXIST |
202 | Both | |
203 | .B O_CREAT | |
204 | and | |
c13182ef | 205 | .B O_EXCL |
fea681da | 206 | were specified to |
bf0cac28 | 207 | .BR shm_open () |
fea681da MK |
208 | and the shared memory object specified by |
209 | .I name | |
210 | already exists. | |
211 | .TP | |
212 | .B EINVAL | |
213 | The | |
214 | .I name | |
c13182ef | 215 | argument to |
bf0cac28 | 216 | .BR shm_open () |
fea681da MK |
217 | was invalid. |
218 | .TP | |
219 | .B EMFILE | |
220 | The process already has the maximum number of files open. | |
221 | .TP | |
222 | .B ENAMETOOLONG | |
c13182ef | 223 | The length of |
fea681da | 224 | .I name |
c13182ef | 225 | exceeds |
fea681da MK |
226 | .BR PATH_MAX . |
227 | .TP | |
228 | .B ENFILE | |
229 | The limit on the total number of files open on the system has been | |
230 | reached. | |
231 | .TP | |
232 | .B ENOENT | |
233 | An attempt was made to | |
bf0cac28 | 234 | .BR shm_open () |
c13182ef MK |
235 | a |
236 | .I name | |
fea681da MK |
237 | that did not exist, and |
238 | .B O_CREAT | |
239 | was not specified. | |
240 | .TP | |
241 | .B ENOENT | |
242 | An attempt was to made to | |
bf0cac28 | 243 | .BR shm_unlink () |
c13182ef MK |
244 | a |
245 | .I name | |
fea681da | 246 | that does not exist. |
67ff1512 MK |
247 | .SH VERSIONS |
248 | These functions are provided in glibc 2.2 and later. | |
47297adb | 249 | .SH CONFORMING TO |
2b2581ee MK |
250 | POSIX.1-2001. |
251 | .LP | |
252 | POSIX.1-2001 says that the group ownership of a newly created shared | |
253 | memory object is set to either the calling process's effective group ID | |
44a2c328 | 254 | or "a system default group ID". |
47297adb | 255 | .SH NOTES |
fea681da | 256 | .LP |
c13182ef | 257 | POSIX leaves the behavior of the combination of |
fea681da MK |
258 | .B O_RDONLY |
259 | and | |
260 | .B O_TRUNC | |
c13182ef MK |
261 | unspecified. |
262 | On Linux, this will successfully truncate an existing | |
5503c85e | 263 | shared memory object\(emthis may not be so on other UNIX systems. |
fea681da MK |
264 | .LP |
265 | The POSIX shared memory object implementation on Linux 2.4 makes use | |
266 | of a dedicated file system, which is normally | |
c13182ef | 267 | mounted under |
bf0cac28 | 268 | .IR /dev/shm . |
47297adb | 269 | .SH SEE ALSO |
fea681da MK |
270 | .BR close (2), |
271 | .BR fchmod (2), | |
272 | .BR fchown (2), | |
273 | .BR fcntl (2), | |
274 | .BR fstat (2), | |
275 | .BR ftruncate (2), | |
276 | .BR mmap (2), | |
277 | .BR open (2), | |
f93af9c6 MK |
278 | .BR umask (2), |
279 | .BR shm_overview (7) |