1.\" Copyright (c) 1991, 1993
2.\" The Regents of the University of California. All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\" notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\" notice, this list of conditions and the following disclaimer in the
11.\" documentation and/or other materials provided with the distribution.
12.\" 3. All advertising materials mentioning features or use of this software
13.\" must display the following acknowledgement:
14.\" This product includes software developed by the University of
15.\" California, Berkeley and its contributors.
16.\" 4. Neither the name of the University nor the names of its contributors
17.\" may be used to endorse or promote products derived from this software
18.\" without specific prior written permission.
19.\"
20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.\" @(#)mmap.2 8.4 (Berkeley) 5/11/95
| 1.\" Copyright (c) 1991, 1993
2.\" The Regents of the University of California. All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\" notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\" notice, this list of conditions and the following disclaimer in the
11.\" documentation and/or other materials provided with the distribution.
12.\" 3. All advertising materials mentioning features or use of this software
13.\" must display the following acknowledgement:
14.\" This product includes software developed by the University of
15.\" California, Berkeley and its contributors.
16.\" 4. Neither the name of the University nor the names of its contributors
17.\" may be used to endorse or promote products derived from this software
18.\" without specific prior written permission.
19.\"
20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.\" @(#)mmap.2 8.4 (Berkeley) 5/11/95
|
33.\" $FreeBSD: head/lib/libc/sys/mmap.2 57550 2000-02-28 04:10:35Z ps $
| 33.\" $FreeBSD: head/lib/libc/sys/mmap.2 57686 2000-03-02 09:14:21Z sheldonh $
|
34.\"
35.Dd May 11, 1995
36.Dt MMAP 2
37.Os BSD 4
38.Sh NAME
39.Nm mmap
40.Nd map files or devices into memory
41.Sh SYNOPSIS
42.Fd #include <sys/types.h>
43.Fd #include <sys/mman.h>
44.Ft void *
45.Fn mmap "void * addr" "size_t len" "int prot" "int flags" "int fd" "off_t offset"
46.Sh DESCRIPTION
47The
48.Fn mmap
49function causes the pages starting at
50.Fa addr
51and continuing for at most
52.Fa len
53bytes to be mapped from the object described by
54.Fa fd ,
55starting at byte offset
56.Fa offset .
57If
58.Fa len
59is not a multiple of the pagesize, the mapped region may extend past the
60specified range.
61Any such extension beyond the end of the mapped object will be zero-filled.
62.Pp
63If
64.Fa addr
65is non-zero, it is used as a hint to the system.
66(As a convenience to the system, the actual address of the region may differ
67from the address supplied.)
68If
69.Fa addr
70is zero, an address will be selected by the system.
71The actual starting address of the region is returned.
72A successful
73.Fa mmap
74deletes any previous mapping in the allocated address range.
75.Pp
76The protections (region accessibility) are specified in the
77.Fa prot
78argument by
79.Em or Ns 'ing
80the following values:
81.Pp
82.Bl -tag -width MAP_FIXEDX
83.It Dv PROT_EXEC
84Pages may be executed.
85.It Dv PROT_READ
86Pages may be read.
87.It Dv PROT_WRITE
88Pages may be written.
89.El
90.Pp
91The
92.Fa flags
93parameter specifies the type of the mapped object, mapping options and
94whether modifications made to the mapped copy of the page are private
95to the process or are to be shared with other references.
96Sharing, mapping type and options are specified in the
97.Fa flags
98argument by
99.Em or Ns 'ing
100the following values:
101.Pp
102.Bl -tag -width MAP_FIXEDX
103.It Dv MAP_ANON
104Map anonymous memory not associated with any specific file.
105The file descriptor used for creating
106.Dv MAP_ANON
107must be \-1.
108The
109.Fa offset
110parameter is ignored.
111.\".It Dv MAP_FILE
112.\"Mapped from a regular file or character-special device memory.
113.It Dv MAP_FIXED
114Do not permit the system to select a different address than the one
115specified.
116If the specified address cannot be used,
117.Fn mmap
118will fail.
119If MAP_FIXED is specified,
120.Fa addr
121must be a multiple of the pagesize.
122Use of this option is discouraged.
123.It Dv MAP_HASSEMAPHORE
124Notify the kernel that the region may contain semaphores and that special
125handling may be necessary.
126.It Dv MAP_INHERIT
127Permit regions to be inherited across
128.Xr execve 2
129system calls.
130.It Dv MAP_PRIVATE
131Modifications are private.
132.It Dv MAP_SHARED
133Modifications are shared.
134.It Dv MAP_STACK
135This option is only available if your system has been compiled with
| 34.\"
35.Dd May 11, 1995
36.Dt MMAP 2
37.Os BSD 4
38.Sh NAME
39.Nm mmap
40.Nd map files or devices into memory
41.Sh SYNOPSIS
42.Fd #include <sys/types.h>
43.Fd #include <sys/mman.h>
44.Ft void *
45.Fn mmap "void * addr" "size_t len" "int prot" "int flags" "int fd" "off_t offset"
46.Sh DESCRIPTION
47The
48.Fn mmap
49function causes the pages starting at
50.Fa addr
51and continuing for at most
52.Fa len
53bytes to be mapped from the object described by
54.Fa fd ,
55starting at byte offset
56.Fa offset .
57If
58.Fa len
59is not a multiple of the pagesize, the mapped region may extend past the
60specified range.
61Any such extension beyond the end of the mapped object will be zero-filled.
62.Pp
63If
64.Fa addr
65is non-zero, it is used as a hint to the system.
66(As a convenience to the system, the actual address of the region may differ
67from the address supplied.)
68If
69.Fa addr
70is zero, an address will be selected by the system.
71The actual starting address of the region is returned.
72A successful
73.Fa mmap
74deletes any previous mapping in the allocated address range.
75.Pp
76The protections (region accessibility) are specified in the
77.Fa prot
78argument by
79.Em or Ns 'ing
80the following values:
81.Pp
82.Bl -tag -width MAP_FIXEDX
83.It Dv PROT_EXEC
84Pages may be executed.
85.It Dv PROT_READ
86Pages may be read.
87.It Dv PROT_WRITE
88Pages may be written.
89.El
90.Pp
91The
92.Fa flags
93parameter specifies the type of the mapped object, mapping options and
94whether modifications made to the mapped copy of the page are private
95to the process or are to be shared with other references.
96Sharing, mapping type and options are specified in the
97.Fa flags
98argument by
99.Em or Ns 'ing
100the following values:
101.Pp
102.Bl -tag -width MAP_FIXEDX
103.It Dv MAP_ANON
104Map anonymous memory not associated with any specific file.
105The file descriptor used for creating
106.Dv MAP_ANON
107must be \-1.
108The
109.Fa offset
110parameter is ignored.
111.\".It Dv MAP_FILE
112.\"Mapped from a regular file or character-special device memory.
113.It Dv MAP_FIXED
114Do not permit the system to select a different address than the one
115specified.
116If the specified address cannot be used,
117.Fn mmap
118will fail.
119If MAP_FIXED is specified,
120.Fa addr
121must be a multiple of the pagesize.
122Use of this option is discouraged.
123.It Dv MAP_HASSEMAPHORE
124Notify the kernel that the region may contain semaphores and that special
125handling may be necessary.
126.It Dv MAP_INHERIT
127Permit regions to be inherited across
128.Xr execve 2
129system calls.
130.It Dv MAP_PRIVATE
131Modifications are private.
132.It Dv MAP_SHARED
133Modifications are shared.
134.It Dv MAP_STACK
135This option is only available if your system has been compiled with
|
136VM_STACK defined when compiling the kernel. This is the default for
137i386 only. Consider adding -DVM_STACK to COPTFLAGS in your /etc/make.conf
138to enable this option for other architechures. MAP_STACK implies
| 136VM_STACK defined when compiling the kernel.
137This is the default for
138i386 only.
139Consider adding -DVM_STACK to COPTFLAGS in your /etc/make.conf
140to enable this option for other architechures.
141MAP_STACK implies
|
139MAP_ANON, and
140.Fa offset
141of 0.
142.Fa fd
143must be -1 and
144.Fa prot
145must include at least PROT_READ and PROT_WRITE. This option creates
146a memory region that grows to at most
147.Fa len
148bytes in size, starting from the stack top and growing down. The
149stack top is the starting address returned by the call, plus
150.Fa len
151bytes. The bottom of the stack at maximum growth is the starting
152address returned by the call.
153.It Dv MAP_NOSYNC
154Causes data dirtied via this VM map to be flushed to physical media
155only when necessary (usually by the pager) rather then gratuitously.
156Typically this prevents the update daemons from flushing pages dirtied
157through such maps and thus allows efficient sharing of memory across
158unassociated processes using a file-backed shared memory map. Without
159this option any VM pages you dirty may be flushed to disk every so often
160(every 30-60 seconds usually) which can create performance problems if you
161do not need that to occur (such as when you are using shared file-backed
162mmap regions for IPC purposes). Note that VM/filesystem coherency is
163maintained whether you use MAP_NOSYNC or not. This option is not portable
164across UNIX platforms (yet), though some may implement the same behavior
165by default.
166.Pp
167The
168.Xr fsync 2
169function will flush all dirty data and metadata associated with a file,
170including dirty NOSYNC VM data, to physical media. The
171.Xr sync 1
172command and
173.Xr sync 2
174system call generally do not flush dirty NOSYNC VM data.
175The
176.Xr msync 2
177system call is obsolete since
178.Bx
179implements a coherent filesystem buffer cache. However, it may be
180used to associate dirty VM pages with filesystem buffers and thus cause
181them to be flushed to physical media sooner rather then later.
182.It Dv MAP_NOCORE
183Region is not included in a core file.
184.El
185.Pp
186The
187.Xr close 2
188function does not unmap pages, see
189.Xr munmap 2
190for further information.
191.Pp
192The current design does not allow a process to specify the location of
193swap space.
194In the future we may define an additional mapping type,
195.Dv MAP_SWAP ,
196in which
197the file descriptor argument specifies a file or device to which swapping
198should be done.
199.Sh RETURN VALUES
200Upon successful completion,
201.Fn mmap
202returns a pointer to the mapped region.
203Otherwise, a value of MAP_FAILED is returned and
204.Va errno
205is set to indicate the error.
206.Sh ERRORS
207.Fn Mmap
208will fail if:
209.Bl -tag -width Er
210.It Bq Er EACCES
211The flag
212.Dv PROT_READ
213was specified as part of the
214.Fa prot
215parameter and
216.Fa fd
217was not open for reading.
218The flags
219.Dv MAP_SHARED
220and
221.Dv PROT_WRITE
222were specified as part of the
223.Fa flags
224and
225.Fa prot
226parameters and
227.Fa fd
228was not open for writing.
229.It Bq Er EBADF
230.Fa Fd
231is not a valid open file descriptor.
232.It Bq Er EINVAL
233.Dv MAP_FIXED
234was specified and the
235.Fa addr
236parameter was not page aligned, or part of the desired address space
237resides out of the valid address space for a user process.
238.It Bq Er EINVAL
239.Fa Len
240was negative.
241.It Bq Er EINVAL
242.Dv MAP_ANON
243was specified and the
244.Fa fd
245parameter was not -1.
246.It Bq Er EINVAL
247.Dv MAP_ANON
248has not been specified and
249.Fa fd
250did not reference a regular or character special file.
251.It Bq Er EINVAL
252.Fa Offset
253was not page-aligned. (See BUGS below.)
254.It Bq Er ENOMEM
255.Dv MAP_FIXED
256was specified and the
257.Fa addr
258parameter wasn't available, or the system has reached the per-process mmap
259limit specified in the vm.max_proc_mmap sysctl.
260.Dv MAP_ANON
261was specified and insufficient memory was available.
262.Sh "SEE ALSO"
263.Xr madvise 2 ,
264.Xr mincore 2 ,
265.Xr mlock 2 ,
266.Xr mprotect 2 ,
267.Xr msync 2 ,
268.Xr munlock 2 ,
269.Xr munmap 2 ,
270.Xr getpagesize 3
271.Sh BUGS
272.Ar len
273is limited to 2GB. Mmapping slightly more than 2GB doesn't work, but
274it is possible to map a window of size (filesize % 2GB) for file sizes
275of slightly less than 2G, 4GB, 6GB and 8GB.
276.Pp
| 142MAP_ANON, and
143.Fa offset
144of 0.
145.Fa fd
146must be -1 and
147.Fa prot
148must include at least PROT_READ and PROT_WRITE. This option creates
149a memory region that grows to at most
150.Fa len
151bytes in size, starting from the stack top and growing down. The
152stack top is the starting address returned by the call, plus
153.Fa len
154bytes. The bottom of the stack at maximum growth is the starting
155address returned by the call.
156.It Dv MAP_NOSYNC
157Causes data dirtied via this VM map to be flushed to physical media
158only when necessary (usually by the pager) rather then gratuitously.
159Typically this prevents the update daemons from flushing pages dirtied
160through such maps and thus allows efficient sharing of memory across
161unassociated processes using a file-backed shared memory map. Without
162this option any VM pages you dirty may be flushed to disk every so often
163(every 30-60 seconds usually) which can create performance problems if you
164do not need that to occur (such as when you are using shared file-backed
165mmap regions for IPC purposes). Note that VM/filesystem coherency is
166maintained whether you use MAP_NOSYNC or not. This option is not portable
167across UNIX platforms (yet), though some may implement the same behavior
168by default.
169.Pp
170The
171.Xr fsync 2
172function will flush all dirty data and metadata associated with a file,
173including dirty NOSYNC VM data, to physical media. The
174.Xr sync 1
175command and
176.Xr sync 2
177system call generally do not flush dirty NOSYNC VM data.
178The
179.Xr msync 2
180system call is obsolete since
181.Bx
182implements a coherent filesystem buffer cache. However, it may be
183used to associate dirty VM pages with filesystem buffers and thus cause
184them to be flushed to physical media sooner rather then later.
185.It Dv MAP_NOCORE
186Region is not included in a core file.
187.El
188.Pp
189The
190.Xr close 2
191function does not unmap pages, see
192.Xr munmap 2
193for further information.
194.Pp
195The current design does not allow a process to specify the location of
196swap space.
197In the future we may define an additional mapping type,
198.Dv MAP_SWAP ,
199in which
200the file descriptor argument specifies a file or device to which swapping
201should be done.
202.Sh RETURN VALUES
203Upon successful completion,
204.Fn mmap
205returns a pointer to the mapped region.
206Otherwise, a value of MAP_FAILED is returned and
207.Va errno
208is set to indicate the error.
209.Sh ERRORS
210.Fn Mmap
211will fail if:
212.Bl -tag -width Er
213.It Bq Er EACCES
214The flag
215.Dv PROT_READ
216was specified as part of the
217.Fa prot
218parameter and
219.Fa fd
220was not open for reading.
221The flags
222.Dv MAP_SHARED
223and
224.Dv PROT_WRITE
225were specified as part of the
226.Fa flags
227and
228.Fa prot
229parameters and
230.Fa fd
231was not open for writing.
232.It Bq Er EBADF
233.Fa Fd
234is not a valid open file descriptor.
235.It Bq Er EINVAL
236.Dv MAP_FIXED
237was specified and the
238.Fa addr
239parameter was not page aligned, or part of the desired address space
240resides out of the valid address space for a user process.
241.It Bq Er EINVAL
242.Fa Len
243was negative.
244.It Bq Er EINVAL
245.Dv MAP_ANON
246was specified and the
247.Fa fd
248parameter was not -1.
249.It Bq Er EINVAL
250.Dv MAP_ANON
251has not been specified and
252.Fa fd
253did not reference a regular or character special file.
254.It Bq Er EINVAL
255.Fa Offset
256was not page-aligned. (See BUGS below.)
257.It Bq Er ENOMEM
258.Dv MAP_FIXED
259was specified and the
260.Fa addr
261parameter wasn't available, or the system has reached the per-process mmap
262limit specified in the vm.max_proc_mmap sysctl.
263.Dv MAP_ANON
264was specified and insufficient memory was available.
265.Sh "SEE ALSO"
266.Xr madvise 2 ,
267.Xr mincore 2 ,
268.Xr mlock 2 ,
269.Xr mprotect 2 ,
270.Xr msync 2 ,
271.Xr munlock 2 ,
272.Xr munmap 2 ,
273.Xr getpagesize 3
274.Sh BUGS
275.Ar len
276is limited to 2GB. Mmapping slightly more than 2GB doesn't work, but
277it is possible to map a window of size (filesize % 2GB) for file sizes
278of slightly less than 2G, 4GB, 6GB and 8GB.
279.Pp
|
277The limit is imposed for a variety of reasons. Most of them have to do
| 280The limit is imposed for a variety of reasons.
281Most of them have to do
|
278with
279.Tn FreeBSD
280not wanting to use 64 bit offsets in the VM system due to
| 282with
283.Tn FreeBSD
284not wanting to use 64 bit offsets in the VM system due to
|
281the extreme performance penalty. So
| 285the extreme performance penalty.
286So
|
282.Tn FreeBSD
283uses 32bit page indexes and
284this gives
285.Tn FreeBSD
| 287.Tn FreeBSD
288uses 32bit page indexes and
289this gives
290.Tn FreeBSD
|
286a maximum of 8TB filesizes. It's actually bugs in
| 291a maximum of 8TB filesizes.
292It's actually bugs in
|
287the filesystem code that causes the limit to be further restricted to
2881TB (loss of precision when doing blockno calculations).
289.Pp
290Another reason for the 2GB limit is that filesystem metadata can
291reside at negative offsets.
292.Pp
293We currently can only deal with page aligned file offsets.
| 293the filesystem code that causes the limit to be further restricted to
2941TB (loss of precision when doing blockno calculations).
295.Pp
296Another reason for the 2GB limit is that filesystem metadata can
297reside at negative offsets.
298.Pp
299We currently can only deal with page aligned file offsets.
|