Linux emulation system call update.
[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 $
1de703da 34.\" $DragonFly: src/lib/libc/sys/mmap.2,v 1.2 2003/06/17 04:26:47 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.
234.El
235.Pp
236The
237.Xr close 2
238function does not unmap pages, see
239.Xr munmap 2
240for further information.
241.Pp
242The current design does not allow a process to specify the location of
243swap space.
244In the future we may define an additional mapping type,
245.Dv MAP_SWAP ,
246in which
247the file descriptor argument specifies a file or device to which swapping
248should be done.
249.Sh RETURN VALUES
250Upon successful completion,
251.Fn mmap
252returns a pointer to the mapped region.
253Otherwise, a value of
254.Dv MAP_FAILED
255is returned and
256.Va errno
257is set to indicate the error.
258.Sh ERRORS
259.Fn Mmap
260will fail if:
261.Bl -tag -width Er
262.It Bq Er EACCES
263The flag
264.Dv PROT_READ
265was specified as part of the
266.Fa prot
267parameter and
268.Fa fd
269was not open for reading.
270The flags
271.Dv MAP_SHARED
272and
273.Dv PROT_WRITE
274were specified as part of the
275.Fa flags
276and
277.Fa prot
278parameters and
279.Fa fd
280was not open for writing.
281.It Bq Er EBADF
282.Fa fd
283is not a valid open file descriptor.
284.It Bq Er EINVAL
285.Dv MAP_FIXED
286was specified and the
287.Fa addr
288parameter was not page aligned, or part of the desired address space
289resides out of the valid address space for a user process.
290.It Bq Er EINVAL
291.Fa Len
292was negative.
293.It Bq Er EINVAL
294.Dv MAP_ANON
295was specified and the
296.Fa fd
297parameter was not -1.
298.It Bq Er EINVAL
299.Dv MAP_ANON
300has not been specified and
301.Fa fd
302did not reference a regular or character special file.
303.It Bq Er EINVAL
304.Fa Offset
305was not page-aligned.
306(See
307.Sx BUGS
308below.)
309.It Bq Er ENOMEM
310.Dv MAP_FIXED
311was specified and the
312.Fa addr
313parameter wasn't available.
314.Dv MAP_ANON
315was specified and insufficient memory was available.
316The system has reached the per-process mmap limit specified in the
317.Va vm.max_proc_mmap
318sysctl.
319.El
320.Sh SEE ALSO
321.Xr madvise 2 ,
322.Xr mincore 2 ,
323.Xr mlock 2 ,
324.Xr mprotect 2 ,
325.Xr msync 2 ,
326.Xr munlock 2 ,
327.Xr munmap 2 ,
328.Xr getpagesize 3
329.Sh BUGS
330.Fa len
331is limited to 2GB. Mmapping slightly more than 2GB doesn't work, but
332it is possible to map a window of size (filesize % 2GB) for file sizes
333of slightly less than 2G, 4GB, 6GB and 8GB.
334.Pp
335The limit is imposed for a variety of reasons.
336Most of them have to do
337with
338.Fx
339not wanting to use 64 bit offsets in the VM system due to
340the extreme performance penalty.
341So
342.Fx
343uses 32bit page indexes and
344this gives
345.Fx
346a maximum of 8TB filesizes.
347It's actually bugs in
348the filesystem code that causes the limit to be further restricted to
3491TB (loss of precision when doing blockno calculations).
350.Pp
351Another reason for the 2GB limit is that filesystem metadata can
352reside at negative offsets.