process_madvise(2)

1PROCESS_MADVISE(2)         Linux Programmer's Manual        PROCESS_MADVISE(2)
2
3
4

NAME

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

SYNOPSIS

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

DESCRIPTION

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

RETURN VALUE

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

ERRORS

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

VERSIONS

103       This system call first appeared in Linux 5.10.  Support for this system
104       call  is  optional,  depending  on  the  setting  of   the   CONFIG_AD‐
105       VISE_SYSCALLS configuration option.
106

CONFORMING TO

108       The process_madvise() system call is Linux-specific.
109

COLOPHON

114       This  page  is  part of release 5.13 of the Linux man-pages project.  A
115       description of the project, information about reporting bugs,  and  the
116       latest     version     of     this    page,    can    be    found    at
117       https://www.kernel.org/doc/man-pages/.
118
119
120
121Linux                             2021-06-20                PROCESS_MADVISE(2)