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 50The 51.Fn shm_open 52function opens (or optionally creates) a 53.Tn POSIX 54shared memory object named 55.Fa path . 56The 57.Fn shm_unlink 58function removes a shared memory object named 59.Fa path . 60.Pp 61In the 62.Dx 63implementation, 64.Tn POSIX 65shared memory objects are implemented as ordinary files. 66The 67.Fn shm_open 68and 69.Fn shm_unlink 70act as wrappers around the 71.Xr open 2 72and 73.Xr unlink 2 74routines, and 75.Fa path , 76.Fa flags , 77and 78.Fa mode 79arguments are as specified for those functions. 80The 81.Fa flags 82argument 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 86In addition, the 87.Dx 88implementation causes 89.Fn mmap 90of a descriptor returned by 91.Fn shm_open 92to behave as if the 93.Dv MAP_NOSYNC 94flag 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 99The 100.Fn shm_unlink 101function makes no effort to ensure that 102.Fa path 103refers to a shared memory object. 104.Sh COMPATIBILITY 105The 106.Fa path 107argument does not necessarily represent a pathname (although it does in this 108and most other implementations). 109Two processes opening the same 110.Fa path 111are guaranteed to access the same shared memory object if and only if 112.Fa path 113begins with a slash 114.Pq Ql \&/ 115character. 116.Pp 117Only the 118.Dv O_RDONLY , 119.Dv O_RDWR , 120.Dv O_CREAT , 121.Dv O_EXCL , 122and 123.Dv O_TRUNC 124flags may be used in portable programs. 125.Pp 126The result of using 127.Xr open 2 , 128.Xr read 2 , 129or 130.Xr write 2 131on a shared memory object, or on the descriptor returned by 132.Fn shm_open , 133is undefined. 134It is also undefined whether the shared memory object itself, or its 135contents, persist across reboots. 136.Sh RETURN VALUES 137If successful, 138.Fn shm_open 139returns a non-negative integer; 140.Fn shm_unlink 141returns zero. 142Both functions return -1 on failure, and set 143.Va errno 144to indicate the error. 145.Sh ERRORS 146The 147.Fn shm_open 148and 149.Fn shm_unlink 150functions can fail with any error defined for 151.Fn open 152and 153.Fn unlink , 154respectively. In addition, the following errors are defined for 155.Fn shm_open : 156.Bl -tag -width Er 157.It Bq Er EINVAL 158The object named by 159.Fa path 160is not a shared memory object 161(i.e., it is not a regular file). 162.It Bq Er EINVAL 163The 164.Fa flags 165argument to 166.Fn shm_open 167specifies 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 176The 177.Fn shm_open 178and 179.Fn shm_unlink 180functions are believed to conform to 181.St -p1003.1b-93 . 182.Sh HISTORY 183The 184.Fn shm_open 185and 186.Fn shm_unlink 187functions 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 195