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