lib/libc/sys/shm_open.2

   1 .\"
   2 .\" Copyright 2000 Massachusetts Institute of Technology
   3 .\"
   4 .\" Permission to use, copy, modify, and distribute this software and
   5 .\" its documentation for any purpose and without fee is hereby
   6 .\" granted, provided that both the above copyright notice and this
   7 .\" permission notice appear in all copies, that both the above
   8 .\" copyright notice and this permission notice appear in all
   9 .\" supporting documentation, and that the name of M.I.T. not be used
  10 .\" in advertising or publicity pertaining to distribution of the
  11 .\" software without specific, written prior permission.  M.I.T. makes
  12 .\" no representations about the suitability of this software for any
  13 .\" purpose.  It is provided "as is" without express or implied
  14 .\" warranty.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY M.I.T. ``AS IS''.  M.I.T. DISCLAIMS
  17 .\" ALL EXPRESS OR IMPLIED WARRANTIES WITH REGARD TO THIS SOFTWARE,
  18 .\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
  19 .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT
  20 .\" SHALL M.I.T. BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  21 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  22 .\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
  23 .\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  24 .\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  25 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  26 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  27 .\" SUCH DAMAGE.
  28 .\"
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd January 20, 2017
  32 .Dt SHM_OPEN 2
  33 .Os
  34 .Sh NAME
  35 .Nm shm_open , shm_unlink
  36 .Nd "shared memory object operations"
  37 .Sh LIBRARY
  38 .Lb libc
  39 .Sh SYNOPSIS
  40 .In sys/types.h
  41 .In sys/mman.h
  42 .In fcntl.h
  43 .Ft int
  44 .Fn shm_open "const char *path" "int flags" "mode_t mode"
  45 .Ft int
  46 .Fn shm_unlink "const char *path"
  47 .Sh DESCRIPTION
  48 The
  49 .Fn shm_open
  50 system call opens (or optionally creates) a
  51 .Tn POSIX
  52 shared memory object named
  53 .Fa path .
  54 The
  55 .Fa flags
  56 argument contains a subset of the flags used by
  57 .Xr open 2 .
  58 An access mode of either
  59 .Dv O_RDONLY
  60 or
  61 .Dv O_RDWR
  62 must be included in
  63 .Fa flags .
  64 The optional flags
  65 .Dv O_CREAT ,
  66 .Dv O_EXCL ,
  67 and
  68 .Dv O_TRUNC
  69 may also be specified.
  70 .Pp
  71 If
  72 .Dv O_CREAT
  73 is specified,
  74 then a new shared memory object named
  75 .Fa path
  76 will be created if it does not exist.
  77 In this case,
  78 the shared memory object is created with mode
  79 .Fa mode
  80 subject to the process' umask value.
  81 If both the
  82 .Dv O_CREAT
  83 and
  84 .Dv O_EXCL
  85 flags are specified and a shared memory object named
  86 .Fa path
  87 already exists,
  88 then
  89 .Fn shm_open
  90 will fail with
  91 .Er EEXIST .
  92 .Pp
  93 Newly created objects start off with a size of zero.
  94 If an existing shared memory object is opened with
  95 .Dv O_RDWR
  96 and the
  97 .Dv O_TRUNC
  98 flag is specified,
  99 then the shared memory object will be truncated to a size of zero.
 100 The size of the object can be adjusted via
 101 .Xr ftruncate 2
 102 and queried via
 103 .Xr fstat 2 .
 104 .Pp
 105 The new descriptor is set to close during
 106 .Xr execve 2
 107 system calls;
 108 see
 109 .Xr close 2
 110 and
 111 .Xr fcntl 2 .
 112 .Pp
 113 As a FreeBSD extension,
 114 the constant
 115 .Dv SHM_ANON
 116 may be used for the
 117 .Fa path
 118 argument to
 119 .Fn shm_open .
 120 In this case, an anonymous, unnamed shared memory object is created.
 121 Since the object has no name,
 122 it cannot be removed via a subsequent call to
 123 .Fn shm_unlink .
 124 Instead,
 125 the shared memory object will be garbage collected when the last reference to
 126 the shared memory object is removed.
 127 The shared memory object may be shared with other processes by sharing the
 128 file descriptor via
 129 .Xr fork 2
 130 or
 131 .Xr sendmsg 2 .
 132 Attempting to open an anonymous shared memory object with
 133 .Dv O_RDONLY
 134 will fail with
 135 .Er EINVAL .
 136 All other flags are ignored.
 137 .Pp
 138 The
 139 .Fn shm_unlink
 140 system call removes a shared memory object named
 141 .Fa path .
 142 .Sh RETURN VALUES
 143 If successful,
 144 .Fn shm_open
 145 returns a non-negative integer,
 146 and
 147 .Fn shm_unlink
 148 returns zero.
 149 Both functions return -1 on failure, and set
 150 .Va errno
 151 to indicate the error.
 152 .Sh COMPATIBILITY
 153 The
 154 .Fa path
 155 argument does not necessarily represent a pathname (although it does in
 156 most other implementations).
 157 Two processes opening the same
 158 .Fa path
 159 are guaranteed to access the same shared memory object if and only if
 160 .Fa path
 161 begins with a slash
 162 .Pq Ql \&/
 163 character.
 164 .Pp
 165 Only the
 166 .Dv O_RDONLY ,
 167 .Dv O_RDWR ,
 168 .Dv O_CREAT ,
 169 .Dv O_EXCL ,
 170 and
 171 .Dv O_TRUNC
 172 flags may be used in portable programs.
 173 .Pp
 174 .Tn POSIX
 175 specifications state that the result of using
 176 .Xr open 2 ,
 177 .Xr read 2 ,
 178 or
 179 .Xr write 2
 180 on a shared memory object, or on the descriptor returned by
 181 .Fn shm_open ,
 182 is undefined.
 183 However, the
 184 .Fx
 185 kernel implementation explicitly includes support for
 186 .Xr read 2
 187 and
 188 .Xr write 2 .
 189 .Pp
 190 .Fx
 191 also supports zero-copy transmission of data from shared memory
 192 objects with
 193 .Xr sendfile 2 .
 194 .Pp
 195 Neither shared memory objects nor their contents persist across reboots.
 196 .Pp
 197 Writes do not extend shared memory objects, so
 198 .Xr ftruncate 2
 199 must be called before any data can be written.
 200 See
 201 .Sx EXAMPLES .
 202 .Sh EXAMPLES
 203 This example fails without the call to
 204 .Xr ftruncate 2 :
 205 .Bd -literal -compact
 206
 207         uint8_t buffer[getpagesize()];
 208         ssize_t len;
 209         int fd;
 210
 211         fd = shm_open(SHM_ANON, O_RDWR | O_CREAT, 0600);
 212         if (fd < 0)
 213                 err(EX_OSERR, "%s: shm_open", __func__);
 214         if (ftruncate(fd, getpagesize()) < 0)
 215                 err(EX_IOERR, "%s: ftruncate", __func__);
 216         len = pwrite(fd, buffer, getpagesize(), 0);
 217         if (len < 0)
 218                 err(EX_IOERR, "%s: pwrite", __func__);
 219         if (len != getpagesize())
 220                 errx(EX_IOERR, "%s: pwrite length mismatch", __func__);
 221 .Ed
 222 .Sh ERRORS
 223 .Fn shm_open
 224 fails with these error codes for these conditions:
 225 .Bl -tag -width Er
 226 .It Bq Er EINVAL
 227 A flag other than
 228 .Dv O_RDONLY ,
 229 .Dv O_RDWR ,
 230 .Dv O_CREAT ,
 231 .Dv O_EXCL ,
 232 or
 233 .Dv O_TRUNC
 234 was included in
 235 .Fa flags .
 236 .It Bq Er EMFILE
 237 The process has already reached its limit for open file descriptors.
 238 .It Bq Er ENFILE
 239 The system file table is full.
 240 .It Bq Er EINVAL
 241 .Dv O_RDONLY
 242 was specified while creating an anonymous shared memory object via
 243 .Dv SHM_ANON .
 244 .It Bq Er EFAULT
 245 The
 246 .Fa path
 247 argument points outside the process' allocated address space.
 248 .It Bq Er ENAMETOOLONG
 249 The entire pathname exceeded 1023 characters.
 250 .It Bq Er EINVAL
 251 The
 252 .Fa path
 253 does not begin with a slash
 254 .Pq Ql \&/
 255 character.
 256 .It Bq Er ENOENT
 257 .Dv O_CREAT
 258 is specified and the named shared memory object does not exist.
 259 .It Bq Er EEXIST
 260 .Dv O_CREAT
 261 and
 262 .Dv O_EXCL
 263 are specified and the named shared memory object does exist.
 264 .It Bq Er EACCES
 265 The required permissions (for reading or reading and writing) are denied.
 266 .El
 267 .Pp
 268 .Fn shm_unlink
 269 fails with these error codes for these conditions:
 270 .Bl -tag -width Er
 271 .It Bq Er EFAULT
 272 The
 273 .Fa path
 274 argument points outside the process' allocated address space.
 275 .It Bq Er ENAMETOOLONG
 276 The entire pathname exceeded 1023 characters.
 277 .It Bq Er ENOENT
 278 The named shared memory object does not exist.
 279 .It Bq Er EACCES
 280 The required permissions are denied.
 281 .Fn shm_unlink
 282 requires write permission to the shared memory object.
 283 .El
 284 .Sh SEE ALSO
 285 .Xr close 2 ,
 286 .Xr fstat 2 ,
 287 .Xr ftruncate 2 ,
 288 .Xr mmap 2 ,
 289 .Xr munmap 2 ,
 290 .Xr sendfile 2
 291 .Sh STANDARDS
 292 The
 293 .Fn shm_open
 294 and
 295 .Fn shm_unlink
 296 functions are believed to conform to
 297 .St -p1003.1b-93 .
 298 .Sh HISTORY
 299 The
 300 .Fn shm_open
 301 and
 302 .Fn shm_unlink
 303 functions first appeared in
 304 .Fx 4.3 .
 305 The functions were reimplemented as system calls using shared memory objects
 306 directly rather than files in
 307 .Fx 8.0 .
 308 .Sh AUTHORS
 309 .An Garrett A. Wollman Aq Mt wollman@FreeBSD.org
 310 (C library support and this manual page)
 311 .Pp
 312 .An Matthew Dillon Aq Mt dillon@FreeBSD.org
 313 .Pq Dv MAP_NOSYNC