Debian Codegraph @

upstream/debian-trixie/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-05-02 "Linux man-pages 6.9.1"
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 The
58 .I advice
59 argument is one of the following values:
60 .TP
61 .B MADV_COLD
62 See
63 .BR madvise (2).
64 .TP
65 .B MADV_COLLAPSE
66 See
67 .BR madvise (2).
68 .TP
69 .B MADV_PAGEOUT
70 See
71 .BR madvise (2).
72 .TP
73 .B MADV_WILLNEED
74 See
75 .BR madvise (2).
76 .P
77 The
78 .I flags
79 argument is reserved for future use; currently, this argument must be
80 specified as 0.
81 .P
82 The
83 .I n
84 and
85 .I iovec
86 arguments are checked before applying any advice.
87 If
88 .I n
89 is too big, or
90 .I iovec
91 is invalid,
92 then an error will be returned immediately and no advice will be applied.
93 .P
94 The advice might be applied to only a part of
95 .I iovec
96 if one of its elements points to an invalid memory region in the
97 remote process.
98 No further elements will be processed beyond that point.
99 (See the discussion regarding partial advice in RETURN VALUE.)
100 .P
101 .\" commit 96cfe2c0fd23ea7c2368d14f769d287e7ae1082e
102 Starting in Linux 5.12,
103 permission to apply advice to another process is governed by
104 ptrace access mode
105 .B PTRACE_MODE_READ_FSCREDS
106 check (see
107 .BR ptrace (2));
108 in addition,
109 because of the performance implications of applying the advice,
110 the caller must have the
111 .B CAP_SYS_NICE
112 capability
113 (see
114 .BR capabilities (7)).
115 .SH RETURN VALUE
116 On success,
117 .BR process_madvise ()
118 returns the number of bytes advised.
119 This return value may be less than the total number of requested bytes,
120 if an error occurred after some
121 .I iovec
122 elements were already processed.
123 The caller should check the return value to determine whether a partial
124 advice occurred.
125 .P
126 On error, \-1 is returned and
127 .I errno
128 is set to indicate the error.
129 .SH ERRORS
130 .TP
131 .B EBADF
132 .I pidfd
133 is not a valid PID file descriptor.
134 .TP
135 .B EFAULT
136 The memory described by
137 .I iovec
138 is outside the accessible address space of the process referred to by
139 .IR pidfd .
140 .TP
141 .B EINVAL
142 .I flags
143 is not 0.
144 .TP
145 .B EINVAL
146 The sum of the
147 .I iov_len
148 values of
149 .I iovec
150 overflows a
151 .I ssize_t
152 value.
153 .TP
154 .B EINVAL
155 .I n
156 is too large.
157 .TP
158 .B ENOMEM
159 Could not allocate memory for internal copies of the
160 .I iovec
161 structures.
162 .TP
163 .B EPERM
164 The caller does not have permission to access the address space of the process
165 .IR pidfd .
166 .TP
167 .B ESRCH
168 The target process does not exist (i.e., it has terminated and been waited on).
169 .P
170 See
171 .BR madvise (2)
172 for
173 .IR advice -specific
174 errors.
175 .SH STANDARDS
176 Linux.
177 .SH HISTORY
178 Linux 5.10.
179 .\" Linux commit ecb8ac8b1f146915aa6b96449b66dd48984caacc
180 glibc 2.36.
181 .\" glibc commit d19ee3473d68ca0e794f3a8b7677a0983ae1342e
182 .P
183 Support for this system call is optional,
184 depending on the setting of the
185 .B CONFIG_ADVISE_SYSCALLS
186 configuration option.
187 .P
188 When this system call first appeared in Linux 5.10,
189 permission to apply advice to another process was entirely governed by
190 ptrace access mode
191 .B PTRACE_MODE_ATTACH_FSCREDS
192 check (see
193 .BR ptrace (2)).
194 This requirement was relaxed in Linux 5.12 so that the caller didn't require
195 full control over the target process.
196 .SH SEE ALSO
197 .BR madvise (2),
198 .BR pidfd_open (2),
199 .BR process_vm_readv (2),
200 .BR process_vm_write (2)