Debian Codegraph @

upstream/fedora-44/man2/process_madvise.2

raw
1 .\" Copyright (C) 2021 Suren Baghdasaryan <[email protected]>
2 .\" and Copyright (C) 2021 Minchan Kim <[email protected]>
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .\" Commit ecb8ac8b1f146915aa6b96449b66dd48984caacc
7 .\"
8 .TH process_madvise 2 2024-12-04 "Linux man-pages 6.13"
9 .SH NAME
10 process_madvise \- give advice about use of memory to a process
11 .SH LIBRARY
12 Standard C library
13 .RI ( libc ,\~ \-lc )
14 .SH SYNOPSIS
15 .nf
16 .B #include <sys/mman.h>
17 .P
18 .BI "ssize_t process_madvise(int " pidfd ", const struct iovec " iovec [. n ],
19 .BI " size_t " n ", int " advice \
20 ", unsigned int " flags );
21 .fi
22 .SH DESCRIPTION
23 The
24 .BR process_madvise ()
25 system call is used to give advice or directions to the kernel about the
26 address ranges of another process or of the calling process.
27 It provides the advice for the address ranges described by
28 .I iovec
29 and
30 .IR n .
31 The goal of such advice is to improve system or application performance.
32 .P
33 The
34 .I pidfd
35 argument is a PID file descriptor (see
36 .BR pidfd_open (2))
37 that specifies the process to which the advice is to be applied.
38 .P
39 The pointer
40 .I iovec
41 points to an array of
42 .I iovec
43 structures, described in
44 .BR iovec (3type).
45 .P
46 .I n
47 specifies the number of elements in the array of
48 .I iovec
49 structures.
50 This value must be less than or equal to
51 .B IOV_MAX
52 (defined in
53 .I <limits.h>
54 or accessible via the call
55 .IR sysconf(_SC_IOV_MAX) ).
56 .P
57 If manipulating another process,
58 or before Linux 6.13,
59 the
60 .I advice
61 argument is one of the following values:
62 .TP
63 .B MADV_COLD
64 See
65 .BR madvise (2).
66 .TP
67 .B MADV_COLLAPSE
68 See
69 .BR madvise (2).
70 .TP
71 .B MADV_PAGEOUT
72 See
73 .BR madvise (2).
74 .TP
75 .B MADV_WILLNEED
76 See
77 .BR madvise (2).
78 .P
79 Since Linux 6.13,
80 when manipulating the calling process,
81 any advice flag is permitted.
82 .P
83 The
84 .I flags
85 argument is reserved for future use; currently, this argument must be
86 specified as 0.
87 .P
88 The
89 .I n
90 and
91 .I iovec
92 arguments are checked before applying any advice.
93 If
94 .I n
95 is too big, or
96 .I iovec
97 is invalid,
98 then an error will be returned immediately and no advice will be applied.
99 .P
100 The advice might be applied to only a part of
101 .I iovec
102 if one of its elements points to an invalid memory region in the
103 remote process.
104 No further elements will be processed beyond that point.
105 (See the discussion regarding partial advice in RETURN VALUE.)
106 .P
107 .\" commit 96cfe2c0fd23ea7c2368d14f769d287e7ae1082e
108 Since Linux 5.12,
109 permission to apply advice to another process is governed by
110 ptrace access mode
111 .B PTRACE_MODE_READ_FSCREDS
112 check (see
113 .BR ptrace (2));
114 in addition,
115 because of the performance implications of applying the advice,
116 the caller must have the
117 .B CAP_SYS_NICE
118 capability
119 (see
120 .BR capabilities (7)).
121 .SH RETURN VALUE
122 On success,
123 .BR process_madvise ()
124 returns the number of bytes advised.
125 This return value may be less than the total number of requested bytes,
126 if an error occurred after some
127 .I iovec
128 elements were already processed.
129 The caller should check the return value to determine whether a partial
130 advice occurred.
131 .P
132 On error, \-1 is returned and
133 .I errno
134 is set to indicate the error.
135 .SH ERRORS
136 .TP
137 .B EBADF
138 .I pidfd
139 is not a valid PID file descriptor.
140 .TP
141 .B EFAULT
142 The memory described by
143 .I iovec
144 is outside the accessible address space of the process referred to by
145 .IR pidfd .
146 .TP
147 .B EINVAL
148 .I flags
149 is not 0.
150 .TP
151 .B EINVAL
152 The sum of the
153 .I iov_len
154 values of
155 .I iovec
156 overflows a
157 .I ssize_t
158 value.
159 .TP
160 .B EINVAL
161 .I n
162 is too large.
163 .TP
164 .B ENOMEM
165 Could not allocate memory for internal copies of the
166 .I iovec
167 structures.
168 .TP
169 .B EPERM
170 The caller does not have permission to access the address space of the process
171 .IR pidfd .
172 .TP
173 .B ESRCH
174 The target process does not exist (i.e., it has terminated and been waited on).
175 .P
176 See
177 .BR madvise (2)
178 for
179 .IR advice -specific
180 errors.
181 .SH STANDARDS
182 Linux.
183 .SH HISTORY
184 Linux 5.10.
185 .\" Linux commit ecb8ac8b1f146915aa6b96449b66dd48984caacc
186 glibc 2.36.
187 .\" glibc commit d19ee3473d68ca0e794f3a8b7677a0983ae1342e
188 .P
189 Support for this system call is optional,
190 depending on the setting of the
191 .B CONFIG_ADVISE_SYSCALLS
192 configuration option.
193 .P
194 When this system call first appeared in Linux 5.10,
195 permission to apply advice to another process was entirely governed by
196 ptrace access mode
197 .B PTRACE_MODE_ATTACH_FSCREDS
198 check (see
199 .BR ptrace (2)).
200 This requirement was relaxed in Linux 5.12 so that the caller didn't require
201 full control over the target process.
202 .SH SEE ALSO
203 .BR madvise (2),
204 .BR pidfd_open (2),
205 .BR process_vm_readv (2),
206 .BR process_vm_write (2)