xref: /openbsd/lib/libc/sys/mmap.2 (revision 2d197172) 
1.\"	$OpenBSD: mmap.2,v 1.50 2014/07/02 22:22:35 matthew Exp $
2.\"	$NetBSD: mmap.2,v 1.5 1995/06/24 10:48:59 cgd Exp $
3.\"
4.\" Copyright (c) 1991, 1993
5.\"	The Regents of the University of California.  All rights reserved.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\" 1. Redistributions of source code must retain the above copyright
11.\"    notice, this list of conditions and the following disclaimer.
12.\" 2. Redistributions in binary form must reproduce the above copyright
13.\"    notice, this list of conditions and the following disclaimer in the
14.\"    documentation and/or other materials provided with the distribution.
15.\" 3. Neither the name of the University nor the names of its contributors
16.\"    may be used to endorse or promote products derived from this software
17.\"    without specific prior written permission.
18.\"
19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29.\" SUCH DAMAGE.
30.\"
31.\"	@(#)mmap.2	8.1 (Berkeley) 6/4/93
32.\"
33.Dd $Mdocdate: July 2 2014 $
34.Dt MMAP 2
35.Os
36.Sh NAME
37.Nm mmap
38.Nd map files or devices into memory
39.Sh SYNOPSIS
40.In sys/mman.h
41.Ft void *
42.Fn mmap "void *addr" "size_t len" "int prot" "int flags" "int fd" "off_t offset"
43.Sh DESCRIPTION
44The
45.Fn mmap
46function causes the contents of
47.Fa fd ,
48starting at
49.Fa offset ,
50to be mapped in memory at the given
51.Fa addr .
52The mapping will extend at least
53.Fa len
54bytes, subject to page alignment restrictions.
55.Pp
56The
57.Fa addr
58argument describes the address where the system should place the mapping.
59If the
60.Dv MAP_FIXED
61flag is specified, the allocation will happen at the specified address,
62replacing any previously established mappings in its range.
63Otherwise, the mapping will be placed at the available spot at
64.Fa addr ;
65failing that it will be placed "close by".
66If
67.Fa addr
68is
69.Dv NULL
70the system can pick any address.
71Except for
72.Dv MAP_FIXED
73mappings, the system will never replace existing mappings.
74.Pp
75The
76.Fa len
77argument describes the minimum amount of bytes the mapping will span.
78Since
79.Fn mmap
80maps pages into memory,
81.Fa len
82may be rounded up to hit a page boundary.
83If
84.Fa len
85is 0, the mapping will fail with
86.Er EINVAL .
87.Pp
88If an
89.Fa fd
90and
91.Fa offset
92are specified, the resulting address may end up not on a page boundary,
93in order to align the page offset in the
94.Fa addr
95to the page offset in
96.Fa offset .
97.Pp
98The protections (region accessibility) are specified in the
99.Fa prot
100argument.
101It should either be
102.Dv PROT_NONE
103.Pq no permissions
104or the bitwise OR of one or more of the following values:
105.Pp
106.Bl -tag -width "PROT_WRITEXX" -offset indent -compact
107.It Dv PROT_EXEC
108Pages may be executed.
109.It Dv PROT_READ
110Pages may be read.
111.It Dv PROT_WRITE
112Pages may be written.
113.El
114.Pp
115The
116.Fa flags
117parameter specifies the type of the mapped object, mapping options, and
118whether modifications made to the mapped copy of the page are private
119to the process or are to be shared with other references.
120Sharing, mapping type, and options are specified in the
121.Fa flags
122argument by OR'ing the following values.
123Exactly one of the first two values must be specified:
124.Bl -tag -width MAP_PRIVATE -offset indent
125.It Dv MAP_PRIVATE
126Modifications are private.
127.It Dv MAP_SHARED
128Modifications are shared.
129.El
130.Pp
131Any combination of the following flags may additionally be used:
132.Bl -tag -width MAP_PRIVATE -offset indent
133.It Dv MAP_ANON
134Map anonymous memory not associated with any specific file.
135The file descriptor used for creating
136.Dv MAP_ANON
137must currently be \-1 indicating no name is associated with the
138region.
139.It Dv MAP_FIXED
140Demand that the mapping is placed at
141.Fa addr ,
142rather than having the system select a location.
143.Fa addr ,
144.Fa len
145and
146.Fa offset
147(in the case of
148.Fa fd
149mappings)
150must be multiples of the page size.
151Existing mappings in the address range will be replaced.
152Use of this option is discouraged.
153.El
154.Pp
155Finally, the following flags are also provided for
156source compatibility with code written for other operating systems,
157but are not recommended for use in new
158.Ox
159code:
160.Bl -tag -width MAP_PRIVATE -offset indent
161.It Dv MAP_COPY
162Modifications are private and, unlike
163.Dv MAP_PRIVATE ,
164modifications made by others are not visible.
165On
166.Ox
167this behaves just like
168.Dv MAP_PRIVATE .
169.It Dv MAP_FILE
170Mapped from a regular file, character special file, or block special file
171specified by file descriptor
172.Fa fd .
173On
174.Ox
175and all systems conforming to
176.St -p1003.1-2008
177this is the default mapping type and need not be specified.
178.It Dv MAP_HASSEMAPHORE
179Notify the kernel that the region may contain semaphores and that special
180handling may be necessary.
181On
182.Ox
183this flag is ignored.
184.It Dv MAP_INHERIT
185Permit regions to be inherited across
186.Xr exec 3
187system calls.
188On
189.Ox
190this flag is ignored.
191.It Dv MAP_TRYFIXED
192Attempt to use the hint provided by
193.Fa addr .
194On
195.Ox
196this is the default behavior.
197.El
198.Pp
199The
200.Xr close 2
201function does not unmap pages; see
202.Xr munmap 2
203for further information.
204.Sh RETURN VALUES
205The
206.Fn mmap
207function returns a pointer to the mapped region if successful;
208otherwise the value
209.Dv MAP_FAILED
210is returned and the global variable
211.Va errno
212is set to indicate the error.
213A successful return from
214.Fn mmap
215will never return the value
216.Dv MAP_FAILED .
217.Sh ERRORS
218.Fn mmap
219will fail if:
220.Bl -tag -width Er
221.It Bq Er EACCES
222The flag
223.Dv PROT_READ
224was specified as part of the
225.Fa prot
226parameter and
227.Fa fd
228was not open for reading.
229The flags
230.Dv MAP_SHARED
231and
232.Dv PROT_WRITE
233were specified as part
234of the
235.Fa flags
236and
237.Fa prot
238parameters and
239.Fa fd
240was not open for writing.
241.It Bq Er EBADF
242.Fa fd
243is not a valid open file descriptor.
244.It Bq Er EINVAL
245.Dv MAP_PRIVATE
246and
247.Dv MAP_SHARED
248were both specified.
249.It Bq Er EINVAL
250.Dv MAP_FIXED
251was specified and the
252.Fa addr
253parameter was not page aligned.
254.It Bq Er EINVAL
255.Fa addr
256and
257.Fa len
258specified a region that would extend beyond the end of the address space.
259.It Bq Er EINVAL
260.Fa fd
261did not specify a regular, character special, or block special file.
262.It Bq Er EINVAL
263The allocation
264.Fa len
265was 0.
266.It Bq Er ENOMEM
267.Dv MAP_FIXED
268was specified and the
269.Fa addr
270parameter wasn't available.
271.Dv MAP_ANON
272was specified and insufficient memory was available.
273.El
274.Sh SEE ALSO
275.Xr madvise 2 ,
276.Xr mincore 2 ,
277.Xr mlock 2 ,
278.Xr mprotect 2 ,
279.Xr mquery 2 ,
280.Xr msync 2 ,
281.Xr munmap 2 ,
282.Xr getpagesize 3
283.Sh STANDARDS
284The
285.Fn mmap
286function conforms to
287.St -p1003.1-2008 .
288.Sh HISTORY
289The
290.Fn mmap
291system call first appeared in
292.Bx 4.1c .
293.Sh CAVEATS
294.St -p1003.1-2008
295specifies that references to pages beyond the end of a mapped object
296shall generate a
297.Dv SIGBUS
298signal; however,
299.Ox
300generates a
301.Dv SIGSEGV
302signal in this case instead.
303.Pp
304Additionally,
305.St -p1003.1-2008
306specifies that
307.Fn mmap
308shall fail with
309.Er EINVAL
310if neither
311.Dv MAP_PRIVATE
312nor
313.Dv MAP_SHARED
314is specified by
315.Fa flags ;
316however, for compatibility with old programs,
317.Ox
318instead defaults to
319.Dv MAP_SHARED
320for mappings of character special files, and to
321.Dv MAP_PRIVATE
322for all other mappings.
323New programs should not rely on this behavior.
324.Sh BUGS
325Due to a limitation of the current vm system (see
326.Xr uvm 9 ) ,
327mapping descriptors
328.Dv PROT_WRITE
329without also specifying
330.Dv PROT_READ
331is useless
332(results in a segmentation fault when first accessing the mapping).
333This means that such descriptors must be opened with
334.Dv O_RDWR ,
335which requires both read and write permissions on the underlying
336object.
337