gdb - Local mods (compile)
[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.
dc71b7ab 12.\" 3. Neither the name of the University nor the names of its contributors
984263bc
MD
13.\" may be used to endorse or promote products derived from this software
14.\" without specific prior written permission.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26.\" SUCH DAMAGE.
27.\"
28.\" @(#)mmap.2 8.4 (Berkeley) 5/11/95
29.\" $FreeBSD: src/lib/libc/sys/mmap.2,v 1.22.2.12 2002/02/27 03:40:13 dd Exp $
30.\"
557e0ff6 31.Dd January 18, 2015
984263bc
MD
32.Dt MMAP 2
33.Os
34.Sh NAME
35.Nm mmap
36.Nd allocate memory, or map files or devices into memory
37.Sh LIBRARY
38.Lb libc
39.Sh SYNOPSIS
40.In sys/types.h
41.In 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.Fn mmap
47function causes the pages starting at
48.Fa addr
49and continuing for at most
50.Fa len
51bytes to be mapped from the object described by
52.Fa fd ,
53starting at byte offset
54.Fa offset .
55If
56.Fa len
57is not a multiple of the pagesize, the mapped region may extend past the
58specified range.
59Any such extension beyond the end of the mapped object will be zero-filled.
60.Pp
61If
62.Fa addr
63is non-zero, it is used as a hint to the system.
64(As a convenience to the system, the actual address of the region may differ
65from the address supplied.)
66If
67.Fa addr
68is zero, an address will be selected by the system.
69The actual starting address of the region is returned.
70A successful
71.Fa mmap
72deletes any previous mapping in the allocated address range.
73.Pp
74The protections (region accessibility) are specified in the
75.Fa prot
76argument by
77.Em or Ns 'ing
78the following values:
79.Pp
80.Bl -tag -width PROT_WRITE -compact
81.It Dv PROT_NONE
82Pages may not be accessed.
83.It Dv PROT_READ
84Pages may be read.
85.It Dv PROT_WRITE
86Pages may be written.
87.It Dv PROT_EXEC
88Pages may be executed.
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.Bl -tag -width MAP_HASSEMAPHORE
102.It Dv MAP_ANON
103Map anonymous memory not associated with any specific file.
104The file descriptor used for creating
105.Dv MAP_ANON
106must be \-1.
107The
108.Fa offset
109parameter is ignored.
557e0ff6 110.It Dv MAP_ANONYMOUS
bdf30e21
SW
111This flag is an alias for
112.Dv MAP_ANON
113and is provided for compatibility.
984263bc
MD
114.\".It Dv MAP_FILE
115.\"Mapped from a regular file or character-special device memory.
116.It Dv MAP_FIXED
117Do not permit the system to select a different address than the one
118specified.
c809941b
MD
119If the specified address contains other mappings those mappings will
120be replaced.
121If the specified address cannot otherwise be used,
984263bc
MD
122.Fn mmap
123will fail.
124If
125.Dv MAP_FIXED
126is specified,
127.Fa addr
128must be a multiple of the pagesize.
c809941b
MD
129.It Dv MAP_TRYFIXED
130Try to do a fixed mapping but fail if another mapping already exists in
131the space instead of overwriting the mapping.
132.Pp
133When used with MAP_STACK this flag allows one MAP_STACK mapping to be
134made within another (typically the master user stack), as long as
135no pages have been faulted in the area requested.
984263bc
MD
136.It Dv MAP_HASSEMAPHORE
137Notify the kernel that the region may contain semaphores and that special
138handling may be necessary.
139.It Dv MAP_NOCORE
140Region is not included in a core file.
141.It Dv MAP_NOSYNC
142Causes data dirtied via this VM map to be flushed to physical media
23265324 143only when necessary (usually by the pager) rather than gratuitously.
984263bc
MD
144Typically this prevents the update daemons from flushing pages dirtied
145through such maps and thus allows efficient sharing of memory across
146unassociated processes using a file-backed shared memory map. Without
147this option any VM pages you dirty may be flushed to disk every so often
148(every 30-60 seconds usually) which can create performance problems if you
149do not need that to occur (such as when you are using shared file-backed
150mmap regions for IPC purposes). Note that VM/filesystem coherency is
151maintained whether you use
152.Dv MAP_NOSYNC
153or not. This option is not portable
154across
155.Ux
156platforms (yet), though some may implement the same behavior
157by default.
158.Pp
159.Em WARNING !
160Extending a file with
161.Xr ftruncate 2 ,
162thus creating a big hole, and then filling the hole by modifying a shared
163.Fn mmap
164can lead to severe file fragmentation.
165In order to avoid such fragmentation you should always pre-allocate the
166file's backing store by
167.Fn write Ns ing
168zero's into the newly extended area prior to modifying the area via your
169.Fn mmap .
170The fragmentation problem is especially sensitive to
171.Dv MAP_NOSYNC
172pages, because pages may be flushed to disk in a totally random order.
173.Pp
174The same applies when using
175.Dv MAP_NOSYNC
176to implement a file-based shared memory store.
177It is recommended that you create the backing store by
178.Fn write Ns ing
23265324 179zero's to the backing file rather than
984263bc
MD
180.Fn ftruncate Ns ing
181it.
182You can test file fragmentation by observing the KB/t (kilobytes per
183transfer) results from an
184.Dq Li iostat 1
185while reading a large file sequentially, e.g. using
186.Dq Li dd if=filename of=/dev/null bs=32k .
187.Pp
188The
189.Xr fsync 2
190function will flush all dirty data and metadata associated with a file,
191including dirty NOSYNC VM data, to physical media. The
192.Xr sync 8
193command and
194.Xr sync 2
195system call generally do not flush dirty NOSYNC VM data.
196The
197.Xr msync 2
198system call is obsolete since
199.Bx
200implements a coherent filesystem buffer cache. However, it may be
201used to associate dirty VM pages with filesystem buffers and thus cause
23265324 202them to be flushed to physical media sooner rather than later.
984263bc
MD
203.It Dv MAP_PRIVATE
204Modifications are private.
205.It Dv MAP_SHARED
206Modifications are shared.
207.It Dv MAP_STACK
c809941b
MD
208Map the area as a stack.
209.Dv MAP_ANON
210is implied.
211.Fa Offset
212should be 0,
984263bc 213.Fa fd
c809941b 214must be -1, and
984263bc 215.Fa prot
c809941b 216should include at least
984263bc
MD
217.Dv PROT_READ
218and
219.Dv PROT_WRITE .
220This option creates
221a memory region that grows to at most
222.Fa len
223bytes in size, starting from the stack top and growing down. The
224stack top is the starting address returned by the call, plus
225.Fa len
c809941b
MD
226bytes.
227The bottom of the stack at maximum growth is the starting
984263bc 228address returned by the call.
c809941b
MD
229.Pp
230The entire area is reserved from the point of view of other
4041d919
SW
231.Fn mmap
232calls, even if not faulted in yet.
c809941b
MD
233.Pp
234WARNING. We currently allow
235.Dv MAP_STACK
236mappings to provide a hint that points within an existing
237.Dv MAP_STACK
238mapping's space, and this will succeed as long as no page have been
239faulted in the area specified, but this behavior is no longer supported
240unless you also specify the
241.Dv MAP_TRYFIXED
242flag.
243.Pp
244Note that unless
245.Dv MAP_FIXED
246or
247.Dv MAP_TRYFIXED
248is used, you cannot count on the returned address matching the hint
249you have provided.
ab09ab4f
MD
250.It Dv MAP_VPAGETABLE
251Memory accessed via this map is not linearly mapped and will be governed
252by a virtual page table. The base address of the virtual page table may
253be set using
254.Xr mcontrol 2
3815fa6d
SW
255with
256.Dv MADV_SETMAP .
257Virtual page tables work with anonymous memory but there
ab09ab4f
MD
258is no way to populate the page table so for all intents and purposes
259.Dv MAP_VPAGETABLE
4e7c41c5
MD
260can only be used when mapping file descriptors. Since the kernel will
261update the VPTE_M bit in the virtual page table, the mapping must R+W
262even though actual access to the memory will be properly governed by
263the virtual page table.
ab09ab4f 264.Pp
3f5e28f4 265Addressable backing store is limited by the range supported in the virtual
ab09ab4f
MD
266page table entries. The kernel may implement a page table abstraction capable
267of addressing a larger range within the backing store then could otherwise
268be mapped into memory.
984263bc
MD
269.El
270.Pp
271The
272.Xr close 2
273function does not unmap pages, see
274.Xr munmap 2
275for further information.
276.Pp
277The current design does not allow a process to specify the location of
278swap space.
279In the future we may define an additional mapping type,
280.Dv MAP_SWAP ,
281in which
282the file descriptor argument specifies a file or device to which swapping
283should be done.
284.Sh RETURN VALUES
285Upon successful completion,
286.Fn mmap
287returns a pointer to the mapped region.
288Otherwise, a value of
289.Dv MAP_FAILED
290is returned and
291.Va errno
292is set to indicate the error.
293.Sh ERRORS
294.Fn Mmap
295will fail if:
296.Bl -tag -width Er
297.It Bq Er EACCES
298The flag
299.Dv PROT_READ
300was specified as part of the
301.Fa prot
302parameter and
303.Fa fd
304was not open for reading.
305The flags
306.Dv MAP_SHARED
307and
308.Dv PROT_WRITE
309were specified as part of the
310.Fa flags
311and
312.Fa prot
313parameters and
314.Fa fd
315was not open for writing.
316.It Bq Er EBADF
317.Fa fd
318is not a valid open file descriptor.
319.It Bq Er EINVAL
320.Dv MAP_FIXED
321was specified and the
322.Fa addr
323parameter was not page aligned, or part of the desired address space
324resides out of the valid address space for a user process.
325.It Bq Er EINVAL
326.Fa Len
327was negative.
328.It Bq Er EINVAL
329.Dv MAP_ANON
330was specified and the
331.Fa fd
332parameter was not -1.
333.It Bq Er EINVAL
334.Dv MAP_ANON
335has not been specified and
336.Fa fd
337did not reference a regular or character special file.
338.It Bq Er EINVAL
339.Fa Offset
340was not page-aligned.
341(See
342.Sx BUGS
343below.)
344.It Bq Er ENOMEM
345.Dv MAP_FIXED
346was specified and the
347.Fa addr
1bf4b486 348parameter wasn't available.
984263bc
MD
349.Dv MAP_ANON
350was specified and insufficient memory was available.
351The system has reached the per-process mmap limit specified in the
352.Va vm.max_proc_mmap
353sysctl.
354.El
355.Sh SEE ALSO
356.Xr madvise 2 ,
357.Xr mincore 2 ,
358.Xr mlock 2 ,
359.Xr mprotect 2 ,
360.Xr msync 2 ,
361.Xr munlock 2 ,
362.Xr munmap 2 ,
363.Xr getpagesize 3