process_madvise(2)

1process_madvise(2)            System Calls Manual           process_madvise(2)
2
3
4

NAME

6       process_madvise - give advice about use of memory to a process
7

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

12       #include <sys/mman.h>      /* Definition of MADV_* constants */
13       #include <sys/syscall.h>   /* Definition of SYS_* constants */
14       #include <sys/uio.h>       /* Definition of struct iovec type */
15       #include <unistd.h>
16
17       ssize_t syscall(SYS_process_madvise, int pidfd,
18                       const struct iovec *iovec, size_t vlen, int advice,
19                       unsigned int flags);
20
21       Note:  glibc  provides  no wrapper for process_madvise(), necessitating
22       the use of syscall(2).
23

DESCRIPTION

25       The process_madvise() system call is used to give advice or  directions
26       to  the  kernel  about  the address ranges of another process or of the
27       calling process.  It provides the advice for  the  address  ranges  de‐
28       scribed  by iovec and vlen.  The goal of such advice is to improve sys‐
29       tem or application performance.
30
31       The pidfd argument is a PID file descriptor  (see  pidfd_open(2))  that
32       specifies the process to which the advice is to be applied.
33
34       The  pointer iovec points to an array of iovec structures, described in
35       iovec(3type).
36
37       vlen specifies the number of elements in the array of iovec structures.
38       This value must be less than or equal to IOV_MAX (defined in <limits.h>
39       or accessible via the call sysconf(_SC_IOV_MAX)).
40
41       The advice argument is one of the following values:
42
43       MADV_COLD
44              See madvise(2).
45
46       MADV_COLLAPSE
47              See madvise(2).
48
49       MADV_PAGEOUT
50              See madvise(2).
51
52       MADV_WILLNEED
53              See madvise(2).
54
55       The flags argument is reserved for future use; currently, this argument
56       must be specified as 0.
57
58       The  vlen  and  iovec arguments are checked before applying any advice.
59       If vlen is too big, or iovec is invalid, then an error will be returned
60       immediately and no advice will be applied.
61
62       The  advice might be applied to only a part of iovec if one of its ele‐
63       ments points to an invalid memory region in  the  remote  process.   No
64       further elements will be processed beyond that point.  (See the discus‐
65       sion regarding partial advice in RETURN VALUE.)
66
67       Starting in Linux 5.12, permission to apply advice to  another  process
68       is  governed  by ptrace access mode PTRACE_MODE_READ_FSCREDS check (see
69       ptrace(2)); in addition, because of the performance implications of ap‐
70       plying  the  advice,  the  caller must have the CAP_SYS_NICE capability
71       (see capabilities(7)).
72

RETURN VALUE

74       On success, process_madvise() returns  the  number  of  bytes  advised.
75       This return value may be less than the total number of requested bytes,
76       if an error occurred after some iovec elements were already  processed.
77       The caller should check the return value to determine whether a partial
78       advice occurred.
79
80       On error, -1 is returned and errno is set to indicate the error.
81

ERRORS

83       EBADF  pidfd is not a valid PID file descriptor.
84
85       EFAULT The memory described by iovec is outside the accessible  address
86              space of the process referred to by pidfd.
87
88       EINVAL flags is not 0.
89
90       EINVAL The  sum  of  the  iov_len  values  of iovec overflows a ssize_t
91              value.
92
93       EINVAL vlen is too large.
94
95       ENOMEM Could not allocate memory  for  internal  copies  of  the  iovec
96              structures.
97
98       EPERM  The  caller does not have permission to access the address space
99              of the process pidfd.
100
101       ESRCH  The target process does not exist (i.e., it has  terminated  and
102              been waited on).
103
104       See madvise(2) for advice-specific errors.
105

STANDARDS

107       Linux.
108

HISTORY

110       Linux 5.10.
111
112       Support  for  this system call is optional, depending on the setting of
113       the CONFIG_ADVISE_SYSCALLS configuration option.
114
115       When this system call first appeared in Linux 5.10, permission to apply
116       advice  to  another process was entirely governed by ptrace access mode
117       PTRACE_MODE_ATTACH_FSCREDS check (see ptrace(2)).  This requirement was
118       relaxed  in  Linux  5.12 so that the caller didn't require full control
119       over the target process.
120