man2/process_madvise.2

   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-06-20 "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 .BR "#include <sys/mman.h>" "      /* Definition of " MADV_* " constants */"
  34 .BR "#include <sys/syscall.h>" "   /* Definition of " SYS_* " constants */"
  35 .BR "#include <sys/uio.h>" "       /* Definition of " "struct iovec" " type */"
  36 .B #include <unistd.h>
  37 .PP
  38 .BI "ssize_t syscall(SYS_process_madvise, int " pidfd ,
  39 .BI "                const struct iovec *" iovec ", size_t " vlen \
  40 ", int " advice ,
  41 .BI "                unsigned int " flags ");"
  42 .fi
  43 .PP
  44 .IR Note :
  45 glibc provides no wrapper for
  46 .BR process_madvise (),
  47 necessitating the use of
  48 .BR syscall (2).
  49 .\" FIXME: See <https://sourceware.org/bugzilla/show_bug.cgi?id=27380>
  50 .SH DESCRIPTION
  51 The
  52 .BR process_madvise()
  53 system call is used to give advice or directions to the kernel about the
  54 address ranges of another process or of the calling process.
  55 It provides the advice for the address ranges described by
  56 .I iovec
  57 and
  58 .IR vlen .
  59 The goal of such advice is to improve system or application performance.
  60 .PP
  61 The
  62 .I pidfd
  63 argument is a PID file descriptor (see
  64 .BR pidfd_open (2))
  65 that specifies the process to which the advice is to be applied.
  66 .PP
  67 The pointer
  68 .I iovec
  69 points to an array of
  70 .I iovec
  71 structures, defined in
  72 .IR <sys/uio.h>
  73 as:
  74 .PP
  75 .in +4n
  76 .EX
  77 struct iovec {
  78     void  *iov_base;    /* Starting address */
  79     size_t iov_len;     /* Length of region */
  80 };
  81 .EE
  82 .in
  83 .PP
  84 The
  85 .I iovec
  86 structure describes address ranges beginning at
  87 .I iov_base
  88 address and with the size of
  89 .I iov_len
  90 bytes.
  91 .PP
  92 The
  93 .I vlen
  94 specifies the number of elements in the
  95 .I iovec
  96 structure.
  97 This value must be less than or equal to
  98 .BR IOV_MAX
  99 (defined in
 100 .I <limits.h>
 101 or accessible via the call
 102 .IR sysconf(_SC_IOV_MAX) ).
 103 .PP
 104 The
 105 .I advice
 106 argument is one of the following values:
 107 .TP
 108 .BR MADV_COLD
 109 See
 110 .BR madvise (2).
 111 .TP
 112 .BR MADV_PAGEOUT
 113 See
 114 .BR madvise (2).
 115 .PP
 116 The
 117 .I flags
 118 argument is reserved for future use; currently, this argument must be
 119 specified as 0.
 120 .PP
 121 The
 122 .I vlen
 123 and
 124 .I iovec
 125 arguments are checked before applying any advice.
 126 If
 127 .I vlen
 128 is too big, or
 129 .I iovec
 130 is invalid,
 131 then an error will be returned immediately and no advice will be applied.
 132 .PP
 133 The advice might be applied to only a part of
 134 .I iovec
 135 if one of its elements points to an invalid memory region in the
 136 remote process.
 137 No further elements will be processed beyond that point.
 138 (See the discussion regarding partial advice in RETURN VALUE.)
 139 .PP
 140 Permission to apply advice to another process is governed by a
 141 ptrace access mode
 142 .B PTRACE_MODE_READ_REALCREDS
 143 check (see
 144 .BR ptrace (2));
 145 in addition,
 146 because of the performance implications of applying the advice,
 147 the caller must have the
 148 .B CAP_SYS_ADMIN
 149 capability.
 150 .SH RETURN VALUE
 151 On success,
 152 .BR process_madvise ()
 153 returns the number of bytes advised.
 154 This return value may be less than the total number of requested bytes,
 155 if an error occurred after some
 156 .I iovec
 157 elements were already processed.
 158 The caller should check the return value to determine whether a partial
 159 advice occurred.
 160 .PP
 161 On error, \-1 is returned and
 162 .I errno
 163 is set to indicate the error.
 164 .SH ERRORS
 165 .TP
 166 .B EBADF
 167 .I pidfd
 168 is not a valid PID file descriptor.
 169 .TP
 170 .B EFAULT
 171 The memory described by
 172 .I iovec
 173 is outside the accessible address space of the process referred to by
 174 .IR pidfd .
 175 .TP
 176 .B EINVAL
 177 .I flags
 178 is not 0.
 179 .TP
 180 .B EINVAL
 181 The sum of the
 182 .I iov_len
 183 values of
 184 .I iovec
 185 overflows a
 186 .I ssize_t
 187 value.
 188 .TP
 189 .B EINVAL
 190 .I vlen
 191 is too large.
 192 .TP
 193 .B ENOMEM
 194 Could not allocate memory for internal copies of the
 195 .I iovec
 196 structures.
 197 .TP
 198 .B EPERM
 199 The caller does not have permission to access the address space of the process
 200 .IR pidfd .
 201 .TP
 202 .B ESRCH
 203 The target process does not exist (i.e., it has terminated and been waited on).
 204 .SH VERSIONS
 205 This system call first appeared in Linux 5.10.
 206 .\" commit ecb8ac8b1f146915aa6b96449b66dd48984caacc
 207 Support for this system call is optional,
 208 depending on the setting of the
 209 .B CONFIG_ADVISE_SYSCALLS
 210 configuration option.
 211 .SH CONFORMING TO
 212 The
 213 .BR process_madvise ()
 214 system call is Linux-specific.
 215 .SH SEE ALSO
 216 .BR madvise (2),
 217 .BR pidfd_open (2),
 218 .BR process_vm_readv (2),
 219 .BR process_vm_write (2)