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 March 20, 2007
  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 .Ft int
  43 .Fn shm_open "const char *path" "int flags" "mode_t mode"
  44 .Ft int
  45 .Fn shm_unlink "const char *path"
  46 .Sh DESCRIPTION
  47 The
  48 .Fn shm_open
  49 system call opens (or optionally creates) a
  50 .Tn POSIX
  51 shared memory object named
  52 .Fa path .
  53 The
  54 .Fa flags
  55 argument contains a subset of the flags used by
  56 .Xr open 2 .
  57 An access mode of either
  58 .Dv O_RDONLY
  59 or
  60 .Dv O_RDWR
  61 must be included in
  62 .Fa flags .
  63 The optional flags
  64 .Dv O_CREAT ,
  65 .Dv O_EXCL ,
  66 and
  67 .Dv O_TRUNC
  68 may also be specified.
  69 .Pp
  70 If
  71 .Dv O_CREAT
  72 is specified,
  73 then a new shared memory object named
  74 .Fa path
  75 will be created if it does not exist.
  76 In this case,
  77 the shared memory object is created with mode
  78 .Fa mode
  79 subject to the process' umask value.
  80 If both the
  81 .Dv O_CREAT
  82 and
  83 .Dv O_EXCL
  84 flags are specified and a shared memory object named
  85 .Fa path
  86 already exists,
  87 then
  88 .Fn shm_open
  89 will fail with
  90 .Er EEXIST.
  91 .Pp
  92 Newly created objects start off with a size of zero.
  93 If an existing shared memory object is opened with
  94 .Dv O_RDWR
  95 and the
  96 .Dv O_TRUNC
  97 flag is specified,
  98 then the shared memory object will be truncated to a size of zero.
  99 The size of the object can be adjusted via
 100 .Xr ftruncate 2
 101 and queried via
 102 .Xr fstat 2 .
 103 .Pp
 104 The new descriptor is set to close during
 105 .Xr execve 2
 106 system calls;
 107 see
 108 .Xr close 2
 109 and
 110 .Xr fcntl 2 .
 111 .Pp
 112 As a FreeBSD extension,
 113 the constant
 114 .Dv SHM_ANON
 115 may be used for the
 116 .Fa path
 117 argument to
 118 .Fn shm_open .
 119 In this case, an anonymous, unnamed shared memory object is created.
 120 Since the object has no name,
 121 it cannot be removed via a subsequent call to
 122 .Fn shm_unlink .
 123 Instead,
 124 the shared memory object will be garbage collected when the last reference to
 125 the shared memory object is removed.
 126 The shared memory object may be shared with other processes by sharing the
 127 file descriptor via
 128 .Xr fork 2
 129 or
 130 .Xr sendmsg 2 .
 131 Attempting to open an anonymous shared memory object with
 132 .Dv O_RDONLY
 133 will fail with
 134 .Er EINVAL .
 135 All other flags are ignored.
 136 .Pp
 137 The
 138 .Fn shm_unlink
 139 system call removes a shared memory object named
 140 .Fa path .
 141 .Pp
 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 The result of using
 175 .Xr open 2 ,
 176 .Xr read 2 ,
 177 or
 178 .Xr write 2
 179 on a shared memory object, or on the descriptor returned by
 180 .Fn shm_open ,
 181 is undefined.
 182 It is also undefined whether the shared memory object itself, or its
 183 contents, persist across reboots.
 184 .Pp
 185 In FreeBSD,
 186 .Xr read 2
 187 and
 188 .Xr write 2
 189 on a shared memory object will fail with
 190 .Er EOPNOTSUPP
 191 and neither shared memory objects nor their contents persist across reboots.
 192 .Sh ERRORS
 193 The following errors are defined for
 194 .Fn shm_open :
 195 .Bl -tag -width Er
 196 .It Bq Er EINVAL
 197 A flag other than
 198 .Dv O_RDONLY ,
 199 .Dv O_RDWR ,
 200 .Dv O_CREAT ,
 201 .Dv O_EXCL ,
 202 or
 203 .Dv O_TRUNC
 204 was included in
 205 .Fa flags .
 206 .It Bq Er EMFILE
 207 The process has already reached its limit for open file descriptors.
 208 .It Bq Er ENFILE
 209 The system file table is full.
 210 .It Bq Er EINVAL
 211 .Dv O_RDONLY
 212 was specified while creating an anonymous shared memory object via
 213 .Dv SHM_ANON .
 214 .It Bq Er EFAULT
 215 The
 216 .Fa path
 217 argument points outside the process' allocated address space.
 218 .It Bq Er ENAMETOOLONG
 219 The entire pathname exceeded 1023 characters.
 220 .It Bq Er EINVAL
 221 The
 222 .Fa path
 223 does not begin with a slash
 224 .Pq Ql \&/
 225 character.
 226 .It Bq Er ENOENT
 227 .Dv O_CREAT
 228 is specified and the named shared memory object does not exist.
 229 .It Bq Er EEXIST
 230 .Dv O_CREAT
 231 and
 232 .Dv O_EXCL
 233 are specified and the named shared memory object dies exist.
 234 .It Bq Er EACCES
 235 The required permissions (for reading or reading and writing) are denied.
 236 .El
 237 .Pp
 238 The following errors are defined for
 239 .Fn shm_unlink :
 240 .Bl -tag -width Er
 241 .It Bq Er EFAULT
 242 The
 243 .Fa path
 244 argument points outside the process' allocated address space.
 245 .It Bq Er ENAMETOOLONG
 246 The entire pathname exceeded 1023 characters.
 247 .It Bq Er ENOENT
 248 The named shared memory object does not exist.
 249 .It Bq Er EACCES
 250 The required permissions are denied.
 251 .Fn shm_unlink
 252 requires write permission to the shared memory object.
 253 .El
 254 .Sh SEE ALSO
 255 .Xr close 2 ,
 256 .Xr ftruncate 2 ,
 257 .Xr fstat 2 ,
 258 .Xr mmap 2 ,
 259 .Xr munmap 2
 260 .Sh STANDARDS
 261 The
 262 .Fn shm_open
 263 and
 264 .Fn shm_unlink
 265 functions are believed to conform to
 266 .St -p1003.1b-93 .
 267 .Sh HISTORY
 268 The
 269 .Fn shm_open
 270 and
 271 .Fn shm_unlink
 272 functions first appeared in
 273 .Fx 4.3 .
 274 The functions were reimplemented as system calls using shared memory objects
 275 directly rather than files in
 276 .Fx 7.0 .
 277 .Sh AUTHORS
 278 .An Garrett A. Wollman Aq wollman@FreeBSD.org
 279 (C library support and this manual page)
 280 .Pp
 281 .An Matthew Dillon Aq dillon@FreeBSD.org
 282 .Pq Dv MAP_NOSYNC