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