Do some syncing with reality.
[dragonfly.git] / lib / libc / sys / mmap.2
CommitLineData
984263bc
MD
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: src/lib/libc/sys/mmap.2,v 1.22.2.12 2002/02/27 03:40:13 dd Exp $
4e7c41c5 34.\" $DragonFly: src/lib/libc/sys/mmap.2,v 1.7 2007/01/08 03:33:34 dillon Exp $
984263bc 35.\"
3815fa6d 36.Dd December 11, 2006
984263bc
MD
37.Dt MMAP 2
38.Os
39.Sh NAME
40.Nm mmap
41.Nd allocate memory, or map files or devices into memory
42.Sh LIBRARY
43.Lb libc
44.Sh SYNOPSIS
45.In sys/types.h
46.In sys/mman.h
47.Ft void *
48.Fn mmap "void *addr" "size_t len" "int prot" "int flags" "int fd" "off_t offset"
49.Sh DESCRIPTION
50The
51.Fn mmap
52function causes the pages starting at
53.Fa addr
54and continuing for at most
55.Fa len
56bytes to be mapped from the object described by
57.Fa fd ,
58starting at byte offset
59.Fa offset .
60If
61.Fa len
62is not a multiple of the pagesize, the mapped region may extend past the
63specified range.
64Any such extension beyond the end of the mapped object will be zero-filled.
65.Pp
66If
67.Fa addr
68is non-zero, it is used as a hint to the system.
69(As a convenience to the system, the actual address of the region may differ
70from the address supplied.)
71If
72.Fa addr
73is zero, an address will be selected by the system.
74The actual starting address of the region is returned.
75A successful
76.Fa mmap
77deletes any previous mapping in the allocated address range.
78.Pp
79The protections (region accessibility) are specified in the
80.Fa prot
81argument by
82.Em or Ns 'ing
83the following values:
84.Pp
85.Bl -tag -width PROT_WRITE -compact
86.It Dv PROT_NONE
87Pages may not be accessed.
88.It Dv PROT_READ
89Pages may be read.
90.It Dv PROT_WRITE
91Pages may be written.
92.It Dv PROT_EXEC
93Pages may be executed.
94.El
95.Pp
96The
97.Fa flags
98parameter specifies the type of the mapped object, mapping options and
99whether modifications made to the mapped copy of the page are private
100to the process or are to be shared with other references.
101Sharing, mapping type and options are specified in the
102.Fa flags
103argument by
104.Em or Ns 'ing
105the following values:
106.Bl -tag -width MAP_HASSEMAPHORE
107.It Dv MAP_ANON
108Map anonymous memory not associated with any specific file.
109The file descriptor used for creating
110.Dv MAP_ANON
111must be \-1.
112The
113.Fa offset
114parameter is ignored.
115.\".It Dv MAP_FILE
116.\"Mapped from a regular file or character-special device memory.
117.It Dv MAP_FIXED
118Do not permit the system to select a different address than the one
119specified.
120If the specified address cannot be used,
121.Fn mmap
122will fail.
123If
124.Dv MAP_FIXED
125is specified,
126.Fa addr
127must be a multiple of the pagesize.
128Use of this option is discouraged.
129.It Dv MAP_HASSEMAPHORE
130Notify the kernel that the region may contain semaphores and that special
131handling may be necessary.
132.It Dv MAP_NOCORE
133Region is not included in a core file.
134.It Dv MAP_NOSYNC
135Causes data dirtied via this VM map to be flushed to physical media
136only when necessary (usually by the pager) rather then gratuitously.
137Typically this prevents the update daemons from flushing pages dirtied
138through such maps and thus allows efficient sharing of memory across
139unassociated processes using a file-backed shared memory map. Without
140this option any VM pages you dirty may be flushed to disk every so often
141(every 30-60 seconds usually) which can create performance problems if you
142do not need that to occur (such as when you are using shared file-backed
143mmap regions for IPC purposes). Note that VM/filesystem coherency is
144maintained whether you use
145.Dv MAP_NOSYNC
146or not. This option is not portable
147across
148.Ux
149platforms (yet), though some may implement the same behavior
150by default.
151.Pp
152.Em WARNING !
153Extending a file with
154.Xr ftruncate 2 ,
155thus creating a big hole, and then filling the hole by modifying a shared
156.Fn mmap
157can lead to severe file fragmentation.
158In order to avoid such fragmentation you should always pre-allocate the
159file's backing store by
160.Fn write Ns ing
161zero's into the newly extended area prior to modifying the area via your
162.Fn mmap .
163The fragmentation problem is especially sensitive to
164.Dv MAP_NOSYNC
165pages, because pages may be flushed to disk in a totally random order.
166.Pp
167The same applies when using
168.Dv MAP_NOSYNC
169to implement a file-based shared memory store.
170It is recommended that you create the backing store by
171.Fn write Ns ing
172zero's to the backing file rather then
173.Fn ftruncate Ns ing
174it.
175You can test file fragmentation by observing the KB/t (kilobytes per
176transfer) results from an
177.Dq Li iostat 1
178while reading a large file sequentially, e.g. using
179.Dq Li dd if=filename of=/dev/null bs=32k .
180.Pp
181The
182.Xr fsync 2
183function will flush all dirty data and metadata associated with a file,
184including dirty NOSYNC VM data, to physical media. The
185.Xr sync 8
186command and
187.Xr sync 2
188system call generally do not flush dirty NOSYNC VM data.
189The
190.Xr msync 2
191system call is obsolete since
192.Bx
193implements a coherent filesystem buffer cache. However, it may be
194used to associate dirty VM pages with filesystem buffers and thus cause
195them to be flushed to physical media sooner rather then later.
196.It Dv MAP_PRIVATE
197Modifications are private.
198.It Dv MAP_SHARED
199Modifications are shared.
200.It Dv MAP_STACK
201This option is only available if your system has been compiled with
202.Dv VM_STACK
203defined when compiling the kernel.
204This is the default for
205i386 only.
206Consider adding
207.Li -DVM_STACK
208to
209.Va COPTFLAGS
210in your
211.Pa /etc/make.conf
212to enable this option for other architechures.
213.Dv MAP_STACK
214implies
215.Dv MAP_ANON ,
216and
217.Fa offset
218of 0.
219.Fa fd
220must be -1 and
221.Fa prot
222must include at least
223.Dv PROT_READ
224and
225.Dv PROT_WRITE .
226This option creates
227a memory region that grows to at most
228.Fa len
229bytes in size, starting from the stack top and growing down. The
230stack top is the starting address returned by the call, plus
231.Fa len
232bytes. The bottom of the stack at maximum growth is the starting
233address returned by the call.
ab09ab4f
MD
234.It Dv MAP_VPAGETABLE
235Memory accessed via this map is not linearly mapped and will be governed
236by a virtual page table. The base address of the virtual page table may
237be set using
238.Xr mcontrol 2
3815fa6d
SW
239with
240.Dv MADV_SETMAP .
241Virtual page tables work with anonymous memory but there
ab09ab4f
MD
242is no way to populate the page table so for all intents and purposes
243.Dv MAP_VPAGETABLE
4e7c41c5
MD
244can only be used when mapping file descriptors. Since the kernel will
245update the VPTE_M bit in the virtual page table, the mapping must R+W
246even though actual access to the memory will be properly governed by
247the virtual page table.
ab09ab4f
MD
248.Pp
249Addressable backing store is limited by the range suppored in the virtual
250page table entries. The kernel may implement a page table abstraction capable
251of addressing a larger range within the backing store then could otherwise
252be mapped into memory.
984263bc
MD
253.El
254.Pp
255The
256.Xr close 2
257function does not unmap pages, see
258.Xr munmap 2
259for further information.
260.Pp
261The current design does not allow a process to specify the location of
262swap space.
263In the future we may define an additional mapping type,
264.Dv MAP_SWAP ,
265in which
266the file descriptor argument specifies a file or device to which swapping
267should be done.
268.Sh RETURN VALUES
269Upon successful completion,
270.Fn mmap
271returns a pointer to the mapped region.
272Otherwise, a value of
273.Dv MAP_FAILED
274is returned and
275.Va errno
276is set to indicate the error.
277.Sh ERRORS
278.Fn Mmap
279will fail if:
280.Bl -tag -width Er
281.It Bq Er EACCES
282The flag
283.Dv PROT_READ
284was specified as part of the
285.Fa prot
286parameter and
287.Fa fd
288was not open for reading.
289The flags
290.Dv MAP_SHARED
291and
292.Dv PROT_WRITE
293were specified as part of the
294.Fa flags
295and
296.Fa prot
297parameters and
298.Fa fd
299was not open for writing.
300.It Bq Er EBADF
301.Fa fd
302is not a valid open file descriptor.
303.It Bq Er EINVAL
304.Dv MAP_FIXED
305was specified and the
306.Fa addr
307parameter was not page aligned, or part of the desired address space
308resides out of the valid address space for a user process.
309.It Bq Er EINVAL
310.Fa Len
311was negative.
312.It Bq Er EINVAL
313.Dv MAP_ANON
314was specified and the
315.Fa fd
316parameter was not -1.
317.It Bq Er EINVAL
318.Dv MAP_ANON
319has not been specified and
320.Fa fd
321did not reference a regular or character special file.
322.It Bq Er EINVAL
323.Fa Offset
324was not page-aligned.
325(See
326.Sx BUGS
327below.)
328.It Bq Er ENOMEM
329.Dv MAP_FIXED
330was specified and the
331.Fa addr
1bf4b486 332parameter wasn't available.
984263bc
MD
333.Dv MAP_ANON
334was specified and insufficient memory was available.
335The system has reached the per-process mmap limit specified in the
336.Va vm.max_proc_mmap
337sysctl.
338.El
339.Sh SEE ALSO
340.Xr madvise 2 ,
341.Xr mincore 2 ,
342.Xr mlock 2 ,
343.Xr mprotect 2 ,
344.Xr msync 2 ,
345.Xr munlock 2 ,
346.Xr munmap 2 ,
347.Xr getpagesize 3
348.Sh BUGS
349.Fa len
350is limited to 2GB. Mmapping slightly more than 2GB doesn't work, but
351it is possible to map a window of size (filesize % 2GB) for file sizes
352of slightly less than 2G, 4GB, 6GB and 8GB.
353.Pp
354The limit is imposed for a variety of reasons.
355Most of them have to do
356with
9bb2a92d 357.Dx
984263bc
MD
358not wanting to use 64 bit offsets in the VM system due to
359the extreme performance penalty.
360So
9bb2a92d 361.Dx
984263bc
MD
362uses 32bit page indexes and
363this gives
9bb2a92d 364.Dx
984263bc
MD
365a maximum of 8TB filesizes.
366It's actually bugs in
367the filesystem code that causes the limit to be further restricted to
3681TB (loss of precision when doing blockno calculations).
369.Pp
370Another reason for the 2GB limit is that filesystem metadata can
371reside at negative offsets.