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