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