Debian Codegraph @

upstream/debian-unstable/man3/posix_madvise.3

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