xref: /openbsd/lib/libc/sys/mmap.2 (revision 91f110e0) 
1.\"	$OpenBSD: mmap.2,v 1.43 2014/01/21 03:15:45 schwarze 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: January 21 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.Fd #include <sys/types.h>
41.Fd #include <sys/mman.h>
42.Ft void *
43.Fn mmap "void *addr" "size_t len" "int prot" "int flags" "int fd" "off_t offset"
44.Sh DESCRIPTION
45The
46.Nm mmap
47function causes the contents of
48.Fa fd ,
49starting at
50.Fa offset ,
51to be mapped in memory at the given
52.Fa addr .
53The mapping will extend at least
54.Fa len
55bytes, subject to page alignment restrictions.
56.Pp
57The
58.Fa addr
59argument describes the address where the system should place the mapping.
60If the
61.Dv MAP_FIXED
62flag is specified, the allocation will happen at the specified address,
63replacing any previously established mappings in its range.
64Otherwise, the mapping will be placed at the available spot at
65.Fa addr ;
66failing that it will be placed "close by".
67If
68.Fa addr
69is
70.Dv NULL
71the system can pick any address.
72Except for
73.Dv MAP_FIXED
74mappings, the system will never replace existing mappings.
75.Pp
76The
77.Fa len
78argument describes the minimum amount of bytes the mapping will span.
79Since
80.Nm
81maps pages into memory,
82.Fa len
83may be rounded up to hit a page boundary.
84If
85.Fa len
86is 0, the mapping will fail with
87.Er EINVAL .
88.Pp
89If an
90.Fa fd
91and
92.Fa offset
93are specified, the resulting address may end up not on a page boundary,
94in order to align the page offset in the
95.Fa addr
96to the page offset in
97.Fa offset .
98.Pp
99The protections (region accessibility) are specified in the
100.Fa prot
101argument by OR'ing the following values:
102.Pp
103.Bl -tag -width "PROT_WRITE  " -offset indent -compact
104.It Dv PROT_EXEC
105Pages may be executed.
106.It Dv PROT_READ
107Pages may be read.
108.It Dv PROT_WRITE
109Pages may be written.
110.It Dv PROT_NONE
111No permissions.
112.El
113.Pp
114The
115.Fa flags
116parameter specifies the type of the mapped object, mapping options, and
117whether modifications made to the mapped copy of the page are private
118to the process or are to be shared with other references.
119Sharing, mapping type, and options are specified in the
120.Fa flags
121argument by OR'ing the following values:
122.Bl -tag -width MAP_FIXEDX
123.It Dv MAP_ANON
124Map anonymous memory not associated with any specific file.
125The file descriptor used for creating
126.Dv MAP_ANON
127must currently be \-1 indicating no name is associated with the
128region.
129.It Dv MAP_FILE
130Mapped from a regular file or character-special device memory.
131(This is the default mapping type, and need not be specified.)
132.It Dv MAP_FIXED
133Demand that the mapping is placed at
134.Fa addr ,
135rather than having the system select a location.
136.Fa addr ,
137.Fa len
138and
139.Fa offset
140(in the case of
141.Fa fd
142mappings)
143must be multiples of the page size.
144Existing mappings in the address range will be replaced.
145Use of this option is discouraged.
146.It Dv MAP_HASSEMAPHORE
147Notify the kernel that the region may contain semaphores and that special
148handling may be necessary.
149.It Dv MAP_INHERIT
150Permit regions to be inherited across
151.Xr exec 3
152system calls.
153.It Dv MAP_PRIVATE
154Modifications are private.
155.It Dv MAP_SHARED
156Modifications are shared.
157.It Dv MAP_TRYFIXED
158Attempt to use the hint provided by
159.Fa addr .
160This is the default mapping type and need not be specified.
161Use of
162.Dv MAP_TRYFIXED
163is discouraged, as it is a non-portable extension.
164.It Dv MAP_COPY
165Modifications are private and, unlike
166.Dv MAP_PRIVATE ,
167modifications made by others are not visible.
168This option is deprecated, shouldn't be used and behaves just like
169.Dv MAP_PRIVATE
170in the current implementation.
171.El
172.Pp
173The
174.Xr close 2
175function does not unmap pages; see
176.Xr munmap 2
177for further information.
178.Sh RETURN VALUES
179Upon successful completion,
180.Nm mmap
181returns a pointer to the mapped region.
182Otherwise, a value of
183.Dv MAP_FAILED
184is returned and
185.Va errno
186is set to indicate the error.
187The symbol
188.Dv MAP_FAILED
189is defined in the header
190.In sys/mman.h .
191A successful return from
192.Nm
193will never return the value
194.Dv MAP_FAILED .
195.Sh ERRORS
196.Nm
197will fail if:
198.Bl -tag -width Er
199.It Bq Er EACCES
200The flag
201.Dv PROT_READ
202was specified as part of the
203.Fa prot
204parameter and
205.Fa fd
206was not open for reading.
207The flags
208.Dv MAP_SHARED
209and
210.Dv PROT_WRITE
211were specified as part
212of the
213.Fa flags
214and
215.Fa prot
216parameters and
217.Fa fd
218was not open for writing.
219.It Bq Er EBADF
220.Fa fd
221is not a valid open file descriptor.
222.It Bq Er EINVAL
223.Dv MAP_FIXED
224was specified and the
225.Fa addr
226parameter was not page aligned.
227.It Bq Er EINVAL
228.Fa addr
229and
230.Fa len
231specified a region that would extend beyond the end of the address space.
232.It Bq Er EINVAL
233.Fa fd
234did not reference a regular or character special file.
235.It Bq Er EINVAL
236The allocation
237.Fa len
238was 0.
239.It Bq Er ENOMEM
240.Dv MAP_FIXED
241was specified and the
242.Fa addr
243parameter wasn't available.
244.Dv MAP_ANON
245was specified and insufficient memory was available.
246.El
247.Sh SEE ALSO
248.Xr madvise 2 ,
249.Xr mincore 2 ,
250.Xr mlock 2 ,
251.Xr mprotect 2 ,
252.Xr mquery 2 ,
253.Xr msync 2 ,
254.Xr munmap 2 ,
255.Xr getpagesize 3
256.Sh HISTORY
257The
258.Fn mmap
259system call first appeared in
260.Bx 4.1c .
261.Sh BUGS
262Due to a limitation of the current vm system (see
263.Xr uvm 9 ) ,
264mapping descriptors
265.Dv PROT_WRITE
266without also specifying
267.Dv PROT_READ
268is useless
269(results in a segmentation fault when first accessing the mapping).
270This means that such descriptors must be opened with
271.Dv O_RDWR ,
272which requires both read and write permissions on the underlying
273object.
274