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