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