Fix typos: mininum/minimun -> minimum
[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 $
ab09ab4f 34.\" $DragonFly: src/lib/libc/sys/mmap.2,v 1.5 2006/12/11 20:55:25 dillon Exp $
984263bc
MD
35.\"
36.Dd November 17, 2001
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
239with MADV_SETMAP. Virtual page tables work with anonymous memory but there
240is no way to populate the page table so for all intents and purposes
241.Dv MAP_VPAGETABLE
242can only be used when mapping file descriptors.
243.Pp
244Addressable backing store is limited by the range suppored in the virtual
245page table entries. The kernel may implement a page table abstraction capable
246of addressing a larger range within the backing store then could otherwise
247be mapped into memory.
984263bc
MD
248.El
249.Pp
250The
251.Xr close 2
252function does not unmap pages, see
253.Xr munmap 2
254for further information.
255.Pp
256The current design does not allow a process to specify the location of
257swap space.
258In the future we may define an additional mapping type,
259.Dv MAP_SWAP ,
260in which
261the file descriptor argument specifies a file or device to which swapping
262should be done.
263.Sh RETURN VALUES
264Upon successful completion,
265.Fn mmap
266returns a pointer to the mapped region.
267Otherwise, a value of
268.Dv MAP_FAILED
269is returned and
270.Va errno
271is set to indicate the error.
272.Sh ERRORS
273.Fn Mmap
274will fail if:
275.Bl -tag -width Er
276.It Bq Er EACCES
277The flag
278.Dv PROT_READ
279was specified as part of the
280.Fa prot
281parameter and
282.Fa fd
283was not open for reading.
284The flags
285.Dv MAP_SHARED
286and
287.Dv PROT_WRITE
288were specified as part of the
289.Fa flags
290and
291.Fa prot
292parameters and
293.Fa fd
294was not open for writing.
295.It Bq Er EBADF
296.Fa fd
297is not a valid open file descriptor.
298.It Bq Er EINVAL
299.Dv MAP_FIXED
300was specified and the
301.Fa addr
302parameter was not page aligned, or part of the desired address space
303resides out of the valid address space for a user process.
304.It Bq Er EINVAL
305.Fa Len
306was negative.
307.It Bq Er EINVAL
308.Dv MAP_ANON
309was specified and the
310.Fa fd
311parameter was not -1.
312.It Bq Er EINVAL
313.Dv MAP_ANON
314has not been specified and
315.Fa fd
316did not reference a regular or character special file.
317.It Bq Er EINVAL
318.Fa Offset
319was not page-aligned.
320(See
321.Sx BUGS
322below.)
323.It Bq Er ENOMEM
324.Dv MAP_FIXED
325was specified and the
326.Fa addr
1bf4b486 327parameter wasn't available.
984263bc
MD
328.Dv MAP_ANON
329was specified and insufficient memory was available.
330The system has reached the per-process mmap limit specified in the
331.Va vm.max_proc_mmap
332sysctl.
333.El
334.Sh SEE ALSO
335.Xr madvise 2 ,
336.Xr mincore 2 ,
337.Xr mlock 2 ,
338.Xr mprotect 2 ,
339.Xr msync 2 ,
340.Xr munlock 2 ,
341.Xr munmap 2 ,
342.Xr getpagesize 3
343.Sh BUGS
344.Fa len
345is limited to 2GB. Mmapping slightly more than 2GB doesn't work, but
346it is possible to map a window of size (filesize % 2GB) for file sizes
347of slightly less than 2G, 4GB, 6GB and 8GB.
348.Pp
349The limit is imposed for a variety of reasons.
350Most of them have to do
351with
9bb2a92d 352.Dx
984263bc
MD
353not wanting to use 64 bit offsets in the VM system due to
354the extreme performance penalty.
355So
9bb2a92d 356.Dx
984263bc
MD
357uses 32bit page indexes and
358this gives
9bb2a92d 359.Dx
984263bc
MD
360a maximum of 8TB filesizes.
361It's actually bugs in
362the filesystem code that causes the limit to be further restricted to
3631TB (loss of precision when doing blockno calculations).
364.Pp
365Another reason for the 2GB limit is that filesystem metadata can
366reside at negative offsets.