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