]>
Commit | Line | Data |
---|---|---|
b99daa3f MK |
1 | .\" Copyright (C) 2015 Michael Kerrisk <mtk.manpages@gmail.com> |
2 | .\" | |
e4a74ca8 | 3 | .\" SPDX-License-Identifier: GPL-2.0-or-later |
b99daa3f | 4 | .\" |
4c1c5274 | 5 | .TH posix_madvise 3 (date) "Linux man-pages (unreleased)" |
b99daa3f MK |
6 | .SH NAME |
7 | posix_madvise \- give advice about patterns of memory usage | |
8497c7a6 AC |
8 | .SH LIBRARY |
9 | Standard C library | |
8fc3b2cf | 10 | .RI ( libc ", " \-lc ) |
b99daa3f MK |
11 | .SH SYNOPSIS |
12 | .nf | |
13 | .B #include <sys/mman.h> | |
c6d039a3 | 14 | .P |
c64cd13e | 15 | .BI "int posix_madvise(void " addr [. len "], size_t " len ", int " advice ); |
b99daa3f | 16 | .fi |
c6d039a3 | 17 | .P |
d39ad78f | 18 | .RS -4 |
b99daa3f MK |
19 | Feature Test Macro Requirements for glibc (see |
20 | .BR feature_test_macros (7)): | |
d39ad78f | 21 | .RE |
c6d039a3 | 22 | .P |
b99daa3f | 23 | .BR posix_madvise (): |
9d2adbae MK |
24 | .nf |
25 | _POSIX_C_SOURCE >= 200112L | |
26 | .fi | |
b99daa3f MK |
27 | .SH DESCRIPTION |
28 | The | |
29 | .BR posix_madvise () | |
30 | function allows an application to advise the system about its expected | |
31 | patterns of usage of memory in the address range starting at | |
32 | .I addr | |
33 | and continuing for | |
34 | .I len | |
35 | bytes. | |
36 | The system is free to use this advice in order to improve the performance | |
37 | of memory accesses (or to ignore the advice altogether), but calling | |
38 | .BR posix_madvise () | |
39 | shall not affect the semantics of access to memory in the specified range. | |
c6d039a3 | 40 | .P |
b99daa3f MK |
41 | The |
42 | .I advice | |
43 | argument is one of the following: | |
44 | .TP | |
45 | .B POSIX_MADV_NORMAL | |
46 | The application has no special advice regarding its memory usage patterns | |
47 | for the specified address range. | |
48 | This is the default behavior. | |
49 | .TP | |
50 | .B POSIX_MADV_SEQUENTIAL | |
51 | The application expects to access the specified address range sequentially, | |
52 | running from lower addresses to higher addresses. | |
53 | Hence, pages in this region can be aggressively read ahead, | |
54 | and may be freed soon after they are accessed. | |
55 | .TP | |
56 | .B POSIX_MADV_RANDOM | |
57 | The application expects to access the specified address range randomly. | |
58 | Thus, read ahead may be less useful than normally. | |
59 | .TP | |
60 | .B POSIX_MADV_WILLNEED | |
61 | The application expects to access the specified address range | |
62 | in the near future. | |
63 | Thus, read ahead may be beneficial. | |
64 | .TP | |
65 | .B POSIX_MADV_DONTNEED | |
66 | The application expects that it will not access the specified address range | |
67 | in the near future. | |
68 | .SH RETURN VALUE | |
69 | On success, | |
70 | .BR posix_madvise () | |
71 | returns 0. | |
72 | On failure, it returns a positive error number. | |
73 | .SH ERRORS | |
74 | .TP | |
75 | .B EINVAL | |
76 | .I addr | |
77 | is not a multiple of the system page size or | |
78 | .I len | |
79 | is negative. | |
80 | .TP | |
81 | .B EINVAL | |
82 | .I advice | |
83 | is invalid. | |
84 | .TP | |
85 | .B ENOMEM | |
86 | Addresses in the specified range are partially or completely outside | |
87 | the caller's address space. | |
88 | .SH VERSIONS | |
b99daa3f MK |
89 | POSIX.1 permits an implementation to generate an error if |
90 | .I len | |
91 | is 0. | |
92 | On Linux, specifying | |
93 | .I len | |
94 | as 0 is permitted (as a successful no-op). | |
c6d039a3 | 95 | .P |
b99daa3f MK |
96 | In glibc, this function is implemented using |
97 | .BR madvise (2). | |
98 | However, since glibc 2.6, | |
1ae6b2c7 | 99 | .B POSIX_MADV_DONTNEED |
b99daa3f MK |
100 | is treated as a no-op, because the corresponding |
101 | .BR madvise (2) | |
102 | value, | |
103 | .BR MADV_DONTNEED , | |
104 | has destructive semantics. | |
4131356c AC |
105 | .SH STANDARDS |
106 | POSIX.1-2008. | |
107 | .SH HISTORY | |
108 | glibc 2.2. | |
109 | POSIX.1-2001. | |
b99daa3f MK |
110 | .SH SEE ALSO |
111 | .BR madvise (2), | |
112 | .BR posix_fadvise (2) |