]>
Commit | Line | Data |
---|---|---|
305a0578 | 1 | .\" Copyright (C) 2003, Michael Kerrisk (mtk-manpages@gmx.net) |
fea681da MK |
2 | .\" |
3 | .\" Permission is granted to make and distribute verbatim copies of this | |
4 | .\" manual provided the copyright notice and this permission notice are | |
5 | .\" preserved on all copies. | |
6 | .\" | |
7 | .\" Permission is granted to copy and distribute modified versions of this | |
8 | .\" manual under the conditions for verbatim copying, provided that the | |
9 | .\" entire resulting derived work is distributed under the terms of a | |
10 | .\" permission notice identical to this one. | |
11 | .\" | |
12 | .\" Since the Linux kernel and libraries are constantly changing, this | |
13 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
14 | .\" responsibility for errors or omissions, or for damages resulting from | |
15 | .\" the use of the information contained herein. | |
16 | .\" | |
17 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
18 | .\" the source, must acknowledge the copyright and authors of this work. | |
19 | .\" | |
305a0578 | 20 | .\" 2003-12-10 Initial creation, Michael Kerrisk <mtk-manpages@gmx.net> |
fea681da MK |
21 | .\" 2004-10-28 aeb, corrected prototype, prot must be 0 |
22 | .\" | |
23 | .TH REMAP_FILE_PAGES 2 2004-10-28 "Linux 2.6" "Linux Programmer's Manual" | |
24 | .SH NAME | |
25 | remap_file_pages \- create a non-linear file mapping | |
26 | .SH SYNOPSIS | |
27 | .B #include <sys/mman.h> | |
28 | .sp | |
29 | .BI "int remap_file_pages(void *" start ", " | |
30 | .BI "size_t " size ", int " prot ", " | |
31 | .BI "ssize_t " pgoff ", int " flags ); | |
32 | .SH DESCRIPTION | |
33 | The | |
63aa9df0 | 34 | .BR remap_file_pages () |
fea681da MK |
35 | system call is used to create a non-linear mapping, that is, a mapping |
36 | in which the pages of the file are mapped into a non-sequential order | |
37 | in memory. | |
38 | The advantage of using | |
63aa9df0 | 39 | .BR remap_file_pages () |
fea681da MK |
40 | over using repeated calls to |
41 | .BR mmap (2) | |
42 | is that the former approach does not require the kernel to create | |
43 | additional VMA (Virtual Memory Area) data structures. | |
44 | ||
45 | To create a non-linear mapping we perform the following steps: | |
46 | .TP | |
47 | \fB1.\fp | |
48 | Use | |
63aa9df0 | 49 | .BR mmap () |
fea681da MK |
50 | to create a mapping (which is initially linear). |
51 | This mapping must be created with the | |
52 | MAP_SHARED flag. | |
53 | .TP | |
54 | \fB2.\fp | |
55 | Use one or more calls to | |
63aa9df0 | 56 | .BR remap_file_pages () |
fea681da MK |
57 | to rearrange the correspondence between the pages of the mapping |
58 | and the pages of the file. | |
59 | It is possible to map the same page of a file | |
60 | into multiple locations within the mapped region. | |
61 | .LP | |
62 | The | |
63 | .I pgoff | |
64 | and | |
65 | .I size | |
66 | arguments specify the region of the file that is to be relocated | |
67 | within the mapping: | |
68 | .I pgoff | |
69 | is a file offset in units of the system page size; | |
70 | .I size | |
71 | is the length of the region in bytes. | |
72 | ||
73 | The | |
74 | .I start | |
75 | argument serves two purposes. | |
76 | First, it identifies the mapping whose pages we want to rearrange. | |
77 | Thus, | |
78 | .I start | |
79 | must be an address that falls within | |
80 | a region previously mapped by a call to | |
63aa9df0 | 81 | .BR mmap (). |
fea681da MK |
82 | Second, |
83 | .I start | |
84 | specifies the address at which the file pages | |
85 | identified by | |
86 | .I pgoff | |
87 | and | |
88 | .I size | |
89 | will be placed. | |
90 | ||
22b6a68b MK |
91 | The values specified in |
92 | .I start | |
93 | and | |
94 | .I size | |
95 | should be multiples of the system page size. | |
96 | If they are not, then the kernel rounds | |
97 | .I both | |
98 | values | |
99 | .I down | |
100 | to the nearest multiple of the page size. | |
101 | .\" This rounding is weird, and not consistent with the treatment of | |
102 | .\" the analogous arguments for munmap()/mprotect() and for mlock(). | |
103 | .\" MTK, 14 Sep 2005 | |
104 | ||
fea681da MK |
105 | The |
106 | .I prot | |
107 | argument must be specified as 0. | |
108 | ||
109 | The | |
110 | .I flags | |
111 | argument has the same meaning as for | |
63aa9df0 | 112 | .BR mmap (), |
fea681da MK |
113 | but all flags other than MAP_NONBLOCK are ignored. |
114 | .SH "RETURN VALUE" | |
115 | On success, | |
63aa9df0 | 116 | .BR remap_file_pages () |
fea681da MK |
117 | returns 0. |
118 | On error, \-1 is returned, and | |
119 | .I errno | |
120 | is set appropriately. | |
121 | .SH NOTES | |
122 | The | |
63aa9df0 | 123 | .BR remap_file_pages () |
fea681da MK |
124 | system call appeared in Linux 2.5.46. |
125 | .SH ERRORS | |
126 | .TP | |
127 | .B EINVAL | |
128 | .I start | |
129 | does not refer to a valid mapping | |
130 | created with the MAP_SHARED flag. | |
131 | .TP | |
132 | .B EINVAL | |
133 | .IR start , | |
134 | .IR size , | |
135 | .IR prot , | |
136 | or | |
137 | .I pgoff | |
138 | is invalid. | |
139 | .\" And possibly others from vma->vm_ops->populate() | |
140 | .SH "CONFORMING TO" | |
141 | The | |
63aa9df0 | 142 | .BR remap_file_pages () |
fea681da MK |
143 | system call is Linux specific. |
144 | .SH "SEE ALSO" | |
145 | .BR getpagesize (2), | |
146 | .BR mmap (2), | |
147 | .BR mmap2 (2), | |
148 | .BR mprotect (2), | |
149 | .BR mremap (2), | |
150 | .BR msync (2) |