| blob | e2b8c16ac79a7b60ef06dbc9df22f9d6b102dd81 |
1 .\" Copyright (C) 2021 Suren Baghdasaryan <surenb@google.com>
2 .\" and Copyright (C) 2021 Minchan Kim <minchan@kernel.org>
3 .\"
4 .\" %%%LICENSE_START(VERBATIM)
5 .\" Permission is granted to make and distribute verbatim copies of this
6 .\" manual provided the copyright notice and this permission notice are
7 .\" preserved on all copies.
8 .\"
9 .\" Permission is granted to copy and distribute modified versions of this
10 .\" manual under the conditions for verbatim copying, provided that the
11 .\" entire resulting derived work is distributed under the terms of a
12 .\" permission notice identical to this one.
13 .\"
14 .\" Since the Linux kernel and libraries are constantly changing, this
15 .\" manual page may be incorrect or out-of-date. The author(s) assume no
16 .\" responsibility for errors or omissions, or for damages resulting from
17 .\" the use of the information contained herein. The author(s) may not
18 .\" have taken the same level of care in the production of this manual,
19 .\" which is licensed free of charge, as they might when working
20 .\" professionally.
21 .\"
22 .\" Formatted or processed versions of this manual, if unaccompanied by
23 .\" the source, must acknowledge the copyright and authors of this work.
24 .\" %%%LICENSE_END
25 .\"
26 .\" Commit ecb8ac8b1f146915aa6b96449b66dd48984caacc
27 .\"
28 .TH PROCESS_MADVISE 2 2021-01-12 "Linux" "Linux Programmer's Manual"
29 .SH NAME
30 process_madvise \- give advice about use of memory to a process
31 .SH SYNOPSIS
32 .nf
33 .B #include <sys/uio.h>
34 .PP
35 .BI "ssize_t process_madvise(int " pidfd ", const struct iovec *" iovec ,
36 .BI " size_t " vlen ", int " advice ,
37 .BI " unsigned int " flags ");"
38 .fi
39 .PP
40 .IR Note :
41 There is no glibc wrapper for this system call; see NOTES.
42 .\" FIXME: See <https://sourceware.org/bugzilla/show_bug.cgi?id=27380>
43 .SH DESCRIPTION
44 The
45 .BR process_madvise()
46 system call is used to give advice or directions to the kernel about the
47 address ranges of another process or of the calling process.
48 It provides the advice for the address ranges described by
49 .I iovec
50 and
51 .IR vlen .
52 The goal of such advice is to improve system or application performance.
53 .PP
54 The
55 .I pidfd
56 argument is a PID file descriptor (see
57 .BR pidfd_open (2))
58 that specifies the process to which the advice is to be applied.
59 .PP
60 The pointer
61 .I iovec
62 points to an array of
63 .I iovec
64 structures, defined in
65 .IR <sys/uio.h>
66 as:
67 .PP
68 .in +4n
69 .EX
70 struct iovec {
71 void *iov_base; /* Starting address */
72 size_t iov_len; /* Length of region */
73 };
74 .EE
75 .in
76 .PP
77 The
78 .I iovec
79 structure describes address ranges beginning at
80 .I iov_base
81 address and with the size of
82 .I iov_len
83 bytes.
84 .PP
85 The
86 .I vlen
87 specifies the number of elements in the
88 .I iovec
89 structure.
90 This value must be less than or equal to
91 .BR IOV_MAX
92 (defined in
93 .I <limits.h>
94 or accessible via the call
95 .IR sysconf(_SC_IOV_MAX) ).
96 .PP
97 The
98 .I advice
99 argument is one of the following values:
100 .TP
101 .BR MADV_COLD
102 See
103 .BR madvise (2).
104 .TP
105 .BR MADV_PAGEOUT
106 See
107 .BR madvise (2).
108 .PP
109 The
110 .I flags
111 argument is reserved for future use; currently, this argument must be
112 specified as 0.
113 .PP
114 The
115 .I vlen
116 and
117 .I iovec
118 arguments are checked before applying any advice.
119 If
120 .I vlen
121 is too big, or
122 .I iovec
123 is invalid,
124 then an error will be returned immediately and no advice will be applied.
125 .PP
126 The advice might be applied to only a part of
127 .I iovec
128 if one of its elements points to an invalid memory region in the
129 remote process.
130 No further elements will be processed beyond that point.
131 (See the discussion regarding partial advice in RETURN VALUE.)
132 .PP
133 Permission to apply advice to another process is governed by a
134 ptrace access mode
135 .B PTRACE_MODE_READ_REALCREDS
136 check (see
137 .BR ptrace (2));
138 in addition,
139 because of the performance implications of applying the advice,
140 the caller must have the
141 .B CAP_SYS_ADMIN
142 capability.
143 .SH RETURN VALUE
144 On success,
145 .BR process_madvise ()
146 returns the number of bytes advised.
147 This return value may be less than the total number of requested bytes,
148 if an error occurred after some
149 .I iovec
150 elements were already processed.
151 The caller should check the return value to determine whether a partial
152 advice occurred.
153 .PP
154 On error, \-1 is returned and
155 .I errno
156 is set to indicate the error.
157 .SH ERRORS
158 .TP
159 .B EBADF
160 .I pidfd
161 is not a valid PID file descriptor.
162 .TP
163 .B EFAULT
164 The memory described by
165 .I iovec
166 is outside the accessible address space of the process referred to by
167 .IR pidfd .
168 .TP
169 .B EINVAL
170 .I flags
171 is not 0.
172 .TP
173 .B EINVAL
174 The sum of the
175 .I iov_len
176 values of
177 .I iovec
178 overflows a
179 .I ssize_t
180 value.
181 .TP
182 .B EINVAL
183 .I vlen
184 is too large.
185 .TP
186 .B ENOMEM
187 Could not allocate memory for internal copies of the
188 .I iovec
189 structures.
190 .TP
191 .B EPERM
192 The caller does not have permission to access the address space of the process
193 .IR pidfd .
194 .TP
195 .B ESRCH
196 The target process does not exist (i.e., it has terminated and been waited on).
197 .SH VERSIONS
198 This system call first appeared in Linux 5.10.
199 .\" commit ecb8ac8b1f146915aa6b96449b66dd48984caacc
200 Support for this system call is optional,
201 depending on the setting of the
202 .B CONFIG_ADVISE_SYSCALLS
203 configuration option.
204 .SH CONFORMING TO
205 The
206 .BR process_madvise ()
207 system call is Linux-specific.
208 .SH NOTES
209 Glibc does not provide a wrapper for this system call; call it using
210 .BR syscall (2).
211 .SH SEE ALSO
212 .BR madvise (2),
213 .BR pidfd_open (2),
214 .BR process_vm_readv (2),
215 .BR process_vm_write (2)