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$
  30 .\"
  31 .Dd March 24, 2000
  32 .Dt SHM_OPEN 3
  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 function opens (or optionally creates) a
  50 .Tn POSIX
  51 shared memory object named
  52 .Fa path .
  53 The
  54 .Fn shm_unlink
  55 function removes a shared memory object named
  56 .Fa path .
  57 .Pp
  58 In the
  59 .Fx
  60 implementation,
  61 .Tn POSIX
  62 shared memory objects are implemented as ordinary files.
  63 The
  64 .Fn shm_open
  65 and
  66 .Fn shm_unlink
  67 act as wrappers around the
  68 .Xr open 2
  69 and
  70 .Xr unlink 2
  71 routines, and
  72 .Fa path ,
  73 .Fa flags ,
  74 and
  75 .Fa mode
  76 arguments are as specified for those functions.
  77 The
  78 .Fa flags
  79 argument is checked to ensure that the access mode specified is not
  80 .Dv O_WRONLY
  81 (which is not defined for shared memory objects).
  82 .Pp
  83 In addition, the
  84 .Fx
  85 implementation causes
  86 .Fn mmap
  87 of a descriptor returned by
  88 .Fn shm_open
  89 to behave as if the
  90 .Dv MAP_NOSYNC
  91 flag had been specified to
  92 .Xr mmap 2 .
  93 (It does so by setting a special file flag using
  94 .Xr fcntl 2 . )
  95 .Pp
  96 The
  97 .Fn shm_unlink
  98 function makes no effort to ensure that
  99 .Fa path
 100 refers to a shared memory object.
 101 .Sh RETURN VALUES
 102 If successful,
 103 .Fn shm_open
 104 returns a non-negative integer;
 105 .Fn shm_unlink
 106 returns zero.
 107 Both functions return -1 on failure, and set
 108 .Va errno
 109 to indicate the error.
 110 .Sh COMPATIBILITY
 111 The
 112 .Fa path
 113 argument does not necessarily represent a pathname (although it does in this
 114 and most other implementations).
 115 Two processes opening the same
 116 .Fa path
 117 are guaranteed to access the same shared memory object if and only if
 118 .Fa path
 119 begins with a slash
 120 .Pq Ql \&/
 121 character.
 122 .Pp
 123 Only the
 124 .Dv O_RDONLY ,
 125 .Dv O_RDWR ,
 126 .Dv O_CREAT ,
 127 .Dv O_EXCL ,
 128 and
 129 .Dv O_TRUNC
 130 flags may be used in portable programs.
 131 .Pp
 132 The result of using
 133 .Xr open 2 ,
 134 .Xr read 2 ,
 135 or
 136 .Xr write 2
 137 on a shared memory object, or on the descriptor returned by
 138 .Fn shm_open ,
 139 is undefined.
 140 It is also undefined whether the shared memory object itself, or its
 141 contents, persist across reboots.
 142 .Sh ERRORS
 143 The
 144 .Fn shm_open
 145 and
 146 .Fn shm_unlink
 147 functions can fail with any error defined for
 148 .Fn open
 149 and
 150 .Fn unlink ,
 151 respectively.
 152 In addition, the following errors are defined for
 153 .Fn shm_open :
 154 .Bl -tag -width Er
 155 .It Bq Er EINVAL
 156 The object named by
 157 .Fa path
 158 is not a shared memory object
 159 (i.e., it is not a regular file).
 160 .It Bq Er EINVAL
 161 The
 162 .Fa flags
 163 argument to
 164 .Fn shm_open
 165 specifies an access mode of
 166 .Dv O_WRONLY .
 167 .El
 168 .Sh SEE ALSO
 169 .Xr mmap 2 ,
 170 .Xr munmap 2 ,
 171 .Xr open 2 ,
 172 .Xr unlink 2
 173 .Sh STANDARDS
 174 The
 175 .Fn shm_open
 176 and
 177 .Fn shm_unlink
 178 functions are believed to conform to
 179 .St -p1003.1b-93 .
 180 .Sh HISTORY
 181 The
 182 .Fn shm_open
 183 and
 184 .Fn shm_unlink
 185 functions first appeared in
 186 .Fx 4.3 .
 187 .Sh AUTHORS
 188 .An Garrett A. Wollman Aq wollman@FreeBSD.org
 189 (C library support and this manual page)
 190 .Pp
 191 .An Matthew Dillon Aq dillon@FreeBSD.org
 192 .Pq Dv MAP_NOSYNC