]>
Commit | Line | Data |
---|---|---|
b99daa3f MK |
1 | .\" Copyright (C) 2015 Michael Kerrisk <mtk.manpages@gmail.com> |
2 | .\" | |
3 | .\" %%%LICENSE_START(GPLv2+) | |
4 | .\" | |
5 | .\" This program is free software; you can redistribute it and/or modify | |
6 | .\" it under the terms of the GNU General Public License as published by | |
7 | .\" the Free Software Foundation; either version 2 of the License, or | |
8 | .\" (at your option) any later version. | |
9 | .\" | |
10 | .\" This program is distributed in the hope that it will be useful, | |
11 | .\" but WITHOUT ANY WARRANTY; without even the implied warranty of | |
12 | .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
13 | .\" GNU General Public License for more details. | |
14 | .\" | |
15 | .\" You should have received a copy of the GNU General Public | |
16 | .\" License along with this manual; if not, see | |
17 | .\" <http://www.gnu.org/licenses/>. | |
18 | .\" %%%LICENSE_END | |
19 | .\" | |
4b8c67d9 | 20 | .TH POSIX_MADVISE 3 2017-09-15 Linux "Linux Programmer's Manual" |
b99daa3f MK |
21 | .SH NAME |
22 | posix_madvise \- give advice about patterns of memory usage | |
23 | .SH SYNOPSIS | |
24 | .nf | |
25 | .B #include <sys/mman.h> | |
dbfe9c70 | 26 | .PP |
b99daa3f MK |
27 | .BI "int posix_madvise(void *" addr ", size_t " len ", int " advice ); |
28 | .fi | |
dbfe9c70 | 29 | .PP |
b99daa3f MK |
30 | .in -4n |
31 | Feature Test Macro Requirements for glibc (see | |
32 | .BR feature_test_macros (7)): | |
33 | .in | |
68e4db0a | 34 | .PP |
b99daa3f MK |
35 | .BR posix_madvise (): |
36 | .br | |
37 | .RS 4 | |
38 | .ad l | |
a446ac0c | 39 | _POSIX_C_SOURCE >= 200112L |
b99daa3f MK |
40 | .RE |
41 | .ad | |
42 | .SH DESCRIPTION | |
43 | The | |
44 | .BR posix_madvise () | |
45 | function allows an application to advise the system about its expected | |
46 | patterns of usage of memory in the address range starting at | |
47 | .I addr | |
48 | and continuing for | |
49 | .I len | |
50 | bytes. | |
51 | The system is free to use this advice in order to improve the performance | |
52 | of memory accesses (or to ignore the advice altogether), but calling | |
53 | .BR posix_madvise () | |
54 | shall not affect the semantics of access to memory in the specified range. | |
847e0d88 | 55 | .PP |
b99daa3f MK |
56 | The |
57 | .I advice | |
58 | argument is one of the following: | |
59 | .TP | |
60 | .B POSIX_MADV_NORMAL | |
61 | The application has no special advice regarding its memory usage patterns | |
62 | for the specified address range. | |
63 | This is the default behavior. | |
64 | .TP | |
65 | .B POSIX_MADV_SEQUENTIAL | |
66 | The application expects to access the specified address range sequentially, | |
67 | running from lower addresses to higher addresses. | |
68 | Hence, pages in this region can be aggressively read ahead, | |
69 | and may be freed soon after they are accessed. | |
70 | .TP | |
71 | .B POSIX_MADV_RANDOM | |
72 | The application expects to access the specified address range randomly. | |
73 | Thus, read ahead may be less useful than normally. | |
74 | .TP | |
75 | .B POSIX_MADV_WILLNEED | |
76 | The application expects to access the specified address range | |
77 | in the near future. | |
78 | Thus, read ahead may be beneficial. | |
79 | .TP | |
80 | .B POSIX_MADV_DONTNEED | |
81 | The application expects that it will not access the specified address range | |
82 | in the near future. | |
83 | .SH RETURN VALUE | |
84 | On success, | |
85 | .BR posix_madvise () | |
86 | returns 0. | |
87 | On failure, it returns a positive error number. | |
88 | .SH ERRORS | |
89 | .TP | |
90 | .B EINVAL | |
91 | .I addr | |
92 | is not a multiple of the system page size or | |
93 | .I len | |
94 | is negative. | |
95 | .TP | |
96 | .B EINVAL | |
97 | .I advice | |
98 | is invalid. | |
99 | .TP | |
100 | .B ENOMEM | |
101 | Addresses in the specified range are partially or completely outside | |
102 | the caller's address space. | |
103 | .SH VERSIONS | |
104 | Support for | |
105 | .BR posix_madvise () | |
106 | first appeared in glibc version 2.2. | |
107 | .SH CONFORMING TO | |
108 | POSIX.1-2001. | |
b99daa3f MK |
109 | .SH NOTES |
110 | POSIX.1 permits an implementation to generate an error if | |
111 | .I len | |
112 | is 0. | |
113 | On Linux, specifying | |
114 | .I len | |
115 | as 0 is permitted (as a successful no-op). | |
847e0d88 | 116 | .PP |
b99daa3f MK |
117 | In glibc, this function is implemented using |
118 | .BR madvise (2). | |
119 | However, since glibc 2.6, | |
120 | .BR POSIX_MADV_DONTNEED | |
121 | is treated as a no-op, because the corresponding | |
122 | .BR madvise (2) | |
123 | value, | |
124 | .BR MADV_DONTNEED , | |
125 | has destructive semantics. | |
126 | .SH SEE ALSO | |
127 | .BR madvise (2), | |
128 | .BR posix_fadvise (2) |