man3/shm_open.3

   1 .\" Copyright (C) 2002 Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\"
   3 .\" %%%LICENSE_START(VERBATIM)
   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.
  12 .\"
  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
  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.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .\" FIXME . Add an example to this page
  26 .TH SHM_OPEN 3 2017-09-15 "Linux" "Linux Programmer's Manual"
  27 .SH NAME
  28 shm_open, shm_unlink \- create/open or unlink POSIX shared memory objects
  29 .SH SYNOPSIS
  30 .B #include <sys/mman.h>
  31 .br
  32 .BR "#include <sys/stat.h>" "        /* For mode constants */"
  33 .br
  34 .BR "#include <fcntl.h>" "           /* For O_* constants */"
  35 .PP
  36 .BI "int shm_open(const char *" name ", int " oflag ", mode_t " mode );
  37 .PP
  38 .BI "int shm_unlink(const char *" name );
  39 .PP
  40 Link with \fI\-lrt\fP.
  41 .SH DESCRIPTION
  42 .BR shm_open ()
  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
  45 be used by unrelated processes to
  46 .BR mmap (2)
  47 the same region of shared memory.
  48 The
  49 .BR shm_unlink ()
  50 function performs the converse operation,
  51 removing an object previously created by
  52 .BR shm_open ().
  53 .PP
  54 The operation of
  55 .BR shm_open ()
  56 is analogous to that of
  57 .BR open (2).
  58 .I name
  59 specifies the shared memory object to be created or opened.
  60 For portable use,
  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
  64 .BI NAME_MAX
  65 (i.e., 255) characters consisting of an initial slash,
  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.
  74 .PP
  75 .I oflag
  76 is a bit mask created by ORing together exactly one of
  77 .B O_RDONLY
  78 or
  79 .B O_RDWR
  80 and any of the other flags listed here:
  81 .TP 1.1i
  82 .B O_RDONLY
  83 Open the object for read access.
  84 A shared memory object opened in this way can be
  85 .BR mmap (2)ed
  86 only for read
  87 .RB ( PROT_READ )
  88 access.
  89 .TP
  90 .B O_RDWR
  91 Open the object for read-write access.
  92 .TP
  93 .B O_CREAT
  94 Create the shared memory object if it does not exist.
  95 The user and group ownership of the object are taken
  96 from the corresponding effective IDs of the calling process,
  97 .\" In truth it is actually the filesystem IDs on Linux, but these
  98 .\" are nearly always the same as the effective IDs.  (MTK, Jul 05)
  99 and the object's
 100 permission bits are set according to the low-order 9 bits of
 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.
 106 A set of macro constants which can be used to define
 107 .I mode
 108 is listed in
 109 .BR open (2).
 110 (Symbolic definitions of these constants can be obtained by including
 111 .IR <sys/stat.h> .)
 112 .IP
 113 A new shared memory object initially has zero length\(emthe size of the
 114 object can be set using
 115 .BR ftruncate (2).
 116 The newly allocated bytes of a shared memory
 117 object are automatically initialized to 0.
 118 .TP
 119 .B O_EXCL
 120 If
 121 .B O_CREAT
 122 was also specified, and a shared memory object with the given
 123 .I name
 124 already exists, return an error.
 125 The check for the existence of the object, and its creation if it
 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.
 130 .PP
 131 Definitions of these flag values can be obtained by including
 132 .IR <fcntl.h> .
 133 .PP
 134 On successful completion
 135 .BR shm_open ()
 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
 138 not previously opened within the process.
 139 The
 140 .B FD_CLOEXEC
 141 flag (see
 142 .BR fcntl (2))
 143 is set for the file descriptor.
 144 .PP
 145 The file descriptor is normally used in subsequent calls
 146 to
 147 .BR ftruncate (2)
 148 (for a newly created object) and
 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.
 153 .PP
 154 The operation
 155 of
 156 .BR shm_unlink ()
 157 is analogous to
 158 .BR unlink (2):
 159 it removes a shared memory object name, and, once all processes
 160 have unmapped the object, de-allocates and
 161 destroys the contents of the associated memory region.
 162 After a successful
 163 .BR shm_unlink (),
 164 attempts to
 165 .BR shm_open ()
 166 an object with the same
 167 .I name
 168 fail (unless
 169 .B O_CREAT
 170 was specified, in which case a new, distinct object is created).
 171 .SH RETURN VALUE
 172 On success,
 173 .BR shm_open ()
 174 returns a nonnegative file descriptor.
 175 On failure,
 176 .BR shm_open ()
 177 returns \-1.
 178 .BR shm_unlink ()
 179 returns 0 on success, or \-1 on error.
 180 .SH ERRORS
 181 On failure,
 182 .I errno
 183 is set to indicate the cause of the error.
 184 Values which may appear in
 185 .I errno
 186 include the following:
 187 .TP
 188 .B EACCES
 189 Permission to
 190 .BR shm_unlink ()
 191 the shared memory object was denied.
 192 .TP
 193 .B EACCES
 194 Permission was denied to
 195 .BR shm_open ()
 196 .I name
 197 in the specified
 198 .IR mode ,
 199 or
 200 .B O_TRUNC
 201 was specified and the caller does not have write permission on the object.
 202 .TP
 203 .B EEXIST
 204 Both
 205 .B O_CREAT
 206 and
 207 .B O_EXCL
 208 were specified to
 209 .BR shm_open ()
 210 and the shared memory object specified by
 211 .I name
 212 already exists.
 213 .TP
 214 .B EINVAL
 215 The
 216 .I name
 217 argument to
 218 .BR shm_open ()
 219 was invalid.
 220 .TP
 221 .B EMFILE
 222 The per-process limit on the number of open file descriptors has been reached.
 223 .TP
 224 .B ENAMETOOLONG
 225 The length of
 226 .I name
 227 exceeds
 228 .BR PATH_MAX .
 229 .TP
 230 .B ENFILE
 231 The system-wide limit on the total number of open files has been reached.
 232 .TP
 233 .B ENOENT
 234 An attempt was made to
 235 .BR shm_open ()
 236 a
 237 .I name
 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
 244 .BR shm_unlink ()
 245 a
 246 .I name
 247 that does not exist.
 248 .SH VERSIONS
 249 These functions are provided in glibc 2.2 and later.
 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
 263 .sp 1
 264 .SH CONFORMING TO
 265 POSIX.1-2001, POSIX.1-2008.
 266 .PP
 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
 269 or "a system default group ID".
 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.
 274 .SH NOTES
 275 .PP
 276 POSIX leaves the behavior of the combination of
 277 .B O_RDONLY
 278 and
 279 .B O_TRUNC
 280 unspecified.
 281 On Linux, this will successfully truncate an existing
 282 shared memory object\(emthis may not be so on other UNIX systems.
 283 .PP
 284 The POSIX shared memory object implementation on Linux makes use
 285 of a dedicated
 286 .BR tmpfs (5)
 287 filesystem that is normally mounted under
 288 .IR /dev/shm .
 289 .SH SEE ALSO
 290 .BR close (2),
 291 .BR fchmod (2),
 292 .BR fchown (2),
 293 .BR fcntl (2),
 294 .BR fstat (2),
 295 .BR ftruncate (2),
 296 .BR memfd_create (2),
 297 .BR mmap (2),
 298 .BR open (2),
 299 .BR umask (2),
 300 .BR shm_overview (7)