]>
Commit | Line | Data |
---|---|---|
c11b1abf | 1 | .\" Copyright (C) 2003, Michael Kerrisk (mtk.manpages@gmail.com) |
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 | |
10d76543 MK |
15 | .\" the use of the information contained herein. The author(s) may not |
16 | .\" have taken the same level of care in the production of this manual, | |
17 | .\" which is licensed free of charge, as they might when working | |
18 | .\" professionally. | |
fea681da MK |
19 | .\" |
20 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
21 | .\" the source, must acknowledge the copyright and authors of this work. | |
22 | .\" | |
c11b1abf | 23 | .\" 2003-12-10 Initial creation, Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da MK |
24 | .\" 2004-10-28 aeb, corrected prototype, prot must be 0 |
25 | .\" | |
14f5ae6d | 26 | .TH REMAP_FILE_PAGES 2 2008-04-22 "Linux" "Linux Programmer's Manual" |
fea681da | 27 | .SH NAME |
fb0e9c48 | 28 | remap_file_pages \- create a nonlinear file mapping |
fea681da | 29 | .SH SYNOPSIS |
e743a184 | 30 | .nf |
b80f966b | 31 | .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" |
fea681da MK |
32 | .B #include <sys/mman.h> |
33 | .sp | |
14f5ae6d | 34 | .BI "int remap_file_pages(void *" addr ", size_t " size ", int " prot , |
e743a184 MK |
35 | .BI " ssize_t " pgoff ", int " flags ); |
36 | .fi | |
fea681da MK |
37 | .SH DESCRIPTION |
38 | The | |
63aa9df0 | 39 | .BR remap_file_pages () |
fb0e9c48 | 40 | system call is used to create a nonlinear mapping, that is, a mapping |
24b74457 | 41 | in which the pages of the file are mapped into a nonsequential order |
fea681da MK |
42 | in memory. |
43 | The advantage of using | |
63aa9df0 | 44 | .BR remap_file_pages () |
fea681da MK |
45 | over using repeated calls to |
46 | .BR mmap (2) | |
47 | is that the former approach does not require the kernel to create | |
48 | additional VMA (Virtual Memory Area) data structures. | |
49 | ||
fb0e9c48 | 50 | To create a nonlinear mapping we perform the following steps: |
218dfacd MK |
51 | .TP 3 |
52 | 1. | |
fea681da | 53 | Use |
0bfa087b | 54 | .BR mmap (2) |
fea681da MK |
55 | to create a mapping (which is initially linear). |
56 | This mapping must be created with the | |
c13182ef | 57 | .B MAP_SHARED |
16fd68e1 | 58 | flag. |
fea681da | 59 | .TP |
218dfacd | 60 | 2. |
fea681da | 61 | Use one or more calls to |
63aa9df0 | 62 | .BR remap_file_pages () |
fea681da MK |
63 | to rearrange the correspondence between the pages of the mapping |
64 | and the pages of the file. | |
65 | It is possible to map the same page of a file | |
66 | into multiple locations within the mapped region. | |
67 | .LP | |
68 | The | |
69 | .I pgoff | |
70 | and | |
71 | .I size | |
72 | arguments specify the region of the file that is to be relocated | |
73 | within the mapping: | |
74 | .I pgoff | |
75 | is a file offset in units of the system page size; | |
76 | .I size | |
77 | is the length of the region in bytes. | |
78 | ||
79 | The | |
14f5ae6d | 80 | .I addr |
fea681da MK |
81 | argument serves two purposes. |
82 | First, it identifies the mapping whose pages we want to rearrange. | |
83 | Thus, | |
14f5ae6d | 84 | .I addr |
fea681da MK |
85 | must be an address that falls within |
86 | a region previously mapped by a call to | |
0bfa087b | 87 | .BR mmap (2). |
fea681da | 88 | Second, |
14f5ae6d | 89 | .I addr |
fea681da MK |
90 | specifies the address at which the file pages |
91 | identified by | |
92 | .I pgoff | |
93 | and | |
94 | .I size | |
95 | will be placed. | |
96 | ||
22b6a68b | 97 | The values specified in |
14f5ae6d | 98 | .I addr |
22b6a68b MK |
99 | and |
100 | .I size | |
101 | should be multiples of the system page size. | |
102 | If they are not, then the kernel rounds | |
c13182ef MK |
103 | .I both |
104 | values | |
22b6a68b MK |
105 | .I down |
106 | to the nearest multiple of the page size. | |
c13182ef MK |
107 | .\" This rounding is weird, and not consistent with the treatment of |
108 | .\" the analogous arguments for munmap()/mprotect() and for mlock(). | |
22b6a68b MK |
109 | .\" MTK, 14 Sep 2005 |
110 | ||
fea681da MK |
111 | The |
112 | .I prot | |
113 | argument must be specified as 0. | |
114 | ||
115 | The | |
116 | .I flags | |
117 | argument has the same meaning as for | |
0bfa087b | 118 | .BR mmap (2), |
c13182ef MK |
119 | but all flags other than |
120 | .B MAP_NONBLOCK | |
16fd68e1 | 121 | are ignored. |
47297adb | 122 | .SH RETURN VALUE |
fea681da | 123 | On success, |
63aa9df0 | 124 | .BR remap_file_pages () |
fea681da MK |
125 | returns 0. |
126 | On error, \-1 is returned, and | |
127 | .I errno | |
128 | is set appropriately. | |
fea681da MK |
129 | .SH ERRORS |
130 | .TP | |
131 | .B EINVAL | |
14f5ae6d | 132 | .I addr |
fea681da | 133 | does not refer to a valid mapping |
c13182ef MK |
134 | created with the |
135 | .B MAP_SHARED | |
16fd68e1 | 136 | flag. |
fea681da MK |
137 | .TP |
138 | .B EINVAL | |
14f5ae6d | 139 | .IR addr , |
fea681da MK |
140 | .IR size , |
141 | .IR prot , | |
142 | or | |
143 | .I pgoff | |
144 | is invalid. | |
145 | .\" And possibly others from vma->vm_ops->populate() | |
a1d5f77c MK |
146 | .SH VERSIONS |
147 | The | |
148 | .BR remap_file_pages () | |
deec2da3 MK |
149 | system call appeared in Linux 2.5.46; |
150 | glibc support was added in version 2.3.3. | |
47297adb | 151 | .SH CONFORMING TO |
fea681da | 152 | The |
63aa9df0 | 153 | .BR remap_file_pages () |
8382f16d | 154 | system call is Linux-specific. |
47297adb | 155 | .SH SEE ALSO |
fea681da MK |
156 | .BR getpagesize (2), |
157 | .BR mmap (2), | |
158 | .BR mmap2 (2), | |
159 | .BR mprotect (2), | |
160 | .BR mremap (2), | |
0a4f8b7b | 161 | .BR msync (2) |