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.3 2004/03/11 12:28:50 hmp 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 COMPATIBILITY
 105 The
 106 .Fa path
 107 argument does not necessarily represent a pathname (although it does in this
 108 and most other implementations).
 109 Two processes opening the same
 110 .Fa path
 111 are guaranteed to access the same shared memory object if and only if
 112 .Fa path
 113 begins with a slash
 114 .Pq Ql \&/
 115 character.
 116 .Pp
 117 Only the
 118 .Dv O_RDONLY ,
 119 .Dv O_RDWR ,
 120 .Dv O_CREAT ,
 121 .Dv O_EXCL ,
 122 and
 123 .Dv O_TRUNC
 124 flags may be used in portable programs.
 125 .Pp
 126 The result of using
 127 .Xr open 2 ,
 128 .Xr read 2 ,
 129 or
 130 .Xr write 2
 131 on a shared memory object, or on the descriptor returned by
 132 .Fn shm_open ,
 133 is undefined.
 134 It is also undefined whether the shared memory object itself, or its
 135 contents, persist across reboots.
 136 .Sh RETURN VALUES
 137 If successful,
 138 .Fn shm_open
 139 returns a non-negative integer;
 140 .Fn shm_unlink
 141 returns zero.
 142 Both functions return -1 on failure, and set
 143 .Va errno
 144 to indicate the error.
 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