Debian Codegraph @

upstream/debian-unstable/man2/remap_file_pages.2

raw
1 .\" Copyright 2003, Michael Kerrisk <[email protected]>
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH remap_file_pages 2 2026-02-08 "Linux man-pages 6.18"
7 .SH NAME
8 remap_file_pages \- create a nonlinear file mapping
9 .SH LIBRARY
10 Standard C library
11 .RI ( libc ,\~ \-lc )
12 .SH SYNOPSIS
13 .nf
14 .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
15 .B #include <sys/mman.h>
16 .P
17 .BR "[[deprecated]] int remap_file_pages(" "size_t size;"
18 .BI " void " addr [ size "], size_t " size ,
19 .BI " int " prot ", size_t " pgoff ", int " flags );
20 .fi
21 .SH DESCRIPTION
22 .BR Note :
23 .\" commit 33041a0d76d3c3e0aff28ac95a2ffdedf1282dbc
24 .\" http://lwn.net/Articles/597632/
25 this system call was marked as deprecated starting with Linux 3.16.
26 In Linux 4.0, the implementation was replaced
27 .\" commit c8d78c1823f46519473949d33f0d1d33fe21ea16
28 by a slower in-kernel emulation.
29 Those few applications that use this system call should
30 consider migrating to alternatives.
31 This change was made because the kernel code for this system call was complex,
32 and it is believed to be little used or perhaps even completely unused.
33 While it had some use cases in database applications on 32-bit systems,
34 those use cases don't exist on 64-bit systems.
35 .P
36 The
37 .BR remap_file_pages ()
38 system call is used to create a nonlinear mapping, that is, a mapping
39 in which the pages of the file are mapped into a nonsequential order
40 in memory.
41 The advantage of using
42 .BR remap_file_pages ()
43 over using repeated calls to
44 .BR mmap (2)
45 is that the former approach does not require the kernel to create
46 additional VMA (Virtual Memory Area) data structures.
47 .P
48 To create a nonlinear mapping we perform the following steps:
49 .TP 3
50 1.
51 Use
52 .BR mmap (2)
53 to create a mapping (which is initially linear).
54 This mapping must be created with the
55 .B MAP_SHARED
56 flag.
57 .TP
58 2.
59 Use one or more calls to
60 .BR remap_file_pages ()
61 to rearrange the correspondence between the pages of the mapping
62 and the pages of the file.
63 It is possible to map the same page of a file
64 into multiple locations within the mapped region.
65 .P
66 The
67 .I pgoff
68 and
69 .I size
70 arguments specify the region of the file that is to be relocated
71 within the mapping:
72 .I pgoff
73 is a file offset in units of the system page size;
74 .I size
75 is the length of the region in bytes.
76 .P
77 The
78 .I addr
79 argument serves two purposes.
80 First, it identifies the mapping whose pages we want to rearrange.
81 Thus,
82 .I addr
83 must be an address that falls within
84 a region previously mapped by a call to
85 .BR mmap (2).
86 Second,
87 .I addr
88 specifies the address at which the file pages
89 identified by
90 .I pgoff
91 and
92 .I size
93 will be placed.
94 .P
95 The values specified in
96 .I addr
97 and
98 .I size
99 should be multiples of the system page size.
100 If they are not, then the kernel rounds
101 .I both
102 values
103 .I down
104 to the nearest multiple of the page size.
105 .\" This rounding is weird, and not consistent with the treatment of
106 .\" the analogous arguments for munmap()/mprotect() and for mlock().
107 .\" MTK, 14 Sep 2005
108 .P
109 The
110 .I prot
111 argument must be specified as 0.
112 .P
113 The
114 .I flags
115 argument has the same meaning as for
116 .BR mmap (2),
117 but all flags other than
118 .B MAP_NONBLOCK
119 are ignored.
120 .SH RETURN VALUE
121 On success,
122 .BR remap_file_pages ()
123 returns 0.
124 On error, \-1 is returned, and
125 .I errno
126 is set to indicate the error.
127 .SH ERRORS
128 .TP
129 .B EINVAL
130 .I addr
131 does not refer to a valid mapping
132 created with the
133 .B MAP_SHARED
134 flag.
135 .TP
136 .B EINVAL
137 .IR addr ,
138 .IR size ,
139 .IR prot ,
140 or
141 .I pgoff
142 is invalid.
143 .\" And possibly others from vma->vm_ops->populate()
144 .SH STANDARDS
145 Linux.
146 .SH HISTORY
147 Linux 2.5.46,
148 glibc 2.3.3.
149 .SH NOTES
150 Since Linux 2.6.23,
151 .\" commit 3ee6dafc677a68e461a7ddafc94a580ebab80735
152 .BR remap_file_pages ()
153 creates non-linear mappings only
154 on in-memory filesystems such as
155 .BR tmpfs (5),
156 hugetlbfs or ramfs.
157 On filesystems with a backing store,
158 .BR remap_file_pages ()
159 is not much more efficient than using
160 .BR mmap (2)
161 to adjust which parts of the file are mapped to which addresses.
162 .SH SEE ALSO
163 .BR getpagesize (2),
164 .BR mmap (2),
165 .BR mmap2 (2),
166 .BR mprotect (2),
167 .BR mremap (2),
168 .BR msync (2)