1 # SOME DESCRIPTIVE TITLE
2 # Copyright (C) YEAR Free Software Foundation, Inc.
3 # This file is distributed under the same license as the PACKAGE package.
4 # FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
9 "Project-Id-Version: PACKAGE VERSION\n"
10 "POT-Creation-Date: 2014-04-27 08:03+0900\n"
11 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
12 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
13 "Language-Team: LANGUAGE <LL@li.org>\n"
16 "Content-Type: text/plain; charset=UTF-8\n"
17 "Content-Transfer-Encoding: 8bit\n"
20 #: build/C/man2/alloc_hugepages.2:25
22 msgid "ALLOC_HUGEPAGES"
26 #: build/C/man2/alloc_hugepages.2:25
32 #: build/C/man2/alloc_hugepages.2:25 build/C/man2/cacheflush.2:25 build/C/man2/fallocate.2:11 build/C/man2/madvise.2:35 build/C/man3/mallinfo.3:26 build/C/man3/malloc_stats.3:26 build/C/man3/malloc_trim.3:26 build/C/man3/mallopt.3:26 build/C/man2/mlock.2:26 build/C/man2/mmap.2:40 build/C/man2/mmap2.2:29 build/C/man2/mprotect.2:38 build/C/man2/mremap.2:30 build/C/man2/msync.2:25 build/C/man2/posix_fadvise.2:28 build/C/man2/readahead.2:28 build/C/man2/remap_file_pages.2:28 build/C/man3/shm_open.3:26 build/C/man7/shm_overview.7:27 build/C/man2/shmctl.2:45 build/C/man2/shmget.2:38 build/C/man2/shmop.2:41 build/C/man2/subpage_prot.2:30 build/C/man2/sync_file_range.2:30
38 #: build/C/man2/alloc_hugepages.2:25 build/C/man3/alloca.3:43 build/C/man2/cacheflush.2:25 build/C/man2/fallocate.2:11 build/C/man2/madvise.2:35 build/C/man3/mallinfo.3:26 build/C/man3/malloc_get_state.3:25 build/C/man3/malloc_hook.3:10 build/C/man3/malloc_info.3:25 build/C/man3/malloc_stats.3:26 build/C/man3/malloc_trim.3:26 build/C/man3/malloc_usable_size.3:25 build/C/man3/mallopt.3:26 build/C/man3/mcheck.3:25 build/C/man2/mlock.2:26 build/C/man2/mmap.2:40 build/C/man2/mmap2.2:29 build/C/man2/mprotect.2:38 build/C/man2/mremap.2:30 build/C/man2/msync.2:25 build/C/man3/mtrace.3:25 build/C/man2/posix_fadvise.2:28 build/C/man3/posix_fallocate.3:25 build/C/man3/posix_memalign.3:29 build/C/man2/readahead.2:28 build/C/man2/remap_file_pages.2:28 build/C/man3/shm_open.3:26 build/C/man7/shm_overview.7:27 build/C/man2/shmctl.2:45 build/C/man2/shmget.2:38 build/C/man2/shmop.2:41 build/C/man2/subpage_prot.2:30 build/C/man2/sync_file_range.2:30
40 msgid "Linux Programmer's Manual"
44 #: build/C/man2/alloc_hugepages.2:26 build/C/man3/alloca.3:44 build/C/man2/cacheflush.2:26 build/C/man2/fallocate.2:12 build/C/man2/madvise.2:36 build/C/man3/mallinfo.3:27 build/C/man3/malloc_get_state.3:26 build/C/man3/malloc_hook.3:11 build/C/man3/malloc_info.3:26 build/C/man3/malloc_stats.3:27 build/C/man3/malloc_trim.3:27 build/C/man3/malloc_usable_size.3:26 build/C/man3/mallopt.3:27 build/C/man3/mcheck.3:26 build/C/man2/mlock.2:27 build/C/man2/mmap.2:41 build/C/man2/mmap2.2:30 build/C/man2/mprotect.2:39 build/C/man2/mremap.2:31 build/C/man2/msync.2:26 build/C/man3/mtrace.3:26 build/C/man2/posix_fadvise.2:29 build/C/man3/posix_fallocate.3:26 build/C/man3/posix_memalign.3:30 build/C/man2/readahead.2:29 build/C/man2/remap_file_pages.2:29 build/C/man3/shm_open.3:27 build/C/man7/shm_overview.7:28 build/C/man2/shmctl.2:46 build/C/man2/shmget.2:39 build/C/man2/shmop.2:42 build/C/man2/subpage_prot.2:31 build/C/man2/sync_file_range.2:31
50 #: build/C/man2/alloc_hugepages.2:28
51 msgid "alloc_hugepages, free_hugepages - allocate or free huge pages"
55 #: build/C/man2/alloc_hugepages.2:28 build/C/man3/alloca.3:46 build/C/man2/cacheflush.2:28 build/C/man2/fallocate.2:14 build/C/man2/madvise.2:38 build/C/man3/mallinfo.3:29 build/C/man3/malloc_get_state.3:28 build/C/man3/malloc_hook.3:15 build/C/man3/malloc_info.3:28 build/C/man3/malloc_stats.3:29 build/C/man3/malloc_trim.3:29 build/C/man3/malloc_usable_size.3:28 build/C/man3/mallopt.3:29 build/C/man3/mcheck.3:28 build/C/man2/mlock.2:29 build/C/man2/mmap.2:43 build/C/man2/mmap2.2:32 build/C/man2/mprotect.2:41 build/C/man2/mremap.2:33 build/C/man2/msync.2:28 build/C/man3/mtrace.3:28 build/C/man2/posix_fadvise.2:31 build/C/man3/posix_fallocate.3:28 build/C/man3/posix_memalign.3:32 build/C/man2/readahead.2:31 build/C/man2/remap_file_pages.2:31 build/C/man3/shm_open.3:29 build/C/man2/shmctl.2:48 build/C/man2/shmget.2:41 build/C/man2/shmop.2:44 build/C/man2/subpage_prot.2:33 build/C/man2/sync_file_range.2:33
60 #. asmlinkage unsigned long sys_alloc_hugepages(int key, unsigned long addr,
61 #. unsigned long len, int prot, int flag);
63 #: build/C/man2/alloc_hugepages.2:34
66 "B<void *alloc_hugepages(int >I<key>B<, void *>I<addr>B<, size_t "
68 "B< int >I<prot>B<, int >I<flag>B<);>\n"
71 #. asmlinkage int sys_free_hugepages(unsigned long addr);
73 #: build/C/man2/alloc_hugepages.2:37
75 msgid "B<int free_hugepages(void *>I<addr>B<);>\n"
79 #: build/C/man2/alloc_hugepages.2:38 build/C/man3/alloca.3:50 build/C/man2/cacheflush.2:34 build/C/man2/fallocate.2:22 build/C/man2/madvise.2:50 build/C/man3/mallinfo.3:33 build/C/man3/malloc_get_state.3:36 build/C/man3/malloc_hook.3:33 build/C/man3/malloc_info.3:34 build/C/man3/malloc_stats.3:33 build/C/man3/malloc_trim.3:33 build/C/man3/malloc_usable_size.3:32 build/C/man3/mallopt.3:33 build/C/man3/mcheck.3:40 build/C/man2/mlock.2:39 build/C/man2/mmap.2:54 build/C/man2/mmap2.2:39 build/C/man2/mprotect.2:47 build/C/man2/mremap.2:42 build/C/man2/msync.2:32 build/C/man3/mtrace.3:34 build/C/man2/posix_fadvise.2:50 build/C/man3/posix_fallocate.3:46 build/C/man3/posix_memalign.3:84 build/C/man2/readahead.2:38 build/C/man2/remap_file_pages.2:39 build/C/man3/shm_open.3:41 build/C/man7/shm_overview.7:30 build/C/man2/shmctl.2:56 build/C/man2/shmget.2:49 build/C/man2/shmop.2:53 build/C/man2/subpage_prot.2:41 build/C/man2/sync_file_range.2:41
85 #: build/C/man2/alloc_hugepages.2:49
87 "The system calls B<alloc_hugepages>() and B<free_hugepages>() were "
88 "introduced in Linux 2.5.36 and removed again in 2.5.54. They existed only "
89 "on i386 and ia64 (when built with B<CONFIG_HUGETLB_PAGE>). In Linux 2.4.20 "
90 "the syscall numbers exist, but the calls fail with the error B<ENOSYS>."
94 #: build/C/man2/alloc_hugepages.2:57
96 "On i386 the memory management hardware knows about ordinary pages (4 KiB) "
97 "and huge pages (2 or 4 MiB). Similarly ia64 knows about huge pages of "
98 "several sizes. These system calls serve to map huge pages into the "
99 "process's memory or to free them again. Huge pages are locked into memory, "
100 "and are not swapped."
104 #: build/C/man2/alloc_hugepages.2:66
106 "The I<key> argument is an identifier. When zero the pages are private, and "
107 "not inherited by children. When positive the pages are shared with other "
108 "applications using the same I<key>, and inherited by child processes."
112 #: build/C/man2/alloc_hugepages.2:81
114 "The I<addr> argument of B<free_hugepages>() tells which page is being "
115 "freed: it was the return value of a call to B<alloc_hugepages>(). (The "
116 "memory is first actually freed when all users have released it.) The "
117 "I<addr> argument of B<alloc_hugepages>() is a hint, that the kernel may or "
118 "may not follow. Addresses must be properly aligned."
122 #: build/C/man2/alloc_hugepages.2:86
124 "The I<len> argument is the length of the required segment. It must be a "
125 "multiple of the huge page size."
129 #: build/C/man2/alloc_hugepages.2:94
131 "The I<prot> argument specifies the memory protection of the segment. It is "
132 "one of B<PROT_READ>, B<PROT_WRITE>, B<PROT_EXEC>."
136 #: build/C/man2/alloc_hugepages.2:109
138 "The I<flag> argument is ignored, unless I<key> is positive. In that case, "
139 "if I<flag> is B<IPC_CREAT>, then a new huge page segment is created when "
140 "none with the given key existed. If this flag is not set, then B<ENOENT> is "
141 "returned when no segment with the given key exists."
145 #: build/C/man2/alloc_hugepages.2:109 build/C/man3/alloca.3:60 build/C/man2/cacheflush.2:53 build/C/man2/fallocate.2:183 build/C/man2/madvise.2:268 build/C/man3/malloc_get_state.3:61 build/C/man3/malloc_info.3:48 build/C/man3/malloc_trim.3:51 build/C/man3/malloc_usable_size.3:40 build/C/man3/mallopt.3:379 build/C/man3/mcheck.3:129 build/C/man2/mlock.2:116 build/C/man2/mmap.2:375 build/C/man2/mmap2.2:54 build/C/man2/mprotect.2:78 build/C/man2/mremap.2:127 build/C/man2/msync.2:68 build/C/man2/posix_fadvise.2:87 build/C/man3/posix_fallocate.3:66 build/C/man3/posix_memalign.3:142 build/C/man2/readahead.2:66 build/C/man2/remap_file_pages.2:124 build/C/man3/shm_open.3:171 build/C/man2/shmctl.2:283 build/C/man2/shmget.2:180 build/C/man2/shmop.2:171 build/C/man2/subpage_prot.2:66 build/C/man2/sync_file_range.2:141
151 #: build/C/man2/alloc_hugepages.2:118
153 "On success, B<alloc_hugepages>() returns the allocated virtual address, and "
154 "B<free_hugepages>() returns zero. On error, -1 is returned, and I<errno> "
155 "is set appropriately."
159 #: build/C/man2/alloc_hugepages.2:118 build/C/man2/cacheflush.2:59 build/C/man2/fallocate.2:190 build/C/man2/madvise.2:275 build/C/man3/malloc_info.3:55 build/C/man3/malloc_trim.3:56 build/C/man3/mallopt.3:384 build/C/man2/mlock.2:122 build/C/man2/mmap.2:392 build/C/man2/mmap2.2:61 build/C/man2/mprotect.2:85 build/C/man2/mremap.2:135 build/C/man2/msync.2:73 build/C/man2/posix_fadvise.2:90 build/C/man3/posix_fallocate.3:72 build/C/man3/posix_memalign.3:157 build/C/man2/readahead.2:72 build/C/man2/remap_file_pages.2:131 build/C/man3/shm_open.3:180 build/C/man2/shmctl.2:305 build/C/man2/shmget.2:185 build/C/man2/shmop.2:185 build/C/man2/subpage_prot.2:71 build/C/man2/sync_file_range.2:147
165 #: build/C/man2/alloc_hugepages.2:119 build/C/man2/fallocate.2:271
171 #: build/C/man2/alloc_hugepages.2:122
172 msgid "The system call is not supported on this kernel."
176 #: build/C/man2/alloc_hugepages.2:122
182 #: build/C/man2/alloc_hugepages.2:126
184 "I</proc/sys/vm/nr_hugepages> Number of configured hugetlb pages. This can "
185 "be read and written."
189 #: build/C/man2/alloc_hugepages.2:130
191 "I</proc/meminfo> Gives info on the number of configured hugetlb pages and on "
192 "their size in the three variables HugePages_Total, HugePages_Free, "
197 #: build/C/man2/alloc_hugepages.2:130 build/C/man3/alloca.3:70 build/C/man2/cacheflush.2:75 build/C/man2/fallocate.2:322 build/C/man2/madvise.2:325 build/C/man3/mallinfo.3:110 build/C/man3/malloc_get_state.3:86 build/C/man3/malloc_hook.3:80 build/C/man3/malloc_info.3:63 build/C/man3/malloc_stats.3:55 build/C/man3/malloc_trim.3:60 build/C/man3/malloc_usable_size.3:48 build/C/man3/mallopt.3:392 build/C/man3/mcheck.3:145 build/C/man2/mlock.2:186 build/C/man2/mmap.2:495 build/C/man2/mmap2.2:77 build/C/man2/mprotect.2:113 build/C/man2/mremap.2:185 build/C/man2/msync.2:96 build/C/man3/mtrace.3:78 build/C/man2/posix_fadvise.2:112 build/C/man3/posix_fallocate.3:103 build/C/man3/posix_memalign.3:182 build/C/man2/readahead.2:88 build/C/man2/remap_file_pages.2:153 build/C/man3/shm_open.3:251 build/C/man7/shm_overview.7:101 build/C/man2/shmctl.2:377 build/C/man2/shmget.2:232 build/C/man2/shmop.2:231 build/C/man2/subpage_prot.2:96 build/C/man2/sync_file_range.2:180
199 msgid "CONFORMING TO"
203 #: build/C/man2/alloc_hugepages.2:133
205 "These calls are specific to Linux on Intel processors, and should not be "
206 "used in programs intended to be portable."
210 #: build/C/man2/alloc_hugepages.2:133 build/C/man3/alloca.3:78 build/C/man2/madvise.2:347 build/C/man3/malloc_get_state.3:88 build/C/man3/malloc_hook.3:82 build/C/man3/malloc_info.3:65 build/C/man3/malloc_stats.3:57 build/C/man3/malloc_trim.3:62 build/C/man3/malloc_usable_size.3:50 build/C/man3/mcheck.3:147 build/C/man2/mlock.2:213 build/C/man2/mmap.2:513 build/C/man2/mmap2.2:79 build/C/man2/mprotect.2:122 build/C/man2/mremap.2:191 build/C/man2/msync.2:120 build/C/man3/mtrace.3:80 build/C/man2/posix_fadvise.2:121 build/C/man3/posix_memalign.3:221 build/C/man2/readahead.2:93 build/C/man3/shm_open.3:257 build/C/man7/shm_overview.7:103 build/C/man2/shmctl.2:382 build/C/man2/shmget.2:238 build/C/man2/shmop.2:250 build/C/man2/subpage_prot.2:98 build/C/man2/sync_file_range.2:183
216 #: build/C/man2/alloc_hugepages.2:141
218 "These system calls are gone; they existed only in Linux 2.5.36 through to "
219 "2.5.54. Now the hugetlbfs filesystem can be used instead. Memory backed by "
220 "huge pages (if the CPU supports them) is obtained by using B<mmap>(2) to "
221 "map files in this virtual filesystem."
225 #: build/C/man2/alloc_hugepages.2:145
227 "The maximal number of huge pages can be specified using the B<hugepages=> "
232 #: build/C/man2/alloc_hugepages.2:150 build/C/man3/alloca.3:162 build/C/man2/cacheflush.2:89 build/C/man2/fallocate.2:330 build/C/man2/madvise.2:381 build/C/man3/mallinfo.3:279 build/C/man3/malloc_get_state.3:114 build/C/man3/malloc_hook.3:142 build/C/man3/malloc_info.3:262 build/C/man3/malloc_stats.3:67 build/C/man3/malloc_trim.3:82 build/C/man3/malloc_usable_size.3:64 build/C/man3/mallopt.3:580 build/C/man3/mcheck.3:208 build/C/man2/mlock.2:343 build/C/man2/mmap.2:735 build/C/man2/mmap2.2:101 build/C/man2/mprotect.2:229 build/C/man2/mremap.2:214 build/C/man2/msync.2:151 build/C/man3/mtrace.3:172 build/C/man2/posix_fadvise.2:197 build/C/man3/posix_fallocate.3:133 build/C/man3/posix_memalign.3:277 build/C/man2/readahead.2:113 build/C/man2/remap_file_pages.2:164 build/C/man3/shm_open.3:282 build/C/man7/shm_overview.7:127 build/C/man2/shmctl.2:435 build/C/man2/shmget.2:325 build/C/man2/shmop.2:295 build/C/man2/subpage_prot.2:134 build/C/man2/sync_file_range.2:226
238 #: build/C/man2/alloc_hugepages.2:157 build/C/man3/alloca.3:169 build/C/man2/cacheflush.2:96 build/C/man2/fallocate.2:337 build/C/man2/madvise.2:388 build/C/man3/mallinfo.3:286 build/C/man3/malloc_get_state.3:121 build/C/man3/malloc_hook.3:149 build/C/man3/malloc_info.3:269 build/C/man3/malloc_stats.3:74 build/C/man3/malloc_trim.3:89 build/C/man3/malloc_usable_size.3:71 build/C/man3/mallopt.3:587 build/C/man3/mcheck.3:215 build/C/man2/mlock.2:350 build/C/man2/mmap.2:742 build/C/man2/mmap2.2:108 build/C/man2/mprotect.2:236 build/C/man2/mremap.2:221 build/C/man2/msync.2:158 build/C/man3/mtrace.3:179 build/C/man2/posix_fadvise.2:204 build/C/man3/posix_fallocate.3:140 build/C/man3/posix_memalign.3:284 build/C/man2/readahead.2:120 build/C/man2/remap_file_pages.2:171 build/C/man3/shm_open.3:289 build/C/man7/shm_overview.7:134 build/C/man2/shmctl.2:442 build/C/man2/shmget.2:332 build/C/man2/shmop.2:302 build/C/man2/subpage_prot.2:141 build/C/man2/sync_file_range.2:233
240 "This page is part of release 3.65 of the Linux I<man-pages> project. A "
241 "description of the project, and information about reporting bugs, can be "
242 "found at \\%http://www.kernel.org/doc/man-pages/."
246 #: build/C/man3/alloca.3:43
252 #: build/C/man3/alloca.3:43
258 #: build/C/man3/alloca.3:43 build/C/man3/malloc_get_state.3:25 build/C/man3/malloc_hook.3:10 build/C/man3/malloc_info.3:25 build/C/man3/malloc_usable_size.3:25 build/C/man3/mcheck.3:25 build/C/man3/mtrace.3:25 build/C/man3/posix_fallocate.3:25 build/C/man3/posix_memalign.3:29
264 #: build/C/man3/alloca.3:46
265 msgid "alloca - allocate memory that is automatically freed"
269 #: build/C/man3/alloca.3:48
270 msgid "B<#include E<lt>alloca.hE<gt>>"
274 #: build/C/man3/alloca.3:50
275 msgid "B<void *alloca(size_t >I<size>B<);>"
279 #: build/C/man3/alloca.3:60
281 "The B<alloca>() function allocates I<size> bytes of space in the stack "
282 "frame of the caller. This temporary space is automatically freed when the "
283 "function that called B<alloca>() returns to its caller."
287 #: build/C/man3/alloca.3:65
289 "The B<alloca>() function returns a pointer to the beginning of the "
290 "allocated space. If the allocation causes stack overflow, program behavior "
295 #: build/C/man3/alloca.3:65
301 #: build/C/man3/alloca.3:66
303 msgid "Multithreading (see pthreads(7))"
307 #: build/C/man3/alloca.3:70
308 msgid "The B<alloca>() function is thread-safe."
312 #: build/C/man3/alloca.3:72
313 msgid "This function is not in POSIX.1-2001."
317 #: build/C/man3/alloca.3:78
319 "There is evidence that the B<alloca>() function appeared in 32V, PWB, "
320 "PWB.2, 3BSD, and 4BSD. There is a man page for it in 4.3BSD. Linux uses "
325 #: build/C/man3/alloca.3:93
327 "The B<alloca>() function is machine- and compiler-dependent. For certain "
328 "applications, its use can improve efficiency compared to the use of "
329 "B<malloc>(3) plus B<free>(3). In certain cases, it can also simplify "
330 "memory deallocation in applications that use B<longjmp>(3) or "
331 "B<siglongjmp>(3). Otherwise, its use is discouraged."
335 #: build/C/man3/alloca.3:102
337 "Because the space allocated by B<alloca>() is allocated within the stack "
338 "frame, that space is automatically freed if the function return is jumped "
339 "over by a call to B<longjmp>(3) or B<siglongjmp>(3)."
343 #: build/C/man3/alloca.3:107
344 msgid "Do not attempt to B<free>(3) space allocated by B<alloca>()!"
348 #: build/C/man3/alloca.3:107
350 msgid "Notes on the GNU version"
354 #: build/C/man3/alloca.3:129
356 "Normally, B<gcc>(1) translates calls to B<alloca>() with inlined code. "
357 "This is not done when either the I<-ansi>, I<-std=c89>, I<-std=c99>, or the "
358 "I<-std=c11> option is given B<and> the header I<E<lt>alloca.hE<gt>> is not "
359 "included. Otherwise (without an -ansi or -std=c* option) the glibc version "
360 "of I<E<lt>stdlib.hE<gt>> includes I<E<lt>alloca.hE<gt>> and that contains "
365 #: build/C/man3/alloca.3:134
369 " #define alloca(size) __builtin_alloca (size)\n"
374 #: build/C/man3/alloca.3:137
375 msgid "with messy consequences if one has a private version of this function."
379 #: build/C/man3/alloca.3:141
381 "The fact that the code is inlined means that it is impossible to take the "
382 "address of this function, or to change its behavior by linking with a "
387 #: build/C/man3/alloca.3:145
389 "The inlined code often consists of a single instruction adjusting the stack "
390 "pointer, and does not check for stack overflow. Thus, there is no NULL "
395 #: build/C/man3/alloca.3:145 build/C/man2/cacheflush.2:82 build/C/man3/mallinfo.3:114 build/C/man3/mallopt.3:406 build/C/man2/mlock.2:311 build/C/man2/mmap.2:585 build/C/man3/mtrace.3:102 build/C/man2/posix_fadvise.2:186 build/C/man2/readahead.2:98 build/C/man2/shmget.2:311
401 #: build/C/man3/alloca.3:150
403 "There is no error indication if the stack frame cannot be extended. "
404 "(However, after a failed allocation, the program is likely to receive a "
405 "B<SIGSEGV> signal if it attempts to access the unallocated space.)"
409 #: build/C/man3/alloca.3:158
411 "On many systems B<alloca>() cannot be used inside the list of arguments of "
412 "a function call, because the stack space reserved by B<alloca>() would "
413 "appear on the stack in the middle of the space for the function arguments."
417 #: build/C/man3/alloca.3:158 build/C/man2/fallocate.2:325 build/C/man2/madvise.2:372 build/C/man3/mallinfo.3:270 build/C/man3/malloc_get_state.3:111 build/C/man3/malloc_hook.3:137 build/C/man3/malloc_info.3:256 build/C/man3/malloc_stats.3:61 build/C/man3/malloc_trim.3:78 build/C/man3/malloc_usable_size.3:62 build/C/man3/mallopt.3:566 build/C/man3/mcheck.3:204 build/C/man2/mlock.2:336 build/C/man2/mmap.2:710 build/C/man2/mmap2.2:95 build/C/man2/mprotect.2:226 build/C/man2/mremap.2:199 build/C/man2/msync.2:147 build/C/man3/mtrace.3:167 build/C/man2/posix_fadvise.2:191 build/C/man3/posix_fallocate.3:128 build/C/man3/posix_memalign.3:272 build/C/man2/readahead.2:107 build/C/man2/remap_file_pages.2:157 build/C/man3/shm_open.3:271 build/C/man7/shm_overview.7:114 build/C/man2/shmctl.2:428 build/C/man2/shmget.2:317 build/C/man2/shmop.2:287 build/C/man2/subpage_prot.2:128 build/C/man2/sync_file_range.2:221
423 #: build/C/man3/alloca.3:162
424 msgid "B<brk>(2), B<longjmp>(3), B<malloc>(3)"
428 #: build/C/man2/cacheflush.2:25
434 #: build/C/man2/cacheflush.2:25
440 #: build/C/man2/cacheflush.2:28
441 msgid "cacheflush - flush contents of instruction and/or data cache"
445 #: build/C/man2/cacheflush.2:31
447 msgid "B<#include E<lt>asm/cachectl.hE<gt>>\n"
451 #: build/C/man2/cacheflush.2:33
453 msgid "B<int cacheflush(char *>I<addr>B<, int >I<nbytes>B<, int >I<cache>B<);>\n"
457 #: build/C/man2/cacheflush.2:43
459 "B<cacheflush>() flushes the contents of the indicated cache(s) for the user "
460 "addresses in the range I<addr> to I<(addr+nbytes-1)>. I<cache> may be one "
465 #: build/C/man2/cacheflush.2:43
471 #: build/C/man2/cacheflush.2:46
472 msgid "Flush the instruction cache."
476 #: build/C/man2/cacheflush.2:46
482 #: build/C/man2/cacheflush.2:49
483 msgid "Write back to memory and invalidate the affected valid cache lines."
487 #: build/C/man2/cacheflush.2:49
493 #: build/C/man2/cacheflush.2:53
494 msgid "Same as B<(ICACHE|DCACHE)>."
498 #: build/C/man2/cacheflush.2:59
500 "B<cacheflush>() returns 0 on success or -1 on error. If errors are "
501 "detected, I<errno> will indicate the error."
505 #: build/C/man2/cacheflush.2:60 build/C/man2/mmap2.2:62 build/C/man2/mremap.2:142 build/C/man2/shmctl.2:314 build/C/man2/subpage_prot.2:72
511 #: build/C/man2/cacheflush.2:67
513 "Some or all of the address range I<addr> to I<(addr+nbytes-1)> is not "
518 #: build/C/man2/cacheflush.2:67 build/C/man2/fallocate.2:202 build/C/man2/fallocate.2:214 build/C/man2/fallocate.2:224 build/C/man2/fallocate.2:234 build/C/man2/fallocate.2:241 build/C/man2/madvise.2:282 build/C/man3/malloc_info.3:56 build/C/man2/mlock.2:157 build/C/man2/mlock.2:164 build/C/man2/mlock.2:176 build/C/man2/mmap.2:421 build/C/man2/mmap.2:429 build/C/man2/mmap.2:434 build/C/man2/mmap2.2:65 build/C/man2/mprotect.2:95 build/C/man2/mremap.2:151 build/C/man2/msync.2:80 build/C/man2/posix_fadvise.2:94 build/C/man3/posix_fallocate.3:81 build/C/man3/posix_memalign.3:158 build/C/man2/readahead.2:77 build/C/man2/remap_file_pages.2:132 build/C/man2/remap_file_pages.2:139 build/C/man3/shm_open.3:213 build/C/man2/shmctl.2:328 build/C/man2/shmget.2:199 build/C/man2/shmop.2:200 build/C/man2/shmop.2:223 build/C/man2/subpage_prot.2:77 build/C/man2/sync_file_range.2:152
524 #: build/C/man2/cacheflush.2:75
525 msgid "I<cache> is not one of B<ICACHE>, B<DCACHE>, or B<BCACHE>."
528 #. FIXME This system call was only on MIPS back in 1.2 days, but
529 #. by now it is on a number of other architectures (but not i386).
530 #. Investigate the details and update this page.
531 #. Irix 6.5 appears to have a cacheflush() syscall -- mtk
533 #: build/C/man2/cacheflush.2:82
535 "This Linux-specific system call is available only on MIPS-based systems. It "
536 "should not be used in programs intended to be portable."
540 #: build/C/man2/cacheflush.2:89
542 "The current implementation ignores the I<addr> and I<nbytes> arguments. "
543 "Therefore, the whole cache is always flushed."
547 #: build/C/man2/fallocate.2:11
553 #: build/C/man2/fallocate.2:11 build/C/man2/shmget.2:38
559 #: build/C/man2/fallocate.2:14
560 msgid "fallocate - manipulate file space"
564 #: build/C/man2/fallocate.2:18 build/C/man2/readahead.2:35
567 "B<#define _GNU_SOURCE> /* See feature_test_macros(7) */\n"
568 "B<#include E<lt>fcntl.hE<gt>>\n"
572 #: build/C/man2/fallocate.2:21
575 "B<int fallocate(int >I<fd>B<, int >I<mode>B<, off_t >I<offset>B<, off_t "
580 #: build/C/man2/fallocate.2:27
582 "This is a nonportable, Linux-specific system call. For the portable, "
583 "POSIX.1-specified method of ensuring that space is allocated for a file, see "
584 "B<posix_fallocate>(3)."
588 #: build/C/man2/fallocate.2:37
590 "B<fallocate>() allows the caller to directly manipulate the allocated disk "
591 "space for the file referred to by I<fd> for the byte range starting at "
592 "I<offset> and continuing for I<len> bytes."
596 #: build/C/man2/fallocate.2:42
598 "The I<mode> argument determines the operation to be performed on the given "
599 "range. Details of the supported operations are given in the subsections "
604 #: build/C/man2/fallocate.2:42
606 msgid "Allocating disk space"
610 #: build/C/man2/fallocate.2:65
612 "The default operation (i.e., I<mode> is zero) of B<fallocate>() allocates "
613 "the disk space within the range specified by I<offset> and I<len>. The file "
614 "size (as reported by B<stat>(2)) will be changed if I<offset>+I<len> is "
615 "greater than the file size. Any subregion within the range specified by "
616 "I<offset> and I<len> that did not contain data before the call will be "
617 "initialized to zero. This default behavior closely resembles the behavior "
618 "of the B<posix_fallocate>(3) library function, and is intended as a method "
619 "of optimally implementing that function."
623 #: build/C/man2/fallocate.2:71
625 "After a successful call, subsequent writes into the range specified by "
626 "I<offset> and I<len> are guaranteed not to fail because of lack of disk "
631 #: build/C/man2/fallocate.2:82
633 "If the B<FALLOC_FL_KEEP_SIZE> flag is specified in I<mode>, the behavior of "
634 "the call is similar, but the file size will not be changed even if "
635 "I<offset>+I<len> is greater than the file size. Preallocating zeroed blocks "
636 "beyond the end of the file in this manner is useful for optimizing append "
641 #: build/C/man2/fallocate.2:86
643 "Because allocation is done in block size chunks, B<fallocate>() may "
644 "allocate a larger range of disk space than was specified."
648 #: build/C/man2/fallocate.2:86
650 msgid "Deallocating file space"
654 #: build/C/man2/fallocate.2:101
656 "Specifying the B<FALLOC_FL_PUNCH_HOLE> flag (available since Linux 2.6.38) "
657 "in I<mode> deallocates space (i.e., creates a hole) in the byte range "
658 "starting at I<offset> and continuing for I<len> bytes. Within the specified "
659 "range, partial filesystem blocks are zeroed, and whole filesystem blocks are "
660 "removed from the file. After a successful call, subsequent reads from this "
661 "range will return zeroes."
665 #: build/C/man2/fallocate.2:112
667 "The B<FALLOC_FL_PUNCH_HOLE> flag must be ORed with B<FALLOC_FL_KEEP_SIZE> in "
668 "I<mode>; in other words, even when punching off the end of the file, the "
669 "file size (as reported by B<stat>(2)) does not change."
673 #: build/C/man2/fallocate.2:117
675 "Not all filesystems support B<FALLOC_FL_PUNCH_HOLE>; if a filesystem doesn't "
676 "support the operation, an error is returned. The operation is supported on "
677 "at least the following filesystems"
681 #: build/C/man2/fallocate.2:117 build/C/man2/fallocate.2:119 build/C/man2/fallocate.2:122 build/C/man2/fallocate.2:124 build/C/man2/madvise.2:286 build/C/man2/madvise.2:292 build/C/man2/madvise.2:295 build/C/man2/madvise.2:298 build/C/man2/madvise.2:301 build/C/man3/mallopt.3:235 build/C/man3/mallopt.3:241
687 #: build/C/man2/fallocate.2:119
688 msgid "XFS (since Linux 2.6.38)"
691 #. commit a4bb6b64e39abc0e41ca077725f2a72c868e7622
693 #: build/C/man2/fallocate.2:122
694 msgid "ext4 (since Linux 3.0)"
698 #: build/C/man2/fallocate.2:124
699 msgid "Btrfs (since Linux 3.7)"
702 #. commit 83e4fa9c16e4af7122e31be3eca5d57881d236fe
704 #: build/C/man2/fallocate.2:127
705 msgid "tmpfs (since Linux 3.5)"
709 #: build/C/man2/fallocate.2:127
711 msgid "Collapsing file space"
714 #. commit 00f5e61998dd17f5375d9dfc01331f104b83f841
716 #: build/C/man2/fallocate.2:147
718 "Specifying the B<FALLOC_FL_COLLAPSE_RANGE> flag (available since Linux 3.15) "
719 "in I<mode> removes a byte range from a file, without leaving a hole. The "
720 "byte range to be collapsed starts at I<offset> and continues for I<len> "
721 "bytes. At the completion of the operation, the contents of the file "
722 "starting at the location I<offset+len> will be appended at the location "
723 "I<offset>, and the file will be I<len> bytes smaller."
727 #: build/C/man2/fallocate.2:161
729 "A filesystem may place limitations on the granularity of the operation, in "
730 "order to ensure efficient implementation. Typically, I<offset> and I<len> "
731 "must be a multiple of the filesystem logical block size, which varies "
732 "according to the filesystem type and configuration. If a filesystem has "
733 "such a requirement, B<fallocate>() will fail with the error B<EINVAL> if "
734 "this requirement is violated."
738 #: build/C/man2/fallocate.2:170
740 "If the region specified by I<offset> plus I<len> reaches or passes the end "
741 "of file, an error is returned; instead, use B<ftruncate>(2) to truncate a "
746 #: build/C/man2/fallocate.2:175
748 "No other flags may be specified in I<mode> in conjunction with "
749 "B<FALLOC_FL_COLLAPSE_RANGE>."
752 #. commit 9eb79482a97152930b113b51dff530aba9e28c8e
753 #. commit e1d8fb88a64c1f8094b9f6c3b6d2d9e6719c970d
755 #: build/C/man2/fallocate.2:183
757 "As at Linux 3.15, B<FALLOC_FL_COLLAPSE_RANGE> is supported by ext4 (only for "
758 "extent-based files) and XFS."
762 #: build/C/man2/fallocate.2:190
764 "On success, B<fallocate>() returns zero. On error, -1 is returned and "
765 "I<errno> is set to indicate the error."
769 #: build/C/man2/fallocate.2:191 build/C/man2/madvise.2:279 build/C/man2/mmap.2:415 build/C/man2/posix_fadvise.2:91 build/C/man3/posix_fallocate.3:73 build/C/man2/readahead.2:73 build/C/man2/sync_file_range.2:148
775 #: build/C/man2/fallocate.2:195 build/C/man3/posix_fallocate.3:77
776 msgid "I<fd> is not a valid file descriptor, or is not opened for writing."
780 #: build/C/man2/fallocate.2:195 build/C/man3/posix_fallocate.3:77
786 #: build/C/man2/fallocate.2:199
787 msgid "I<offset>+I<len> exceeds the maximum file size."
791 #: build/C/man2/fallocate.2:199
797 #: build/C/man2/fallocate.2:202
798 msgid "A signal was caught during execution."
802 #: build/C/man2/fallocate.2:214 build/C/man3/posix_fallocate.3:87
803 msgid "I<offset> was less than 0, or I<len> was less than or equal to 0."
807 #: build/C/man2/fallocate.2:224
809 "I<mode> is B<FALLOC_FL_COLLAPSE_RANGE> and the range specified by I<offset> "
810 "plus I<len> reaches or passes the end of the file."
814 #: build/C/man2/fallocate.2:234
816 "I<mode> is B<FALLOC_FL_COLLAPSE_RANGE>, but either I<offset> or I<len> is "
817 "not a multiple of the filesystem block size."
821 #: build/C/man2/fallocate.2:241
823 "mode contains both B<FALLOC_FL_COLLAPSE_RANGE> and other flags; no other "
824 "flags are permitted with B<FALLOC_FL_COLLAPSE_RANGE>."
827 #. There was a inconsistency in 3.15-rc1, that should be resolved so that all
828 #. filesystems use this error for this case. (Tytso says ex4 will change.)
829 #. http://thread.gmane.org/gmane.comp.file-systems.xfs.general/60485/focus=5521
830 #. From: Michael Kerrisk (man-pages <mtk.manpages@...>
831 #. Subject: Re: [PATCH v5 10/10] manpage: update FALLOC_FL_COLLAPSE_RANGE flag in fallocate
832 #. Newsgroups: gmane.linux.man, gmane.linux.file-systems
833 #. Date: 2014-04-17 13:40:05 GMT
835 #: build/C/man2/fallocate.2:256
837 "I<mode> is B<FALLOC_FL_COLLAPSE_RANGE>, but the file referred to by I<fd> is "
838 "not a regular file."
842 #: build/C/man2/fallocate.2:256 build/C/man2/madvise.2:310 build/C/man2/sync_file_range.2:160
848 #: build/C/man2/fallocate.2:259
849 msgid "An I/O error occurred while reading from or writing to a filesystem."
853 #: build/C/man2/fallocate.2:259 build/C/man2/mmap.2:450 build/C/man3/posix_fallocate.3:87
859 #: build/C/man2/fallocate.2:266
861 "I<fd> does not refer to a regular file or a directory. (If I<fd> is a pipe "
862 "or FIFO, a different error results.)"
866 #: build/C/man2/fallocate.2:266 build/C/man3/posix_fallocate.3:91 build/C/man2/shmget.2:217 build/C/man2/sync_file_range.2:166
872 #: build/C/man2/fallocate.2:271 build/C/man3/posix_fallocate.3:96
874 "There is not enough space left on the device containing the file referred to "
879 #: build/C/man2/fallocate.2:275
880 msgid "This kernel does not implement B<fallocate>()."
884 #: build/C/man2/fallocate.2:275
886 msgid "B<EOPNOTSUPP>"
890 #: build/C/man2/fallocate.2:284
892 "The filesystem containing the file referred to by I<fd> does not support "
893 "this operation; or the I<mode> is not supported by the filesystem containing "
894 "the file referred to by I<fd>."
898 #: build/C/man2/fallocate.2:284 build/C/man2/mlock.2:143 build/C/man2/mlock.2:182 build/C/man2/mmap.2:458 build/C/man2/shmctl.2:353 build/C/man2/shmget.2:225
904 #: build/C/man2/fallocate.2:302
906 "The file referred to by I<fd> is marked immutable (see B<chattr>(1)). Or: "
907 "I<mode> specifies B<FALLOC_FL_PUNCH_HOLE> or B<FALLOC_FL_COLLAPSE_RANGE> and "
908 "the file referred to by I<fd> is marked append-only (see B<chattr>(1))."
912 #: build/C/man2/fallocate.2:302 build/C/man2/posix_fadvise.2:97 build/C/man3/posix_fallocate.3:96 build/C/man2/sync_file_range.2:169
918 #: build/C/man2/fallocate.2:306
919 msgid "I<fd> refers to a pipe or FIFO."
923 #: build/C/man2/fallocate.2:306 build/C/man2/mmap.2:467
929 #: build/C/man2/fallocate.2:314
931 "I<mode> specifies B<FALLOC_FL_COLLAPSE_RANGE>, but the file referred to by "
932 "I<fd> is currently being executed."
936 #: build/C/man2/fallocate.2:314 build/C/man3/malloc_info.3:60 build/C/man3/mcheck.3:134 build/C/man2/mmap2.2:74 build/C/man2/posix_fadvise.2:104 build/C/man3/posix_fallocate.3:100 build/C/man3/posix_memalign.3:167 build/C/man2/readahead.2:83 build/C/man2/remap_file_pages.2:148 build/C/man3/shm_open.3:249 build/C/man2/subpage_prot.2:90 build/C/man2/sync_file_range.2:177
941 #. See http://sourceware.org/bugzilla/show_bug.cgi?id=14964
943 #: build/C/man2/fallocate.2:322
945 "B<fallocate>() is available on Linux since kernel 2.6.23. Support is "
946 "provided by glibc since version 2.10. The B<FALLOC_FL_*> flags are defined "
947 "in glibc headers only since version 2.18."
951 #: build/C/man2/fallocate.2:325
952 msgid "B<fallocate>() is Linux-specific."
956 #: build/C/man2/fallocate.2:330
957 msgid "B<fallocate>(1), B<ftruncate>(2), B<posix_fadvise>(3), B<posix_fallocate>(3)"
961 #: build/C/man2/madvise.2:35
967 #: build/C/man2/madvise.2:35 build/C/man2/msync.2:25
973 #: build/C/man2/madvise.2:38
974 msgid "madvise - give advice about use of memory"
978 #: build/C/man2/madvise.2:40 build/C/man2/msync.2:30 build/C/man3/shm_open.3:31
979 msgid "B<#include E<lt>sys/mman.hE<gt>>"
983 #: build/C/man2/madvise.2:42
984 msgid "B<int madvise(void *>I<addr>B<, size_t >I<length>B<, int >I<advice>B<);>"
988 #: build/C/man2/madvise.2:46 build/C/man2/posix_fadvise.2:43 build/C/man3/posix_fallocate.3:39 build/C/man3/posix_memalign.3:49
989 msgid "Feature Test Macro Requirements for glibc (see B<feature_test_macros>(7)):"
993 #: build/C/man2/madvise.2:50
994 msgid "B<madvise>(): _BSD_SOURCE"
998 #: build/C/man2/madvise.2:68
1000 "The B<madvise>() system call advises the kernel about how to handle paging "
1001 "input/output in the address range beginning at address I<addr> and with size "
1002 "I<length> bytes. It allows an application to tell the kernel how it expects "
1003 "to use some mapped or shared memory areas, so that the kernel can choose "
1004 "appropriate read-ahead and caching techniques. This call does not influence "
1005 "the semantics of the application (except in the case of B<MADV_DONTNEED>), "
1006 "but may influence its performance. The kernel is free to ignore the advice."
1010 #: build/C/man2/madvise.2:72
1011 msgid "The advice is indicated in the I<advice> argument which can be"
1015 #: build/C/man2/madvise.2:72
1017 msgid "B<MADV_NORMAL>"
1021 #: build/C/man2/madvise.2:76
1022 msgid "No special treatment. This is the default."
1026 #: build/C/man2/madvise.2:76
1028 msgid "B<MADV_RANDOM>"
1032 #: build/C/man2/madvise.2:80
1034 "Expect page references in random order. (Hence, read ahead may be less "
1035 "useful than normally.)"
1039 #: build/C/man2/madvise.2:80
1041 msgid "B<MADV_SEQUENTIAL>"
1045 #: build/C/man2/madvise.2:85
1047 "Expect page references in sequential order. (Hence, pages in the given "
1048 "range can be aggressively read ahead, and may be freed soon after they are "
1053 #: build/C/man2/madvise.2:85
1055 msgid "B<MADV_WILLNEED>"
1059 #: build/C/man2/madvise.2:89
1061 "Expect access in the near future. (Hence, it might be a good idea to read "
1062 "some pages ahead.)"
1066 #: build/C/man2/madvise.2:89
1068 msgid "B<MADV_DONTNEED>"
1072 #: build/C/man2/madvise.2:100
1074 "Do not expect access in the near future. (For the time being, the "
1075 "application is finished with the given range, so the kernel can free "
1076 "resources associated with it.) Subsequent accesses of pages in this range "
1077 "will succeed, but will result either in reloading of the memory contents "
1078 "from the underlying mapped file (see B<mmap>(2)) or zero-fill-on-demand "
1079 "pages for mappings without an underlying file."
1083 #: build/C/man2/madvise.2:100
1085 msgid "B<MADV_REMOVE> (since Linux 2.6.16)"
1089 #. Databases want to use this feature to drop a section of their
1090 #. bufferpool (shared memory segments) - without writing back to
1091 #. disk/swap space. This feature is also useful for supporting
1092 #. hot-plug memory on UML.
1094 #: build/C/man2/madvise.2:113
1096 "Free up a given range of pages and its associated backing store. Currently, "
1097 "only shmfs/tmpfs supports this; other filesystems return with the error "
1102 #: build/C/man2/madvise.2:113
1104 msgid "B<MADV_DONTFORK> (since Linux 2.6.16)"
1107 #. See http://lwn.net/Articles/171941/
1108 #. [PATCH] madvise MADV_DONTFORK/MADV_DOFORK
1109 #. Currently, copy-on-write may change the physical address of
1110 #. a page even if the user requested that the page is pinned in
1111 #. memory (either by mlock or by get_user_pages). This happens
1112 #. if the process forks meanwhile, and the parent writes to that
1113 #. page. As a result, the page is orphaned: in case of
1114 #. get_user_pages, the application will never see any data hardware
1115 #. DMA's into this page after the COW. In case of mlock'd memory,
1116 #. the parent is not getting the realtime/security benefits of mlock.
1118 #. In particular, this affects the Infiniband modules which do DMA from
1119 #. and into user pages all the time.
1121 #. This patch adds madvise options to control whether memory range is
1122 #. inherited across fork. Useful e.g. for when hardware is doing DMA
1123 #. from/into these pages. Could also be useful to an application
1124 #. wanting to speed up its forks by cutting large areas out of
1127 #. SEE ALSO: http://lwn.net/Articles/171941/
1128 #. "Tweaks to madvise() and posix_fadvise()", 14 Feb 2006
1130 #: build/C/man2/madvise.2:144
1132 "Do not make the pages in this range available to the child after a "
1133 "B<fork>(2). This is useful to prevent copy-on-write semantics from changing "
1134 "the physical location of a page(s) if the parent writes to it after a "
1135 "B<fork>(2). (Such page relocations cause problems for hardware that DMAs "
1136 "into the page(s).)"
1140 #: build/C/man2/madvise.2:144
1142 msgid "B<MADV_DOFORK> (since Linux 2.6.16)"
1146 #: build/C/man2/madvise.2:150
1148 "Undo the effect of B<MADV_DONTFORK>, restoring the default behavior, whereby "
1149 "a mapping is inherited across B<fork>(2)."
1153 #: build/C/man2/madvise.2:150
1155 msgid "B<MADV_HWPOISON> (since Linux 2.6.32)"
1159 #: build/C/man2/madvise.2:162
1161 "Poison a page and handle it like a hardware memory corruption. This "
1162 "operation is available only for privileged (B<CAP_SYS_ADMIN>) processes. "
1163 "This operation may result in the calling process receiving a B<SIGBUS> and "
1164 "the page being unmapped. This feature is intended for testing of memory "
1165 "error-handling code; it is available only if the kernel was configured with "
1166 "B<CONFIG_MEMORY_FAILURE>."
1170 #: build/C/man2/madvise.2:162
1172 msgid "B<MADV_SOFT_OFFLINE> (since Linux 2.6.33)"
1176 #: build/C/man2/madvise.2:180
1178 "Soft offline the pages in the range specified by I<addr> and I<length>. The "
1179 "memory of each page in the specified range is preserved (i.e., when next "
1180 "accessed, the same content will be visible, but in a new physical page "
1181 "frame), and the original page is offlined (i.e., no longer used, and taken "
1182 "out of normal memory management). The effect of the B<MADV_SOFT_OFFLINE> "
1183 "operation is invisible to (i.e., does not change the semantics of) the "
1184 "calling process. This feature is intended for testing of memory "
1185 "error-handling code; it is available only if the kernel was configured with "
1186 "B<CONFIG_MEMORY_FAILURE>."
1190 #: build/C/man2/madvise.2:180
1192 msgid "B<MADV_MERGEABLE> (since Linux 2.6.32)"
1196 #: build/C/man2/madvise.2:205
1198 "Enable Kernel Samepage Merging (KSM) for the pages in the range specified by "
1199 "I<addr> and I<length>. The kernel regularly scans those areas of user "
1200 "memory that have been marked as mergeable, looking for pages with identical "
1201 "content. These are replaced by a single write-protected page (which is "
1202 "automatically copied if a process later wants to update the content of the "
1203 "page). KSM merges only private anonymous pages (see B<mmap>(2)). The KSM "
1204 "feature is intended for applications that generate many instances of the "
1205 "same data (e.g., virtualization systems such as KVM). It can consume a lot "
1206 "of processing power; use with care. See the Linux kernel source file "
1207 "I<Documentation/vm/ksm.txt> for more details. The B<MADV_MERGEABLE> and "
1208 "B<MADV_UNMERGEABLE> operations are available only if the kernel was "
1209 "configured with B<CONFIG_KSM>."
1213 #: build/C/man2/madvise.2:205
1215 msgid "B<MADV_UNMERGEABLE> (since Linux 2.6.32)"
1219 #: build/C/man2/madvise.2:214
1221 "Undo the effect of an earlier B<MADV_MERGEABLE> operation on the specified "
1222 "address range; KSM unmerges whatever pages it had merged in the address "
1223 "range specified by I<addr> and I<length>."
1227 #: build/C/man2/madvise.2:214
1229 msgid "B<MADV_HUGEPAGE> (since Linux 2.6.38)"
1232 #. http://lwn.net/Articles/358904/
1233 #. https://lwn.net/Articles/423584/
1235 #: build/C/man2/madvise.2:243
1237 "Enables Transparent Huge Pages (THP) for pages in the range specified by "
1238 "I<addr> and I<length>. Currently, Transparent Huge Pages work only with "
1239 "private anonymous pages (see B<mmap>(2)). The kernel will regularly scan "
1240 "the areas marked as huge page candidates to replace them with huge pages. "
1241 "The kernel will also allocate huge pages directly when the region is "
1242 "naturally aligned to the huge page size (see B<posix_memalign>(2)). This "
1243 "feature is primarily aimed at applications that use large mappings of data "
1244 "and access large regions of that memory at a time (e.g., virtualization "
1245 "systems such as QEMU). It can very easily waste memory (e.g., a 2MB mapping "
1246 "that only ever accesses 1 byte will result in 2MB of wired memory instead of "
1247 "one 4KB page). See the Linux kernel source file "
1248 "I<Documentation/vm/transhuge.txt> for more details. The B<MADV_HUGEPAGE> "
1249 "and B<MADV_NOHUGEPAGE> operations are available only if the kernel was "
1250 "configured with B<CONFIG_TRANSPARENT_HUGEPAGE>."
1254 #: build/C/man2/madvise.2:243
1256 msgid "B<MADV_NOHUGEPAGE> (since Linux 2.6.38)"
1260 #: build/C/man2/madvise.2:250
1262 "Ensures that memory in the address range specified by I<addr> and I<length> "
1263 "will not be collapsed into huge pages."
1267 #: build/C/man2/madvise.2:250
1269 msgid "B<MADV_DONTDUMP> (since Linux 3.4)"
1273 #: build/C/man2/madvise.2:264
1275 "Exclude from a core dump those pages in the range specified by I<addr> and "
1276 "I<length>. This is useful in applications that have large areas of memory "
1277 "that are known not to be useful in a core dump. The effect of "
1278 "B<MADV_DONTDUMP> takes precedence over the bit mask that is set via the "
1279 "I</proc/PID/coredump_filter> file (see B<core>(5))."
1283 #: build/C/man2/madvise.2:264
1285 msgid "B<MADV_DODUMP> (since Linux 3.4)"
1289 #: build/C/man2/madvise.2:268
1290 msgid "Undo the effect of an earlier B<MADV_DONTDUMP>."
1294 #: build/C/man2/madvise.2:275
1296 "On success B<madvise>() returns zero. On error, it returns -1 and I<errno> "
1297 "is set appropriately."
1301 #: build/C/man2/madvise.2:276 build/C/man2/mlock.2:154 build/C/man2/mmap.2:411 build/C/man2/mremap.2:136
1307 #: build/C/man2/madvise.2:279
1308 msgid "A kernel resource was temporarily unavailable."
1312 #: build/C/man2/madvise.2:282
1313 msgid "The map exists, but the area maps something that isn't a file."
1317 #: build/C/man2/madvise.2:285
1318 msgid "This error can occur for the following reasons:"
1324 #: build/C/man2/madvise.2:292
1325 msgid "The value I<len> is negative."
1329 #: build/C/man2/madvise.2:295
1330 msgid "I<addr> is not page-aligned."
1334 #: build/C/man2/madvise.2:298
1335 msgid "I<advice> is not a valid value"
1339 #: build/C/man2/madvise.2:301
1341 "The application is attempting to release locked or shared pages (with "
1342 "B<MADV_DONTNEED>)."
1346 #: build/C/man2/madvise.2:309
1348 "B<MADV_MERGEABLE> or B<MADV_UNMERGEABLE> was specified in I<advice>, but the "
1349 "kernel was not configured with B<CONFIG_KSM>."
1353 #: build/C/man2/madvise.2:316
1355 "(for B<MADV_WILLNEED>) Paging in this area would exceed the process's "
1356 "maximum resident set size."
1360 #: build/C/man2/madvise.2:316 build/C/man2/madvise.2:321 build/C/man2/mlock.2:123 build/C/man2/mlock.2:131 build/C/man2/mlock.2:169 build/C/man2/mmap.2:454 build/C/man2/mprotect.2:100 build/C/man2/mprotect.2:103 build/C/man2/mremap.2:179 build/C/man2/msync.2:93 build/C/man3/posix_memalign.3:164 build/C/man2/shmctl.2:337 build/C/man2/shmget.2:214 build/C/man2/shmop.2:214 build/C/man2/subpage_prot.2:87 build/C/man2/sync_file_range.2:163
1366 #: build/C/man2/madvise.2:321
1367 msgid "(for B<MADV_WILLNEED>) Not enough memory: paging in failed."
1371 #: build/C/man2/madvise.2:325
1373 "Addresses in the specified range are not currently mapped, or are outside "
1374 "the address space of the process."
1377 #. FIXME . Write a posix_madvise(3) page.
1379 #: build/C/man2/madvise.2:338
1381 "POSIX.1b. POSIX.1-2001 describes B<posix_madvise>(3) with constants "
1382 "B<POSIX_MADV_NORMAL>, B<POSIX_MADV_RANDOM>, and so on, with a behavior close "
1383 "to that described here. There is a similar B<posix_fadvise>(2) for file "
1388 #: build/C/man2/madvise.2:347
1390 "B<MADV_REMOVE>, B<MADV_DONTFORK>, B<MADV_DOFORK>, B<MADV_HWPOISON>, "
1391 "B<MADV_MERGEABLE>, and B<MADV_UNMERGEABLE> are Linux-specific."
1395 #: build/C/man2/madvise.2:348 build/C/man2/mlock.2:274 build/C/man2/shmget.2:305
1401 #: build/C/man2/madvise.2:356
1403 "The current Linux implementation (2.4.0) views this system call more as a "
1404 "command than as advice and hence may return an error when it cannot do what "
1405 "it usually would do in response to this advice. (See the ERRORS description "
1406 "above.) This is nonstandard behavior."
1412 #. function first appeared in 4.4BSD.
1414 #: build/C/man2/madvise.2:372
1416 "The Linux implementation requires that the address I<addr> be page-aligned, "
1417 "and allows I<length> to be zero. If there are some parts of the specified "
1418 "address range that are not mapped, the Linux version of B<madvise>() "
1419 "ignores them and applies the call to the rest (but returns B<ENOMEM> from "
1420 "the system call, as it should)."
1424 #: build/C/man2/madvise.2:381
1426 "B<getrlimit>(2), B<mincore>(2), B<mmap>(2), B<mprotect>(2), B<msync>(2), "
1427 "B<munmap>(2), B<prctl>(2), B<core>(5)"
1431 #: build/C/man3/mallinfo.3:26
1437 #: build/C/man3/mallinfo.3:26 build/C/man3/malloc_stats.3:26
1443 #: build/C/man3/mallinfo.3:29
1444 msgid "mallinfo - obtain memory allocation information"
1448 #: build/C/man3/mallinfo.3:31 build/C/man3/malloc_stats.3:31 build/C/man3/malloc_trim.3:31 build/C/man3/malloc_usable_size.3:30 build/C/man3/mallopt.3:31
1449 msgid "B<#include E<lt>malloc.hE<gt>>"
1453 #: build/C/man3/mallinfo.3:33
1454 msgid "B<struct mallinfo mallinfo(void);>"
1458 #: build/C/man3/mallinfo.3:41
1460 "The B<mallinfo>() function returns a copy of a structure containing "
1461 "information about memory allocations performed by B<malloc>(3) and related "
1462 "functions. This structure is defined as follows:"
1466 #: build/C/man3/mallinfo.3:56
1469 "struct mallinfo {\n"
1470 " int arena; /* Non-mmapped space allocated (bytes) */\n"
1471 " int ordblks; /* Number of free chunks */\n"
1472 " int smblks; /* Number of free fastbin blocks */\n"
1473 " int hblks; /* Number of mmapped regions */\n"
1474 " int hblkhd; /* Space allocated in mmapped regions (bytes) */\n"
1475 " int usmblks; /* Maximum total allocated space (bytes) */\n"
1476 " int fsmblks; /* Space in freed fastbin blocks (bytes) */\n"
1477 " int uordblks; /* Total allocated space (bytes) */\n"
1478 " int fordblks; /* Total free space (bytes) */\n"
1479 " int keepcost; /* Top-most, releasable space (bytes) */\n"
1484 #: build/C/man3/mallinfo.3:62
1485 msgid "The fields of the I<mallinfo> structure contain the following information:"
1489 #: build/C/man3/mallinfo.3:62
1495 #: build/C/man3/mallinfo.3:68
1497 "The total amount of memory allocated by means other than B<mmap>(2) (i.e., "
1498 "memory allocated on the heap). This figure includes both in-use blocks and "
1499 "blocks on the free list."
1503 #: build/C/man3/mallinfo.3:68
1509 #: build/C/man3/mallinfo.3:71
1510 msgid "The number of ordinary (i.e., non-fastbin) free blocks."
1514 #: build/C/man3/mallinfo.3:71
1520 #: build/C/man3/mallinfo.3:75
1521 msgid "The number of fastbin free blocks (see B<mallopt>(3))."
1525 #: build/C/man3/mallinfo.3:75
1531 #: build/C/man3/mallinfo.3:83
1533 "The number of blocks currently allocated using B<mmap>(2). (See the "
1534 "discussion of B<M_MMAP_THRESHOLD> in B<mallopt>(3).)"
1538 #: build/C/man3/mallinfo.3:83
1544 #: build/C/man3/mallinfo.3:87
1545 msgid "The number of bytes in blocks currently allocated using B<mmap>(2)."
1549 #: build/C/man3/mallinfo.3:87
1555 #: build/C/man3/mallinfo.3:92
1557 "The \"highwater mark\" for allocated space\\(emthat is, the maximum amount "
1558 "of space that was ever allocated. This field is maintained only in "
1559 "nonthreading environments."
1563 #: build/C/man3/mallinfo.3:92
1569 #: build/C/man3/mallinfo.3:95
1570 msgid "The total number of bytes in fastbin free blocks."
1574 #: build/C/man3/mallinfo.3:95
1580 #: build/C/man3/mallinfo.3:98
1581 msgid "The total number of bytes used by in-use allocations."
1585 #: build/C/man3/mallinfo.3:98
1591 #: build/C/man3/mallinfo.3:101
1592 msgid "The total number of bytes in free blocks."
1596 #: build/C/man3/mallinfo.3:101
1602 #. Available already in glibc 2.0, possibly earlier
1604 #: build/C/man3/mallinfo.3:110
1606 "The total amount of releasable free space at the top of the heap. This is "
1607 "the maximum number of bytes that could ideally (i.e., ignoring page "
1608 "alignment restrictions, and so on) be released by B<malloc_trim>(3)."
1612 #: build/C/man3/mallinfo.3:114
1614 "This function is not specified by POSIX or the C standards. A similar "
1615 "function exists on many System V derivatives, and was specified in the SVID."
1618 #. FIXME http://sourceware.org/bugzilla/show_bug.cgi?id=208
1619 #. See the 24 Aug 2011 mail by Paul Pluzhnikov:
1620 #. "[patch] Fix mallinfo() to accumulate results for all arenas"
1621 #. on libc-alpha@sourceware.org
1623 #: build/C/man3/mallinfo.3:126
1625 "B<Information is returned for only the main memory allocation area.> "
1626 "Allocations in other arenas are excluded. See B<malloc_stats>(3) and "
1627 "B<malloc_info>(3) for alternatives that include information about other "
1632 #: build/C/man3/mallinfo.3:134
1634 "The fields of the I<mallinfo> structure are typed as I<int>. However, "
1635 "because some internal bookkeeping values may be of type I<long>, the "
1636 "reported values may wrap around zero and thus be inaccurate."
1640 #: build/C/man3/mallinfo.3:134 build/C/man3/malloc_hook.3:89 build/C/man3/malloc_info.3:84 build/C/man3/mallopt.3:466 build/C/man3/mcheck.3:159 build/C/man2/mmap.2:628 build/C/man2/mprotect.2:148 build/C/man3/mtrace.3:108
1646 #: build/C/man3/mallinfo.3:140
1648 "The program below employs B<mallinfo>() to retrieve memory allocation "
1649 "statistics before and after allocating and freeing some blocks of memory. "
1650 "The statistics are displayed on standard output."
1654 #: build/C/man3/mallinfo.3:144
1656 "The first two command-line arguments specify the number and size of blocks "
1657 "to be allocated with B<malloc>(3)."
1661 #: build/C/man3/mallinfo.3:158
1663 "The remaining three arguments specify which of the allocated blocks should "
1664 "be freed with B<free>(3). These three arguments are optional, and specify "
1665 "(in order): the step size to be used in the loop that frees blocks (the "
1666 "default is 1, meaning free all blocks in the range); the ordinal position of "
1667 "the first block to be freed (default 0, meaning the first allocated block); "
1668 "and a number one greater than the ordinal position of the last block to be "
1669 "freed (default is one greater than the maximum block number). If these "
1670 "three arguments are omitted, then the defaults cause all allocated blocks to "
1675 #: build/C/man3/mallinfo.3:162
1677 "In the following example run of the program, 1000 allocations of 100 bytes "
1678 "are performed, and then every second allocated block is freed:"
1682 #: build/C/man3/mallinfo.3:177
1685 "$ B<./a.out 1000 100 2>\n"
1686 "============== Before allocating blocks ==============\n"
1687 "Total non-mmapped bytes (arena): 0\n"
1688 "# of free chunks (ordblks): 1\n"
1689 "# of free fastbin blocks (smblks): 0\n"
1690 "# of mapped regions (hblks): 0\n"
1691 "Bytes in mapped regions (hblkhd): 0\n"
1692 "Max. total allocated space (usmblks): 0\n"
1693 "Free bytes held in fastbins (fsmblks): 0\n"
1694 "Total allocated space (uordblks): 0\n"
1695 "Total free space (fordblks): 0\n"
1696 "Topmost releasable block (keepcost): 0\n"
1700 #: build/C/man3/mallinfo.3:189
1703 "============== After allocating blocks ==============\n"
1704 "Total non-mmapped bytes (arena): 135168\n"
1705 "# of free chunks (ordblks): 1\n"
1706 "# of free fastbin blocks (smblks): 0\n"
1707 "# of mapped regions (hblks): 0\n"
1708 "Bytes in mapped regions (hblkhd): 0\n"
1709 "Max. total allocated space (usmblks): 0\n"
1710 "Free bytes held in fastbins (fsmblks): 0\n"
1711 "Total allocated space (uordblks): 104000\n"
1712 "Total free space (fordblks): 31168\n"
1713 "Topmost releasable block (keepcost): 31168\n"
1717 #: build/C/man3/mallinfo.3:201
1720 "============== After freeing blocks ==============\n"
1721 "Total non-mmapped bytes (arena): 135168\n"
1722 "# of free chunks (ordblks): 501\n"
1723 "# of free fastbin blocks (smblks): 0\n"
1724 "# of mapped regions (hblks): 0\n"
1725 "Bytes in mapped regions (hblkhd): 0\n"
1726 "Max. total allocated space (usmblks): 0\n"
1727 "Free bytes held in fastbins (fsmblks): 0\n"
1728 "Total allocated space (uordblks): 52000\n"
1729 "Total free space (fordblks): 83168\n"
1730 "Topmost releasable block (keepcost): 31168\n"
1734 #: build/C/man3/mallinfo.3:203 build/C/man3/malloc_info.3:167 build/C/man3/mallopt.3:532 build/C/man3/mcheck.3:176 build/C/man2/mmap.2:640 build/C/man2/mprotect.2:165
1736 msgid "Program source"
1740 #: build/C/man3/mallinfo.3:208
1743 "#include E<lt>malloc.hE<gt>\n"
1744 "#include \"tlpi_hdr.h\"\n"
1748 #: build/C/man3/mallinfo.3:213
1752 "display_mallinfo(void)\n"
1754 " struct mallinfo mi;\n"
1758 #: build/C/man3/mallinfo.3:215
1760 msgid " mi = mallinfo();\n"
1764 #: build/C/man3/mallinfo.3:227
1767 " printf(\"Total non-mmapped bytes (arena): %d\\en\", mi.arena);\n"
1768 " printf(\"# of free chunks (ordblks): %d\\en\", mi.ordblks);\n"
1769 " printf(\"# of free fastbin blocks (smblks): %d\\en\", mi.smblks);\n"
1770 " printf(\"# of mapped regions (hblks): %d\\en\", mi.hblks);\n"
1771 " printf(\"Bytes in mapped regions (hblkhd): %d\\en\", mi.hblkhd);\n"
1772 " printf(\"Max. total allocated space (usmblks): %d\\en\", mi.usmblks);\n"
1773 " printf(\"Free bytes held in fastbins (fsmblks): %d\\en\", mi.fsmblks);\n"
1774 " printf(\"Total allocated space (uordblks): %d\\en\", "
1776 " printf(\"Total free space (fordblks): %d\\en\", "
1778 " printf(\"Topmost releasable block (keepcost): %d\\en\", "
1784 #: build/C/man3/mallinfo.3:235
1788 "main(int argc, char *argv[])\n"
1790 "#define MAX_ALLOCS 2000000\n"
1791 " char *alloc[MAX_ALLOCS];\n"
1792 " int numBlocks, j, freeBegin, freeEnd, freeStep;\n"
1793 " size_t blockSize;\n"
1797 #: build/C/man3/mallinfo.3:239
1800 " if (argc E<lt> 3 || strcmp(argv[1], \"--help\") == 0)\n"
1801 " usageErr(\"%s num-blocks block-size [free-step [start-free \"\n"
1802 " \"[end-free]]]\\en\", argv[0]);\n"
1806 #: build/C/man3/mallinfo.3:245
1809 " numBlocks = atoi(argv[1]);\n"
1810 " blockSize = atoi(argv[2]);\n"
1811 " freeStep = (argc E<gt> 3) ? atoi(argv[3]) : 1;\n"
1812 " freeBegin = (argc E<gt> 4) ? atoi(argv[4]) : 0;\n"
1813 " freeEnd = (argc E<gt> 5) ? atoi(argv[5]) : numBlocks;\n"
1817 #: build/C/man3/mallinfo.3:248
1820 " printf(\"============== Before allocating blocks "
1821 "==============\\en\");\n"
1822 " display_mallinfo();\n"
1826 #: build/C/man3/mallinfo.3:252
1829 " for (j = 0; j E<lt> numBlocks; j++) {\n"
1830 " if (numBlocks E<gt>= MAX_ALLOCS)\n"
1831 " fatal(\"Too many allocations\");\n"
1835 #: build/C/man3/mallinfo.3:257
1838 " alloc[j] = malloc(blockSize);\n"
1839 " if (alloc[j] == NULL)\n"
1840 " errExit(\"malloc\");\n"
1845 #: build/C/man3/mallinfo.3:260
1848 " printf(\"\\en============== After allocating blocks "
1849 "==============\\en\");\n"
1850 " display_mallinfo();\n"
1854 #: build/C/man3/mallinfo.3:263
1857 " for (j = freeBegin; j E<lt> freeEnd; j += freeStep)\n"
1858 " free(alloc[j]);\n"
1862 #: build/C/man3/mallinfo.3:266
1865 " printf(\"\\en============== After freeing blocks "
1866 "==============\\en\");\n"
1867 " display_mallinfo();\n"
1871 #: build/C/man3/mallinfo.3:269 build/C/man3/malloc_info.3:255 build/C/man3/mallopt.3:565 build/C/man3/mcheck.3:203 build/C/man2/mmap.2:709
1874 " exit(EXIT_SUCCESS);\n"
1879 #: build/C/man3/mallinfo.3:279
1881 "B<mmap>(2), B<malloc>(3), B<malloc_info>(3), B<malloc_stats>(3), "
1882 "B<malloc_trim>(3), B<mallopt>(3)"
1886 #: build/C/man3/malloc_get_state.3:25
1888 msgid "MALLOC_GET_STATE"
1892 #: build/C/man3/malloc_get_state.3:25
1898 #: build/C/man3/malloc_get_state.3:28
1900 "malloc_get_state, malloc_set_state - record and restore state of malloc "
1905 #: build/C/man3/malloc_get_state.3:31 build/C/man3/posix_memalign.3:35
1907 msgid "B<#include E<lt>stdlib.hE<gt>>\n"
1911 #: build/C/man3/malloc_get_state.3:33
1913 msgid "B<void* malloc_get_state(void);>\n"
1917 #: build/C/man3/malloc_get_state.3:35
1919 msgid "B<int malloc_set_state(void *>I<state>B<);>\n"
1923 #: build/C/man3/malloc_get_state.3:53
1925 "The B<malloc_get_state>() function records the current state of all "
1926 "B<malloc>(3) internal bookkeeping variables (but not the actual contents of "
1927 "the heap or the state of B<malloc_hook>(3) functions pointers). The state "
1928 "is recorded in a system-dependent opaque data structure dynamically "
1929 "allocated via B<malloc>(3), and a pointer to that data structure is returned "
1930 "as the function result. (It is the caller's responsibility to B<free>(3) "
1935 #: build/C/man3/malloc_get_state.3:61
1937 "The B<malloc_set_state>() function restores the state of all B<malloc>(3) "
1938 "internal bookkeeping variables to the values recorded in the opaque data "
1939 "structure pointed to by I<state>."
1943 #: build/C/man3/malloc_get_state.3:68
1945 "On success, B<malloc_get_state>() returns a pointer to a newly allocated "
1946 "opaque data structure. On error (for example, memory could not be allocated "
1947 "for the data structure), B<malloc_get_state>() returns NULL."
1950 #. if(ms->magic != MALLOC_STATE_MAGIC) return -1;
1951 #. /* Must fail if the major version is too high. */
1952 #. if((ms->version & ~0xffl) > (MALLOC_STATE_VERSION & ~0xffl)) return -2;
1954 #: build/C/man3/malloc_get_state.3:86
1956 "On success, B<malloc_set_state>() returns 0. If the implementation detects "
1957 "that I<state> does not point to a correctly formed data structure, "
1958 "B<malloc_set_state>() returns -1. If the implementation detects that the "
1959 "version of the data structure referred to by I<state> is a more recent "
1960 "version than this implementation knows about, B<malloc_set_state>() returns "
1965 #: build/C/man3/malloc_get_state.3:88 build/C/man3/malloc_hook.3:82 build/C/man3/mcheck.3:147 build/C/man3/mtrace.3:80
1966 msgid "These functions are GNU extensions."
1970 #: build/C/man3/malloc_get_state.3:94
1972 "These functions are especially useful when using this B<malloc>(3) "
1973 "implementation as part of a shared library, and the heap contents are "
1974 "saved/restored via some other method. This technique is used by the GNU "
1975 "Emacs to implement its \"dumping\" function."
1978 #. i.e., calls __malloc_check_init()
1979 #. i.e., malloc checking is not already in use
1980 #. and the caller requested malloc checking
1982 #: build/C/man3/malloc_get_state.3:111
1984 "Hook function pointers are never saved or restored by these functions, with "
1985 "two exceptions: if malloc checking (see B<mallopt>(3)) was in use when "
1986 "B<malloc_get_state>() was called, then B<malloc_set_state>() resets malloc "
1987 "checking hooks if possible; if malloc checking was not in use in the "
1988 "recorded state, but the caller has requested malloc checking, then the hooks "
1993 #: build/C/man3/malloc_get_state.3:114
1994 msgid "B<malloc>(3), B<mallopt>(3)"
1998 #: build/C/man3/malloc_hook.3:10
2004 #: build/C/man3/malloc_hook.3:10
2010 #: build/C/man3/malloc_hook.3:15
2012 "__malloc_hook, __malloc_initialize_hook, __memalign_hook, __free_hook, "
2013 "__realloc_hook, __after_morecore_hook - malloc debugging variables"
2017 #: build/C/man3/malloc_hook.3:18 build/C/man3/malloc_info.3:31 build/C/man3/posix_memalign.3:41
2019 msgid "B<#include E<lt>malloc.hE<gt>>\n"
2023 #: build/C/man3/malloc_hook.3:20
2025 msgid "B<void *(*__malloc_hook)(size_t >I<size>B<, const void *>I<caller>B<);>\n"
2029 #: build/C/man3/malloc_hook.3:23
2032 "B<void *(*__realloc_hook)(void *>I<ptr>B<, size_t >I<size>B<, const void "
2033 "*>I<caller>B<);>\n"
2037 #: build/C/man3/malloc_hook.3:26
2040 "B<void *(*__memalign_hook)(size_t >I<alignment>B<, size_t >I<size>B<,>\n"
2041 "B< const void *>I<caller>B<);>\n"
2045 #: build/C/man3/malloc_hook.3:28
2047 msgid "B<void (*__free_hook)(void *>I<ptr>B<, const void *>I<caller>B<);>\n"
2051 #: build/C/man3/malloc_hook.3:30
2053 msgid "B<void (*__malloc_initialize_hook)(void);>\n"
2057 #: build/C/man3/malloc_hook.3:32
2059 msgid "B<void (*__after_morecore_hook)(void);>\n"
2063 #: build/C/man3/malloc_hook.3:43
2065 "The GNU C library lets you modify the behavior of B<malloc>(3), "
2066 "B<realloc>(3), and B<free>(3) by specifying appropriate hook functions. "
2067 "You can use these hooks to help you debug programs that use dynamic memory "
2068 "allocation, for example."
2072 #: build/C/man3/malloc_hook.3:50
2074 "The variable B<__malloc_initialize_hook> points at a function that is called "
2075 "once when the malloc implementation is initialized. This is a weak "
2076 "variable, so it can be overridden in the application with a definition like "
2081 #: build/C/man3/malloc_hook.3:53
2083 msgid " void (*__malloc_initialize_hook)(void) = my_init_hook;\n"
2087 #: build/C/man3/malloc_hook.3:58
2088 msgid "Now the function I<my_init_hook>() can do the initialization of all hooks."
2092 #: build/C/man3/malloc_hook.3:74
2094 "The four functions pointed to by B<__malloc_hook>, B<__realloc_hook>, "
2095 "B<__memalign_hook>, B<__free_hook> have a prototype like the functions "
2096 "B<malloc>(3), B<realloc>(3), B<memalign>(3), B<free>(3), respectively, "
2097 "except that they have a final argument I<caller> that gives the address of "
2098 "the caller of B<malloc>(3), etc."
2102 #: build/C/man3/malloc_hook.3:80
2104 "The variable B<__after_morecore_hook> points at a function that is called "
2105 "each time after B<sbrk>(2) was asked for more memory."
2108 #. https://bugzilla.redhat.com/show_bug.cgi?id=450187
2109 #. http://sourceware.org/bugzilla/show_bug.cgi?id=9957
2111 #: build/C/man3/malloc_hook.3:89
2113 "The use of these hook functions is not safe in multithreaded programs, and "
2114 "they are now deprecated. Programmers should instead preempt calls to the "
2115 "relevant functions by defining and exporting functions such as \"malloc\" "
2120 #: build/C/man3/malloc_hook.3:91
2121 msgid "Here is a short example of how to use these variables."
2125 #: build/C/man3/malloc_hook.3:95
2128 "#include E<lt>stdio.hE<gt>\n"
2129 "#include E<lt>malloc.hE<gt>\n"
2133 #: build/C/man3/malloc_hook.3:99
2136 "/* Prototypes for our hooks. */\n"
2137 "static void my_init_hook(void);\n"
2138 "static void *my_malloc_hook(size_t, const void *);\n"
2142 #: build/C/man3/malloc_hook.3:102
2145 "/* Variables to save original hooks. */\n"
2146 "static void *(*old_malloc_hook)(size_t, const void *);\n"
2150 #: build/C/man3/malloc_hook.3:105
2153 "/* Override initializing hook from the C library. */\n"
2154 "void (*__malloc_initialize_hook) (void) = my_init_hook;\n"
2158 #: build/C/man3/malloc_hook.3:112
2162 "my_init_hook(void)\n"
2164 " old_malloc_hook = __malloc_hook;\n"
2165 " __malloc_hook = my_malloc_hook;\n"
2170 #: build/C/man3/malloc_hook.3:117
2174 "my_malloc_hook(size_t size, const void *caller)\n"
2180 #: build/C/man3/malloc_hook.3:120
2183 " /* Restore all old hooks */\n"
2184 " __malloc_hook = old_malloc_hook;\n"
2188 #: build/C/man3/malloc_hook.3:123
2191 " /* Call recursively */\n"
2192 " result = malloc(size);\n"
2196 #: build/C/man3/malloc_hook.3:126
2199 " /* Save underlying hooks */\n"
2200 " old_malloc_hook = __malloc_hook;\n"
2204 #: build/C/man3/malloc_hook.3:130
2207 " /* printf() might call malloc(), so protect it too. */\n"
2208 " printf(\"malloc(%u) called from %p returns %p\\en\",\n"
2209 " (unsigned int) size, caller, result);\n"
2213 #: build/C/man3/malloc_hook.3:133
2216 " /* Restore our own hooks */\n"
2217 " __malloc_hook = my_malloc_hook;\n"
2221 #: build/C/man3/malloc_hook.3:136
2229 #: build/C/man3/malloc_hook.3:142
2230 msgid "B<mallinfo>(3), B<malloc>(3), B<mcheck>(3), B<mtrace>(3)"
2234 #: build/C/man3/malloc_info.3:25
2240 #: build/C/man3/malloc_info.3:25
2246 #: build/C/man3/malloc_info.3:28
2247 msgid "malloc_info - export malloc state to a stream"
2251 #: build/C/man3/malloc_info.3:33
2253 msgid "B<int malloc_info(int >I<options>B<, FILE *>I<fp>B<);>\n"
2257 #: build/C/man3/malloc_info.3:44
2259 "The B<malloc_info>() function exports an XML string that describes the "
2260 "current state of the memory-allocation implementation in the caller. The "
2261 "string is printed on the file stream I<fp>. The exported string includes "
2262 "information about all arenas (see B<malloc>(3))."
2266 #: build/C/man3/malloc_info.3:48
2267 msgid "As currently implemented, I<options> must be zero."
2271 #: build/C/man3/malloc_info.3:55
2273 "On success, B<malloc_info>() returns 0; on error, it returns -1, with "
2274 "I<errno> set to indicate the cause."
2278 #: build/C/man3/malloc_info.3:60
2279 msgid "I<options> was nonzero."
2283 #: build/C/man3/malloc_info.3:63
2284 msgid "B<malloc_info>() was added to glibc in version 2.10."
2288 #: build/C/man3/malloc_info.3:65 build/C/man3/malloc_stats.3:57 build/C/man3/malloc_trim.3:62 build/C/man3/malloc_usable_size.3:50
2289 msgid "This function is a GNU extension."
2293 #: build/C/man3/malloc_info.3:71
2295 "The memory-allocation information is provided as an XML string (rather than "
2296 "a C structure) because the information may change over time (according to "
2297 "changes in the underlying implementation). The output XML string includes a "
2302 #: build/C/man3/malloc_info.3:77
2304 "The B<open_memstream>(3) function can be used to send the output of "
2305 "B<malloc_info>() directly into a buffer in memory, rather than to a file."
2309 #: build/C/man3/malloc_info.3:84
2311 "The B<malloc_info>() function is designed to address deficiencies in "
2312 "B<malloc_stats>(3) and B<mallinfo>(3)."
2316 #: build/C/man3/malloc_info.3:95
2318 "The program below takes up to four command-line arguments, of which the "
2319 "first three are mandatory. The first argument specifies the number of "
2320 "threads that the program should create. All of the threads, including the "
2321 "main thread, allocate the number of blocks of memory specified by the second "
2322 "argument. The third argument controls the size of the blocks to be "
2323 "allocated. The main thread creates blocks of this size, the second thread "
2324 "created by the program allocates blocks of twice this size, the third thread "
2325 "allocates blocks of three times this size, and so on."
2329 #: build/C/man3/malloc_info.3:102
2331 "The program calls B<malloc_info>() twice to display the memory-allocation "
2332 "state. The first call takes place before any threads are created or memory "
2333 "allocated. The second call is performed after all threads have allocated "
2338 #: build/C/man3/malloc_info.3:110
2340 "In the following example, the command-line arguments specify the creation of "
2341 "one additional thread, and both the main thread and the additional thread "
2342 "allocate 10000 blocks of memory. After the blocks of memory have been "
2343 "allocated, B<malloc_info>() shows the state of two allocation arenas."
2347 #: build/C/man3/malloc_info.3:135
2350 "$ B<getconf GNU_LIBC_VERSION>\n"
2352 "$ B<./a.out 1 10000 100>\n"
2353 "============ Before allocating blocks ============\n"
2354 "E<lt>malloc version=\"1\"E<gt>\n"
2355 "E<lt>heap nr=\"0\"E<gt>\n"
2357 "E<lt>/sizesE<gt>\n"
2358 "E<lt>total type=\"fast\" count=\"0\" size=\"0\"/E<gt>\n"
2359 "E<lt>total type=\"rest\" count=\"0\" size=\"0\"/E<gt>\n"
2360 "E<lt>system type=\"current\" size=\"135168\"/E<gt>\n"
2361 "E<lt>system type=\"max\" size=\"135168\"/E<gt>\n"
2362 "E<lt>aspace type=\"total\" size=\"135168\"/E<gt>\n"
2363 "E<lt>aspace type=\"mprotect\" size=\"135168\"/E<gt>\n"
2365 "E<lt>total type=\"fast\" count=\"0\" size=\"0\"/E<gt>\n"
2366 "E<lt>total type=\"rest\" count=\"0\" size=\"0\"/E<gt>\n"
2367 "E<lt>system type=\"current\" size=\"135168\"/E<gt>\n"
2368 "E<lt>system type=\"max\" size=\"135168\"/E<gt>\n"
2369 "E<lt>aspace type=\"total\" size=\"135168\"/E<gt>\n"
2370 "E<lt>aspace type=\"mprotect\" size=\"135168\"/E<gt>\n"
2371 "E<lt>/mallocE<gt>\n"
2375 #: build/C/man3/malloc_info.3:165
2378 "============ After allocating blocks ============\n"
2379 "E<lt>malloc version=\"1\"E<gt>\n"
2380 "E<lt>heap nr=\"0\"E<gt>\n"
2382 "E<lt>/sizesE<gt>\n"
2383 "E<lt>total type=\"fast\" count=\"0\" size=\"0\"/E<gt>\n"
2384 "E<lt>total type=\"rest\" count=\"0\" size=\"0\"/E<gt>\n"
2385 "E<lt>system type=\"current\" size=\"1081344\"/E<gt>\n"
2386 "E<lt>system type=\"max\" size=\"1081344\"/E<gt>\n"
2387 "E<lt>aspace type=\"total\" size=\"1081344\"/E<gt>\n"
2388 "E<lt>aspace type=\"mprotect\" size=\"1081344\"/E<gt>\n"
2390 "E<lt>heap nr=\"1\"E<gt>\n"
2392 "E<lt>/sizesE<gt>\n"
2393 "E<lt>total type=\"fast\" count=\"0\" size=\"0\"/E<gt>\n"
2394 "E<lt>total type=\"rest\" count=\"0\" size=\"0\"/E<gt>\n"
2395 "E<lt>system type=\"current\" size=\"1032192\"/E<gt>\n"
2396 "E<lt>system type=\"max\" size=\"1032192\"/E<gt>\n"
2397 "E<lt>aspace type=\"total\" size=\"1032192\"/E<gt>\n"
2398 "E<lt>aspace type=\"mprotect\" size=\"1032192\"/E<gt>\n"
2400 "E<lt>total type=\"fast\" count=\"0\" size=\"0\"/E<gt>\n"
2401 "E<lt>total type=\"rest\" count=\"0\" size=\"0\"/E<gt>\n"
2402 "E<lt>system type=\"current\" size=\"2113536\"/E<gt>\n"
2403 "E<lt>system type=\"max\" size=\"2113536\"/E<gt>\n"
2404 "E<lt>aspace type=\"total\" size=\"2113536\"/E<gt>\n"
2405 "E<lt>aspace type=\"mprotect\" size=\"2113536\"/E<gt>\n"
2406 "E<lt>/mallocE<gt>\n"
2410 #: build/C/man3/malloc_info.3:175
2413 "#include E<lt>unistd.hE<gt>\n"
2414 "#include E<lt>stdlib.hE<gt>\n"
2415 "#include E<lt>pthread.hE<gt>\n"
2416 "#include E<lt>malloc.hE<gt>\n"
2417 "#include E<lt>errno.hE<gt>\n"
2421 #: build/C/man3/malloc_info.3:178
2424 "static size_t blockSize;\n"
2425 "static int numThreads, numBlocks;\n"
2429 #: build/C/man3/malloc_info.3:181
2432 "#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \\e\n"
2437 #: build/C/man3/malloc_info.3:187
2441 "thread_func(void *arg)\n"
2444 " int tn = (int) arg;\n"
2448 #: build/C/man3/malloc_info.3:190
2451 " /* The multiplier \\(aq(2 + tn)\\(aq ensures that each thread "
2453 " the main thread) allocates a different amount of memory */\n"
2457 #: build/C/man3/malloc_info.3:194
2460 " for (j = 0; j E<lt> numBlocks; j++)\n"
2461 " if (malloc(blockSize * (2 + tn)) == NULL)\n"
2462 " errExit(\"malloc-thread\");\n"
2466 #: build/C/man3/malloc_info.3:198
2469 " sleep(100); /* Sleep until main thread terminates */\n"
2475 #: build/C/man3/malloc_info.3:204
2479 "main(int argc, char *argv[])\n"
2481 " int j, tn, sleepTime;\n"
2482 " pthread_t *thr;\n"
2486 #: build/C/man3/malloc_info.3:211
2489 " if (argc E<lt> 4) {\n"
2490 " fprintf(stderr,\n"
2491 " \"%s num-threads num-blocks block-size [sleep-time]\\en\",\n"
2493 " exit(EXIT_FAILURE);\n"
2498 #: build/C/man3/malloc_info.3:216
2501 " numThreads = atoi(argv[1]);\n"
2502 " numBlocks = atoi(argv[2]);\n"
2503 " blockSize = atoi(argv[3]);\n"
2504 " sleepTime = (argc E<gt> 4) ? atoi(argv[4]) : 0;\n"
2508 #: build/C/man3/malloc_info.3:220
2511 " thr = calloc(numThreads, sizeof(pthread_t));\n"
2512 " if (thr == NULL)\n"
2513 " errExit(\"calloc\");\n"
2517 #: build/C/man3/malloc_info.3:223
2520 " printf(\"============ Before allocating blocks ============\\en\");\n"
2521 " malloc_info(0, stdout);\n"
2525 #: build/C/man3/malloc_info.3:225
2527 msgid " /* Create threads that allocate different amounts of memory */\n"
2531 #: build/C/man3/malloc_info.3:231
2534 " for (tn = 0; tn E<lt> numThreads; tn++) {\n"
2535 " errno = pthread_create(&thr[tn], NULL, thread_func,\n"
2537 " if (errno != 0)\n"
2538 " errExit(\"pthread_create\");\n"
2542 #: build/C/man3/malloc_info.3:236
2545 " /* If we add a sleep interval after the start-up of each\n"
2546 " thread, the threads likely won\\(aqt contend for malloc\n"
2547 " mutexes, and therefore additional arenas won\\(aqt be\n"
2548 " allocated (see malloc(3)). */\n"
2552 #: build/C/man3/malloc_info.3:240
2555 " if (sleepTime E<gt> 0)\n"
2556 " sleep(sleepTime);\n"
2561 #: build/C/man3/malloc_info.3:242
2563 msgid " /* The main thread also allocates some memory */\n"
2567 #: build/C/man3/malloc_info.3:246
2570 " for (j = 0; j E<lt> numBlocks; j++)\n"
2571 " if (malloc(blockSize) == NULL)\n"
2572 " errExit(\"malloc\");\n"
2576 #: build/C/man3/malloc_info.3:249
2579 " sleep(2); /* Give all threads a chance to\n"
2580 " complete allocations */\n"
2584 #: build/C/man3/malloc_info.3:252
2587 " printf(\"\\en============ After allocating blocks ============\\en\");\n"
2588 " malloc_info(0, stdout);\n"
2592 #: build/C/man3/malloc_info.3:262
2594 "B<mallinfo>(3), B<malloc>(3), B<malloc_stats>(3), B<mallopt>(3), "
2595 "B<open_memstream>(3)"
2599 #: build/C/man3/malloc_stats.3:26
2601 msgid "MALLOC_STATS"
2605 #: build/C/man3/malloc_stats.3:29
2606 msgid "malloc_stats - print memory allocation statistics"
2610 #: build/C/man3/malloc_stats.3:33
2611 msgid "B<void malloc_stats(void);>"
2615 #. Available already in glibc 2.0, possibly earlier
2617 #: build/C/man3/malloc_stats.3:55
2619 "The B<malloc_stats>() function prints (on standard error) statistics about "
2620 "memory allocated by B<malloc>(3) and related functions. For each arena "
2621 "(allocation area), this function prints the total amount of memory allocated "
2622 "and the total number of bytes consumed by in-use allocations. (These two "
2623 "values correspond to the I<arena> and I<uordblks> fields retrieved by "
2624 "B<mallinfo>(3).) In addition, the function prints the sum of these two "
2625 "statistics for all arenas, and the maximum number of blocks and bytes that "
2626 "were ever simultaneously allocated using B<mmap>(2)."
2630 #: build/C/man3/malloc_stats.3:61
2632 "More detailed information about memory allocations in the main arena can be "
2633 "obtained using B<mallinfo>(3)."
2637 #: build/C/man3/malloc_stats.3:67
2638 msgid "B<mmap>(2), B<mallinfo>(3), B<malloc>(3), B<malloc_info>(3), B<mallopt>(3)"
2642 #: build/C/man3/malloc_trim.3:26
2648 #: build/C/man3/malloc_trim.3:26 build/C/man3/malloc_usable_size.3:25
2654 #: build/C/man3/malloc_trim.3:29
2655 msgid "malloc_trim - release free memory from the top of the heap"
2659 #: build/C/man3/malloc_trim.3:33
2660 msgid "B<void malloc_trim(size_t >I<pad>B<);>"
2664 #: build/C/man3/malloc_trim.3:40
2666 "The B<malloc_trim>() function attempts to release free memory at the top of "
2667 "the heap (by calling B<sbrk>(2) with a suitable argument)."
2671 #: build/C/man3/malloc_trim.3:51
2673 "The I<pad> argument specifies the amount of free space to leave untrimmed at "
2674 "the top of the heap. If this argument is 0, only the minimum amount of "
2675 "memory is maintained at the top of the heap (i.e., one page or less). A "
2676 "nonzero argument can be used to maintain some trailing space at the top of "
2677 "the heap in order to allow future allocations to be made without having to "
2678 "extend the heap with B<sbrk>(2)."
2682 #: build/C/man3/malloc_trim.3:56
2684 "The B<malloc_trim>() function returns 1 if memory was actually released "
2685 "back to the system, or 0 if it was not possible to release any memory."
2689 #. Available already in glibc 2.0, possibly earlier
2691 #: build/C/man3/malloc_trim.3:60
2692 msgid "No errors are defined."
2696 #: build/C/man3/malloc_trim.3:71
2698 "This function is automatically called by B<free>(3) in certain "
2699 "circumstances; see the discussion of B<M_TOP_PAD> and B<M_TRIM_THRESHOLD> in "
2704 #: build/C/man3/malloc_trim.3:74
2706 "This function cannot release free memory located at places other than the "
2710 #. malloc/malloc.c::mTRIm():
2711 #. return result | (av == &main_arena ? sYSTRIm (pad, av) : 0);
2713 #: build/C/man3/malloc_trim.3:78
2714 msgid "This function releases only memory in the main arena."
2718 #: build/C/man3/malloc_trim.3:82
2719 msgid "B<sbrk>(2), B<malloc>(3), B<mallopt>(3)"
2723 #: build/C/man3/malloc_usable_size.3:25
2725 msgid "MALLOC_USABLE_SIZE"
2729 #: build/C/man3/malloc_usable_size.3:28
2730 msgid "malloc_usable_size - obtain size of block of memory allocated from heap"
2734 #: build/C/man3/malloc_usable_size.3:32
2735 msgid "B<size_t malloc_usable_size (void *>I<ptr>B<);>"
2739 #: build/C/man3/malloc_usable_size.3:40
2741 "The B<malloc_usable_size>() function returns the number of usable bytes in "
2742 "the block pointed to by I<ptr>, a pointer to a block of memory allocated by "
2743 "B<malloc>(3) or a related function."
2747 #: build/C/man3/malloc_usable_size.3:48
2749 "B<malloc_usable_size>() returns the number of usable bytes in the block of "
2750 "allocated memory pointed to by I<ptr>. If I<ptr> is NULL, 0 is returned."
2754 #: build/C/man3/malloc_usable_size.3:60
2756 "The value returned by B<malloc_usable_size>() may be greater than the "
2757 "requested size of the allocation because of alignment and minimum size "
2758 "constraints. Although the excess bytes can be overwritten by the "
2759 "application without ill effects, this is not good programming practice: the "
2760 "number of excess bytes in an allocation depends on the underlying "
2765 #: build/C/man3/malloc_usable_size.3:62
2766 msgid "The main use of this function is for debugging and introspection."
2770 #: build/C/man3/malloc_usable_size.3:64
2771 msgid "B<malloc>(3)"
2775 #: build/C/man3/mallopt.3:26
2781 #: build/C/man3/mallopt.3:26
2787 #: build/C/man3/mallopt.3:29
2788 msgid "mallopt - set memory allocation parameters"
2792 #: build/C/man3/mallopt.3:33
2793 msgid "B<int mallopt(int >I<param>B<, int >I<value>B<);>"
2797 #: build/C/man3/mallopt.3:44
2799 "The B<mallopt>() function adjusts parameters that control the behavior of "
2800 "the memory-allocation functions (see B<malloc>(3)). The I<param> argument "
2801 "specifies the parameter to be modified, and I<value> specifies the new value "
2802 "for that parameter."
2806 #: build/C/man3/mallopt.3:47
2807 msgid "The following values can be specified for I<param>:"
2811 #: build/C/man3/mallopt.3:47
2813 msgid "B<M_CHECK_ACTION>"
2817 #: build/C/man3/mallopt.3:53
2819 "Setting this parameter controls how glibc responds when various kinds of "
2820 "programming errors are detected (e.g., freeing the same pointer twice). The "
2821 "3 least significant bits (2, 1, and 0) of the value assigned to this "
2822 "parameter determine the glibc behavior, as follows:"
2826 #: build/C/man3/mallopt.3:54
2832 #: build/C/man3/mallopt.3:64
2834 "If this bit is set, then print a one-line message on I<stderr> that provides "
2835 "details about the error. The message starts with the string \"***\\ glibc "
2836 "detected\\ ***\", followed by the program name, the name of the "
2837 "memory-allocation function in which the error was detected, a brief "
2838 "description of the error, and the memory address where the error was "
2843 #: build/C/man3/mallopt.3:64
2849 #: build/C/man3/mallopt.3:79
2851 "If this bit is set, then, after printing any error message specified by bit "
2852 "0, the program is terminated by calling B<abort>(3). In glibc versions "
2853 "since 2.4, if bit 0 is also set, then, between printing the error message "
2854 "and aborting, the program also prints a stack trace in the manner of "
2855 "B<backtrace>(3), and prints the process's memory mapping in the style of "
2856 "I</proc/[pid]/maps> (see B<proc>(5))."
2860 #: build/C/man3/mallopt.3:79
2862 msgid "Bit 2 (since glibc 2.4)"
2866 #: build/C/man3/mallopt.3:86
2868 "This bit has an effect only if bit 0 is also set. If this bit is set, then "
2869 "the one-line message describing the error is simplified to contain just the "
2870 "name of the function where the error was detected and the brief description "
2875 #: build/C/man3/mallopt.3:91
2876 msgid "The remaining bits in I<value> are ignored."
2880 #: build/C/man3/mallopt.3:95
2882 "Combining the above details, the following numeric values are meaningful for "
2883 "B<M_CHECK_ACTION>:"
2887 #: build/C/man3/mallopt.3:96
2893 #: build/C/man3/mallopt.3:98
2894 msgid "Ignore error conditions; continue execution (with undefined results)."
2898 #: build/C/man3/mallopt.3:98
2904 #: build/C/man3/mallopt.3:100
2905 msgid "Print a detailed error message and continue execution."
2909 #: build/C/man3/mallopt.3:100
2915 #: build/C/man3/mallopt.3:102
2916 msgid "Abort the program."
2920 #: build/C/man3/mallopt.3:102
2926 #: build/C/man3/mallopt.3:105
2928 "Print detailed error message, stack trace, and memory mappings, and abort "
2933 #: build/C/man3/mallopt.3:105
2939 #: build/C/man3/mallopt.3:107
2940 msgid "Print a simple error message and continue execution."
2944 #: build/C/man3/mallopt.3:107
2950 #: build/C/man3/mallopt.3:110
2952 "Print simple error message, stack trace, and memory mappings, and abort the "
2957 #: build/C/man3/mallopt.3:116
2959 "Since glibc 2.3.4, the default value for the B<M_CHECK_ACTION> parameter is "
2960 "3. In glibc version 2.3.3 and earlier, the default value is 1."
2964 #: build/C/man3/mallopt.3:121
2966 "Using a nonzero B<M_CHECK_ACTION> value can be useful because otherwise a "
2967 "crash may happen much later, and the true cause of the problem is then very "
2968 "hard to track down."
2972 #: build/C/man3/mallopt.3:121
2974 msgid "B<M_MMAP_MAX>"
2977 #. The following text adapted from comments in the glibc source:
2979 #: build/C/man3/mallopt.3:131
2981 "This parameter specifies the maximum number of allocation requests that may "
2982 "be simultaneously serviced using B<mmap>(2). This parameter exists because "
2983 "some systems have a limited number of internal tables for use by B<mmap>(2), "
2984 "and using more than a few of them may degrade performance."
2988 #: build/C/man3/mallopt.3:138
2990 "The default value is 65,536, a value which has no special significance and "
2991 "which servers only as a safeguard. Setting this parameter to 0 disables the "
2992 "use of B<mmap>(2) for servicing large allocation requests."
2996 #: build/C/man3/mallopt.3:138
2998 msgid "B<M_MMAP_THRESHOLD>"
3002 #: build/C/man3/mallopt.3:147
3004 "For allocations greater than or equal to the limit specified (in bytes) by "
3005 "B<M_MMAP_THRESHOLD> that can't be satisfied from the free list, the "
3006 "memory-allocation functions employ B<mmap>(2) instead of increasing the "
3007 "program break using B<sbrk>(2)."
3011 #: build/C/man3/mallopt.3:167
3013 "Allocating memory using B<mmap>(2) has the significant advantage that the "
3014 "allocated memory blocks can always be independently released back to the "
3015 "system. (By contrast, the heap can be trimmed only if memory is freed at "
3016 "the top end.) On the other hand, there are some disadvantages to the use of "
3017 "B<mmap>(2): deallocated space is not placed on the free list for reuse by "
3018 "later allocations; memory may be wasted because B<mmap>(2) allocations must "
3019 "be page-aligned; and the kernel must perform the expensive task of zeroing "
3020 "out memory allocated via B<mmap>(2). Balancing these factors leads to a "
3021 "default setting of 128*1024 for the B<M_MMAP_THRESHOLD> parameter."
3025 #: build/C/man3/mallopt.3:174
3027 "The lower limit for this parameter is 0. The upper limit is "
3028 "B<DEFAULT_MMAP_THRESHOLD_MAX>: 512*1024 on 32-bit systems or "
3029 "I<4*1024*1024*sizeof(long)> on 64-bit systems."
3033 #: build/C/man3/mallopt.3:192
3035 "I<Note:> Nowadays, glibc uses a dynamic mmap threshold by default. The "
3036 "initial value of the threshold is 128*1024, but when blocks larger than the "
3037 "current threshold and less than or equal to B<DEFAULT_MMAP_THRESHOLD_MAX> "
3038 "are freed, the threshold is adjusted upward to the size of the freed block. "
3039 "When dynamic mmap thresholding is in effect, the threshold for trimming the "
3040 "heap is also dynamically adjusted to be twice the dynamic mmap threshold. "
3041 "Dynamic adjustment of the mmap threshold is disabled if any of the "
3042 "B<M_TRIM_THRESHOLD>, B<M_TOP_PAD>, B<M_MMAP_THRESHOLD>, or B<M_MMAP_MAX> "
3043 "parameters is set."
3047 #: build/C/man3/mallopt.3:192
3049 msgid "B<M_MXFAST> (since glibc 2.3)"
3052 #. The following text adapted from comments in the glibc sources:
3054 #: build/C/man3/mallopt.3:212
3056 "Set the upper limit for memory allocation requests that are satisfied using "
3057 "\"fastbins\". (The measurement unit for this parameter is bytes.) Fastbins "
3058 "are storage areas that hold deallocated blocks of memory of the same size "
3059 "without merging adjacent free blocks. Subsequent reallocation of blocks of "
3060 "the same size can be handled very quickly by allocating from the fastbin, "
3061 "although memory fragmentation and the overall memory footprint of the "
3062 "program can increase. The default value for this parameter is "
3063 "I<64*sizeof(size_t)/4> (i.e., 64 on 32-bit architectures). The range for "
3064 "this parameter is 0 to I<80*sizeof(size_t)/4>. Setting B<M_MXFAST> to 0 "
3065 "disables the use of fastbins."
3069 #: build/C/man3/mallopt.3:212
3071 msgid "B<M_PERTURB> (since glibc 2.4)"
3075 #: build/C/man3/mallopt.3:227
3077 "If this parameter is set to a nonzero value, then bytes of allocated memory "
3078 "(other than allocations via B<calloc>(3)) are initialized to the complement "
3079 "of the value in the least significant byte of I<value>, and when allocated "
3080 "memory is released using B<free>(3), the freed bytes are set to the least "
3081 "significant byte of I<value>. This can be useful for detecting errors where "
3082 "programs incorrectly rely on allocated memory being initialized to zero, or "
3083 "reuse values in memory that has already been freed."
3087 #: build/C/man3/mallopt.3:227
3089 msgid "B<M_TOP_PAD>"
3093 #: build/C/man3/mallopt.3:234
3095 "This parameter defines the amount of padding to employ when calling "
3096 "B<sbrk>(2) to modify the program break. (The measurement unit for this "
3097 "parameter is bytes.) This parameter has an effect in the following "
3102 #: build/C/man3/mallopt.3:241
3104 "When the program break is increased, then B<M_TOP_PAD> bytes are added to "
3105 "the B<sbrk>(2) request."
3109 #: build/C/man3/mallopt.3:247
3111 "When the heap is trimmed as a consequence of calling B<free>(3) (see the "
3112 "discussion of B<M_TRIM_THRESHOLD>) this much free space is preserved at the "
3117 #: build/C/man3/mallopt.3:251
3119 "In either case, the amount of padding is always rounded to a system page "
3124 #: build/C/man3/mallopt.3:258
3126 "Modifying B<M_TOP_PAD> is a trade-off between increasing the number of "
3127 "system calls (when the parameter is set low) and wasting unused memory at "
3128 "the top of the heap (when the parameter is set high)."
3131 #. DEFAULT_TOP_PAD in glibc source
3133 #: build/C/man3/mallopt.3:261
3134 msgid "The default value for this parameter is 128*1024."
3138 #: build/C/man3/mallopt.3:261
3140 msgid "B<M_TRIM_THRESHOLD>"
3144 #: build/C/man3/mallopt.3:277
3146 "When the amount of contiguous free memory at the top of the heap grows "
3147 "sufficiently large, B<free>(3) employs B<sbrk>(2) to release this memory "
3148 "back to the system. (This can be useful in programs that continue to "
3149 "execute for a long period after freeing a significant amount of memory.) "
3150 "The B<M_TRIM_THRESHOLD> parameter specifies the minimum size (in bytes) that "
3151 "this block of memory must reach before B<sbrk>(2) is used to trim the heap."
3155 #: build/C/man3/mallopt.3:282
3157 "The default value for this parameter is 128*1024. Setting "
3158 "B<M_TRIM_THRESHOLD> to -1 disables trimming completely."
3161 #. FIXME Do the arena parameters need to be documented?
3163 #. .BR M_ARENA_TEST " (since glibc 2.10)"
3165 #. .BR M_ARENA_MAX " (since glibc 2.10)"
3167 #. Environment variables
3168 #. MALLOC_ARENA_MAX_
3169 #. MALLOC_ARENA_TEST_
3171 #. http://udrepper.livejournal.com/20948.html describes some details
3172 #. of the MALLOC_ARENA_* environment variables.
3174 #. These macros aren't enabled in production releases until 2.15?
3175 #. (see glibc malloc/Makefile)
3177 #: build/C/man3/mallopt.3:305
3179 "Modifying B<M_TRIM_THRESHOLD> is a trade-off between increasing the number "
3180 "of system calls (when the parameter is set low) and wasting unused memory "
3181 "at the top of the heap (when the parameter is set high)."
3185 #: build/C/man3/mallopt.3:305
3187 msgid "Environment variables"
3191 #: build/C/man3/mallopt.3:320
3193 "A number of environment variables can be defined to modify some of the same "
3194 "parameters as are controlled by B<mallopt>(). Using these variables has the "
3195 "advantage that the source code of the program need not be changed. To be "
3196 "effective, these variables must be defined before the first call to a "
3197 "memory-allocation function. (If the same parameters are adjusted via "
3198 "B<mallopt>(), then the B<mallopt>() settings take precedence.) For "
3199 "security reasons, these variables are ignored in set-user-ID and "
3200 "set-group-ID programs."
3204 #: build/C/man3/mallopt.3:323
3206 "The environment variables are as follows (note the trailing underscore at "
3207 "the end of the name of each variable):"
3211 #: build/C/man3/mallopt.3:323
3213 msgid "B<MALLOC_CHECK_>"
3216 #. On glibc 2.12/x86, a simple malloc()+free() loop is about 70% slower
3217 #. when MALLOC_CHECK_ was set.
3219 #: build/C/man3/mallopt.3:340
3221 "This environment variable controls the same parameter as B<mallopt>() "
3222 "B<M_CHECK_ACTION>. If this variable is set to a nonzero value, then a "
3223 "special implementation of the memory-allocation functions is used. (This is "
3224 "accomplished using the B<malloc_hook>(3) feature.) This implementation "
3225 "performs additional error checking, but is slower than the standard set of "
3226 "memory-allocation functions. (This implementation does not detect all "
3227 "possible errors; memory leaks can still occur.)"
3231 #: build/C/man3/mallopt.3:345
3233 "The value assigned to this environment variable should be a single digit, "
3234 "whose meaning is as described for B<M_CHECK_ACTION>. Any characters beyond "
3235 "the initial digit are ignored."
3239 #: build/C/man3/mallopt.3:354
3241 "For security reasons, the effect of B<MALLOC_CHECK_> is disabled by default "
3242 "for set-user-ID and set-group-ID programs. However, if the file "
3243 "I</etc/suid-debug> exists (the content of the file is irrelevant), then "
3244 "B<MALLOC_CHECK_> also has an effect for set-user-ID and set-group-ID "
3249 #: build/C/man3/mallopt.3:354
3251 msgid "B<MALLOC_MMAP_MAX_>"
3255 #: build/C/man3/mallopt.3:359
3256 msgid "Controls the same parameter as B<mallopt>() B<M_MMAP_MAX>."
3260 #: build/C/man3/mallopt.3:359
3262 msgid "B<MALLOC_MMAP_THRESHOLD_>"
3266 #: build/C/man3/mallopt.3:364
3267 msgid "Controls the same parameter as B<mallopt>() B<M_MMAP_THRESHOLD>."
3271 #: build/C/man3/mallopt.3:364
3273 msgid "B<MALLOC_PERTURB_>"
3277 #: build/C/man3/mallopt.3:369
3278 msgid "Controls the same parameter as B<mallopt>() B<M_PERTURB>."
3282 #: build/C/man3/mallopt.3:369
3284 msgid "B<MALLOC_TRIM_THRESHOLD_>"
3288 #: build/C/man3/mallopt.3:374
3289 msgid "Controls the same parameter as B<mallopt>() B<M_TRIM_THRESHOLD>."
3293 #: build/C/man3/mallopt.3:374
3295 msgid "B<MALLOC_TOP_PAD_>"
3299 #: build/C/man3/mallopt.3:379
3300 msgid "Controls the same parameter as B<mallopt>() B<M_TOP_PAD>."
3304 #: build/C/man3/mallopt.3:384
3305 msgid "On success, B<mallopt>() returns 1. On error, it returns 0."
3309 #. Available already in glibc 2.0, possibly earlier
3311 #: build/C/man3/mallopt.3:392
3312 msgid "On error, I<errno> is I<not> set."
3317 #: build/C/man3/mallopt.3:406
3319 "This function is not specified by POSIX or the C standards. A similar "
3320 "function exists on many System V derivatives, but the range of values for "
3321 "I<param> varies across systems. The SVID defined options B<M_MXFAST>, "
3322 "B<M_NLBLKS>, B<M_GRAIN>, and B<M_KEEP>, but only the first of these is "
3323 "implemented in glibc."
3327 #: build/C/man3/mallopt.3:410
3328 msgid "Specifying an invalid value for I<param> does not generate an error."
3331 #. FIXME This looks buggy:
3332 #. setting the M_MXFAST limit rounds up: (s + SIZE_SZ) & ~MALLOC_ALIGN_MASK)
3333 #. malloc requests are rounded up:
3334 #. (req) + SIZE_SZ + MALLOC_ALIGN_MASK) & ~MALLOC_ALIGN_MASK
3335 #. http://sources.redhat.com/bugzilla/show_bug.cgi?id=12129
3337 #: build/C/man3/mallopt.3:418
3339 "A calculation error within the glibc implementation means that a call of the "
3344 #: build/C/man3/mallopt.3:421
3346 msgid " mallopt(M_MXFAST, n)\n"
3349 #. Bins are multiples of 2 * sizeof(size_t) + sizeof(size_t)
3351 #: build/C/man3/mallopt.3:433
3353 "does not result in fastbins being employed for all allocations of size up to "
3354 "I<n>. To ensure desired results, I<n> should be rounded up to the next "
3355 "multiple greater than or equal to I<(2k+1)*sizeof(size_t)>, where I<k> is an "
3359 #. FIXME MALLOC_MMAP_THRESHOLD_ and MALLOC_MMAP_MAX_
3360 #. do have an effect for set-user-ID programs (but not
3361 #. set-group-ID programs).
3362 #. http://sources.redhat.com/bugzilla/show_bug.cgi?id=12155
3364 #: build/C/man3/mallopt.3:445
3366 "The B<MALLOC_MMAP_THRESHOLD_> and B<MALLOC_MMAP_MAX_> variables are I<not> "
3367 "ignored in set-group-ID programs."
3370 #. FIXME http://sources.redhat.com/bugzilla/show_bug.cgi?id=12140
3372 #: build/C/man3/mallopt.3:466
3374 "If B<mallopt>() is used to set B<M_PERTURB>, then, as expected, the bytes "
3375 "of allocated memory are initialized to the complement of the byte in "
3376 "I<value>, and when that memory is freed, the bytes of the region are "
3377 "initialized to the byte specified in I<value>. However, there is an "
3378 "off-by-I<sizeof(size_t)> error in the implementation: instead of "
3379 "initializing precisely the block of memory being freed by the call "
3380 "I<free(p)>, the block starting at I<p+sizeof(size_t)> is initialized."
3384 #: build/C/man3/mallopt.3:475
3386 "The program below demonstrates the use of B<M_CHECK_ACTION>. If the program "
3387 "is supplied with an (integer) command-line argument, then that argument is "
3388 "used to set the B<M_CHECK_ACTION> parameter. The program then allocates a "
3389 "block of memory, and frees it twice (an error)."
3393 #: build/C/man3/mallopt.3:479
3395 "The following shell session shows what happens when we run this program "
3396 "under glibc, with the default value for B<M_CHECK_ACTION>:"
3400 #: build/C/man3/mallopt.3:499
3404 "main(): returned from first free() call\n"
3405 "*** glibc detected *** ./a.out: double free or corruption (top): 0x09d30008 "
3407 "======= Backtrace: =========\n"
3408 "/lib/libc.so.6(+0x6c501)[0x523501]\n"
3409 "/lib/libc.so.6(+0x6dd70)[0x524d70]\n"
3410 "/lib/libc.so.6(cfree+0x6d)[0x527e5d]\n"
3411 "\\&./a.out[0x80485db]\n"
3412 "/lib/libc.so.6(__libc_start_main+0xe7)[0x4cdce7]\n"
3413 "\\&./a.out[0x8048471]\n"
3414 "======= Memory map: ========\n"
3415 "001e4000-001fe000 r-xp 00000000 08:06 1083555 /lib/libgcc_s.so.1\n"
3416 "001fe000-001ff000 r--p 00019000 08:06 1083555 /lib/libgcc_s.so.1\n"
3417 "[some lines omitted]\n"
3418 "b7814000-b7817000 rw-p 00000000 00:00 0\n"
3419 "bff53000-bff74000 rw-p 00000000 00:00 0 [stack]\n"
3420 "Aborted (core dumped)\n"
3424 #: build/C/man3/mallopt.3:504
3426 "The following runs show the results when employing other values for "
3427 "B<M_CHECK_ACTION>:"
3431 #: build/C/man3/mallopt.3:517
3434 "$ B<./a.out 1> # Diagnose error and continue\n"
3435 "main(): returned from first free() call\n"
3436 "*** glibc detected *** ./a.out: double free or corruption (top): 0x09cbe008 "
3438 "main(): returned from second free() call\n"
3439 "$ B<./a.out 2> # Abort without error message\n"
3440 "main(): returned from first free() call\n"
3441 "Aborted (core dumped)\n"
3442 "$ B<./a.out 0> # Ignore error and continue\n"
3443 "main(): returned from first free() call\n"
3444 "main(): returned from second free() call\n"
3448 #: build/C/man3/mallopt.3:523
3450 "The next run shows how to set the same parameter using the B<MALLOC_CHECK_> "
3451 "environment variable:"
3455 #: build/C/man3/mallopt.3:530
3458 "$ B<MALLOC_CHECK_=1 ./a.out>\n"
3459 "main(): returned from first free() call\n"
3460 "*** glibc detected *** ./a.out: free(): invalid pointer: 0x092c2008 ***\n"
3461 "main(): returned from second free() call\n"
3465 #: build/C/man3/mallopt.3:538
3468 "#include E<lt>malloc.hE<gt>\n"
3469 "#include E<lt>stdio.hE<gt>\n"
3470 "#include E<lt>stdlib.hE<gt>\n"
3474 #: build/C/man3/mallopt.3:543 build/C/man3/mcheck.3:187
3478 "main(int argc, char *argv[])\n"
3484 #: build/C/man3/mallopt.3:550
3487 " if (argc E<gt> 1) {\n"
3488 " if (mallopt(M_CHECK_ACTION, atoi(argv[1])) != 1) {\n"
3489 " fprintf(stderr, \"mallopt() failed\");\n"
3490 " exit(EXIT_FAILURE);\n"
3496 #: build/C/man3/mallopt.3:556
3499 " p = malloc(1000);\n"
3500 " if (p == NULL) {\n"
3501 " fprintf(stderr, \"malloc() failed\");\n"
3502 " exit(EXIT_FAILURE);\n"
3507 #: build/C/man3/mallopt.3:559
3511 " printf(\"main(): returned from first free() call\\en\");\n"
3515 #: build/C/man3/mallopt.3:562
3519 " printf(\"main(): returned from second free() call\\en\");\n"
3523 #: build/C/man3/mallopt.3:580
3525 "B<mmap>(2), B<sbrk>(2), B<mallinfo>(3), B<malloc>(3), B<malloc_hook>(3), "
3526 "B<malloc_info>(3), B<malloc_stats>(3), B<malloc_trim>(3), B<mcheck>(3), "
3527 "B<mtrace>(3), B<posix_memalign>(3)"
3531 #: build/C/man3/mcheck.3:25
3537 #: build/C/man3/mcheck.3:25
3543 #: build/C/man3/mcheck.3:28
3545 "mcheck, mcheck_check_all, mcheck_pedantic, mprobe - heap consistency "
3550 #: build/C/man3/mcheck.3:31
3552 msgid "B<#include E<lt>mcheck.hE<gt>>\n"
3556 #: build/C/man3/mcheck.3:33
3558 msgid "B<int mcheck(void (*>I<abortfunc>B<)(enum mcheck_status >I<mstatus>B<));>\n"
3562 #: build/C/man3/mcheck.3:35
3565 "B<int mcheck_pedantic(void (*>I<abortfunc>B<)(enum mcheck_status "
3566 ">I<mstatus>B<));>\n"
3570 #: build/C/man3/mcheck.3:37
3572 msgid "B<void mcheck_check_all(void);>\n"
3576 #: build/C/man3/mcheck.3:39
3578 msgid "B<enum mcheck_status mprobe(void *>I<ptr>B<);>\n"
3582 #: build/C/man3/mcheck.3:51
3584 "The B<mcheck>() function installs a set of debugging hooks for the "
3585 "B<malloc>(3) family of memory-allocation functions. These hooks cause "
3586 "certain consistency checks to be performed on the state of the heap. The "
3587 "checks can detect application errors such as freeing a block of memory more "
3588 "than once or corrupting the bookkeeping data structures that immediately "
3589 "precede a block of allocated memory."
3593 #: build/C/man3/mcheck.3:63
3595 "To be effective, the B<mcheck>() function must be called before the first "
3596 "call to B<malloc>(3) or a related function. In cases where this is "
3597 "difficult to ensure, linking the program with I<-lmcheck> inserts an "
3598 "implicit call to B<mcheck>() (with a NULL argument) before the first call "
3599 "to a memory-allocation function."
3603 #: build/C/man3/mcheck.3:71
3605 "The B<mcheck_pedantic>() function is similar to B<mcheck>(), but performs "
3606 "checks on all allocated blocks whenever one of the memory-allocation "
3607 "functions is called. This can be very slow!"
3611 #: build/C/man3/mcheck.3:78
3613 "The B<mcheck_check_all>() function causes an immediate check on all "
3614 "allocated blocks. This call is effective only if B<mcheck>() is called "
3619 #: build/C/man3/mcheck.3:91
3621 "If the system detects an inconsistency in the heap, the caller-supplied "
3622 "function pointed to by I<abortfunc> is invoked with a single argument "
3623 "argument, I<mstatus>, that indicates what type of inconsistency was "
3624 "detected. If I<abortfunc> is NULL, a default function prints an error "
3625 "message on I<stderr> and calls B<abort>(3)."
3629 #: build/C/man3/mcheck.3:103
3631 "The B<mprobe>() function performs a consistency check on the block of "
3632 "allocated memory pointed to by I<ptr>. The B<mcheck>() function should be "
3633 "called beforehand (otherwise B<mprobe>() returns B<MCHECK_DISABLED>)."
3637 #: build/C/man3/mcheck.3:111
3639 "The following list describes the values returned by B<mprobe>() or passed "
3640 "as the I<mstatus> argument when I<abortfunc> is invoked:"
3644 #: build/C/man3/mcheck.3:111
3646 msgid "B<MCHECK_DISABLED> (B<mprobe>() only)"
3650 #: build/C/man3/mcheck.3:116
3652 "B<mcheck>() was not called before the first memory allocation function was "
3653 "called. Consistency checking is not possible."
3657 #: build/C/man3/mcheck.3:116
3659 msgid "B<MCHECK_OK> (B<mprobe>() only)"
3663 #: build/C/man3/mcheck.3:119
3664 msgid "No inconsistency detected."
3668 #: build/C/man3/mcheck.3:119
3670 msgid "B<MCHECK_HEAD>"
3674 #: build/C/man3/mcheck.3:122
3675 msgid "Memory preceding an allocated block was clobbered."
3679 #: build/C/man3/mcheck.3:122
3681 msgid "B<MCHECK_TAIL>"
3685 #: build/C/man3/mcheck.3:125
3686 msgid "Memory following an allocated block was clobbered."
3690 #: build/C/man3/mcheck.3:125
3692 msgid "B<MCHECK_FREE>"
3696 #: build/C/man3/mcheck.3:129
3697 msgid "A block of memory was freed twice."
3701 #: build/C/man3/mcheck.3:134
3702 msgid "B<mcheck>() and B<mcheck_pedantic>() return 0 on success, or -1 on error."
3706 #: build/C/man3/mcheck.3:145
3708 "The B<mcheck_pedantic>() and B<mcheck_check_all>() functions are available "
3709 "since glibc 2.2. The B<mcheck>() and B<mprobe>() functions are present "
3710 "since at least glibc 2.0"
3713 #. But is MALLOC_CHECK_ slower?
3715 #: build/C/man3/mcheck.3:159
3717 "Linking a program with I<-lmcheck> and using the B<MALLOC_CHECK_> "
3718 "environment variable (described in B<mallopt>(3)) cause the same kinds of "
3719 "errors to be detected. But, using B<MALLOC_CHECK_> does not require the "
3720 "application to be relinked."
3724 #: build/C/man3/mcheck.3:165
3726 "The program below calls B<mcheck>() with a NULL argument and then frees the "
3727 "same block of memory twice. The following shell session demonstrates what "
3728 "happens when running the program:"
3732 #: build/C/man3/mcheck.3:170
3740 #: build/C/man3/mcheck.3:174
3743 "About to free a second time\n"
3744 "block freed twice\n"
3745 "Aborted (core dumped)\n"
3749 #: build/C/man3/mcheck.3:182
3752 "#include E<lt>stdlib.hE<gt>\n"
3753 "#include E<lt>stdio.hE<gt>\n"
3754 "#include E<lt>mcheck.hE<gt>\n"
3758 #: build/C/man3/mcheck.3:190
3761 " if (mcheck(NULL) != 0) {\n"
3762 " fprintf(stderr, \"mcheck() failed\\en\");\n"
3766 #: build/C/man3/mcheck.3:193
3769 " exit(EXIT_FAILURE);\n"
3774 #: build/C/man3/mcheck.3:195
3776 msgid " p = malloc(1000);\n"
3780 #: build/C/man3/mcheck.3:200
3783 " fprintf(stderr, \"About to free\\en\");\n"
3785 " fprintf(stderr, \"\\enAbout to free a second time\\en\");\n"
3790 #: build/C/man3/mcheck.3:208
3791 msgid "B<malloc>(3), B<mallopt>(3), B<mtrace>(3)"
3795 #: build/C/man2/mlock.2:26
3801 #: build/C/man2/mlock.2:26
3807 #: build/C/man2/mlock.2:29
3808 msgid "mlock, munlock, mlockall, munlockall - lock and unlock memory"
3812 #: build/C/man2/mlock.2:32 build/C/man2/mmap.2:46 build/C/man2/mmap2.2:35 build/C/man2/mprotect.2:44 build/C/man2/mremap.2:38
3814 msgid "B<#include E<lt>sys/mman.hE<gt>>\n"
3818 #: build/C/man2/mlock.2:35
3821 "B<int mlock(const void *>I<addr>B<, size_t >I<len>B<);>\n"
3822 "B<int munlock(const void *>I<addr>B<, size_t >I<len>B<);>\n"
3826 #: build/C/man2/mlock.2:38
3829 "B<int mlockall(int >I<flags>B<);>\n"
3830 "B<int munlockall(void);>\n"
3834 #: build/C/man2/mlock.2:54
3836 "B<mlock>() and B<mlockall>() respectively lock part or all of the calling "
3837 "process's virtual address space into RAM, preventing that memory from being "
3838 "paged to the swap area. B<munlock>() and B<munlockall>() perform the "
3839 "converse operation, respectively unlocking part or all of the calling "
3840 "process's virtual address space, so that pages in the specified virtual "
3841 "address range may once more to be swapped out if required by the kernel "
3842 "memory manager. Memory locking and unlocking are performed in units of "
3847 #: build/C/man2/mlock.2:54
3849 msgid "mlock() and munlock()"
3853 #: build/C/man2/mlock.2:64
3855 "B<mlock>() locks pages in the address range starting at I<addr> and "
3856 "continuing for I<len> bytes. All pages that contain a part of the specified "
3857 "address range are guaranteed to be resident in RAM when the call returns "
3858 "successfully; the pages are guaranteed to stay in RAM until later unlocked."
3862 #: build/C/man2/mlock.2:73
3864 "B<munlock>() unlocks pages in the address range starting at I<addr> and "
3865 "continuing for I<len> bytes. After this call, all pages that contain a part "
3866 "of the specified memory range can be moved to external swap space again by "
3871 #: build/C/man2/mlock.2:73
3873 msgid "mlockall() and munlockall()"
3877 #: build/C/man2/mlock.2:83
3879 "B<mlockall>() locks all pages mapped into the address space of the calling "
3880 "process. This includes the pages of the code, data and stack segment, as "
3881 "well as shared libraries, user space kernel data, shared memory, and "
3882 "memory-mapped files. All mapped pages are guaranteed to be resident in RAM "
3883 "when the call returns successfully; the pages are guaranteed to stay in RAM "
3884 "until later unlocked."
3888 #: build/C/man2/mlock.2:88
3890 "The I<flags> argument is constructed as the bitwise OR of one or more of the "
3891 "following constants:"
3895 #: build/C/man2/mlock.2:88
3897 msgid "B<MCL_CURRENT>"
3901 #: build/C/man2/mlock.2:92
3903 "Lock all pages which are currently mapped into the address space of the "
3908 #: build/C/man2/mlock.2:92
3910 msgid "B<MCL_FUTURE>"
3914 #: build/C/man2/mlock.2:99
3916 "Lock all pages which will become mapped into the address space of the "
3917 "process in the future. These could be for instance new pages required by a "
3918 "growing heap and stack as well as new memory-mapped files or shared memory "
3923 #: build/C/man2/mlock.2:112
3925 "If B<MCL_FUTURE> has been specified, then a later system call (e.g., "
3926 "B<mmap>(2), B<sbrk>(2), B<malloc>(3)), may fail if it would cause the number "
3927 "of locked bytes to exceed the permitted maximum (see below). In the same "
3928 "circumstances, stack growth may likewise fail: the kernel will deny stack "
3929 "expansion and deliver a B<SIGSEGV> signal to the process."
3933 #: build/C/man2/mlock.2:116
3935 "B<munlockall>() unlocks all pages mapped into the address space of the "
3940 #: build/C/man2/mlock.2:122
3942 "On success these system calls return 0. On error, -1 is returned, I<errno> "
3943 "is set appropriately, and no changes are made to any locks in the address "
3944 "space of the process."
3948 #: build/C/man2/mlock.2:131
3950 "(Linux 2.6.9 and later) the caller had a nonzero B<RLIMIT_MEMLOCK> soft "
3951 "resource limit, but tried to lock more memory than the limit permitted. "
3952 "This limit is not enforced if the process is privileged (B<CAP_IPC_LOCK>)."
3955 #. In the case of mlock(), this check is somewhat buggy: it doesn't
3956 #. take into account whether the to-be-locked range overlaps with
3957 #. already locked pages. Thus, suppose we allocate
3958 #. (num_physpages / 4 + 1) of memory, and lock those pages once using
3959 #. mlock(), and then lock the *same* page range a second time.
3960 #. In the case, the second mlock() call will fail, since the check
3961 #. calculates that the process is trying to lock (num_physpages / 2 + 2)
3962 #. pages, which of course is not true. (MTK, Nov 04, kernel 2.4.28)
3964 #: build/C/man2/mlock.2:143
3966 "(Linux 2.4 and earlier) the calling process tried to lock more than half of "
3970 #. SVr4 documents an additional EAGAIN error code.
3972 #: build/C/man2/mlock.2:149
3974 "The caller is not privileged, but needs privilege (B<CAP_IPC_LOCK>) to "
3975 "perform the requested operation."
3979 #: build/C/man2/mlock.2:154
3980 msgid "For B<mlock>() and B<munlock>():"
3984 #: build/C/man2/mlock.2:157
3985 msgid "Some or all of the specified address range could not be locked."
3989 #: build/C/man2/mlock.2:164
3991 "The result of the addition I<start>+I<len> was less than I<start> (e.g., the "
3992 "addition may have resulted in an overflow)."
3996 #: build/C/man2/mlock.2:169
3997 msgid "(Not on Linux) I<addr> was not a multiple of the page size."
4001 #: build/C/man2/mlock.2:173
4003 "Some of the specified address range does not correspond to mapped pages in "
4004 "the address space of the process."
4008 #: build/C/man2/mlock.2:176
4009 msgid "For B<mlockall>():"
4013 #: build/C/man2/mlock.2:179
4014 msgid "Unknown I<flags> were specified."
4018 #: build/C/man2/mlock.2:182
4019 msgid "For B<munlockall>():"
4023 #: build/C/man2/mlock.2:186
4024 msgid "(Linux 2.6.8 and earlier) The caller was not privileged (B<CAP_IPC_LOCK>)."
4028 #: build/C/man2/mlock.2:188
4029 msgid "POSIX.1-2001, SVr4."
4033 #: build/C/man2/mlock.2:188 build/C/man2/mmap.2:499 build/C/man2/msync.2:105
4035 msgid "AVAILABILITY"
4039 #: build/C/man2/mlock.2:200
4041 "On POSIX systems on which B<mlock>() and B<munlock>() are available, "
4042 "B<_POSIX_MEMLOCK_RANGE> is defined in I<E<lt>unistd.hE<gt>> and the number "
4043 "of bytes in a page can be determined from the constant B<PAGESIZE> (if "
4044 "defined) in I<E<lt>limits.hE<gt>> or by calling I<sysconf(_SC_PAGESIZE)>."
4047 #. POSIX.1-2001: It shall be defined to -1 or 0 or 200112L.
4048 #. -1: unavailable, 0: ask using sysconf().
4049 #. glibc defines it to 1.
4051 #: build/C/man2/mlock.2:213
4053 "On POSIX systems on which B<mlockall>() and B<munlockall>() are available, "
4054 "B<_POSIX_MEMLOCK> is defined in I<E<lt>unistd.hE<gt>> to a value greater "
4055 "than 0. (See also B<sysconf>(3).)"
4059 #: build/C/man2/mlock.2:231
4061 "Memory locking has two main applications: real-time algorithms and "
4062 "high-security data processing. Real-time applications require deterministic "
4063 "timing, and, like scheduling, paging is one major cause of unexpected "
4064 "program execution delays. Real-time applications will usually also switch "
4065 "to a real-time scheduler with B<sched_setscheduler>(2). Cryptographic "
4066 "security software often handles critical bytes like passwords or secret keys "
4067 "as data structures. As a result of paging, these secrets could be "
4068 "transferred onto a persistent swap store medium, where they might be "
4069 "accessible to the enemy long after the security software has erased the "
4070 "secrets in RAM and terminated. (But be aware that the suspend mode on "
4071 "laptops and some desktop computers will save a copy of the system's RAM to "
4072 "disk, regardless of memory locks.)"
4076 #: build/C/man2/mlock.2:244
4078 "Real-time processes that are using B<mlockall>() to prevent delays on page "
4079 "faults should reserve enough locked stack pages before entering the "
4080 "time-critical section, so that no page fault can be caused by function "
4081 "calls. This can be achieved by calling a function that allocates a "
4082 "sufficiently large automatic variable (an array) and writes to the memory "
4083 "occupied by this array in order to touch these stack pages. This way, "
4084 "enough pages will be mapped for the stack and can be locked into RAM. The "
4085 "dummy writes ensure that not even copy-on-write page faults can occur in the "
4090 #: build/C/man2/mlock.2:257
4092 "Memory locks are not inherited by a child created via B<fork>(2) and are "
4093 "automatically removed (unlocked) during an B<execve>(2) or when the process "
4094 "terminates. The B<mlockall>() B<MCL_FUTURE> setting is not inherited by a "
4095 "child created via B<fork>(2) and is cleared during an B<execve>(2)."
4099 #: build/C/man2/mlock.2:261
4101 "The memory lock on an address range is automatically removed if the address "
4102 "range is unmapped via B<munmap>(2)."
4106 #: build/C/man2/mlock.2:274
4108 "Memory locks do not stack, that is, pages which have been locked several "
4109 "times by calls to B<mlock>() or B<mlockall>() will be unlocked by a single "
4110 "call to B<munlock>() for the corresponding range or by B<munlockall>(). "
4111 "Pages which are mapped to several locations or by several processes stay "
4112 "locked into RAM as long as they are locked at least at one location or by at "
4113 "least one process."
4117 #: build/C/man2/mlock.2:285
4119 "Under Linux, B<mlock>() and B<munlock>() automatically round I<addr> down "
4120 "to the nearest page boundary. However, POSIX.1-2001 allows an "
4121 "implementation to require that I<addr> is page aligned, so portable "
4122 "applications should ensure this."
4126 #: build/C/man2/mlock.2:298
4128 "The I<VmLck> field of the Linux-specific I</proc/PID/status> file shows how "
4129 "many kilobytes of memory the process with ID I<PID> has locked using "
4130 "B<mlock>(), B<mlockall>(), and B<mmap>(2) B<MAP_LOCKED>."
4134 #: build/C/man2/mlock.2:298
4136 msgid "Limits and permissions"
4140 #: build/C/man2/mlock.2:305
4142 "In Linux 2.6.8 and earlier, a process must be privileged (B<CAP_IPC_LOCK>) "
4143 "in order to lock memory and the B<RLIMIT_MEMLOCK> soft resource limit "
4144 "defines a limit on how much memory the process may lock."
4148 #: build/C/man2/mlock.2:311
4150 "Since Linux 2.6.9, no limits are placed on the amount of memory that a "
4151 "privileged process can lock and the B<RLIMIT_MEMLOCK> soft resource limit "
4152 "instead defines a limit on how much memory an unprivileged process may lock."
4156 #: build/C/man2/mlock.2:319
4158 "In the 2.4 series Linux kernels up to and including 2.4.17, a bug caused the "
4159 "B<mlockall>() B<MCL_FUTURE> flag to be inherited across a B<fork>(2). This "
4160 "was rectified in kernel 2.4.18."
4163 #. See the following LKML thread:
4164 #. http://marc.theaimsgroup.com/?l=linux-kernel&m=113801392825023&w=2
4165 #. "Rationale for RLIMIT_MEMLOCK"
4168 #: build/C/man2/mlock.2:336
4170 "Since kernel 2.6.9, if a privileged process calls I<mlockall(MCL_FUTURE)> "
4171 "and later drops privileges (loses the B<CAP_IPC_LOCK> capability by, for "
4172 "example, setting its effective UID to a nonzero value), then subsequent "
4173 "memory allocations (e.g., B<mmap>(2), B<brk>(2)) will fail if the "
4174 "B<RLIMIT_MEMLOCK> resource limit is encountered."
4178 #: build/C/man2/mlock.2:343
4180 "B<mmap>(2), B<setrlimit>(2), B<shmctl>(2), B<sysconf>(3), B<proc>(5), "
4181 "B<capabilities>(7)"
4185 #: build/C/man2/mmap.2:40
4191 #: build/C/man2/mmap.2:40
4197 #: build/C/man2/mmap.2:43
4198 msgid "mmap, munmap - map or unmap files or devices into memory"
4202 #: build/C/man2/mmap.2:51
4205 "B<void *mmap(void *>I<addr>B<, size_t >I<length>B<, int >I<prot>B<, int "
4207 "B< int >I<fd>B<, off_t >I<offset>B<);>\n"
4208 "B<int munmap(void *>I<addr>B<, size_t >I<length>B<);>\n"
4212 #: build/C/man2/mmap.2:54
4213 msgid "See NOTES for information on feature test macro requirements."
4217 #: build/C/man2/mmap.2:63
4219 "B<mmap>() creates a new mapping in the virtual address space of the calling "
4220 "process. The starting address for the new mapping is specified in I<addr>. "
4221 "The I<length> argument specifies the length of the mapping."
4224 #. Before Linux 2.6.24, the address was rounded up to the next page
4225 #. boundary; since 2.6.24, it is rounded down!
4227 #: build/C/man2/mmap.2:77
4229 "If I<addr> is NULL, then the kernel chooses the address at which to create "
4230 "the mapping; this is the most portable method of creating a new mapping. If "
4231 "I<addr> is not NULL, then the kernel takes it as a hint about where to place "
4232 "the mapping; on Linux, the mapping will be created at a nearby page "
4233 "boundary. The address of the new mapping is returned as the result of the "
4238 #: build/C/man2/mmap.2:89
4240 "The contents of a file mapping (as opposed to an anonymous mapping; see "
4241 "B<MAP_ANONYMOUS> below), are initialized using I<length> bytes starting at "
4242 "offset I<offset> in the file (or other object) referred to by the file "
4243 "descriptor I<fd>. I<offset> must be a multiple of the page size as returned "
4244 "by I<sysconf(_SC_PAGE_SIZE)>."
4248 #: build/C/man2/mmap.2:97
4250 "The I<prot> argument describes the desired memory protection of the mapping "
4251 "(and must not conflict with the open mode of the file). It is either "
4252 "B<PROT_NONE> or the bitwise OR of one or more of the following flags:"
4256 #: build/C/man2/mmap.2:97 build/C/man2/mprotect.2:73
4258 msgid "B<PROT_EXEC>"
4262 #: build/C/man2/mmap.2:100
4263 msgid "Pages may be executed."
4267 #: build/C/man2/mmap.2:100 build/C/man2/mprotect.2:67
4269 msgid "B<PROT_READ>"
4273 #: build/C/man2/mmap.2:103
4274 msgid "Pages may be read."
4278 #: build/C/man2/mmap.2:103 build/C/man2/mprotect.2:70
4280 msgid "B<PROT_WRITE>"
4284 #: build/C/man2/mmap.2:106
4285 msgid "Pages may be written."
4289 #: build/C/man2/mmap.2:106 build/C/man2/mprotect.2:64
4291 msgid "B<PROT_NONE>"
4295 #: build/C/man2/mmap.2:109
4296 msgid "Pages may not be accessed."
4300 #: build/C/man2/mmap.2:118
4302 "The I<flags> argument determines whether updates to the mapping are visible "
4303 "to other processes mapping the same region, and whether updates are carried "
4304 "through to the underlying file. This behavior is determined by including "
4305 "exactly one of the following values in I<flags>:"
4309 #: build/C/man2/mmap.2:118
4311 msgid "B<MAP_SHARED>"
4315 #: build/C/man2/mmap.2:128
4317 "Share this mapping. Updates to the mapping are visible to other processes "
4318 "that map this file, and are carried through to the underlying file. The "
4319 "file may not actually be updated until B<msync>(2) or B<munmap>() is "
4324 #: build/C/man2/mmap.2:128
4326 msgid "B<MAP_PRIVATE>"
4330 #: build/C/man2/mmap.2:137
4332 "Create a private copy-on-write mapping. Updates to the mapping are not "
4333 "visible to other processes mapping the same file, and are not carried "
4334 "through to the underlying file. It is unspecified whether changes made to "
4335 "the file after the B<mmap>() call are visible in the mapped region."
4339 #: build/C/man2/mmap.2:139
4340 msgid "Both of these flags are described in POSIX.1-2001."
4344 #: build/C/man2/mmap.2:142
4345 msgid "In addition, zero or more of the following values can be ORed in I<flags>:"
4349 #: build/C/man2/mmap.2:142
4351 msgid "B<MAP_32BIT> (since Linux 2.4.20, 2.6)"
4354 #. See http://lwn.net/Articles/294642 "Tangled up in threads", 19 Aug 08
4356 #: build/C/man2/mmap.2:158
4358 "Put the mapping into the first 2 Gigabytes of the process address space. "
4359 "This flag is supported only on x86-64, for 64-bit programs. It was added to "
4360 "allow thread stacks to be allocated somewhere in the first 2GB of memory, so "
4361 "as to improve context-switch performance on some early 64-bit processors. "
4362 "Modern x86-64 processors no longer have this performance problem, so use of "
4363 "this flag is not required on those systems. The B<MAP_32BIT> flag is "
4364 "ignored when B<MAP_FIXED> is set."
4368 #: build/C/man2/mmap.2:158
4374 #: build/C/man2/mmap.2:163
4375 msgid "Synonym for B<MAP_ANONYMOUS>. Deprecated."
4379 #: build/C/man2/mmap.2:163
4381 msgid "B<MAP_ANONYMOUS>"
4385 #: build/C/man2/mmap.2:185
4387 "The mapping is not backed by any file; its contents are initialized to "
4388 "zero. The I<fd> and I<offset> arguments are ignored; however, some "
4389 "implementations require I<fd> to be -1 if B<MAP_ANONYMOUS> (or B<MAP_ANON>) "
4390 "is specified, and portable applications should ensure this. The use of "
4391 "B<MAP_ANONYMOUS> in conjunction with B<MAP_SHARED> is supported on Linux "
4392 "only since kernel 2.4."
4396 #: build/C/man2/mmap.2:185
4398 msgid "B<MAP_DENYWRITE>"
4401 #. Introduced in 1.1.36, removed in 1.3.24.
4403 #: build/C/man2/mmap.2:193
4405 "This flag is ignored. (Long ago, it signaled that attempts to write to the "
4406 "underlying file should fail with B<ETXTBUSY>. But this was a source of "
4407 "denial-of-service attacks.)"
4411 #: build/C/man2/mmap.2:193
4413 msgid "B<MAP_EXECUTABLE>"
4416 #. Introduced in 1.1.38, removed in 1.3.24. Flag tested in proc_follow_link.
4417 #. (Long ago, it signaled that the underlying file is an executable.
4418 #. However, that information was not really used anywhere.)
4419 #. Linus talked about DOS related to MAP_EXECUTABLE, but he was thinking of
4422 #: build/C/man2/mmap.2:201
4423 msgid "This flag is ignored."
4427 #: build/C/man2/mmap.2:201
4432 #. On some systems, this was required as the opposite of
4433 #. MAP_ANONYMOUS -- mtk, 1 May 2007
4435 #: build/C/man2/mmap.2:207
4436 msgid "Compatibility flag. Ignored."
4440 #: build/C/man2/mmap.2:207
4442 msgid "B<MAP_FIXED>"
4446 #: build/C/man2/mmap.2:225
4448 "Don't interpret I<addr> as a hint: place the mapping at exactly that "
4449 "address. I<addr> must be a multiple of the page size. If the memory region "
4450 "specified by I<addr> and I<len> overlaps pages of any existing mapping(s), "
4451 "then the overlapped part of the existing mapping(s) will be discarded. If "
4452 "the specified address cannot be used, B<mmap>() will fail. Because "
4453 "requiring a fixed address for a mapping is less portable, the use of this "
4454 "option is discouraged."
4458 #: build/C/man2/mmap.2:225
4460 msgid "B<MAP_GROWSDOWN>"
4464 #: build/C/man2/mmap.2:230
4466 "Used for stacks. Indicates to the kernel virtual memory system that the "
4467 "mapping should extend downward in memory."
4471 #: build/C/man2/mmap.2:230
4473 msgid "B<MAP_HUGETLB> (since Linux 2.6.32)"
4477 #: build/C/man2/mmap.2:236
4479 "Allocate the mapping using \"huge pages.\" See the Linux kernel source file "
4480 "I<Documentation/vm/hugetlbpage.txt> for further information."
4484 #: build/C/man2/mmap.2:236
4486 msgid "B<MAP_LOCKED> (since Linux 2.5.37)"
4489 #. If set, the mapped pages will not be swapped out.
4491 #: build/C/man2/mmap.2:242
4493 "Lock the pages of the mapped region into memory in the manner of "
4494 "B<mlock>(2). This flag is ignored in older kernels."
4498 #: build/C/man2/mmap.2:242
4500 msgid "B<MAP_NONBLOCK> (since Linux 2.5.46)"
4504 #: build/C/man2/mmap.2:257
4506 "Only meaningful in conjunction with B<MAP_POPULATE>. Don't perform "
4507 "read-ahead: create page tables entries only for pages that are already "
4508 "present in RAM. Since Linux 2.6.23, this flag causes B<MAP_POPULATE> to do "
4509 "nothing. One day the combination of B<MAP_POPULATE> and B<MAP_NONBLOCK> may "
4514 #: build/C/man2/mmap.2:257
4516 msgid "B<MAP_NORESERVE>"
4520 #: build/C/man2/mmap.2:272
4522 "Do not reserve swap space for this mapping. When swap space is reserved, "
4523 "one has the guarantee that it is possible to modify the mapping. When swap "
4524 "space is not reserved one might get B<SIGSEGV> upon a write if no physical "
4525 "memory is available. See also the discussion of the file "
4526 "I</proc/sys/vm/overcommit_memory> in B<proc>(5). In kernels before 2.6, "
4527 "this flag had effect only for private writable mappings."
4531 #: build/C/man2/mmap.2:272
4533 msgid "B<MAP_POPULATE> (since Linux 2.5.46)"
4537 #: build/C/man2/mmap.2:279
4539 "Populate (prefault) page tables for a mapping. For a file mapping, this "
4540 "causes read-ahead on the file. Later accesses to the mapping will not be "
4541 "blocked by page faults. B<MAP_POPULATE> is supported for private mappings "
4542 "only since Linux 2.6.23."
4546 #: build/C/man2/mmap.2:279
4548 msgid "B<MAP_STACK> (since Linux 2.6.27)"
4551 #. See http://lwn.net/Articles/294642 "Tangled up in threads", 19 Aug 08
4552 #. commit cd98a04a59e2f94fa64d5bf1e26498d27427d5e7
4553 #. http://thread.gmane.org/gmane.linux.kernel/720412
4554 #. "pthread_create() slow for many threads; also time to revisit 64b
4555 #. context switch optimization?"
4557 #: build/C/man2/mmap.2:292
4559 "Allocate the mapping at an address suitable for a process or thread stack. "
4560 "This flag is currently a no-op, but is used in the glibc threading "
4561 "implementation so that if some architectures require special treatment for "
4562 "stack allocations, support can later be transparently implemented for glibc."
4566 #: build/C/man2/mmap.2:292
4568 msgid "B<MAP_UNINITIALIZED> (since Linux 2.6.33)"
4572 #: build/C/man2/mmap.2:302
4574 "Don't clear anonymous pages. This flag is intended to improve performance "
4575 "on embedded devices. This flag is honored only if the kernel was configured "
4576 "with the B<CONFIG_MMAP_ALLOW_UNINITIALIZED> option. Because of the security "
4577 "implications, that option is normally enabled only on embedded devices "
4578 "(i.e., devices where one has complete control of the contents of user "
4583 #: build/C/man2/mmap.2:310
4585 "Of the above flags, only B<MAP_FIXED> is specified in POSIX.1-2001. "
4586 "However, most systems also support B<MAP_ANONYMOUS> (or its synonym "
4591 #: build/C/man2/mmap.2:317
4593 "Some systems document the additional flags B<MAP_AUTOGROW>, "
4594 "B<MAP_AUTORESRV>, B<MAP_COPY>, and B<MAP_LOCAL>."
4598 #: build/C/man2/mmap.2:323
4600 "Memory mapped by B<mmap>() is preserved across B<fork>(2), with the same "
4605 #: build/C/man2/mmap.2:331
4607 "A file is mapped in multiples of the page size. For a file that is not a "
4608 "multiple of the page size, the remaining memory is zeroed when mapped, and "
4609 "writes to that region are not written out to the file. The effect of "
4610 "changing the size of the underlying file of a mapping on the pages that "
4611 "correspond to added or removed regions of the file is unspecified."
4615 #: build/C/man2/mmap.2:331
4621 #: build/C/man2/mmap.2:341
4623 "The B<munmap>() system call deletes the mappings for the specified address "
4624 "range, and causes further references to addresses within the range to "
4625 "generate invalid memory references. The region is also automatically "
4626 "unmapped when the process is terminated. On the other hand, closing the "
4627 "file descriptor does not unmap the region."
4631 #: build/C/man2/mmap.2:351
4633 "The address I<addr> must be a multiple of the page size. All pages "
4634 "containing a part of the indicated range are unmapped, and subsequent "
4635 "references to these pages will generate B<SIGSEGV>. It is not an error if "
4636 "the indicated range does not contain any mapped pages."
4640 #: build/C/man2/mmap.2:351
4642 msgid "Timestamps changes for file-backed mappings"
4646 #: build/C/man2/mmap.2:358
4648 "For file-backed mappings, the I<st_atime> field for the mapped file may be "
4649 "updated at any time between the B<mmap>() and the corresponding unmapping; "
4650 "the first reference to a mapped page will update the field if it has not "
4655 #: build/C/man2/mmap.2:375
4657 "The I<st_ctime> and I<st_mtime> field for a file mapped with B<PROT_WRITE> "
4658 "and B<MAP_SHARED> will be updated after a write to the mapped region, and "
4659 "before a subsequent B<msync>(2) with the B<MS_SYNC> or B<MS_ASYNC> flag, if "
4664 #: build/C/man2/mmap.2:392
4666 "On success, B<mmap>() returns a pointer to the mapped area. On error, the "
4667 "value B<MAP_FAILED> (that is, I<(void\\ *)\\ -1>) is returned, and I<errno> "
4668 "is set appropriately. On success, B<munmap>() returns 0, on failure -1, "
4669 "and I<errno> is set (probably to B<EINVAL>)."
4673 #: build/C/man2/mmap.2:393 build/C/man2/mprotect.2:86 build/C/man3/shm_open.3:187 build/C/man3/shm_open.3:192 build/C/man2/shmctl.2:306 build/C/man2/shmget.2:189 build/C/man2/shmop.2:191
4679 #: build/C/man2/mmap.2:411
4681 "A file descriptor refers to a non-regular file. Or a file mapping was "
4682 "requested, but I<fd> is not open for reading. Or B<MAP_SHARED> was "
4683 "requested and B<PROT_WRITE> is set, but I<fd> is not open in read/write "
4684 "(B<O_RDWR>) mode. Or B<PROT_WRITE> is set, but the file is append-only."
4688 #: build/C/man2/mmap.2:415
4690 "The file has been locked, or too much memory has been locked (see "
4695 #: build/C/man2/mmap.2:421
4696 msgid "I<fd> is not a valid file descriptor (and B<MAP_ANONYMOUS> was not set)."
4700 #: build/C/man2/mmap.2:429
4702 "We don't like I<addr>, I<length>, or I<offset> (e.g., they are too large, or "
4703 "not aligned on a page boundary)."
4707 #: build/C/man2/mmap.2:434
4708 msgid "(since Linux 2.6.12) I<length> was 0."
4712 #: build/C/man2/mmap.2:442
4714 "I<flags> contained neither B<MAP_PRIVATE> or B<MAP_SHARED>, or contained "
4715 "both of these values."
4719 #: build/C/man2/mmap.2:442 build/C/man3/shm_open.3:229 build/C/man2/shmget.2:205
4724 #. [2.6.7] shmem_zero_setup()-->shmem_file_setup()-->get_empty_filp()
4726 #: build/C/man2/mmap.2:450 build/C/man2/shmget.2:209
4727 msgid "The system limit on the total number of open files has been reached."
4731 #: build/C/man2/mmap.2:454
4733 "The underlying filesystem of the specified file does not support memory "
4738 #: build/C/man2/mmap.2:458
4740 "No memory is available, or the process's maximum number of mappings would "
4741 "have been exceeded."
4744 #. (Since 2.4.25 / 2.6.0.)
4746 #: build/C/man2/mmap.2:467
4748 "The I<prot> argument asks for B<PROT_EXEC> but the mapped area belongs to a "
4749 "file on a filesystem that was mounted no-exec."
4753 #: build/C/man2/mmap.2:473
4755 "B<MAP_DENYWRITE> was set but the object specified by I<fd> is open for "
4760 #: build/C/man2/mmap.2:473 build/C/man2/shmctl.2:348
4762 msgid "B<EOVERFLOW>"
4766 #: build/C/man2/mmap.2:485
4768 "On 32-bit architecture together with the large file extension (i.e., using "
4769 "64-bit I<off_t>): the number of pages used for I<length> plus number of "
4770 "pages used for I<offset> would overflow I<unsigned long> (32 bits)."
4774 #: build/C/man2/mmap.2:487
4775 msgid "Use of a mapped region can result in these signals:"
4779 #: build/C/man2/mmap.2:487
4785 #: build/C/man2/mmap.2:490
4786 msgid "Attempted write into a region mapped as read-only."
4790 #: build/C/man2/mmap.2:490
4796 #: build/C/man2/mmap.2:495
4798 "Attempted access to a portion of the buffer that does not correspond to the "
4799 "file (for example, beyond the end of the file, including the case where "
4800 "another process has truncated the file)."
4803 #. SVr4 documents additional error codes ENXIO and ENODEV.
4804 #. SUSv2 documents additional error codes EMFILE and EOVERFLOW.
4806 #: build/C/man2/mmap.2:499
4807 msgid "SVr4, 4.4BSD, POSIX.1-2001."
4810 #. POSIX.1-2001: It shall be defined to -1 or 0 or 200112L.
4811 #. -1: unavailable, 0: ask using sysconf().
4812 #. glibc defines it to 1.
4814 #: build/C/man2/mmap.2:513
4816 "On POSIX systems on which B<mmap>(), B<msync>(2) and B<munmap>() are "
4817 "available, B<_POSIX_MAPPED_FILES> is defined in I<E<lt>unistd.hE<gt>> to a "
4818 "value greater than 0. (See also B<sysconf>(3).)"
4821 #. Since around glibc 2.1/2.2, depending on the platform.
4823 #: build/C/man2/mmap.2:528
4825 "This page describes the interface provided by the glibc B<mmap>() wrapper "
4826 "function. Originally, this function invoked a system call of the same "
4827 "name. Since kernel 2.4, that system call has been superseded by "
4828 "B<mmap2>(2), and nowadays the glibc B<mmap>() wrapper function invokes "
4829 "B<mmap2>(2) with a suitably adjusted value for I<offset>."
4833 #: build/C/man2/mmap.2:541
4835 "On some hardware architectures (e.g., i386), B<PROT_WRITE> implies "
4836 "B<PROT_READ>. It is architecture dependent whether B<PROT_READ> implies "
4837 "B<PROT_EXEC> or not. Portable programs should always set B<PROT_EXEC> if "
4838 "they intend to execute code in the new mapping."
4842 #: build/C/man2/mmap.2:556
4844 "The portable way to create a mapping is to specify I<addr> as 0 (NULL), and "
4845 "omit B<MAP_FIXED> from I<flags>. In this case, the system chooses the "
4846 "address for the mapping; the address is chosen so as not to conflict with "
4847 "any existing mapping, and will not be 0. If the B<MAP_FIXED> flag is "
4848 "specified, and I<addr> is 0 (NULL), then the mapped address will be 0 "
4853 #: build/C/man2/mmap.2:585
4855 "Certain I<flags> constants are defined only if either B<_BSD_SOURCE> or "
4856 "B<_SVID_SOURCE> is defined. (Requiring B<_GNU_SOURCE> also suffices, and "
4857 "requiring that macro specifically would have been more logical, since these "
4858 "flags are all Linux-specific.) The relevant flags are: B<MAP_32BIT>, "
4859 "B<MAP_ANONYMOUS> (and the synonym B<MAP_ANON>), B<MAP_DENYWRITE>, "
4860 "B<MAP_EXECUTABLE>, B<MAP_FILE>, B<MAP_GROWSDOWN>, B<MAP_HUGETLB>, "
4861 "B<MAP_LOCKED>, B<MAP_NONBLOCK>, B<MAP_NORESERVE>, B<MAP_POPULATE>, and "
4866 #: build/C/man2/mmap.2:590
4868 "On Linux there are no guarantees like those suggested above under "
4869 "B<MAP_NORESERVE>. By default, any process can be killed at any moment when "
4870 "the system runs out of memory."
4874 #: build/C/man2/mmap.2:597
4876 "In kernels before 2.6.7, the B<MAP_POPULATE> flag has effect only if I<prot> "
4877 "is specified as B<PROT_NONE>."
4881 #: build/C/man2/mmap.2:612
4883 "SUSv3 specifies that B<mmap>() should fail if I<length> is 0. However, in "
4884 "kernels before 2.6.12, B<mmap>() succeeded in this case: no mapping was "
4885 "created and the call returned I<addr>. Since kernel 2.6.12, B<mmap>() "
4886 "fails with the error B<EINVAL> for this case."
4890 #: build/C/man2/mmap.2:628
4892 "POSIX specifies that the system shall always zero fill any partial page at "
4893 "the end of the object and that system will never write any modification of "
4894 "the object beyond its end. On Linux, when you write data to such partial "
4895 "page after the end of the object, the data stays in the page cache even "
4896 "after the file is closed and unmapped and even though the data is never "
4897 "written to the file itself, subsequent mappings may see the modified "
4898 "content. In some cases, this could be fixed by calling B<msync>(2) before "
4899 "the unmap takes place; however, this doesn't work on tmpfs (for example, "
4900 "when using POSIX shared memory interface documented in B<shm_overview>(7))."
4904 #: build/C/man2/mmap.2:640
4906 "The following program prints part of the file specified in its first "
4907 "command-line argument to standard output. The range of bytes to be printed "
4908 "is specified via offset and length values in the second and third "
4909 "command-line arguments. The program creates a memory mapping of the "
4910 "required pages of the file and then uses B<write>(2) to output the desired "
4915 #: build/C/man2/mmap.2:648
4918 "#include E<lt>sys/mman.hE<gt>\n"
4919 "#include E<lt>sys/stat.hE<gt>\n"
4920 "#include E<lt>fcntl.hE<gt>\n"
4921 "#include E<lt>stdio.hE<gt>\n"
4922 "#include E<lt>stdlib.hE<gt>\n"
4923 "#include E<lt>unistd.hE<gt>\n"
4927 #: build/C/man2/mmap.2:651 build/C/man2/mprotect.2:178
4930 "#define handle_error(msg) \\e\n"
4931 " do { perror(msg); exit(EXIT_FAILURE); } while (0)\n"
4935 #: build/C/man2/mmap.2:661
4939 "main(int argc, char *argv[])\n"
4943 " struct stat sb;\n"
4944 " off_t offset, pa_offset;\n"
4950 #: build/C/man2/mmap.2:666
4953 " if (argc E<lt> 3 || argc E<gt> 4) {\n"
4954 " fprintf(stderr, \"%s file offset [length]\\en\", argv[0]);\n"
4955 " exit(EXIT_FAILURE);\n"
4960 #: build/C/man2/mmap.2:670
4963 " fd = open(argv[1], O_RDONLY);\n"
4965 " handle_error(\"open\");\n"
4969 #: build/C/man2/mmap.2:673
4972 " if (fstat(fd, &sb) == -1) /* To obtain file size */\n"
4973 " handle_error(\"fstat\");\n"
4977 #: build/C/man2/mmap.2:677
4980 " offset = atoi(argv[2]);\n"
4981 " pa_offset = offset & ~(sysconf(_SC_PAGE_SIZE) - 1);\n"
4982 " /* offset for mmap() must be page aligned */\n"
4986 #: build/C/man2/mmap.2:682
4989 " if (offset E<gt>= sb.st_size) {\n"
4990 " fprintf(stderr, \"offset is past end of file\\en\");\n"
4991 " exit(EXIT_FAILURE);\n"
4996 #: build/C/man2/mmap.2:688
4999 " if (argc == 4) {\n"
5000 " length = atoi(argv[3]);\n"
5001 " if (offset + length E<gt> sb.st_size)\n"
5002 " length = sb.st_size - offset;\n"
5003 " /* Can\\(aqt display bytes past end of file */\n"
5007 #: build/C/man2/mmap.2:692
5010 " } else { /* No length arg ==E<gt> display to end of file */\n"
5011 " length = sb.st_size - offset;\n"
5016 #: build/C/man2/mmap.2:697
5019 " addr = mmap(NULL, length + offset - pa_offset, PROT_READ,\n"
5020 " MAP_PRIVATE, fd, pa_offset);\n"
5021 " if (addr == MAP_FAILED)\n"
5022 " handle_error(\"mmap\");\n"
5026 #: build/C/man2/mmap.2:702
5029 " s = write(STDOUT_FILENO, addr + offset - pa_offset, length);\n"
5030 " if (s != length) {\n"
5032 " handle_error(\"write\");\n"
5036 #: build/C/man2/mmap.2:706
5039 " fprintf(stderr, \"partial write\");\n"
5040 " exit(EXIT_FAILURE);\n"
5045 #: build/C/man2/mmap.2:723
5047 "B<getpagesize>(2), B<mincore>(2), B<mlock>(2), B<mmap2>(2), B<mprotect>(2), "
5048 "B<mremap>(2), B<msync>(2), B<remap_file_pages>(2), B<setrlimit>(2), "
5049 "B<shmat>(2), B<shm_open>(3), B<shm_overview>(7)"
5053 #: build/C/man2/mmap.2:730
5055 "The descriptions of the following files in B<proc>(5): I</proc/[pid]/maps>, "
5056 "I</proc/[pid]/map_files>, and I</proc/[pid]/smaps>."
5060 #: build/C/man2/mmap.2:735 build/C/man2/msync.2:151
5061 msgid "B.O. Gallmeister, POSIX.4, O'Reilly, pp. 128-129 and 389-391."
5065 #: build/C/man2/mmap2.2:29
5071 #: build/C/man2/mmap2.2:29
5077 #: build/C/man2/mmap2.2:32
5078 msgid "mmap2 - map files or devices into memory"
5082 #: build/C/man2/mmap2.2:38
5085 "B<void *mmap2(void *>I<addr>B<, size_t >I<length>B<, int >I<prot>B<,>\n"
5086 "B< int >I<flags>B<, int >I<fd>B<, off_t >I<pgoffset>B<);>\n"
5090 #: build/C/man2/mmap2.2:43
5092 "This is probably not the system call that you are interested in; instead, "
5093 "see B<mmap>(2), which describes the glibc wrapper function that invokes this "
5098 #: build/C/man2/mmap2.2:54
5100 "The B<mmap2>() system call provides the same interface as B<mmap>(2), "
5101 "except that the final argument specifies the offset into the file in "
5102 "4096-byte units (instead of bytes, as is done by B<mmap>(2)). This enables "
5103 "applications that use a 32-bit I<off_t> to map large files (up to 2^44 "
5108 #: build/C/man2/mmap2.2:61
5110 "On success, B<mmap2>() returns a pointer to the mapped area. On error, -1 "
5111 "is returned and I<errno> is set appropriately."
5115 #: build/C/man2/mmap2.2:65
5116 msgid "Problem with getting the data from user space."
5120 #: build/C/man2/mmap2.2:70
5122 "(Various platforms where the page size is not 4096 bytes.) I<offset\\ *\\ "
5123 "4096> is not a multiple of the system page size."
5127 #: build/C/man2/mmap2.2:74
5128 msgid "B<mmap2>() can also return any of the errors described in B<mmap>(2)."
5132 #: build/C/man2/mmap2.2:77
5133 msgid "B<mmap2>() is available since Linux 2.3.31."
5137 #: build/C/man2/mmap2.2:79 build/C/man2/subpage_prot.2:98
5138 msgid "This system call is Linux-specific."
5142 #: build/C/man2/mmap2.2:86
5144 "On architectures where this system call is present, the glibc B<mmap>() "
5145 "wrapper function invokes this system call rather than the B<mmap>(2) system "
5150 #: build/C/man2/mmap2.2:88
5151 msgid "This system call does not exist on x86-64."
5154 #. ia64 can have page sizes ranging from 4kB to 64kB.
5155 #. On cris, it looks like the unit might also be the page size,
5156 #. which is 8192 bytes. -- mtk, June 2007
5158 #: build/C/man2/mmap2.2:95
5160 "On ia64, the unit for I<offset> is actually the system page size, rather "
5165 #: build/C/man2/mmap2.2:101
5166 msgid "B<getpagesize>(2), B<mmap>(2), B<mremap>(2), B<msync>(2), B<shm_open>(3)"
5170 #: build/C/man2/mprotect.2:38
5176 #: build/C/man2/mprotect.2:38
5182 #: build/C/man2/mprotect.2:41
5183 msgid "mprotect - set protection on a region of memory"
5187 #: build/C/man2/mprotect.2:46
5189 msgid "B<int mprotect(void *>I<addr>B<, size_t >I<len>B<, int >I<prot>B<);>\n"
5193 #: build/C/man2/mprotect.2:54
5195 "B<mprotect>() changes protection for the calling process's memory page(s) "
5196 "containing any part of the address range in the interval [I<addr>,\\ "
5197 "I<addr>+I<len>-1]. I<addr> must be aligned to a page boundary."
5201 #: build/C/man2/mprotect.2:59
5203 "If the calling process tries to access memory in a manner that violates the "
5204 "protection, then the kernel generates a B<SIGSEGV> signal for the process."
5208 #: build/C/man2/mprotect.2:64
5210 "I<prot> is either B<PROT_NONE> or a bitwise-or of the other values in the "
5215 #: build/C/man2/mprotect.2:67
5216 msgid "The memory cannot be accessed at all."
5220 #: build/C/man2/mprotect.2:70
5221 msgid "The memory can be read."
5225 #: build/C/man2/mprotect.2:73
5226 msgid "The memory can be modified."
5230 #. Document PROT_GROWSUP and PROT_GROWSDOWN
5232 #: build/C/man2/mprotect.2:78
5233 msgid "The memory can be executed."
5237 #: build/C/man2/mprotect.2:85
5239 "On success, B<mprotect>() returns zero. On error, -1 is returned, and "
5240 "I<errno> is set appropriately."
5244 #: build/C/man2/mprotect.2:95
5246 "The memory cannot be given the specified access. This can happen, for "
5247 "example, if you B<mmap>(2) a file to which you have read-only access, then "
5248 "ask B<mprotect>() to mark it B<PROT_WRITE>."
5251 #. Or: both PROT_GROWSUP and PROT_GROWSDOWN were specified in 'prot'.
5253 #: build/C/man2/mprotect.2:100
5254 msgid "I<addr> is not a valid pointer, or not a multiple of the system page size."
5258 #: build/C/man2/mprotect.2:103
5259 msgid "Internal kernel structures could not be allocated."
5263 #: build/C/man2/mprotect.2:113
5265 "Addresses in the range [I<addr>, I<addr>+I<len>-1] are invalid for the "
5266 "address space of the process, or specify one or more pages that are not "
5267 "mapped. (Before kernel 2.4.19, the error B<EFAULT> was incorrectly produced "
5271 #. SVr4 defines an additional error
5272 #. code EAGAIN. The SVr4 error conditions don't map neatly onto Linux's.
5274 #: build/C/man2/mprotect.2:122
5276 "SVr4, POSIX.1-2001. POSIX says that the behavior of B<mprotect>() is "
5277 "unspecified if it is applied to a region of memory that was not obtained via "
5282 #: build/C/man2/mprotect.2:129
5284 "On Linux it is always permissible to call B<mprotect>() on any address in a "
5285 "process's address space (except for the kernel vsyscall area). In "
5286 "particular it can be used to change existing code mappings to be writable."
5290 #: build/C/man2/mprotect.2:139
5292 "Whether B<PROT_EXEC> has any effect different from B<PROT_READ> is "
5293 "architecture- and kernel version-dependent. On some hardware architectures "
5294 "(e.g., i386), B<PROT_WRITE> implies B<PROT_READ>."
5298 #: build/C/man2/mprotect.2:148
5300 "POSIX.1-2001 says that an implementation may permit access other than that "
5301 "specified in I<prot>, but at a minimum can allow write access only if "
5302 "B<PROT_WRITE> has been set, and must not allow any access if B<PROT_NONE> "
5307 #: build/C/man2/mprotect.2:154
5309 "The program below allocates four pages of memory, makes the third of these "
5310 "pages read-only, and then executes a loop that walks upward through the "
5311 "allocated region modifying bytes."
5315 #: build/C/man2/mprotect.2:157
5316 msgid "An example of what we might see when running the program is the following:"
5320 #: build/C/man2/mprotect.2:163
5324 "Start of region: 0x804c000\n"
5325 "Got SIGSEGV at address: 0x804e000\n"
5329 #: build/C/man2/mprotect.2:175
5332 "#include E<lt>unistd.hE<gt>\n"
5333 "#include E<lt>signal.hE<gt>\n"
5334 "#include E<lt>stdio.hE<gt>\n"
5335 "#include E<lt>malloc.hE<gt>\n"
5336 "#include E<lt>stdlib.hE<gt>\n"
5337 "#include E<lt>errno.hE<gt>\n"
5338 "#include E<lt>sys/mman.hE<gt>\n"
5342 #: build/C/man2/mprotect.2:180
5344 msgid "static char *buffer;\n"
5348 #: build/C/man2/mprotect.2:188
5352 "handler(int sig, siginfo_t *si, void *unused)\n"
5354 " printf(\"Got SIGSEGV at address: 0x%lx\\en\",\n"
5355 " (long) si-E<gt>si_addr);\n"
5356 " exit(EXIT_FAILURE);\n"
5361 #: build/C/man2/mprotect.2:195
5365 "main(int argc, char *argv[])\n"
5369 " struct sigaction sa;\n"
5373 #: build/C/man2/mprotect.2:201
5376 " sa.sa_flags = SA_SIGINFO;\n"
5377 " sigemptyset(&sa.sa_mask);\n"
5378 " sa.sa_sigaction = handler;\n"
5379 " if (sigaction(SIGSEGV, &sa, NULL) == -1)\n"
5380 " handle_error(\"sigaction\");\n"
5384 #: build/C/man2/mprotect.2:205
5387 " pagesize = sysconf(_SC_PAGE_SIZE);\n"
5388 " if (pagesize == -1)\n"
5389 " handle_error(\"sysconf\");\n"
5393 #: build/C/man2/mprotect.2:208
5396 " /* Allocate a buffer aligned on a page boundary;\n"
5397 " initial protection is PROT_READ | PROT_WRITE */\n"
5401 #: build/C/man2/mprotect.2:212
5404 " buffer = memalign(pagesize, 4 * pagesize);\n"
5405 " if (buffer == NULL)\n"
5406 " handle_error(\"memalign\");\n"
5410 #: build/C/man2/mprotect.2:214
5412 msgid " printf(\"Start of region: 0x%lx\\en\", (long) buffer);\n"
5416 #: build/C/man2/mprotect.2:218
5419 " if (mprotect(buffer + pagesize * 2, pagesize,\n"
5420 " PROT_READ) == -1)\n"
5421 " handle_error(\"mprotect\");\n"
5425 #: build/C/man2/mprotect.2:221
5428 " for (p = buffer ; ; )\n"
5429 " *(p++) = \\(aqa\\(aq;\n"
5433 #: build/C/man2/mprotect.2:225
5436 " printf(\"Loop completed\\en\"); /* Should never happen */\n"
5437 " exit(EXIT_SUCCESS);\n"
5442 #: build/C/man2/mprotect.2:229
5443 msgid "B<mmap>(2), B<sysconf>(3)"
5447 #: build/C/man2/mremap.2:30
5453 #: build/C/man2/mremap.2:30
5459 #: build/C/man2/mremap.2:33
5460 msgid "mremap - remap a virtual memory address"
5464 #: build/C/man2/mremap.2:36
5466 msgid "B<#define _GNU_SOURCE> /* See feature_test_macros(7) */\n"
5470 #: build/C/man2/mremap.2:41
5473 "B<void *mremap(void *>I<old_address>B<, size_t >I<old_size>B<,>\n"
5474 "B< size_t >I<new_size>B<, int >I<flags>B<, ... /* void "
5475 "*>I<new_address>B< */);>\n"
5479 #: build/C/man2/mremap.2:47
5481 "B<mremap>() expands (or shrinks) an existing memory mapping, potentially "
5482 "moving it at the same time (controlled by the I<flags> argument and the "
5483 "available virtual address space)."
5487 #: build/C/man2/mremap.2:61
5489 "I<old_address> is the old address of the virtual memory block that you want "
5490 "to expand (or shrink). Note that I<old_address> has to be page aligned. "
5491 "I<old_size> is the old size of the virtual memory block. I<new_size> is the "
5492 "requested size of the virtual memory block after the resize. An optional "
5493 "fifth argument, I<new_address>, may be provided; see the description of "
5494 "B<MREMAP_FIXED> below."
5498 #: build/C/man2/mremap.2:73
5500 "In Linux the memory is divided into pages. A user process has (one or) "
5501 "several linear virtual memory segments. Each virtual memory segment has one "
5502 "or more mappings to real memory pages (in the page table). Each virtual "
5503 "memory segment has its own protection (access rights), which may cause a "
5504 "segmentation violation if the memory is accessed incorrectly (e.g., writing "
5505 "to a read-only segment). Accessing virtual memory outside of the segments "
5506 "will also cause a segmentation violation."
5510 #: build/C/man2/mremap.2:81
5512 "B<mremap>() uses the Linux page table scheme. B<mremap>() changes the "
5513 "mapping between virtual addresses and memory pages. This can be used to "
5514 "implement a very efficient B<realloc>(3)."
5518 #: build/C/man2/mremap.2:83
5519 msgid "The I<flags> bit-mask argument may be 0, or include the following flag:"
5523 #: build/C/man2/mremap.2:83
5525 msgid "B<MREMAP_MAYMOVE>"
5529 #: build/C/man2/mremap.2:95
5531 "By default, if there is not sufficient space to expand a mapping at its "
5532 "current location, then B<mremap>() fails. If this flag is specified, then "
5533 "the kernel is permitted to relocate the mapping to a new virtual address, if "
5534 "necessary. If the mapping is relocated, then absolute pointers into the old "
5535 "mapping location become invalid (offsets relative to the starting address of "
5536 "the mapping should be employed)."
5540 #: build/C/man2/mremap.2:95
5542 msgid "B<MREMAP_FIXED> (since Linux 2.3.31)"
5546 #: build/C/man2/mremap.2:117
5548 "This flag serves a similar purpose to the B<MAP_FIXED> flag of B<mmap>(2). "
5549 "If this flag is specified, then B<mremap>() accepts a fifth argument, "
5550 "I<void\\ *new_address>, which specifies a page-aligned address to which the "
5551 "mapping must be moved. Any previous mapping at the address range specified "
5552 "by I<new_address> and I<new_size> is unmapped. If B<MREMAP_FIXED> is "
5553 "specified, then B<MREMAP_MAYMOVE> must also be specified."
5557 #: build/C/man2/mremap.2:127
5559 "If the memory segment specified by I<old_address> and I<old_size> is locked "
5560 "(using B<mlock>(2) or similar), then this lock is maintained when the "
5561 "segment is resized and/or relocated. As a consequence, the amount of memory "
5562 "locked by the process may change."
5566 #: build/C/man2/mremap.2:135
5568 "On success B<mremap>() returns a pointer to the new virtual memory area. "
5569 "On error, the value B<MAP_FAILED> (that is, I<(void\\ *)\\ -1>) is returned, "
5570 "and I<errno> is set appropriately."
5574 #: build/C/man2/mremap.2:142
5576 "The caller tried to expand a memory segment that is locked, but this was not "
5577 "possible without exceeding the B<RLIMIT_MEMLOCK> resource limit."
5581 #: build/C/man2/mremap.2:151
5583 "\"Segmentation fault.\" Some address in the range I<old_address> to "
5584 "I<old_address>+I<old_size> is an invalid virtual memory address for this "
5585 "process. You can also get B<EFAULT> even if there exist mappings that cover "
5586 "the whole address space requested, but those mappings are of different "
5591 #: build/C/man2/mremap.2:179
5593 "An invalid argument was given. Possible causes are: I<old_address> was not "
5594 "page aligned; a value other than B<MREMAP_MAYMOVE> or B<MREMAP_FIXED> was "
5595 "specified in I<flags>; I<new_size> was zero; I<new_size> or I<new_address> "
5596 "was invalid; or the new address range specified by I<new_address> and "
5597 "I<new_size> overlapped the old address range specified by I<old_address> and "
5598 "I<old_size>; or B<MREMAP_FIXED> was specified without also specifying "
5599 "B<MREMAP_MAYMOVE>."
5603 #: build/C/man2/mremap.2:185
5605 "The memory area cannot be expanded at the current virtual address, and the "
5606 "B<MREMAP_MAYMOVE> flag is not set in I<flags>. Or, there is not enough "
5607 "(virtual) memory available."
5610 #. 4.2BSD had a (never actually implemented)
5612 #. call with completely different semantics.
5614 #: build/C/man2/mremap.2:191
5616 "This call is Linux-specific, and should not be used in programs intended to "
5621 #: build/C/man2/mremap.2:199
5623 "Prior to version 2.4, glibc did not expose the definition of "
5624 "B<MREMAP_FIXED>, and the prototype for B<mremap>() did not allow for the "
5625 "I<new_address> argument."
5629 #: build/C/man2/mremap.2:208
5631 "B<brk>(2), B<getpagesize>(2), B<getrlimit>(2), B<mlock>(2), B<mmap>(2), "
5632 "B<sbrk>(2), B<malloc>(3), B<realloc>(3)"
5636 #: build/C/man2/mremap.2:214
5638 "Your favorite text book on operating systems for more information on paged "
5639 "memory (e.g., I<Modern Operating Systems> by Andrew S. Tanenbaum, I<Inside "
5640 "Linux> by Randolf Bentson, I<The Design of the UNIX Operating System> by "
5645 #: build/C/man2/msync.2:25
5651 #: build/C/man2/msync.2:28
5652 msgid "msync - synchronize a file with a memory map"
5656 #: build/C/man2/msync.2:32
5657 msgid "B<int msync(void *>I<addr>B<, size_t >I<length>B<, int >I<flags>B<);>"
5661 #: build/C/man2/msync.2:48
5663 "B<msync>() flushes changes made to the in-core copy of a file that was "
5664 "mapped into memory using B<mmap>(2) back to disk. Without use of this call "
5665 "there is no guarantee that changes are written back before B<munmap>(2) is "
5666 "called. To be more precise, the part of the file that corresponds to the "
5667 "memory area starting at I<addr> and having length I<length> is updated."
5671 #: build/C/man2/msync.2:68
5673 "The I<flags> argument may have the bits B<MS_ASYNC>, B<MS_SYNC>, and "
5674 "B<MS_INVALIDATE> set, but not both B<MS_ASYNC> and B<MS_SYNC>. B<MS_ASYNC> "
5675 "specifies that an update be scheduled, but the call returns immediately. "
5676 "B<MS_SYNC> asks for an update and waits for it to complete. "
5677 "B<MS_INVALIDATE> asks to invalidate other mappings of the same file (so that "
5678 "they can be updated with the fresh values just written)."
5682 #: build/C/man2/msync.2:73
5684 "On success, zero is returned. On error, -1 is returned, and I<errno> is set "
5689 #: build/C/man2/msync.2:74
5695 #: build/C/man2/msync.2:80
5697 "B<MS_INVALIDATE> was specified in I<flags>, and a memory lock exists for the "
5698 "specified address range."
5702 #: build/C/man2/msync.2:93
5704 "I<addr> is not a multiple of PAGESIZE; or any bit other than B<MS_ASYNC> | "
5705 "B<MS_INVALIDATE> | B<MS_SYNC> is set in I<flags>; or both B<MS_SYNC> and "
5706 "B<MS_ASYNC> are set in I<flags>."
5710 #: build/C/man2/msync.2:96
5711 msgid "The indicated memory (or part of it) was not mapped."
5715 #: build/C/man2/msync.2:98 build/C/man3/posix_fallocate.3:105 build/C/man3/shm_open.3:253 build/C/man7/shm_overview.7:103
5716 msgid "POSIX.1-2001."
5720 #: build/C/man2/msync.2:105
5722 "This call was introduced in Linux 1.3.21, and then used B<EFAULT> instead of "
5723 "B<ENOMEM>. In Linux 2.4.19 this was changed to the POSIX value B<ENOMEM>."
5726 #. POSIX.1-2001: It shall be defined to -1 or 0 or 200112L.
5727 #. -1: unavailable, 0: ask using sysconf().
5728 #. glibc defines them to 1.
5730 #: build/C/man2/msync.2:120
5732 "On POSIX systems on which B<msync>() is available, both "
5733 "B<_POSIX_MAPPED_FILES> and B<_POSIX_SYNCHRONIZED_IO> are defined in "
5734 "I<E<lt>unistd.hE<gt>> to a value greater than 0. (See also B<sysconf>(3).)"
5737 #. commit 204ec841fbea3e5138168edbc3a76d46747cc987
5739 #: build/C/man2/msync.2:147
5741 "According to POSIX, either B<MS_SYNC> or B<MS_ASYNC> must be specified in "
5742 "I<flags>, and indeed failure to include one of these flags will cause "
5743 "B<msync>() to fail on some systems. However, Linux permits a call to "
5744 "B<msync>() that specifies neither of these flags, with semantics that are "
5745 "(currently) equivalent to specifying B<MS_ASYNC>. (Since Linux 2.6.19, "
5746 "B<MS_ASYNC> is in fact a no-op, since the kernel properly tracks dirty pages "
5747 "and flushes them to storage as necessary.) Notwithstanding the Linux "
5748 "behavior, portable, future-proof applications should ensure that they "
5749 "specify either B<MS_SYNC> or B<MS_ASYNC> in I<flags>."
5753 #: build/C/man2/msync.2:149 build/C/man7/shm_overview.7:46
5759 #: build/C/man3/mtrace.3:25
5765 #: build/C/man3/mtrace.3:25
5771 #: build/C/man3/mtrace.3:28
5772 msgid "mtrace, muntrace - malloc tracing"
5776 #: build/C/man3/mtrace.3:30
5777 msgid "B<#include E<lt>mcheck.hE<gt>>"
5781 #: build/C/man3/mtrace.3:32
5782 msgid "B<void mtrace(void);>"
5786 #: build/C/man3/mtrace.3:34
5787 msgid "B<void muntrace(void);>"
5791 #: build/C/man3/mtrace.3:46
5793 "The B<mtrace>() function installs hook functions for the memory-allocation "
5794 "functions (B<malloc>(3), B<realloc>(3) B<memalign>(3), B<free>(3)). These "
5795 "hook functions record tracing information about memory allocation and "
5796 "deallocation. The tracing information can be used to discover memory leaks "
5797 "and attempts to free nonallocated memory in a program."
5801 #: build/C/man3/mtrace.3:57
5803 "The B<muntrace>() function disables the hook functions installed by "
5804 "B<mtrace>(), so that tracing information is no longer recorded for the "
5805 "memory-allocation functions. If no hook functions were successfully "
5806 "installed by B<mtrace>(), B<muntrace>() does nothing."
5810 #: build/C/man3/mtrace.3:65
5812 "When B<mtrace>() is called, it checks the value of the environment variable "
5813 "B<MALLOC_TRACE>, which should contain the pathname of a file in which the "
5814 "tracing information is to be recorded. If the pathname is successfully "
5815 "opened, it is truncated to zero length."
5819 #: build/C/man3/mtrace.3:78
5821 "If B<MALLOC_TRACE> is not set, or the pathname it specifies is invalid or "
5822 "not writable, then no hook functions are installed, and B<mtrace>() has no "
5823 "effect. In set-user-ID and set-group-ID programs, B<MALLOC_TRACE> is "
5824 "ignored, and B<mtrace>() has no effect."
5828 #: build/C/man3/mtrace.3:86
5830 "In normal usage, B<mtrace>() is called once at the start of execution of a "
5831 "program, and B<muntrace>() is never called."
5835 #: build/C/man3/mtrace.3:96
5837 "The tracing output produced after a call to B<mtrace>() is textual, but not "
5838 "designed to be human readable. The GNU C library provides a Perl script, "
5839 "B<mtrace>(1), that interprets the trace log and produces human-readable "
5840 "output. For best results, the traced program should be compiled with "
5841 "debugging enabled, so that line-number information is recorded in the "
5846 #: build/C/man3/mtrace.3:102
5848 "The tracing performed by B<mtrace>() incurs a performance penalty (if "
5849 "B<MALLOC_TRACE> points to a valid, writable pathname)."
5853 #: build/C/man3/mtrace.3:108
5855 "The line-number information produced by B<mtrace>(1) is not always precise: "
5856 "the line number references may refer to the previous or following (nonblank) "
5857 "line of the source code."
5861 #: build/C/man3/mtrace.3:115
5863 "The shell session below demonstrates the use of the B<mtrace>() function "
5864 "and the B<mtrace>(1) command in a program that has memory leaks at two "
5865 "different locations. The demonstration uses the following program:"
5869 #: build/C/man3/mtrace.3:122
5872 "$ B<cat t_mtrace.c>\n"
5873 "#include E<lt>mcheck.hE<gt>\n"
5874 "#include E<lt>stdlib.hE<gt>\n"
5875 "#include E<lt>stdio.hE<gt>\n"
5879 #: build/C/man3/mtrace.3:127
5883 "main(int argc, char *argv[])\n"
5889 #: build/C/man3/mtrace.3:129
5891 msgid " mtrace();\n"
5895 #: build/C/man3/mtrace.3:132
5898 " for (j = 0; j E<lt> 2; j++)\n"
5899 " malloc(100); /* Never freed--a memory leak */\n"
5903 #: build/C/man3/mtrace.3:136
5906 " calloc(16, 16); /* Never freed--a memory leak */\n"
5907 " exit(EXIT_SUCCESS);\n"
5912 #: build/C/man3/mtrace.3:142
5914 "When we run the program as follows, we see that B<mtrace>() diagnosed "
5915 "memory leaks at two different locations in the program:"
5919 #: build/C/man3/mtrace.3:155
5922 "$ B<cc -g t_mtrace.c -o t_mtrace>\n"
5923 "$ B<export MALLOC_TRACE=/tmp/t>\n"
5925 "$ B<mtrace ./t_mtrace $MALLOC_TRACE>\n"
5926 "Memory not freed:\n"
5927 "-----------------\n"
5928 " Address Size Caller\n"
5929 "0x084c9378 0x64 at /home/cecilia/t_mtrace.c:12\n"
5930 "0x084c93e0 0x64 at /home/cecilia/t_mtrace.c:12\n"
5931 "0x084c9448 0x100 at /home/cecilia/t_mtrace.c:16\n"
5935 #: build/C/man3/mtrace.3:167
5937 "The first two messages about unfreed memory correspond to the two "
5938 "B<malloc>(3) calls inside the I<for> loop. The final message corresponds "
5939 "to the call to B<calloc>(3) (which in turn calls B<malloc>(3))."
5943 #: build/C/man3/mtrace.3:172
5944 msgid "B<mtrace>(1), B<malloc>(3), B<malloc_hook>(3), B<mcheck>(3)"
5948 #: build/C/man2/posix_fadvise.2:28
5950 msgid "POSIX_FADVISE"
5954 #: build/C/man2/posix_fadvise.2:28 build/C/man2/sync_file_range.2:30
5960 #: build/C/man2/posix_fadvise.2:31
5961 msgid "posix_fadvise - predeclare an access pattern for file data"
5965 #: build/C/man2/posix_fadvise.2:34 build/C/man3/posix_fallocate.3:31
5967 msgid "B<#include E<lt>fcntl.hE<gt>>\n"
5971 #: build/C/man2/posix_fadvise.2:37
5974 "B<int posix_fadvise(int >I<fd>B<, off_t >I<offset>B<, off_t >I<len>B<, int "
5979 #: build/C/man2/posix_fadvise.2:46
5980 msgid "B<posix_fadvise>():"
5984 #: build/C/man2/posix_fadvise.2:48 build/C/man3/posix_fallocate.3:44
5985 msgid "_XOPEN_SOURCE\\ E<gt>=\\ 600 || _POSIX_C_SOURCE\\ E<gt>=\\ 200112L"
5989 #: build/C/man2/posix_fadvise.2:56
5991 "Programs can use B<posix_fadvise>() to announce an intention to access file "
5992 "data in a specific pattern in the future, thus allowing the kernel to "
5993 "perform appropriate optimizations."
5997 #: build/C/man2/posix_fadvise.2:63
5999 "The I<advice> applies to a (not necessarily existent) region starting at "
6000 "I<offset> and extending for I<len> bytes (or until the end of the file if "
6001 "I<len> is 0) within the file referred to by I<fd>. The I<advice> is not "
6002 "binding; it merely constitutes an expectation on behalf of the application."
6006 #: build/C/man2/posix_fadvise.2:65
6007 msgid "Permissible values for I<advice> include:"
6011 #: build/C/man2/posix_fadvise.2:65
6013 msgid "B<POSIX_FADV_NORMAL>"
6017 #: build/C/man2/posix_fadvise.2:71
6019 "Indicates that the application has no advice to give about its access "
6020 "pattern for the specified data. If no advice is given for an open file, "
6021 "this is the default assumption."
6025 #: build/C/man2/posix_fadvise.2:71
6027 msgid "B<POSIX_FADV_SEQUENTIAL>"
6031 #: build/C/man2/posix_fadvise.2:75
6033 "The application expects to access the specified data sequentially (with "
6034 "lower offsets read before higher ones)."
6038 #: build/C/man2/posix_fadvise.2:75
6040 msgid "B<POSIX_FADV_RANDOM>"
6044 #: build/C/man2/posix_fadvise.2:78
6045 msgid "The specified data will be accessed in random order."
6049 #: build/C/man2/posix_fadvise.2:78
6051 msgid "B<POSIX_FADV_NOREUSE>"
6055 #: build/C/man2/posix_fadvise.2:81
6056 msgid "The specified data will be accessed only once."
6060 #: build/C/man2/posix_fadvise.2:81
6062 msgid "B<POSIX_FADV_WILLNEED>"
6066 #: build/C/man2/posix_fadvise.2:84
6067 msgid "The specified data will be accessed in the near future."
6071 #: build/C/man2/posix_fadvise.2:84
6073 msgid "B<POSIX_FADV_DONTNEED>"
6077 #: build/C/man2/posix_fadvise.2:87
6078 msgid "The specified data will not be accessed in the near future."
6082 #: build/C/man2/posix_fadvise.2:90
6083 msgid "On success, zero is returned. On error, an error number is returned."
6087 #: build/C/man2/posix_fadvise.2:94
6088 msgid "The I<fd> argument was not a valid file descriptor."
6092 #: build/C/man2/posix_fadvise.2:97
6093 msgid "An invalid value was specified for I<advice>."
6097 #: build/C/man2/posix_fadvise.2:104
6099 "The specified file descriptor refers to a pipe or FIFO. (Linux actually "
6100 "returns B<EINVAL> in this case.)"
6103 #. of fadvise64_64()
6105 #: build/C/man2/posix_fadvise.2:112
6107 "Kernel support first appeared in Linux 2.5.60; the underlying system call is "
6108 "called B<fadvise64>(). Library support has been provided since glibc "
6109 "version 2.2, via the wrapper function B<posix_fadvise>()."
6113 #: build/C/man2/posix_fadvise.2:121
6115 "POSIX.1-2001. Note that the type of the I<len> argument was changed from "
6116 "I<size_t> to I<off_t> in POSIX.1-2003 TC1."
6120 #: build/C/man2/posix_fadvise.2:127
6122 "Under Linux, B<POSIX_FADV_NORMAL> sets the readahead window to the default "
6123 "size for the backing device; B<POSIX_FADV_SEQUENTIAL> doubles this size, and "
6124 "B<POSIX_FADV_RANDOM> disables file readahead entirely. These changes affect "
6125 "the entire file, not just the specified region (but other open file handles "
6126 "to the same file are unaffected)."
6130 #: build/C/man2/posix_fadvise.2:134
6132 "B<POSIX_FADV_WILLNEED> initiates a nonblocking read of the specified region "
6133 "into the page cache. The amount of data read may be decreased by the kernel "
6134 "depending on virtual memory load. (A few megabytes will usually be fully "
6135 "satisfied, and more is rarely useful.)"
6139 #: build/C/man2/posix_fadvise.2:138
6141 "In kernels before 2.6.18, B<POSIX_FADV_NOREUSE> had the same semantics as "
6142 "B<POSIX_FADV_WILLNEED>. This was probably a bug; since kernel 2.6.18, this "
6147 #: build/C/man2/posix_fadvise.2:146
6149 "B<POSIX_FADV_DONTNEED> attempts to free cached pages associated with the "
6150 "specified region. This is useful, for example, while streaming large "
6151 "files. A program may periodically request the kernel to free cached data "
6152 "that has already been used, so that more useful cached pages are not "
6153 "discarded instead."
6157 #: build/C/man2/posix_fadvise.2:154
6159 "Pages that have not yet been written out will be unaffected, so if the "
6160 "application wishes to guarantee that pages will be released, it should call "
6161 "B<fsync>(2) or B<fdatasync>(2) first."
6165 #: build/C/man2/posix_fadvise.2:154
6167 msgid "Architecture-specific variants"
6171 #: build/C/man2/posix_fadvise.2:171
6173 "Some architectures require 64-bit arguments to be aligned in a suitable pair "
6174 "of registers (see B<syscall>(2) for further detail). On such "
6175 "architectures, the call signature of B<posix_fadvise>() shown in the "
6176 "SYNOPSIS would force a register to be wasted as padding between the I<fd> "
6177 "and I<len> arguments. Therefore, these architectures define a version of "
6178 "the system call that orders the arguments suitably, but otherwise is "
6179 "otherwise exactly the same as B<posix_fadvise>()."
6183 #: build/C/man2/posix_fadvise.2:173
6184 msgid "For example, since Linux 2.6.14, ARM has the following system call:"
6188 #: build/C/man2/posix_fadvise.2:178
6191 "B<long arm_fadvise64_64(int >I<fd>B<, int >I<advice>B<,>\n"
6192 "B< loff_t >I<offset>B<, loff_t >I<len>B<);>\n"
6196 #: build/C/man2/posix_fadvise.2:186
6198 "These architecture-specific details are generally hidden from applications "
6199 "by the glibc B<posix_fadvise>() wrapper function, which invokes the "
6200 "appropriate architecture-specific system call."
6204 #: build/C/man2/posix_fadvise.2:191
6206 "In kernels before 2.6.6, if I<len> was specified as 0, then this was "
6207 "interpreted literally as \"zero bytes\", rather than as meaning \"all bytes "
6208 "through to the end of the file\"."
6211 #. FIXME . Write a posix_fadvise(3) page.
6213 #: build/C/man2/posix_fadvise.2:197
6215 "B<readahead>(2), B<sync_file_range>(2), B<posix_fallocate>(3), "
6216 "B<posix_madvise>(3)"
6220 #: build/C/man3/posix_fallocate.3:25
6222 msgid "POSIX_FALLOCATE"
6226 #: build/C/man3/posix_fallocate.3:25 build/C/man2/shmop.2:41
6232 #: build/C/man3/posix_fallocate.3:28
6233 msgid "posix_fallocate - allocate file space"
6237 #: build/C/man3/posix_fallocate.3:33
6239 msgid "B<int posix_fallocate(int >I<fd>B<, off_t >I<offset>B<, off_t >I<len>B<);>\n"
6243 #: build/C/man3/posix_fallocate.3:42
6244 msgid "B<posix_fallocate>():"
6248 #: build/C/man3/posix_fallocate.3:61
6250 "The function B<posix_fallocate>() ensures that disk space is allocated for "
6251 "the file referred to by the descriptor I<fd> for the bytes in the range "
6252 "starting at I<offset> and continuing for I<len> bytes. After a successful "
6253 "call to B<posix_fallocate>(), subsequent writes to bytes in the specified "
6254 "range are guaranteed not to fail because of lack of disk space."
6258 #: build/C/man3/posix_fallocate.3:66
6260 "If the size of the file is less than I<offset>+I<len>, then the file is "
6261 "increased to this size; otherwise the file size is left unchanged."
6265 #: build/C/man3/posix_fallocate.3:72
6267 "B<posix_fallocate>() returns zero on success, or an error number on "
6268 "failure. Note that I<errno> is not set."
6272 #: build/C/man3/posix_fallocate.3:81
6273 msgid "I<offset+len> exceeds the maximum file size."
6277 #: build/C/man3/posix_fallocate.3:91
6278 msgid "I<fd> does not refer to a regular file."
6282 #: build/C/man3/posix_fallocate.3:100
6283 msgid "I<fd> refers to a pipe."
6287 #: build/C/man3/posix_fallocate.3:103
6288 msgid "B<posix_fallocate>() is available since glibc 2.1.94."
6292 #: build/C/man3/posix_fallocate.3:128
6294 "POSIX.1-2008 says that an implementation I<shall> give the B<EINVAL> error "
6295 "if I<len> was 0, or I<offset> was less than 0. POSIX.1-2001 says that an "
6296 "implementation I<shall> give the B<EINVAL> error if I<len> is less than 0, "
6297 "or I<offset> was less than 0, and I<may> give the error if I<len> equals "
6302 #: build/C/man3/posix_fallocate.3:133
6303 msgid "B<fallocate>(1), B<fallocate>(2), B<lseek>(2), B<posix_fadvise>(2)"
6307 #: build/C/man3/posix_memalign.3:29
6309 msgid "POSIX_MEMALIGN"
6313 #: build/C/man3/posix_memalign.3:29
6319 #: build/C/man3/posix_memalign.3:32
6321 "posix_memalign, aligned_alloc, memalign, valloc, pvalloc - allocate aligned "
6326 #: build/C/man3/posix_memalign.3:39
6329 "B<int posix_memalign(void **>I<memptr>B<, size_t >I<alignment>B<, size_t "
6331 "B<void *aligned_alloc(size_t >I<alignment>B<, size_t >I<size>B<);>\n"
6332 "B<void *valloc(size_t >I<size>B<);>\n"
6336 #: build/C/man3/posix_memalign.3:44
6339 "B<void *memalign(size_t >I<alignment>B<, size_t >I<size>B<);>\n"
6340 "B<void *pvalloc(size_t >I<size>B<);>\n"
6344 #: build/C/man3/posix_memalign.3:54
6346 "B<posix_memalign>(): _POSIX_C_SOURCE\\ E<gt>=\\ 200112L || _XOPEN_SOURCE\\ "
6351 #: build/C/man3/posix_memalign.3:57
6352 msgid "B<aligned_alloc>(): _ISOC11_SOURCE"
6356 #: build/C/man3/posix_memalign.3:59
6357 msgid "B<valloc>():"
6361 #: build/C/man3/posix_memalign.3:62
6363 msgid "Since glibc 2.12:"
6367 #: build/C/man3/posix_memalign.3:69
6371 " (_XOPEN_SOURCE\\ E<gt>=\\ 500 ||\n"
6372 " _XOPEN_SOURCE\\ &&\\ _XOPEN_SOURCE_EXTENDED) &&\n"
6373 " !(_POSIX_C_SOURCE\\ E<gt>=\\ 200112L || _XOPEN_SOURCE\\ E<gt>=\\ 600)\n"
6377 #: build/C/man3/posix_memalign.3:71
6379 msgid "Before glibc 2.12:"
6383 #: build/C/man3/posix_memalign.3:75
6385 "_BSD_SOURCE || _XOPEN_SOURCE\\ E<gt>=\\ 500 || _XOPEN_SOURCE\\ &&\\ "
6386 "_XOPEN_SOURCE_EXTENDED"
6390 #: build/C/man3/posix_memalign.3:82
6392 "(The (nonstandard) header file I<E<lt>malloc.hE<gt>> also exposes the "
6393 "declaration of B<valloc>(); no feature test macros are required.)"
6398 #: build/C/man3/posix_memalign.3:104
6400 "The function B<posix_memalign>() allocates I<size> bytes and places the "
6401 "address of the allocated memory in I<*memptr>. The address of the allocated "
6402 "memory will be a multiple of I<alignment>, which must be a power of two and "
6403 "a multiple of I<sizeof(void\\ *)>. If I<size> is 0, then the value placed "
6404 "in I<*memptr> is either NULL, or a unique pointer value that can later be "
6405 "successfully passed to B<free>(3)."
6408 #. The behavior of memalign() for size==0 is as for posix_memalign()
6409 #. but no standards govern this.
6411 #: build/C/man3/posix_memalign.3:115
6413 "The obsolete function B<memalign>() allocates I<size> bytes and returns a "
6414 "pointer to the allocated memory. The memory address will be a multiple of "
6415 "I<alignment>, which must be a power of two."
6419 #: build/C/man3/posix_memalign.3:124
6421 "The function B<aligned_alloc>() is the same as B<memalign>(), except for "
6422 "the added restriction that I<size> should be a multiple of I<alignment>."
6426 #: build/C/man3/posix_memalign.3:133
6428 "The obsolete function B<valloc>() allocates I<size> bytes and returns a "
6429 "pointer to the allocated memory. The memory address will be a multiple of "
6430 "the page size. It is equivalent to I<memalign(sysconf(_SC_PAGESIZE),size)>."
6434 #: build/C/man3/posix_memalign.3:140
6436 "The obsolete function B<pvalloc>() is similar to B<valloc>(), but rounds "
6437 "the size of the allocation up to the next multiple of the system page size."
6441 #: build/C/man3/posix_memalign.3:142
6442 msgid "For all of these functions, the memory is not zeroed."
6446 #: build/C/man3/posix_memalign.3:149
6448 "B<aligned_alloc>(), B<memalign>(), B<valloc>(), and B<pvalloc>() return a "
6449 "pointer to the allocated memory, or NULL if the request fails."
6453 #: build/C/man3/posix_memalign.3:157
6455 "B<posix_memalign>() returns zero on success, or one of the error values "
6456 "listed in the next section on failure. The value of I<errno> is "
6457 "indeterminate after a call to B<posix_memalign>()."
6461 #: build/C/man3/posix_memalign.3:164
6463 "The I<alignment> argument was not a power of two, or was not a multiple of "
6464 "I<sizeof(void\\ *)>."
6468 #: build/C/man3/posix_memalign.3:167
6469 msgid "There was insufficient memory to fulfill the allocation request."
6473 #: build/C/man3/posix_memalign.3:174
6475 "The functions B<memalign>(), B<valloc>(), and B<pvalloc>() have been "
6476 "available in all Linux libc libraries."
6480 #: build/C/man3/posix_memalign.3:178
6481 msgid "The function B<aligned_alloc>() was added to glibc in version 2.16."
6485 #: build/C/man3/posix_memalign.3:182
6486 msgid "The function B<posix_memalign>() is available since glibc 2.1.91."
6490 #: build/C/man3/posix_memalign.3:189
6492 "The function B<valloc>() appeared in 3.0BSD. It is documented as being "
6493 "obsolete in 4.3BSD, and as legacy in SUSv2. It does not appear in "
6498 #: build/C/man3/posix_memalign.3:193
6499 msgid "The function B<pvalloc>() is a GNU extension."
6503 #: build/C/man3/posix_memalign.3:197
6504 msgid "The function B<memalign>() appears in SunOS 4.1.3 but not in 4.4BSD."
6508 #: build/C/man3/posix_memalign.3:201
6509 msgid "The function B<posix_memalign>() comes from POSIX.1d."
6513 #: build/C/man3/posix_memalign.3:206
6514 msgid "The function B<aligned_alloc>() is specified in the C11 standard."
6518 #: build/C/man3/posix_memalign.3:206
6524 #: build/C/man3/posix_memalign.3:210
6526 "Everybody agrees that B<posix_memalign>() is declared in "
6527 "I<E<lt>stdlib.hE<gt>>."
6531 #: build/C/man3/posix_memalign.3:214
6533 "On some systems B<memalign>() is declared in I<E<lt>stdlib.hE<gt>> instead "
6534 "of I<E<lt>malloc.hE<gt>>."
6538 #: build/C/man3/posix_memalign.3:221
6540 "According to SUSv2, B<valloc>() is declared in I<E<lt>stdlib.hE<gt>>. "
6541 "Libc4,5 and glibc declare it in I<E<lt>malloc.hE<gt>>, and also in "
6542 "I<E<lt>stdlib.hE<gt>> if suitable feature test macros are defined (see "
6547 #: build/C/man3/posix_memalign.3:230
6549 "On many systems there are alignment restrictions, for example, on buffers "
6550 "used for direct block device I/O. POSIX specifies the "
6551 "I<pathconf(path,_PC_REC_XFER_ALIGN)> call that tells what alignment is "
6552 "needed. Now one can use B<posix_memalign>() to satisfy this requirement."
6556 #: build/C/man3/posix_memalign.3:239
6558 "B<posix_memalign>() verifies that I<alignment> matches the requirements "
6559 "detailed above. B<memalign>() may not check that the I<alignment> argument "
6563 #. Other systems allow passing the result of
6570 #: build/C/man3/posix_memalign.3:267
6572 "POSIX requires that memory obtained from B<posix_memalign>() can be freed "
6573 "using B<free>(3). Some systems provide no way to reclaim memory allocated "
6574 "with B<memalign>() or B<valloc>() (because one can pass to B<free>(3) "
6575 "only a pointer obtained from B<malloc>(3), while, for example, B<memalign>() "
6576 "would call B<malloc>(3) and then align the obtained value). The glibc "
6577 "implementation allows memory obtained from any of these functions to be "
6578 "reclaimed with B<free>(3)."
6582 #: build/C/man3/posix_memalign.3:272
6584 "The glibc B<malloc>(3) always returns 8-byte aligned memory addresses, so "
6585 "these functions are needed only if you require larger alignment values."
6589 #: build/C/man3/posix_memalign.3:277
6590 msgid "B<brk>(2), B<getpagesize>(2), B<free>(3), B<malloc>(3)"
6594 #: build/C/man2/readahead.2:28
6600 #: build/C/man2/readahead.2:28
6606 #: build/C/man2/readahead.2:31
6607 msgid "readahead - initiate file readahead into page cache"
6611 #: build/C/man2/readahead.2:37
6614 "B<ssize_t readahead(int >I<fd>B<, off64_t >I<offset>B<, size_t "
6619 #: build/C/man2/readahead.2:44
6621 "B<readahead>() initiates readahead on a file so that subsequent reads from "
6622 "that file will be satisfied from the cache, and not block on disk I/O "
6623 "(assuming the readahead was initiated early enough and that other activity "
6624 "on the system did not in the meantime flush pages from the cache)."
6628 #: build/C/man2/readahead.2:66
6630 "The I<fd> argument is a file descriptor identifying the file which is to be "
6631 "read. The I<offset> argument specifies the starting point from which data "
6632 "is to be read and I<count> specifies the number of bytes to be read. I/O is "
6633 "performed in whole pages, so that I<offset> is effectively rounded down to a "
6634 "page boundary and bytes are read up to the next page boundary greater than "
6635 "or equal to I<(offset+count)>. B<readahead>() does not read beyond the end "
6636 "of the file. The current file offset of the open file referred to by I<fd> "
6637 "is left unchanged."
6641 #: build/C/man2/readahead.2:72
6643 "On success, B<readahead>() returns 0; on failure, -1 is returned, with "
6644 "I<errno> set to indicate the cause of the error."
6648 #: build/C/man2/readahead.2:77
6649 msgid "I<fd> is not a valid file descriptor or is not open for reading."
6653 #: build/C/man2/readahead.2:83
6654 msgid "I<fd> does not refer to a file type to which B<readahead>() can be applied."
6658 #: build/C/man2/readahead.2:88
6660 "The B<readahead>() system call appeared in Linux 2.4.13; glibc support has "
6661 "been provided since version 2.3."
6665 #: build/C/man2/readahead.2:93
6667 "The B<readahead>() system call is Linux-specific, and its use should be "
6668 "avoided in portable applications."
6672 #: build/C/man2/readahead.2:98
6674 "On some 32-bit architectures, the calling signature for this system call "
6675 "differs, for the reasons described in B<syscall>(2)."
6679 #: build/C/man2/readahead.2:107
6681 "B<readahead>() attempts to schedule the reads in the background and return "
6682 "immediately. However, it may block while it reads the filesystem metadata "
6683 "needed to locate the requested blocks. This occurs frequently with ext[234] "
6684 "on large files using indirect blocks instead of extents, giving the "
6685 "appearance that the call blocks until the requested data has been read."
6689 #: build/C/man2/readahead.2:113
6690 msgid "B<lseek>(2), B<madvise>(2), B<mmap>(2), B<posix_fadvise>(2), B<read>(2)"
6694 #: build/C/man2/remap_file_pages.2:28
6696 msgid "REMAP_FILE_PAGES"
6700 #: build/C/man2/remap_file_pages.2:28
6706 #: build/C/man2/remap_file_pages.2:31
6707 msgid "remap_file_pages - create a nonlinear file mapping"
6711 #: build/C/man2/remap_file_pages.2:35
6714 "B<#define _GNU_SOURCE> /* See feature_test_macros(7) */\n"
6715 "B<#include E<lt>sys/mman.hE<gt>>\n"
6719 #: build/C/man2/remap_file_pages.2:38
6722 "B<int remap_file_pages(void *>I<addr>B<, size_t >I<size>B<, int "
6724 "B< ssize_t >I<pgoff>B<, int >I<flags>B<);>\n"
6728 #: build/C/man2/remap_file_pages.2:51
6730 "The B<remap_file_pages>() system call is used to create a nonlinear "
6731 "mapping, that is, a mapping in which the pages of the file are mapped into a "
6732 "nonsequential order in memory. The advantage of using B<remap_file_pages>() "
6733 "over using repeated calls to B<mmap>(2) is that the former approach does "
6734 "not require the kernel to create additional VMA (Virtual Memory Area) data "
6739 #: build/C/man2/remap_file_pages.2:53
6740 msgid "To create a nonlinear mapping we perform the following steps:"
6744 #: build/C/man2/remap_file_pages.2:53
6750 #: build/C/man2/remap_file_pages.2:61
6752 "Use B<mmap>(2) to create a mapping (which is initially linear). This "
6753 "mapping must be created with the B<MAP_SHARED> flag."
6757 #: build/C/man2/remap_file_pages.2:61
6763 #: build/C/man2/remap_file_pages.2:69
6765 "Use one or more calls to B<remap_file_pages>() to rearrange the "
6766 "correspondence between the pages of the mapping and the pages of the file. "
6767 "It is possible to map the same page of a file into multiple locations within "
6768 "the mapped region."
6772 #: build/C/man2/remap_file_pages.2:80
6774 "The I<pgoff> and I<size> arguments specify the region of the file that is to "
6775 "be relocated within the mapping: I<pgoff> is a file offset in units of the "
6776 "system page size; I<size> is the length of the region in bytes."
6780 #: build/C/man2/remap_file_pages.2:98
6782 "The I<addr> argument serves two purposes. First, it identifies the mapping "
6783 "whose pages we want to rearrange. Thus, I<addr> must be an address that "
6784 "falls within a region previously mapped by a call to B<mmap>(2). Second, "
6785 "I<addr> specifies the address at which the file pages identified by I<pgoff> "
6786 "and I<size> will be placed."
6789 #. This rounding is weird, and not consistent with the treatment of
6790 #. the analogous arguments for munmap()/mprotect() and for mlock().
6793 #: build/C/man2/remap_file_pages.2:112
6795 "The values specified in I<addr> and I<size> should be multiples of the "
6796 "system page size. If they are not, then the kernel rounds I<both> values "
6797 "I<down> to the nearest multiple of the page size."
6801 #: build/C/man2/remap_file_pages.2:116
6802 msgid "The I<prot> argument must be specified as 0."
6806 #: build/C/man2/remap_file_pages.2:124
6808 "The I<flags> argument has the same meaning as for B<mmap>(2), but all flags "
6809 "other than B<MAP_NONBLOCK> are ignored."
6813 #: build/C/man2/remap_file_pages.2:131
6815 "On success, B<remap_file_pages>() returns 0. On error, -1 is returned, and "
6816 "I<errno> is set appropriately."
6820 #: build/C/man2/remap_file_pages.2:139
6822 "I<addr> does not refer to a valid mapping created with the B<MAP_SHARED> "
6826 #. And possibly others from vma->vm_ops->populate()
6828 #: build/C/man2/remap_file_pages.2:148
6829 msgid "I<addr>, I<size>, I<prot>, or I<pgoff> is invalid."
6833 #: build/C/man2/remap_file_pages.2:153
6835 "The B<remap_file_pages>() system call appeared in Linux 2.5.46; glibc "
6836 "support was added in version 2.3.3."
6840 #: build/C/man2/remap_file_pages.2:157
6841 msgid "The B<remap_file_pages>() system call is Linux-specific."
6845 #: build/C/man2/remap_file_pages.2:164
6847 "B<getpagesize>(2), B<mmap>(2), B<mmap2>(2), B<mprotect>(2), B<mremap>(2), "
6852 #: build/C/man3/shm_open.3:26
6858 #: build/C/man3/shm_open.3:26
6864 #: build/C/man3/shm_open.3:29
6865 msgid "shm_open, shm_unlink - create/open or unlink POSIX shared memory objects"
6869 #: build/C/man3/shm_open.3:33
6870 msgid "B<#include E<lt>sys/stat.hE<gt>> /* For mode constants */"
6874 #: build/C/man3/shm_open.3:35
6875 msgid "B<#include E<lt>fcntl.hE<gt>> /* For O_* constants */"
6879 #: build/C/man3/shm_open.3:37
6880 msgid "B<int shm_open(const char *>I<name>B<, int >I<oflag>B<, mode_t >I<mode>B<);>"
6884 #: build/C/man3/shm_open.3:39
6885 msgid "B<int shm_unlink(const char *>I<name>B<);>"
6889 #: build/C/man3/shm_open.3:41
6890 msgid "Link with I<-lrt>."
6894 #: build/C/man3/shm_open.3:53
6896 "B<shm_open>() creates and opens a new, or opens an existing, POSIX shared "
6897 "memory object. A POSIX shared memory object is in effect a handle which can "
6898 "be used by unrelated processes to B<mmap>(2) the same region of shared "
6899 "memory. The B<shm_unlink>() function performs the converse operation, "
6900 "removing an object previously created by B<shm_open>()."
6903 #. glibc allows the initial slash to be omitted, and makes
6904 #. multiple initial slashes equivalent to a single slash.
6905 #. This differs from the implementation of POSIX message queues.
6906 #. glibc allows subdirectory components in the name, in which
6907 #. case the subdirectory must exist under /dev/shm, and allow the
6908 #. required permissions if a user wants to create a shared memory
6909 #. object in that subdirectory.
6911 #: build/C/man3/shm_open.3:74
6913 "The operation of B<shm_open>() is analogous to that of B<open>(2). I<name> "
6914 "specifies the shared memory object to be created or opened. For portable "
6915 "use, a shared memory object should be identified by a name of the form "
6916 "I</somename>; that is, a null-terminated string of up to B<NAME_MAX> (i.e., "
6917 "255) characters consisting of an initial slash, followed by one or more "
6918 "characters, none of which are slashes."
6922 #: build/C/man3/shm_open.3:81
6924 "I<oflag> is a bit mask created by ORing together exactly one of B<O_RDONLY> "
6925 "or B<O_RDWR> and any of the other flags listed here:"
6929 #: build/C/man3/shm_open.3:81
6935 #: build/C/man3/shm_open.3:89
6937 "Open the object for read access. A shared memory object opened in this way "
6938 "can be B<mmap>(2)ed only for read (B<PROT_READ>) access."
6942 #: build/C/man3/shm_open.3:89
6948 #: build/C/man3/shm_open.3:92
6949 msgid "Open the object for read-write access."
6953 #: build/C/man3/shm_open.3:92
6958 #. In truth it is actually the filesystem IDs on Linux, but these
6959 #. are nearly always the same as the effective IDs. (MTK, Jul 05)
6961 #: build/C/man3/shm_open.3:112
6963 "Create the shared memory object if it does not exist. The user and group "
6964 "ownership of the object are taken from the corresponding effective IDs of "
6965 "the calling process, and the object's permission bits are set according to "
6966 "the low-order 9 bits of I<mode>, except that those bits set in the process "
6967 "file mode creation mask (see B<umask>(2)) are cleared for the new object. "
6968 "A set of macro constants which can be used to define I<mode> is listed in "
6969 "B<open>(2). (Symbolic definitions of these constants can be obtained by "
6970 "including I<E<lt>sys/stat.hE<gt>>.)"
6974 #: build/C/man3/shm_open.3:118
6976 "A new shared memory object initially has zero length\\(emthe size of the "
6977 "object can be set using B<ftruncate>(2). The newly allocated bytes of a "
6978 "shared memory object are automatically initialized to 0."
6982 #: build/C/man3/shm_open.3:118
6988 #: build/C/man3/shm_open.3:127
6990 "If B<O_CREAT> was also specified, and a shared memory object with the given "
6991 "I<name> already exists, return an error. The check for the existence of the "
6992 "object, and its creation if it does not exist, are performed atomically."
6996 #: build/C/man3/shm_open.3:127
7002 #: build/C/man3/shm_open.3:130
7003 msgid "If the shared memory object already exists, truncate it to zero bytes."
7007 #: build/C/man3/shm_open.3:133
7009 "Definitions of these flag values can be obtained by including "
7010 "I<E<lt>fcntl.hE<gt>>."
7014 #: build/C/man3/shm_open.3:144
7016 "On successful completion B<shm_open>() returns a new file descriptor "
7017 "referring to the shared memory object. This file descriptor is guaranteed "
7018 "to be the lowest-numbered file descriptor not previously opened within the "
7019 "process. The B<FD_CLOEXEC> flag (see B<fcntl>(2)) is set for the file "
7024 #: build/C/man3/shm_open.3:153
7026 "The file descriptor is normally used in subsequent calls to B<ftruncate>(2) "
7027 "(for a newly created object) and B<mmap>(2). After a call to B<mmap>(2) "
7028 "the file descriptor may be closed without affecting the memory mapping."
7032 #: build/C/man3/shm_open.3:171
7034 "The operation of B<shm_unlink>() is analogous to B<unlink>(2): it removes a "
7035 "shared memory object name, and, once all processes have unmapped the object, "
7036 "de-allocates and destroys the contents of the associated memory region. "
7037 "After a successful B<shm_unlink>(), attempts to B<shm_open>() an object "
7038 "with the same I<name> will fail (unless B<O_CREAT> was specified, in which "
7039 "case a new, distinct object is created)."
7043 #: build/C/man3/shm_open.3:180
7045 "On success, B<shm_open>() returns a nonnegative file descriptor. On "
7046 "failure, B<shm_open>() returns -1. B<shm_unlink>() returns 0 on success, "
7051 #: build/C/man3/shm_open.3:187
7053 "On failure, I<errno> is set to indicate the cause of the error. Values "
7054 "which may appear in I<errno> include the following:"
7058 #: build/C/man3/shm_open.3:192
7059 msgid "Permission to B<shm_unlink>() the shared memory object was denied."
7063 #: build/C/man3/shm_open.3:202
7065 "Permission was denied to B<shm_open>() I<name> in the specified I<mode>, or "
7066 "B<O_TRUNC> was specified and the caller does not have write permission on "
7071 #: build/C/man3/shm_open.3:202 build/C/man2/shmget.2:195
7077 #: build/C/man3/shm_open.3:213
7079 "Both B<O_CREAT> and B<O_EXCL> were specified to B<shm_open>() and the "
7080 "shared memory object specified by I<name> already exists."
7084 #: build/C/man3/shm_open.3:220
7085 msgid "The I<name> argument to B<shm_open>() was invalid."
7089 #: build/C/man3/shm_open.3:220
7095 #: build/C/man3/shm_open.3:223
7096 msgid "The process already has the maximum number of files open."
7100 #: build/C/man3/shm_open.3:223
7102 msgid "B<ENAMETOOLONG>"
7106 #: build/C/man3/shm_open.3:229
7107 msgid "The length of I<name> exceeds B<PATH_MAX>."
7111 #: build/C/man3/shm_open.3:233
7112 msgid "The limit on the total number of files open on the system has been reached."
7116 #: build/C/man3/shm_open.3:233 build/C/man3/shm_open.3:242 build/C/man2/shmget.2:209
7122 #: build/C/man3/shm_open.3:242
7124 "An attempt was made to B<shm_open>() a I<name> that did not exist, and "
7125 "B<O_CREAT> was not specified."
7129 #: build/C/man3/shm_open.3:249
7130 msgid "An attempt was to made to B<shm_unlink>() a I<name> that does not exist."
7134 #: build/C/man3/shm_open.3:251
7135 msgid "These functions are provided in glibc 2.2 and later."
7139 #: build/C/man3/shm_open.3:257
7141 "POSIX.1-2001 says that the group ownership of a newly created shared memory "
7142 "object is set to either the calling process's effective group ID or \"a "
7143 "system default group ID\"."
7147 #: build/C/man3/shm_open.3:266
7149 "POSIX leaves the behavior of the combination of B<O_RDONLY> and B<O_TRUNC> "
7150 "unspecified. On Linux, this will successfully truncate an existing shared "
7151 "memory object\\(emthis may not be so on other UNIX systems."
7155 #: build/C/man3/shm_open.3:271
7157 "The POSIX shared memory object implementation on Linux 2.4 makes use of a "
7158 "dedicated filesystem, which is normally mounted under I</dev/shm>."
7162 #: build/C/man3/shm_open.3:282
7164 "B<close>(2), B<fchmod>(2), B<fchown>(2), B<fcntl>(2), B<fstat>(2), "
7165 "B<ftruncate>(2), B<mmap>(2), B<open>(2), B<umask>(2), B<shm_overview>(7)"
7169 #: build/C/man7/shm_overview.7:27
7171 msgid "SHM_OVERVIEW"
7175 #: build/C/man7/shm_overview.7:27
7181 #: build/C/man7/shm_overview.7:30
7182 msgid "shm_overview - overview of POSIX shared memory"
7186 #: build/C/man7/shm_overview.7:33
7188 "The POSIX shared memory API allows processes to communicate information by "
7189 "sharing a region of memory."
7193 #: build/C/man7/shm_overview.7:35
7194 msgid "The interfaces employed in the API are:"
7198 #: build/C/man7/shm_overview.7:35
7200 msgid "B<shm_open>(3)"
7204 #: build/C/man7/shm_overview.7:42
7206 "Create and open a new object, or open an existing object. This is analogous "
7207 "to B<open>(2). The call returns a file descriptor for use by the other "
7208 "interfaces listed below."
7212 #: build/C/man7/shm_overview.7:42
7214 msgid "B<ftruncate>(2)"
7218 #: build/C/man7/shm_overview.7:46
7220 "Set the size of the shared memory object. (A newly created shared memory "
7221 "object has a length of zero.)"
7225 #: build/C/man7/shm_overview.7:50
7227 "Map the shared memory object into the virtual address space of the calling "
7232 #: build/C/man7/shm_overview.7:50
7234 msgid "B<munmap>(2)"
7238 #: build/C/man7/shm_overview.7:54
7240 "Unmap the shared memory object from the virtual address space of the calling "
7245 #: build/C/man7/shm_overview.7:54
7247 msgid "B<shm_unlink>(3)"
7251 #: build/C/man7/shm_overview.7:57
7252 msgid "Remove a shared memory object name."
7256 #: build/C/man7/shm_overview.7:57
7262 #: build/C/man7/shm_overview.7:62
7264 "Close the file descriptor allocated by B<shm_open>(3) when it is no longer "
7269 #: build/C/man7/shm_overview.7:62
7275 #: build/C/man7/shm_overview.7:76
7277 "Obtain a I<stat> structure that describes the shared memory object. Among "
7278 "the information returned by this call are the object's size (I<st_size>), "
7279 "permissions (I<st_mode>), owner (I<st_uid>), and group (I<st_gid>)."
7283 #: build/C/man7/shm_overview.7:76
7285 msgid "B<fchown>(2)"
7289 #: build/C/man7/shm_overview.7:79
7290 msgid "To change the ownership of a shared memory object."
7294 #: build/C/man7/shm_overview.7:79
7296 msgid "B<fchmod>(2)"
7300 #: build/C/man7/shm_overview.7:82
7301 msgid "To change the permissions of a shared memory object."
7305 #: build/C/man7/shm_overview.7:82
7311 #: build/C/man7/shm_overview.7:84
7312 msgid "POSIX shared memory is supported since Linux 2.4 and glibc 2.2."
7316 #: build/C/man7/shm_overview.7:84
7322 #: build/C/man7/shm_overview.7:89
7324 "POSIX shared memory objects have kernel persistence: a shared memory object "
7325 "will exist until the system is shut down, or until all processes have "
7326 "unmapped the object and it has been deleted with B<shm_unlink>(3)"
7330 #: build/C/man7/shm_overview.7:89
7336 #: build/C/man7/shm_overview.7:94
7338 "Programs using the POSIX shared memory API must be compiled with I<cc -lrt> "
7339 "to link against the real-time library, I<librt>."
7343 #: build/C/man7/shm_overview.7:94
7345 msgid "Accessing shared memory objects via the filesystem"
7349 #: build/C/man7/shm_overview.7:101
7351 "On Linux, shared memory objects are created in a (I<tmpfs>) virtual "
7352 "filesystem, normally mounted under I</dev/shm>. Since kernel 2.6.19, Linux "
7353 "supports the use of access control lists (ACLs) to control the permissions "
7354 "of objects in the virtual filesystem."
7358 #: build/C/man7/shm_overview.7:106
7360 "Typically, processes must synchronize their access to a shared memory "
7361 "object, using, for example, POSIX semaphores."
7365 #: build/C/man7/shm_overview.7:114
7367 "System V shared memory (B<shmget>(2), B<shmop>(2), etc.) is an older shared "
7368 "memory API. POSIX shared memory provides a simpler, and better designed "
7369 "interface; on the other hand POSIX shared memory is somewhat less widely "
7370 "available (especially on older systems) than System V shared memory."
7374 #: build/C/man7/shm_overview.7:127
7376 "B<fchmod>(2), B<fchown>(2), B<fstat>(2), B<ftruncate>(2), B<mmap>(2), "
7377 "B<mprotect>(2), B<munmap>(2), B<shmget>(2), B<shmop>(2), B<shm_open>(3), "
7378 "B<shm_unlink>(3), B<sem_overview>(7)"
7382 #: build/C/man2/shmctl.2:45
7388 #: build/C/man2/shmctl.2:45
7394 #: build/C/man2/shmctl.2:48
7395 msgid "shmctl - System V shared memory control"
7399 #: build/C/man2/shmctl.2:51 build/C/man2/shmget.2:44
7400 msgid "B<#include E<lt>sys/ipc.hE<gt>>"
7404 #: build/C/man2/shmctl.2:53 build/C/man2/shmget.2:46
7405 msgid "B<#include E<lt>sys/shm.hE<gt>>"
7409 #: build/C/man2/shmctl.2:55
7410 msgid "B<int shmctl(int >I<shmid>B<, int >I<cmd>B<, struct shmid_ds *>I<buf>B<);>"
7414 #: build/C/man2/shmctl.2:62
7416 "B<shmctl>() performs the control operation specified by I<cmd> on the "
7417 "System V shared memory segment whose identifier is given in I<shmid>."
7421 #: build/C/man2/shmctl.2:67
7423 "The I<buf> argument is a pointer to a I<shmid_ds> structure, defined in "
7424 "I<E<lt>sys/shm.hE<gt>> as follows:"
7428 #: build/C/man2/shmctl.2:81
7431 "struct shmid_ds {\n"
7432 " struct ipc_perm shm_perm; /* Ownership and permissions */\n"
7433 " size_t shm_segsz; /* Size of segment (bytes) */\n"
7434 " time_t shm_atime; /* Last attach time */\n"
7435 " time_t shm_dtime; /* Last detach time */\n"
7436 " time_t shm_ctime; /* Last change time */\n"
7437 " pid_t shm_cpid; /* PID of creator */\n"
7438 " pid_t shm_lpid; /* PID of last shmat(2)/shmdt(2) */\n"
7439 " shmatt_t shm_nattch; /* No. of current attaches */\n"
7445 #: build/C/man2/shmctl.2:89
7447 "The I<ipc_perm> structure is defined as follows (the highlighted fields are "
7448 "settable using B<IPC_SET>):"
7452 #: build/C/man2/shmctl.2:102
7455 "struct ipc_perm {\n"
7456 " key_t __key; /* Key supplied to shmget(2) */\n"
7457 " uid_t B<uid>; /* Effective UID of owner */\n"
7458 " gid_t B<gid>; /* Effective GID of owner */\n"
7459 " uid_t cuid; /* Effective UID of creator */\n"
7460 " gid_t cgid; /* Effective GID of creator */\n"
7461 " unsigned short B<mode>; /* B<Permissions> + SHM_DEST and\n"
7462 " SHM_LOCKED flags */\n"
7463 " unsigned short __seq; /* Sequence number */\n"
7468 #: build/C/man2/shmctl.2:108
7469 msgid "Valid values for I<cmd> are:"
7473 #: build/C/man2/shmctl.2:109
7479 #: build/C/man2/shmctl.2:118
7481 "Copy information from the kernel data structure associated with I<shmid> "
7482 "into the I<shmid_ds> structure pointed to by I<buf>. The caller must have "
7483 "read permission on the shared memory segment."
7487 #: build/C/man2/shmctl.2:118
7493 #: build/C/man2/shmctl.2:136
7495 "Write the values of some members of the I<shmid_ds> structure pointed to by "
7496 "I<buf> to the kernel data structure associated with this shared memory "
7497 "segment, updating also its I<shm_ctime> member. The following fields can be "
7498 "changed: I<shm_perm.uid>, I<shm_perm.gid>, and (the least significant 9 bits "
7499 "of) I<shm_perm.mode>. The effective UID of the calling process must match "
7500 "the owner (I<shm_perm.uid>) or creator (I<shm_perm.cuid>) of the shared "
7501 "memory segment, or the caller must be privileged."
7505 #: build/C/man2/shmctl.2:136
7511 #: build/C/man2/shmctl.2:149
7513 "Mark the segment to be destroyed. The segment will only actually be "
7514 "destroyed after the last process detaches it (i.e., when the I<shm_nattch> "
7515 "member of the associated structure I<shmid_ds> is zero). The caller must be "
7516 "the owner or creator of the segment, or be privileged. The I<buf> argument "
7521 #: build/C/man2/shmctl.2:157
7523 "If a segment has been marked for destruction, then the (nonstandard) "
7524 "B<SHM_DEST> flag of the I<shm_perm.mode> field in the associated data "
7525 "structure retrieved by B<IPC_STAT> will be set."
7529 #: build/C/man2/shmctl.2:160
7531 "The caller I<must> ensure that a segment is eventually destroyed; otherwise "
7532 "its pages that were faulted in will remain in memory or swap."
7536 #: build/C/man2/shmctl.2:165
7538 "See also the description of I</proc/sys/kernel/shm_rmid_forced> in "
7543 #: build/C/man2/shmctl.2:165
7545 msgid "B<IPC_INFO> (Linux-specific)"
7549 #: build/C/man2/shmctl.2:178
7551 "Returns information about system-wide shared memory limits and parameters in "
7552 "the structure pointed to by I<buf>. This structure is of type I<shminfo> "
7553 "(thus, a cast is required), defined in I<E<lt>sys/shm.hE<gt>> if the "
7554 "B<_GNU_SOURCE> feature test macro is defined:"
7558 #: build/C/man2/shmctl.2:192
7561 "struct shminfo {\n"
7562 " unsigned long shmmax; /* Maximum segment size */\n"
7563 " unsigned long shmmin; /* Minimum segment size;\n"
7565 " unsigned long shmmni; /* Maximum number of segments */\n"
7566 " unsigned long shmseg; /* Maximum number of segments\n"
7567 " that a process can attach;\n"
7568 " unused within kernel */\n"
7569 " unsigned long shmall; /* Maximum number of pages of\n"
7570 " shared memory, system-wide */\n"
7575 #: build/C/man2/shmctl.2:205
7577 "The I<shmmni>, I<shmmax>, and I<shmall> settings can be changed via I</proc> "
7578 "files of the same name; see B<proc>(5) for details."
7582 #: build/C/man2/shmctl.2:205
7584 msgid "B<SHM_INFO> (Linux-specific)"
7588 #: build/C/man2/shmctl.2:216
7590 "Returns a I<shm_info> structure whose fields contain information about "
7591 "system resources consumed by shared memory. This structure is defined in "
7592 "I<E<lt>sys/shm.hE<gt>> if the B<_GNU_SOURCE> feature test macro is defined:"
7596 #: build/C/man2/shmctl.2:233
7599 "struct shm_info {\n"
7600 " int used_ids; /* # of currently existing\n"
7602 " unsigned long shm_tot; /* Total number of shared\n"
7603 " memory pages */\n"
7604 " unsigned long shm_rss; /* # of resident shared\n"
7605 " memory pages */\n"
7606 " unsigned long shm_swp; /* # of swapped shared\n"
7607 " memory pages */\n"
7608 " unsigned long swap_attempts;\n"
7609 " /* Unused since Linux 2.4 */\n"
7610 " unsigned long swap_successes;\n"
7611 " /* Unused since Linux 2.4 */\n"
7616 #: build/C/man2/shmctl.2:235
7618 msgid "B<SHM_STAT> (Linux-specific)"
7622 #: build/C/man2/shmctl.2:246
7624 "Returns a I<shmid_ds> structure as for B<IPC_STAT>. However, the I<shmid> "
7625 "argument is not a segment identifier, but instead an index into the kernel's "
7626 "internal array that maintains information about all shared memory segments "
7631 #: build/C/man2/shmctl.2:249
7633 "The caller can prevent or allow swapping of a shared memory segment with the "
7634 "following I<cmd> values:"
7638 #: build/C/man2/shmctl.2:250
7640 msgid "B<SHM_LOCK> (Linux-specific)"
7644 #: build/C/man2/shmctl.2:262
7646 "Prevent swapping of the shared memory segment. The caller must fault in any "
7647 "pages that are required to be present after locking is enabled. If a "
7648 "segment has been locked, then the (nonstandard) B<SHM_LOCKED> flag of the "
7649 "I<shm_perm.mode> field in the associated data structure retrieved by "
7650 "B<IPC_STAT> will be set."
7654 #: build/C/man2/shmctl.2:262
7656 msgid "B<SHM_UNLOCK> (Linux-specific)"
7660 #: build/C/man2/shmctl.2:265
7661 msgid "Unlock the segment, allowing it to be swapped out."
7664 #. There was some weirdness in 2.6.9: SHM_LOCK and SHM_UNLOCK could
7665 #. be applied to a segment, regardless of ownership of the segment.
7666 #. This was a botch-up in the move to RLIMIT_MEMLOCK, and was fixed
7667 #. in 2.6.10. MTK, May 2005
7669 #: build/C/man2/shmctl.2:283
7671 "In kernels before 2.6.10, only a privileged process could employ B<SHM_LOCK> "
7672 "and B<SHM_UNLOCK>. Since kernel 2.6.10, an unprivileged process can employ "
7673 "these operations if its effective UID matches the owner or creator UID of "
7674 "the segment, and (for B<SHM_LOCK>) the amount of memory to be locked falls "
7675 "within the B<RLIMIT_MEMLOCK> resource limit (see B<setrlimit>(2))."
7679 #: build/C/man2/shmctl.2:301
7681 "A successful B<IPC_INFO> or B<SHM_INFO> operation returns the index of the "
7682 "highest used entry in the kernel's internal array recording information "
7683 "about all shared memory segments. (This information can be used with "
7684 "repeated B<SHM_STAT> operations to obtain information about all shared "
7685 "memory segments on the system.) A successful B<SHM_STAT> operation returns "
7686 "the identifier of the shared memory segment whose index was given in "
7687 "I<shmid>. Other operations return 0 on success."
7691 #: build/C/man2/shmctl.2:305
7692 msgid "On error, -1 is returned, and I<errno> is set appropriately."
7696 #: build/C/man2/shmctl.2:314
7698 "B<IPC_STAT> or B<SHM_STAT> is requested and I<shm_perm.mode> does not allow "
7699 "read access for I<shmid>, and the calling process does not have the "
7700 "B<CAP_IPC_OWNER> capability."
7704 #: build/C/man2/shmctl.2:325
7706 "The argument I<cmd> has value B<IPC_SET> or B<IPC_STAT> but the address "
7707 "pointed to by I<buf> isn't accessible."
7711 #: build/C/man2/shmctl.2:325 build/C/man2/shmop.2:197
7717 #: build/C/man2/shmctl.2:328 build/C/man2/shmop.2:200
7718 msgid "I<shmid> points to a removed identifier."
7722 #: build/C/man2/shmctl.2:337
7724 "I<shmid> is not a valid identifier, or I<cmd> is not a valid command. Or: "
7725 "for a B<SHM_STAT> operation, the index value specified in I<shmid> referred "
7726 "to an array slot that is currently unused."
7730 #: build/C/man2/shmctl.2:348
7732 "(In kernels since 2.6.9), B<SHM_LOCK> was specified and the size of the "
7733 "to-be-locked segment would mean that the total bytes in locked shared memory "
7734 "segments would exceed the limit for the real user ID of the calling "
7735 "process. This limit is defined by the B<RLIMIT_MEMLOCK> soft resource limit "
7736 "(see B<setrlimit>(2))."
7740 #: build/C/man2/shmctl.2:353
7742 "B<IPC_STAT> is attempted, and the GID or UID value is too large to be stored "
7743 "in the structure pointed to by I<buf>."
7747 #: build/C/man2/shmctl.2:365
7749 "B<IPC_SET> or B<IPC_RMID> is attempted, and the effective user ID of the "
7750 "calling process is not that of the creator (found in I<shm_perm.cuid>), or "
7751 "the owner (found in I<shm_perm.uid>), and the process was not privileged "
7752 "(Linux: did not have the B<CAP_SYS_ADMIN> capability)."
7756 #: build/C/man2/shmctl.2:377
7758 "Or (in kernels before 2.6.9), B<SHM_LOCK> or B<SHM_UNLOCK> was specified, "
7759 "but the process was not privileged (Linux: did not have the B<CAP_IPC_LOCK> "
7760 "capability). (Since Linux 2.6.9, this error can also occur if the "
7761 "B<RLIMIT_MEMLOCK> is 0 and the caller is not privileged.)"
7764 #. SVr4 documents an additional error condition EMFILE.
7766 #: build/C/man2/shmctl.2:382 build/C/man2/shmget.2:235 build/C/man2/shmop.2:234
7767 msgid "SVr4, POSIX.1-2001."
7770 #. Like Linux, the FreeBSD man pages still document
7771 #. the inclusion of these header files.
7773 #: build/C/man2/shmctl.2:395 build/C/man2/shmget.2:251
7775 "The inclusion of I<E<lt>sys/types.hE<gt>> and I<E<lt>sys/ipc.hE<gt>> isn't "
7776 "required on Linux or by any version of POSIX. However, some old "
7777 "implementations required the inclusion of these header files, and the SVID "
7778 "also documented their inclusion. Applications intended to be portable to "
7779 "such old systems may need to include these header files."
7783 #: build/C/man2/shmctl.2:407
7785 "The B<IPC_INFO>, B<SHM_STAT> and B<SHM_INFO> operations are used by the "
7786 "B<ipcs>(1) program to provide information on allocated resources. In the "
7787 "future these may modified or moved to a I</proc> filesystem interface."
7791 #: build/C/man2/shmctl.2:415
7793 "Linux permits a process to attach (B<shmat>(2)) a shared memory segment "
7794 "that has already been marked for deletion using I<shmctl(IPC_RMID)>. This "
7795 "feature is not available on other UNIX implementations; portable "
7796 "applications should avoid relying on it."
7800 #: build/C/man2/shmctl.2:428
7802 "Various fields in a I<struct shmid_ds> were typed as I<short> under Linux "
7803 "2.2 and have become I<long> under Linux 2.4. To take advantage of this, a "
7804 "recompilation under glibc-2.1.91 or later should suffice. (The kernel "
7805 "distinguishes old and new calls by an B<IPC_64> flag in I<cmd>.)"
7809 #: build/C/man2/shmctl.2:435
7811 "B<mlock>(2), B<setrlimit>(2), B<shmget>(2), B<shmop>(2), B<capabilities>(7), "
7816 #: build/C/man2/shmget.2:38
7822 #: build/C/man2/shmget.2:41
7823 msgid "shmget - allocates a System V shared memory segment"
7827 #: build/C/man2/shmget.2:48
7828 msgid "B<int shmget(key_t >I<key>B<, size_t >I<size>B<, int >I<shmflg>B<);>"
7832 #: build/C/man2/shmget.2:72
7834 "B<shmget>() returns the identifier of the System V shared memory segment "
7835 "associated with the value of the argument I<key>. A new shared memory "
7836 "segment, with size equal to the value of I<size> rounded up to a multiple of "
7837 "B<PAGE_SIZE>, is created if I<key> has the value B<IPC_PRIVATE> or I<key> "
7838 "isn't B<IPC_PRIVATE>, no shared memory segment corresponding to I<key> "
7839 "exists, and B<IPC_CREAT> is specified in I<shmflg>."
7843 #: build/C/man2/shmget.2:91
7845 "If I<shmflg> specifies both B<IPC_CREAT> and B<IPC_EXCL> and a shared memory "
7846 "segment already exists for I<key>, then B<shmget>() fails with I<errno> set "
7847 "to B<EEXIST>. (This is analogous to the effect of the combination B<O_CREAT "
7848 "| O_EXCL> for B<open>(2).)"
7852 #: build/C/man2/shmget.2:95
7853 msgid "The value I<shmflg> is composed of:"
7857 #: build/C/man2/shmget.2:95
7859 msgid "B<IPC_CREAT>"
7863 #: build/C/man2/shmget.2:102
7865 "to create a new segment. If this flag is not used, then B<shmget>() will "
7866 "find the segment associated with I<key> and check to see if the user has "
7867 "permission to access the segment."
7871 #: build/C/man2/shmget.2:102
7877 #: build/C/man2/shmget.2:105
7878 msgid "used with B<IPC_CREAT> to ensure failure if the segment already exists."
7882 #: build/C/man2/shmget.2:105
7884 msgid "I<mode_flags>"
7888 #: build/C/man2/shmget.2:115
7890 "(least significant 9 bits) specifying the permissions granted to the owner, "
7891 "group, and world. These bits have the same format, and the same meaning, as "
7892 "the I<mode> argument of B<open>(2). Presently, the execute permissions are "
7893 "not used by the system."
7897 #: build/C/man2/shmget.2:115
7899 msgid "B<SHM_HUGETLB> (since Linux 2.6)"
7903 #: build/C/man2/shmget.2:121
7905 "Allocate the segment using \"huge pages.\" See the Linux kernel source file "
7906 "I<Documentation/vm/hugetlbpage.txt> for further information."
7910 #: build/C/man2/shmget.2:121
7912 msgid "B<SHM_NORESERVE> (since Linux 2.6.15)"
7915 #. As at 2.6.17-rc2, this flag has no effect if SHM_HUGETLB was also
7918 #: build/C/man2/shmget.2:140
7920 "This flag serves the same purpose as the B<mmap>(2) B<MAP_NORESERVE> flag. "
7921 "Do not reserve swap space for this segment. When swap space is reserved, "
7922 "one has the guarantee that it is possible to modify the segment. When swap "
7923 "space is not reserved one might get B<SIGSEGV> upon a write if no physical "
7924 "memory is available. See also the discussion of the file "
7925 "I</proc/sys/vm/overcommit_memory> in B<proc>(5)."
7929 #: build/C/man2/shmget.2:148
7931 "When a new shared memory segment is created, its contents are initialized to "
7932 "zero values, and its associated data structure, I<shmid_ds> (see "
7933 "B<shmctl>(2)), is initialized as follows:"
7937 #: build/C/man2/shmget.2:153
7939 "I<shm_perm.cuid> and I<shm_perm.uid> are set to the effective user ID of the "
7944 #: build/C/man2/shmget.2:158
7946 "I<shm_perm.cgid> and I<shm_perm.gid> are set to the effective group ID of "
7947 "the calling process."
7951 #: build/C/man2/shmget.2:163
7953 "The least significant 9 bits of I<shm_perm.mode> are set to the least "
7954 "significant 9 bit of I<shmflg>."
7958 #: build/C/man2/shmget.2:167
7959 msgid "I<shm_segsz> is set to the value of I<size>."
7963 #: build/C/man2/shmget.2:174
7964 msgid "I<shm_lpid>, I<shm_nattch>, I<shm_atime>, and I<shm_dtime> are set to 0."
7968 #: build/C/man2/shmget.2:177
7969 msgid "I<shm_ctime> is set to the current time."
7973 #: build/C/man2/shmget.2:180
7975 "If the shared memory segment already exists, the permissions are verified, "
7976 "and a check is made to see if it is marked for destruction."
7980 #: build/C/man2/shmget.2:185
7982 "On success, a valid shared memory identifier is returned. On error, -1 is "
7983 "returned, and I<errno> is set to indicate the error."
7987 #: build/C/man2/shmget.2:189
7988 msgid "On failure, I<errno> is set to one of the following:"
7992 #: build/C/man2/shmget.2:195
7994 "The user does not have permission to access the shared memory segment, and "
7995 "does not have the B<CAP_IPC_OWNER> capability."
7999 #: build/C/man2/shmget.2:199
8000 msgid "B<IPC_CREAT | IPC_EXCL> was specified and the segment exists."
8004 #: build/C/man2/shmget.2:205
8006 "A new segment was to be created and I<size> E<lt> B<SHMMIN> or I<size> E<gt> "
8007 "B<SHMMAX>, or no new segment was to be created, a segment with given key "
8008 "existed, but I<size> is greater than the size of that segment."
8012 #: build/C/man2/shmget.2:214
8013 msgid "No segment exists for the given I<key>, and B<IPC_CREAT> was not specified."
8017 #: build/C/man2/shmget.2:217
8018 msgid "No memory could be allocated for segment overhead."
8022 #: build/C/man2/shmget.2:225
8024 "All possible shared memory IDs have been taken (B<SHMMNI>), or allocating a "
8025 "segment of the requested I<size> would cause the system to exceed the "
8026 "system-wide limit on shared memory (B<SHMALL>)."
8030 #: build/C/man2/shmget.2:232
8032 "The B<SHM_HUGETLB> flag was specified, but the caller was not privileged "
8033 "(did not have the B<CAP_IPC_LOCK> capability)."
8037 #: build/C/man2/shmget.2:238
8038 msgid "B<SHM_HUGETLB> is a nonportable Linux extension."
8042 #: build/C/man2/shmget.2:261
8044 "B<IPC_PRIVATE> isn't a flag field but a I<key_t> type. If this special "
8045 "value is used for I<key>, the system call ignores everything but the least "
8046 "significant 9 bits of I<shmflg> and creates a new shared memory segment (on "
8051 #: build/C/man2/shmget.2:265
8053 "The following limits on shared memory segment resources affect the "
8058 #: build/C/man2/shmget.2:265
8064 #: build/C/man2/shmget.2:269
8066 "System wide maximum of shared memory pages. Since Linux 2.2, the default "
8067 "value for this limit is"
8071 #: build/C/man2/shmget.2:271
8073 msgid " SHMMAX / PAGE_SIZE * (SHMMNI / 16)\n"
8077 #: build/C/man2/shmget.2:274
8079 "Assuming a 4kB page size, this formula yields (since Linux 2.4) the value "
8084 #: build/C/man2/shmget.2:277
8086 "On Linux, this limit can be read and modified via "
8087 "I</proc/sys/kernel/shmall>."
8091 #: build/C/man2/shmget.2:277
8097 #: build/C/man2/shmget.2:281
8099 "Maximum size in bytes for a shared memory segment. Since Linux 2.2, the "
8100 "default value of this limit is 0x2000000 (32MB)."
8104 #: build/C/man2/shmget.2:284
8106 "On Linux, this limit can be read and modified via "
8107 "I</proc/sys/kernel/shmmax>."
8111 #: build/C/man2/shmget.2:284
8117 #: build/C/man2/shmget.2:290
8119 "Minimum size in bytes for a shared memory segment: implementation dependent "
8120 "(currently 1 byte, though B<PAGE_SIZE> is the effective minimum size)."
8124 #: build/C/man2/shmget.2:290
8130 #: build/C/man2/shmget.2:295
8132 "System wide maximum number of shared memory segments. In Linux 2.2, the "
8133 "default value for this limit was 128; since Linux 2.4, the default value is "
8137 #. Kernels between 2.4.x and 2.6.8 had an off-by-one error that meant
8138 #. that we could create one more segment than SHMMNI -- MTK
8139 #. This /proc file is not available in Linux 2.2 and earlier -- MTK
8141 #: build/C/man2/shmget.2:301
8143 "On Linux, this limit can be read and modified via "
8144 "I</proc/sys/kernel/shmmni>."
8148 #: build/C/man2/shmget.2:305
8150 "The implementation has no specific limits for the per-process maximum number "
8151 "of shared memory segments (B<SHMSEG>)."
8155 #: build/C/man2/shmget.2:311
8157 "Until version 2.3.30 Linux would return B<EIDRM> for a B<shmget>() on a "
8158 "shared memory segment scheduled for deletion."
8162 #: build/C/man2/shmget.2:317
8164 "The name choice B<IPC_PRIVATE> was perhaps unfortunate, B<IPC_NEW> would "
8165 "more clearly show its function."
8169 #: build/C/man2/shmget.2:325
8171 "B<shmat>(2), B<shmctl>(2), B<shmdt>(2), B<ftok>(3), B<capabilities>(7), "
8172 "B<shm_overview>(7), B<svipc>(7)"
8176 #: build/C/man2/shmop.2:41
8182 #: build/C/man2/shmop.2:44
8183 msgid "shmat, shmdt - System V shared memory operations"
8187 #: build/C/man2/shmop.2:48
8190 "B<#include E<lt>sys/types.hE<gt>>\n"
8191 "B<#include E<lt>sys/shm.hE<gt>>\n"
8195 #: build/C/man2/shmop.2:50
8198 "B<void *shmat(int >I<shmid>B<, const void *>I<shmaddr>B<, int "
8203 #: build/C/man2/shmop.2:52
8205 msgid "B<int shmdt(const void *>I<shmaddr>B<);>\n"
8209 #: build/C/man2/shmop.2:61
8211 "B<shmat>() attaches the System V shared memory segment identified by "
8212 "I<shmid> to the address space of the calling process. The attaching address "
8213 "is specified by I<shmaddr> with one of the following criteria:"
8217 #: build/C/man2/shmop.2:67
8219 "If I<shmaddr> is NULL, the system chooses a suitable (unused) address at "
8220 "which to attach the segment."
8224 #: build/C/man2/shmop.2:82
8226 "If I<shmaddr> isn't NULL and B<SHM_RND> is specified in I<shmflg>, the "
8227 "attach occurs at the address equal to I<shmaddr> rounded down to the nearest "
8228 "multiple of B<SHMLBA>. Otherwise I<shmaddr> must be a page-aligned address "
8229 "at which the attach occurs."
8233 #: build/C/man2/shmop.2:92
8235 "If B<SHM_RDONLY> is specified in I<shmflg>, the segment is attached for "
8236 "reading and the process must have read permission for the segment. "
8237 "Otherwise the segment is attached for read and write and the process must "
8238 "have read and write permission for the segment. There is no notion of a "
8239 "write-only shared memory segment."
8243 #: build/C/man2/shmop.2:107
8245 "The (Linux-specific) B<SHM_REMAP> flag may be specified in I<shmflg> to "
8246 "indicate that the mapping of the segment should replace any existing mapping "
8247 "in the range starting at I<shmaddr> and continuing for the size of the "
8248 "segment. (Normally an B<EINVAL> error would result if a mapping already "
8249 "exists in this address range.) In this case, I<shmaddr> must not be NULL."
8253 #: build/C/man2/shmop.2:114
8255 "The B<brk>(2) value of the calling process is not altered by the attach. "
8256 "The segment will automatically be detached at process exit. The same "
8257 "segment may be attached as a read and as a read-write one, and more than "
8258 "once, in the process's address space."
8262 #: build/C/man2/shmop.2:122
8264 "A successful B<shmat>() call updates the members of the I<shmid_ds> "
8265 "structure (see B<shmctl>(2)) associated with the shared memory segment as "
8270 #: build/C/man2/shmop.2:125
8271 msgid "I<shm_atime> is set to the current time."
8275 #: build/C/man2/shmop.2:128 build/C/man2/shmop.2:154
8276 msgid "I<shm_lpid> is set to the process-ID of the calling process."
8280 #: build/C/man2/shmop.2:131
8281 msgid "I<shm_nattch> is incremented by one."
8285 #: build/C/man2/shmop.2:142
8287 "B<shmdt>() detaches the shared memory segment located at the address "
8288 "specified by I<shmaddr> from the address space of the calling process. The "
8289 "to-be-detached segment must be currently attached with I<shmaddr> equal to "
8290 "the value returned by the attaching B<shmat>() call."
8294 #: build/C/man2/shmop.2:148
8296 "On a successful B<shmdt>() call the system updates the members of the "
8297 "I<shmid_ds> structure associated with the shared memory segment as follows:"
8301 #: build/C/man2/shmop.2:151
8302 msgid "I<shm_dtime> is set to the current time."
8306 #: build/C/man2/shmop.2:159
8308 "I<shm_nattch> is decremented by one. If it becomes 0 and the segment is "
8309 "marked for deletion, the segment is deleted."
8313 #: build/C/man2/shmop.2:163
8314 msgid "After a B<fork>(2) the child inherits the attached shared memory segments."
8318 #: build/C/man2/shmop.2:167
8320 "After an B<execve>(2) all attached shared memory segments are detached from "
8325 #: build/C/man2/shmop.2:171
8327 "Upon B<_exit>(2) all attached shared memory segments are detached from the "
8332 #: build/C/man2/shmop.2:179
8334 "On success B<shmat>() returns the address of the attached shared memory "
8335 "segment; on error I<(void\\ *)\\ -1> is returned, and I<errno> is set to "
8336 "indicate the cause of the error."
8340 #: build/C/man2/shmop.2:185
8342 "On success B<shmdt>() returns 0; on error -1 is returned, and I<errno> is "
8343 "set to indicate the cause of the error."
8347 #: build/C/man2/shmop.2:191
8348 msgid "When B<shmat>() fails, I<errno> is set to one of the following:"
8352 #: build/C/man2/shmop.2:197
8354 "The calling process does not have the required permissions for the requested "
8355 "attach type, and does not have the B<CAP_IPC_OWNER> capability."
8359 #: build/C/man2/shmop.2:214
8361 "Invalid I<shmid> value, unaligned (i.e., not page-aligned and B<SHM_RND> was "
8362 "not specified) or invalid I<shmaddr> value, or can't attach segment at "
8363 "I<shmaddr>, or B<SHM_REMAP> was specified and I<shmaddr> was NULL."
8367 #: build/C/man2/shmop.2:217
8368 msgid "Could not allocate memory for the descriptor or for the page tables."
8372 #: build/C/man2/shmop.2:223
8373 msgid "When B<shmdt>() fails, I<errno> is set as follows:"
8376 #. The following since 2.6.17-rc1:
8378 #: build/C/man2/shmop.2:231
8380 "There is no shared memory segment attached at I<shmaddr>; or, I<shmaddr> is "
8381 "not aligned on a page boundary."
8385 #: build/C/man2/shmop.2:250
8387 "In SVID 3 (or perhaps earlier) the type of the I<shmaddr> argument was "
8388 "changed from I<char\\ *> into I<const void\\ *>, and the returned type of "
8389 "B<shmat>() from I<char\\ *> into I<void\\ *>. (Linux libc4 and libc5 have "
8390 "the I<char\\ *> prototypes; glibc2 has I<void\\ *>.)"
8394 #: build/C/man2/shmop.2:262
8396 "Using B<shmat>() with I<shmaddr> equal to NULL is the preferred, portable "
8397 "way of attaching a shared memory segment. Be aware that the shared memory "
8398 "segment attached in this way may be attached at different addresses in "
8399 "different processes. Therefore, any pointers maintained within the shared "
8400 "memory must be made relative (typically to the starting address of the "
8401 "segment), rather than absolute."
8405 #: build/C/man2/shmop.2:267
8407 "On Linux, it is possible to attach a shared memory segment even if it is "
8408 "already marked to be deleted. However, POSIX.1-2001 does not specify this "
8409 "behavior and many other implementations do not support it."
8413 #: build/C/man2/shmop.2:270
8414 msgid "The following system parameter affects B<shmat>():"
8417 #. FIXME A good explanation of the rationale for the existence
8418 #. of SHMLBA would be useful here
8420 #: build/C/man2/shmop.2:270
8425 #. FIXME That last sentence isn't true for all Linux
8426 #. architectures (i.e., SHMLBA != PAGE_SIZE for some architectures)
8429 #: build/C/man2/shmop.2:283
8431 "Segment low boundary address multiple. Must be page aligned. For the "
8432 "current implementation the B<SHMLBA> value is B<PAGE_SIZE>."
8436 #: build/C/man2/shmop.2:287
8438 "The implementation places no intrinsic limit on the per-process maximum "
8439 "number of shared memory segments (B<SHMSEG>)."
8443 #: build/C/man2/shmop.2:295
8445 "B<brk>(2), B<mmap>(2), B<shmctl>(2), B<shmget>(2), B<capabilities>(7), "
8446 "B<shm_overview>(7), B<svipc>(7)"
8450 #: build/C/man2/subpage_prot.2:30
8452 msgid "SUBPAGE_PROT"
8456 #: build/C/man2/subpage_prot.2:30
8462 #: build/C/man2/subpage_prot.2:33
8463 msgid "subpage_prot - define a subpage protection for an address range"
8467 #: build/C/man2/subpage_prot.2:37
8470 "B<long subpage_prot(unsigned long >I<addr>B<, unsigned long >I<len>B<,>\n"
8471 "B< uint32_t *>I<map>B<);>\n"
8475 #: build/C/man2/subpage_prot.2:41
8476 msgid "I<Note>: There is no glibc wrapper for this system call; see NOTES."
8480 #: build/C/man2/subpage_prot.2:47
8482 "The PowerPC-specific B<subpage_prot>() system call provides the facility to "
8483 "control the access permissions on individual 4kB subpages on systems "
8484 "configured with a page size of 64kB."
8488 #: build/C/man2/subpage_prot.2:54
8490 "The protection map is applied to the memory pages in the region starting at "
8491 "I<addr> and continuing for I<len> bytes. Both of these arguments must be "
8492 "aligned to a 64-kB boundary."
8496 #: build/C/man2/subpage_prot.2:66
8498 "The protection map is specified in the buffer pointed to by I<map>. The map "
8499 "has 2 bits per 4kB subpage; thus each 32-bit word specifies the protections "
8500 "of 16 4kB subpages inside a 64kB page (so, the number of 32-bit words "
8501 "pointed to by I<map> should equate to the number of 64-kB pages specified by "
8502 "I<len>). Each 2-bit field in the protection map is either 0 to allow any "
8503 "access, 1 to prevent writes, or 2 or 3 to prevent all accesses."
8507 #: build/C/man2/subpage_prot.2:71
8509 "On success, B<subpage_prot>() returns 0. Otherwise, one of the error codes "
8510 "specified below is returned."
8514 #: build/C/man2/subpage_prot.2:77
8515 msgid "The buffer referred to by I<map> is not accessible."
8519 #: build/C/man2/subpage_prot.2:87
8521 "The I<addr> or I<len> arguments are incorrect. Both of these arguments must "
8522 "be aligned to a multiple of the system page size, and they must not refer to "
8523 "a region outside of the address space of the process or to a region that "
8524 "consists of huge pages."
8528 #: build/C/man2/subpage_prot.2:90 build/C/man2/sync_file_range.2:166
8529 msgid "Out of memory."
8533 #: build/C/man2/subpage_prot.2:96
8535 "This system call is provided on the PowerPC architecture since Linux "
8536 "2.6.25. The system call is provided only if the kernel is configured with "
8537 "B<CONFIG_PPC_64K_PAGES>. No library support is provided."
8541 #: build/C/man2/subpage_prot.2:101
8543 "Glibc does not provide a wrapper for this system call; call it using "
8548 #: build/C/man2/subpage_prot.2:106
8550 "Normal page protections (at the 64-kB page level) also apply; the subpage "
8551 "protection mechanism is an additional constraint, so putting 0 in a 2-bit "
8552 "field won't allow writes to a page that is otherwise write-protected."
8556 #: build/C/man2/subpage_prot.2:106
8561 #. In the initial implementation, it was the case that:
8562 #. In fact the whole process is switched to use 4k hardware pages when the
8563 #. subpage_prot system call is used, but this could be improved in future
8564 #. to switch only the affected segments.
8565 #. But Paul Mackerass says (Oct 2010): I'm pretty sure we now only switch
8566 #. the affected segment, not the whole process.
8568 #: build/C/man2/subpage_prot.2:128
8570 "This system call is provided to assist writing emulators that operate using "
8571 "64-kB pages on PowerPC systems. When emulating systems such as x86, which "
8572 "uses a smaller page size, the emulator can no longer use the "
8573 "memory-management unit (MMU) and normal system calls for controlling page "
8574 "protections. (The emulator could emulate the MMU by checking and possibly "
8575 "remapping the address for each memory access in software, but that is slow.) "
8576 "The idea is that the emulator supplies an array of protection masks to apply "
8577 "to a specified range of virtual addresses. These masks are applied at the "
8578 "level where hardware page-table entries (PTEs) are inserted into the "
8579 "hardware page table based on the Linux PTEs, so the Linux PTEs are not "
8580 "affected. Implicit in this is that the regions of the address space that "
8581 "are protected are switched to use 4-kB hardware pages rather than 64-kB "
8582 "hardware pages (on machines with hardware 64-kB page support)."
8586 #: build/C/man2/subpage_prot.2:131
8587 msgid "B<mprotect>(2), B<syscall>(2)"
8591 #: build/C/man2/subpage_prot.2:134
8592 msgid "I<Documentation/vm/hugetlbpage.txt> in the Linux kernel source tree"
8596 #: build/C/man2/sync_file_range.2:30
8598 msgid "SYNC_FILE_RANGE"
8602 #: build/C/man2/sync_file_range.2:33
8603 msgid "sync_file_range - sync a file segment with disk"
8607 #: build/C/man2/sync_file_range.2:37
8610 "B<#define _GNU_SOURCE> /* See feature_test_macros(7) */\n"
8611 "B<#include E<lt>fcntl.hE<gt>>\n"
8615 #: build/C/man2/sync_file_range.2:40
8618 "B<int sync_file_range(int >I<fd>B<, off64_t >I<offset>B<, off64_t "
8620 "B< unsigned int >I<flags>B<);>\n"
8624 #: build/C/man2/sync_file_range.2:47
8626 "B<sync_file_range>() permits fine control when synchronizing the open file "
8627 "referred to by the file descriptor I<fd> with disk."
8631 #: build/C/man2/sync_file_range.2:61
8633 "I<offset> is the starting byte of the file range to be synchronized. "
8634 "I<nbytes> specifies the length of the range to be synchronized, in bytes; if "
8635 "I<nbytes> is zero, then all bytes from I<offset> through to the end of file "
8636 "are synchronized. Synchronization is in units of the system page size: "
8637 "I<offset> is rounded down to a page boundary; I<(offset+nbytes-1)> is "
8638 "rounded up to a page boundary."
8642 #: build/C/man2/sync_file_range.2:65
8643 msgid "The I<flags> bit-mask argument can include any of the following values:"
8647 #: build/C/man2/sync_file_range.2:65
8649 msgid "B<SYNC_FILE_RANGE_WAIT_BEFORE>"
8653 #: build/C/man2/sync_file_range.2:70
8655 "Wait upon write-out of all pages in the specified range that have already "
8656 "been submitted to the device driver for write-out before performing any "
8661 #: build/C/man2/sync_file_range.2:70 build/C/man2/sync_file_range.2:120
8663 msgid "B<SYNC_FILE_RANGE_WRITE>"
8667 #: build/C/man2/sync_file_range.2:76
8669 "Initiate write-out of all dirty pages in the specified range which are not "
8670 "presently submitted write-out. Note that even this may block if you attempt "
8671 "to write more than request queue size."
8675 #: build/C/man2/sync_file_range.2:76
8677 msgid "B<SYNC_FILE_RANGE_WAIT_AFTER>"
8681 #: build/C/man2/sync_file_range.2:80
8682 msgid "Wait upon write-out of all pages in the range after performing any write."
8686 #: build/C/man2/sync_file_range.2:84
8687 msgid "Specifying I<flags> as 0 is permitted, as a no-op."
8691 #: build/C/man2/sync_file_range.2:84
8697 #: build/C/man2/sync_file_range.2:100
8699 "This system call is extremely dangerous and should not be used in portable "
8700 "programs. None of these operations writes out the file's metadata. "
8701 "Therefore, unless the application is strictly performing overwrites of "
8702 "already-instantiated disk blocks, there are no guarantees that the data will "
8703 "be available after a crash. There is no user interface to know if a write "
8704 "is purely an overwrite. On filesystems using copy-on-write semantics (e.g., "
8705 "I<btrfs>) an overwrite of existing allocated blocks is impossible. When "
8706 "writing into preallocated space, many filesystems also require calls into "
8707 "the block allocator, which this system call does not sync out to disk. This "
8708 "system call does not flush disk write caches and thus does not provide any "
8709 "data integrity on systems with volatile disk write caches."
8713 #: build/C/man2/sync_file_range.2:100
8715 msgid "Some details"
8719 #: build/C/man2/sync_file_range.2:108
8721 "B<SYNC_FILE_RANGE_WAIT_BEFORE> and B<SYNC_FILE_RANGE_WAIT_AFTER> will detect "
8722 "any I/O errors or B<ENOSPC> conditions and will return these to the caller."
8726 #: build/C/man2/sync_file_range.2:112
8727 msgid "Useful combinations of the I<flags> bits are:"
8731 #: build/C/man2/sync_file_range.2:112
8733 msgid "B<SYNC_FILE_RANGE_WAIT_BEFORE | SYNC_FILE_RANGE_WRITE>"
8737 #: build/C/man2/sync_file_range.2:120
8739 "Ensures that all pages in the specified range which were dirty when "
8740 "B<sync_file_range>() was called are placed under write-out. This is a "
8741 "start-write-for-data-integrity operation."
8745 #: build/C/man2/sync_file_range.2:127
8747 "Start write-out of all dirty pages in the specified range which are not "
8748 "presently under write-out. This is an asynchronous flush-to-disk "
8749 "operation. This is not suitable for data integrity operations."
8753 #: build/C/man2/sync_file_range.2:127
8755 msgid "B<SYNC_FILE_RANGE_WAIT_BEFORE> (or B<SYNC_FILE_RANGE_WAIT_AFTER>)"
8759 #: build/C/man2/sync_file_range.2:134
8761 "Wait for completion of write-out of all pages in the specified range. This "
8762 "can be used after an earlier B<SYNC_FILE_RANGE_WAIT_BEFORE | "
8763 "SYNC_FILE_RANGE_WRITE> operation to wait for completion of that operation, "
8764 "and obtain its result."
8768 #: build/C/man2/sync_file_range.2:134
8771 "B<SYNC_FILE_RANGE_WAIT_BEFORE | SYNC_FILE_RANGE_WRITE | "
8772 "SYNC_FILE_RANGE_WAIT_AFTER>"
8776 #: build/C/man2/sync_file_range.2:141
8778 "This is a write-for-data-integrity operation that will ensure that all pages "
8779 "in the specified range which were dirty when B<sync_file_range>() was "
8780 "called are committed to disk."
8784 #: build/C/man2/sync_file_range.2:147
8786 "On success, B<sync_file_range>() returns 0; on failure -1 is returned and "
8787 "I<errno> is set to indicate the error."
8791 #: build/C/man2/sync_file_range.2:152
8792 msgid "I<fd> is not a valid file descriptor."
8796 #: build/C/man2/sync_file_range.2:160
8797 msgid "I<flags> specifies an invalid bit; or I<offset> or I<nbytes> is invalid."
8801 #: build/C/man2/sync_file_range.2:163
8806 #: build/C/man2/sync_file_range.2:169
8807 msgid "Out of disk space."
8810 #. FIXME . (bug?) Actually, how can 'fd' refer to a symbolic link (S_ISLNK)?
8811 #. (In user space at least) it isn't possible to obtain a file descriptor
8812 #. for a symbolic link.
8814 #: build/C/man2/sync_file_range.2:177
8816 "I<fd> refers to something other than a regular file, a block device, a "
8817 "directory, or a symbolic link."
8821 #: build/C/man2/sync_file_range.2:180
8822 msgid "B<sync_file_range>() appeared on Linux in kernel 2.6.17."
8826 #: build/C/man2/sync_file_range.2:183
8828 "This system call is Linux-specific, and should be avoided in portable "
8832 #. See kernel commit edd5cd4a9424f22b0fa08bef5e299d41befd5622
8834 #: build/C/man2/sync_file_range.2:200
8836 "Some architectures (e.g., PowerPC, ARM) need 64-bit arguments to be aligned "
8837 "in a suitable pair of registers. On such architectures, the call signature "
8838 "of B<sync_file_range>() shown in the SYNOPSIS would force a register to be "
8839 "wasted as padding between the I<fd> and I<offset> arguments. (See "
8840 "B<syscall>(2) for details.) Therefore, these architectures define a "
8841 "different system call that orders the arguments suitably:"
8845 #: build/C/man2/sync_file_range.2:205
8848 "B<int sync_file_range2(int >I<fd>B<, unsigned int >I<flags>B<,>\n"
8849 "B< off64_t >I<offset>B<, off64_t >I<nbytes>B<);>\n"
8853 #: build/C/man2/sync_file_range.2:210
8855 "The behavior of this system call is otherwise exactly the same as "
8856 "B<sync_file_range>()."
8860 #: build/C/man2/sync_file_range.2:221
8862 "A system call with this signature first appeared on the ARM architecture in "
8863 "Linux 2.6.20, with the name B<arm_sync_file_range>(). It was renamed in "
8864 "Linux 2.6.22, when the analogous system call was added for PowerPC. On "
8865 "architectures where glibc support is provided, glibc transparently wraps "
8866 "B<sync_file_range2>() under the name B<sync_file_range>()."
8870 #: build/C/man2/sync_file_range.2:226
8871 msgid "B<fdatasync>(2), B<fsync>(2), B<msync>(2), B<sync>(2)"