xref: /openbsd/lib/libc/sys/mmap.2 (revision 264ca280) 
1.\"	$OpenBSD: mmap.2,v 1.52 2016/05/27 19:45:04 deraadt 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: May 27 2016 $
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_ANONYMOUS -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_ANONYMOUS -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_ANONYMOUS
140Synonym for
141.Dv MAP_ANON .
142.It Dv MAP_FIXED
143Demand that the mapping is placed at
144.Fa addr ,
145rather than having the system select a location.
146.Fa addr ,
147.Fa len
148and
149.Fa offset
150(in the case of
151.Fa fd
152mappings)
153must be multiples of the page size.
154Existing mappings in the address range will be replaced.
155Use of this option is discouraged.
156.El
157.Pp
158Finally, the following flags are also provided for
159source compatibility with code written for other operating systems,
160but are not recommended for use in new
161.Ox
162code:
163.Bl -tag -width MAP_ANONYMOUS -offset indent
164.It Dv MAP_COPY
165Modifications are private and, unlike
166.Dv MAP_PRIVATE ,
167modifications made by others are not visible.
168On
169.Ox
170this behaves just like
171.Dv MAP_PRIVATE .
172.It Dv MAP_FILE
173Mapped from a regular file, character special file, or block special file
174specified by file descriptor
175.Fa fd .
176On
177.Ox
178and all systems conforming to
179.St -p1003.1-2008
180this is the default mapping type and need not be specified.
181.It Dv MAP_HASSEMAPHORE
182Notify the kernel that the region may contain semaphores and that special
183handling may be necessary.
184On
185.Ox
186this flag is ignored.
187.It Dv MAP_INHERIT
188Permit regions to be inherited across
189.Xr exec 3
190system calls.
191On
192.Ox
193this flag is ignored.
194.It Dv MAP_TRYFIXED
195Attempt to use the hint provided by
196.Fa addr .
197On
198.Ox
199this is the default behavior.
200.El
201.Pp
202The
203.Xr close 2
204function does not unmap pages; see
205.Xr munmap 2
206for further information.
207.Sh RETURN VALUES
208The
209.Fn mmap
210function returns a pointer to the mapped region if successful;
211otherwise the value
212.Dv MAP_FAILED
213is returned and the global variable
214.Va errno
215is set to indicate the error.
216A successful return from
217.Fn mmap
218will never return the value
219.Dv MAP_FAILED .
220.Sh ERRORS
221.Fn mmap
222will fail if:
223.Bl -tag -width Er
224.It Bq Er EACCES
225The flag
226.Dv PROT_READ
227was specified as part of the
228.Fa prot
229parameter and
230.Fa fd
231was not open for reading.
232The flags
233.Dv MAP_SHARED
234and
235.Dv PROT_WRITE
236were specified as part
237of the
238.Fa flags
239and
240.Fa prot
241parameters and
242.Fa fd
243was not open for writing.
244.It Bq Er EBADF
245.Fa fd
246is not a valid open file descriptor.
247.It Bq Er EINVAL
248.Dv MAP_PRIVATE
249and
250.Dv MAP_SHARED
251were both specified.
252.It Bq Er EINVAL
253.Dv MAP_FIXED
254was specified and the
255.Fa addr
256parameter was not page aligned.
257.It Bq Er EINVAL
258.Fa addr
259and
260.Fa len
261specified a region that would extend beyond the end of the address space.
262.It Bq Er EINVAL
263.Fa fd
264did not specify a regular, character special, or block special file.
265.It Bq Er EINVAL
266The allocation
267.Fa len
268was 0.
269.It Bq Er ENOMEM
270.Dv MAP_FIXED
271was specified and the
272.Fa addr
273parameter wasn't available.
274.Dv MAP_ANON
275was specified and insufficient memory was available.
276.It Bq Er ENOTSUP
277The accesses requested in the
278.Ar prot
279argument are not allowed.
280In particular,
281.Dv PROT_WRITE | PROT_EXEC
282mappings are not permitted in most binaries (see
283.Dv kern.wxabort
284in sysctl 3
285for more information).
286.El
287.Sh SEE ALSO
288.Xr madvise 2 ,
289.Xr mincore 2 ,
290.Xr mlock 2 ,
291.Xr mprotect 2 ,
292.Xr mquery 2 ,
293.Xr msync 2 ,
294.Xr munmap 2 ,
295.Xr getpagesize 3
296.Sh STANDARDS
297The
298.Fn mmap
299function conforms to
300.St -p1003.1-2008 .
301.Sh HISTORY
302The
303.Fn mmap
304system call first appeared in
305.Bx 4.1c .
306.Sh CAVEATS
307.St -p1003.1-2008
308specifies that references to pages beyond the end of a mapped object
309shall generate a
310.Dv SIGBUS
311signal; however,
312.Ox
313generates a
314.Dv SIGSEGV
315signal in this case instead.
316.Pp
317Additionally,
318.St -p1003.1-2008
319specifies that
320.Fn mmap
321shall fail with
322.Er EINVAL
323if neither
324.Dv MAP_PRIVATE
325nor
326.Dv MAP_SHARED
327is specified by
328.Fa flags ;
329however, for compatibility with old programs,
330.Ox
331instead defaults to
332.Dv MAP_SHARED
333for mappings of character special files, and to
334.Dv MAP_PRIVATE
335for all other mappings.
336New programs should not rely on this behavior.
337.Sh BUGS
338Due to a limitation of the current vm system (see
339.Xr uvm 9 ) ,
340mapping descriptors
341.Dv PROT_WRITE
342without also specifying
343.Dv PROT_READ
344is useless
345(results in a segmentation fault when first accessing the mapping).
346This means that such descriptors must be opened with
347.Dv O_RDWR ,
348which requires both read and write permissions on the underlying
349object.
350