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