lib/libc/gen/shm_open.3

   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: src/lib/libc/gen/shm_open.3,v 1.3.2.5 2001/12/14 18:33:51 ru Exp $
  30 .\"
  31 .Dd June 28, 2019
  32 .Dt SHM_OPEN 3
  33 .Os
  34 .Sh NAME
  35 .Nm shm_open ,
  36 .Nm shm_unlink
  37 .Nd POSIX shared memory object operations
  38 .Sh LIBRARY
  39 .Lb libc
  40 .Sh SYNOPSIS
  41 .In sys/types.h
  42 .In sys/mman.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 function opens (or optionally creates) a
  51 .Tn POSIX
  52 shared memory object named
  53 .Fa path .
  54 The
  55 .Fn shm_unlink
  56 function removes a shared memory object named
  57 .Fa path .
  58 Using the same
  59 .Fa path
  60 allows unrelated processes to access the same object.
  61 .Sh IMPLEMENTATION NOTES
  62 .Dx
  63 mounts a
  64 .Xr tmpfs 5
  65 file system at
  66 .Pa /var/run/shm .
  67 .Tn POSIX
  68 shared memory objects are implemented as ordinary files under
  69 that directory.
  70 The
  71 .Fn shm_open
  72 and
  73 .Fn shm_unlink
  74 functions act as wrappers around
  75 .Xr open 2
  76 and
  77 .Xr unlink 2 .
  78 Any leading slash
  79 .Pq Ql \&/
  80 characters are removed from
  81 .Fa path
  82 to make it relative to
  83 .Pa /var/run/shm .
  84 The
  85 .Fa flags
  86 and
  87 .Fa mode
  88 arguments are passed through unaltered.
  89 .Fa flags
  90 is checked to ensure that the access mode specified is not
  91 .Dv O_WRONLY
  92 (which is not defined for shared memory objects).
  93 .Pp
  94 In addition, the
  95 .Dx
  96 implementation causes
  97 .Fn mmap
  98 of a descriptor returned by
  99 .Fn shm_open
 100 to behave as if the
 101 .Dv MAP_NOSYNC
 102 flag had been specified to
 103 .Xr mmap 2 .
 104 (It does so by setting a special file flag using
 105 .Xr fcntl 2 . )
 106 .Sh RETURN VALUES
 107 If successful,
 108 .Fn shm_open
 109 returns a non-negative integer;
 110 .Fn shm_unlink
 111 returns zero.
 112 Both functions return -1 on failure, and set
 113 .Va errno
 114 to indicate the error.
 115 .Sh COMPATIBILITY
 116 On
 117 .Dx
 118 and many other operating systems the
 119 .Fa path
 120 argument is interpreted as a file system pathname under a special
 121 directory where a memory-backed file system is mounted.
 122 Most operating systems do some name mangling to
 123 .Fa path .
 124 Leading slashes are commonly removed to turn an absolute pathname into
 125 a relative one.
 126 Problematic characters may be escaped and there may be a length limit on
 127 .Fa path .
 128 On some systems the mangled pathname is completely different from the
 129 given
 130 .Fa path .
 131 On a few systems, shared memory objects live outside the ordinary file
 132 system in their own dedicated namespace.
 133 .Pp
 134 According to
 135 .Tn POSIX
 136 two processes opening the same
 137 .Fa path
 138 are guaranteed to access the same shared memory object if and only if
 139 .Fa path
 140 begins with a slash.
 141 The most portable form of pathname is probably
 142 .Ql /foobar ,
 143 i.e.\& one leading slash, no other slashes and no dots.
 144 .Pp
 145 The result of using
 146 .Xr open 2
 147 on the pathname of a shared memory object,
 148 or using
 149 .Xr read 2
 150 or
 151 .Xr write 2
 152 on a file descriptor returned by
 153 .Fn shm_open ,
 154 is undefined by
 155 .Tn POSIX .
 156 It is also undefined whether the shared memory object itself, or its
 157 contents, persist across reboots.
 158 On
 159 .Dx
 160 and most other systems they do not.
 161 Only the
 162 .Dv O_RDONLY ,
 163 .Dv O_RDWR ,
 164 .Dv O_CREAT ,
 165 .Dv O_EXCL ,
 166 and
 167 .Dv O_TRUNC
 168 flags may be used in portable programs.
 169 .Sh ERRORS
 170 The
 171 .Fn shm_open
 172 and
 173 .Fn shm_unlink
 174 functions can fail with any error defined for
 175 .Fn open
 176 and
 177 .Fn unlink ,
 178 respectively.
 179 In addition, the following errors are defined for
 180 .Fn shm_open :
 181 .Bl -tag -width Er
 182 .It Bq Er EINVAL
 183 The object named by
 184 .Fa path
 185 is not a shared memory object
 186 (i.e., it is not a regular file).
 187 .It Bq Er EINVAL
 188 The
 189 .Fa flags
 190 argument to
 191 .Fn shm_open
 192 specifies an access mode of
 193 .Dv O_WRONLY .
 194 .El
 195 .Sh SEE ALSO
 196 .Xr mmap 2 ,
 197 .Xr munmap 2 ,
 198 .Xr open 2 ,
 199 .Xr unlink 2 ,
 200 .Xr tmpfs 5
 201 .Sh STANDARDS
 202 The
 203 .Fn shm_open
 204 and
 205 .Fn shm_unlink
 206 functions are believed to conform to
 207 .St -p1003.1b-93 .
 208 .Sh HISTORY
 209 The
 210 .Fn shm_open
 211 and
 212 .Fn shm_unlink
 213 functions first appeared in
 214 .Fx 4.3 .
 215 .Sh AUTHORS
 216 .An Garrett A. Wollman Aq Mt wollman@FreeBSD.org
 217 (C library support and this manual page)
 218 .An Matthew Dillon Aq Mt dillon@FreeBSD.org
 219 .Pq Dv MAP_NOSYNC