| .\" Copyright (C) 2021 Suren Baghdasaryan <surenb@google.com> |
| .\" and Copyright (C) 2021 Minchan Kim <minchan@kernel.org> |
| .\" |
| .\" %%%LICENSE_START(VERBATIM) |
| .\" Permission is granted to make and distribute verbatim copies of this |
| .\" manual provided the copyright notice and this permission notice are |
| .\" preserved on all copies. |
| .\" |
| .\" Permission is granted to copy and distribute modified versions of this |
| .\" manual under the conditions for verbatim copying, provided that the |
| .\" entire resulting derived work is distributed under the terms of a |
| .\" permission notice identical to this one. |
| .\" |
| .\" Since the Linux kernel and libraries are constantly changing, this |
| .\" manual page may be incorrect or out-of-date. The author(s) assume no |
| .\" responsibility for errors or omissions, or for damages resulting from |
| .\" the use of the information contained herein. The author(s) may not |
| .\" have taken the same level of care in the production of this manual, |
| .\" which is licensed free of charge, as they might when working |
| .\" professionally. |
| .\" |
| .\" Formatted or processed versions of this manual, if unaccompanied by |
| .\" the source, must acknowledge the copyright and authors of this work. |
| .\" %%%LICENSE_END |
| .\" |
| .\" Commit ecb8ac8b1f146915aa6b96449b66dd48984caacc |
| .\" |
| .TH PROCESS_MADVISE 2 2021-01-12 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| process_madvise \- give advice about use of memory to a process |
| .SH SYNOPSIS |
| .nf |
| .B #include <sys/uio.h> |
| .PP |
| .BI "ssize_t process_madvise(int " pidfd ", const struct iovec *" iovec , |
| .BI " size_t " vlen ", int " advice , |
| .BI " unsigned int " flags ");" |
| .fi |
| .PP |
| .IR Note : |
| There is no glibc wrapper for this system call; see NOTES. |
| .\" FIXME: See <https://sourceware.org/bugzilla/show_bug.cgi?id=27380> |
| .SH DESCRIPTION |
| The |
| .BR process_madvise() |
| system call is used to give advice or directions to the kernel about the |
| address ranges of another process or of the calling process. |
| It provides the advice for the address ranges described by |
| .I iovec |
| and |
| .IR vlen . |
| The goal of such advice is to improve system or application performance. |
| .PP |
| The |
| .I pidfd |
| argument is a PID file descriptor (see |
| .BR pidfd_open (2)) |
| that specifies the process to which the advice is to be applied. |
| .PP |
| The pointer |
| .I iovec |
| points to an array of |
| .I iovec |
| structures, defined in |
| .IR <sys/uio.h> |
| as: |
| .PP |
| .in +4n |
| .EX |
| struct iovec { |
| void *iov_base; /* Starting address */ |
| size_t iov_len; /* Length of region */ |
| }; |
| .EE |
| .in |
| .PP |
| The |
| .I iovec |
| structure describes address ranges beginning at |
| .I iov_base |
| address and with the size of |
| .I iov_len |
| bytes. |
| .PP |
| The |
| .I vlen |
| specifies the number of elements in the |
| .I iovec |
| structure. |
| This value must be less than or equal to |
| .BR IOV_MAX |
| (defined in |
| .I <limits.h> |
| or accessible via the call |
| .IR sysconf(_SC_IOV_MAX) ). |
| .PP |
| The |
| .I advice |
| argument is one of the following values: |
| .TP |
| .BR MADV_COLD |
| See |
| .BR madvise (2). |
| .TP |
| .BR MADV_PAGEOUT |
| See |
| .BR madvise (2). |
| .PP |
| The |
| .I flags |
| argument is reserved for future use; currently, this argument must be |
| specified as 0. |
| .PP |
| The |
| .I vlen |
| and |
| .I iovec |
| arguments are checked before applying any advice. |
| If |
| .I vlen |
| is too big, or |
| .I iovec |
| is invalid, |
| then an error will be returned immediately and no advice will be applied. |
| .PP |
| The advice might be applied to only a part of |
| .I iovec |
| if one of its elements points to an invalid memory region in the |
| remote process. |
| No further elements will be processed beyond that point. |
| (See the discussion regarding partial advice in RETURN VALUE.) |
| .PP |
| Permission to apply advice to another process is governed by a |
| ptrace access mode |
| .B PTRACE_MODE_READ_REALCREDS |
| check (see |
| .BR ptrace (2)); |
| in addition, |
| because of the performance implications of applying the advice, |
| the caller must have the |
| .B CAP_SYS_ADMIN |
| capability. |
| .SH RETURN VALUE |
| On success, |
| .BR process_madvise () |
| returns the number of bytes advised. |
| This return value may be less than the total number of requested bytes, |
| if an error occurred after some |
| .I iovec |
| elements were already processed. |
| The caller should check the return value to determine whether a partial |
| advice occurred. |
| .PP |
| On error, \-1 is returned and |
| .I errno |
| is set to indicate the error. |
| .SH ERRORS |
| .TP |
| .B EBADF |
| .I pidfd |
| is not a valid PID file descriptor. |
| .TP |
| .B EFAULT |
| The memory described by |
| .I iovec |
| is outside the accessible address space of the process referred to by |
| .IR pidfd . |
| .TP |
| .B EINVAL |
| .I flags |
| is not 0. |
| .TP |
| .B EINVAL |
| The sum of the |
| .I iov_len |
| values of |
| .I iovec |
| overflows a |
| .I ssize_t |
| value. |
| .TP |
| .B EINVAL |
| .I vlen |
| is too large. |
| .TP |
| .B ENOMEM |
| Could not allocate memory for internal copies of the |
| .I iovec |
| structures. |
| .TP |
| .B EPERM |
| The caller does not have permission to access the address space of the process |
| .IR pidfd . |
| .TP |
| .B ESRCH |
| The target process does not exist (i.e., it has terminated and been waited on). |
| .SH VERSIONS |
| This system call first appeared in Linux 5.10. |
| .\" commit ecb8ac8b1f146915aa6b96449b66dd48984caacc |
| Support for this system call is optional, |
| depending on the setting of the |
| .B CONFIG_ADVISE_SYSCALLS |
| configuration option. |
| .SH CONFORMING TO |
| The |
| .BR process_madvise () |
| system call is Linux-specific. |
| .SH NOTES |
| Glibc does not provide a wrapper for this system call; call it using |
| .BR syscall (2). |
| .SH SEE ALSO |
| .BR madvise (2), |
| .BR pidfd_open (2), |
| .BR process_vm_readv (2), |
| .BR process_vm_write (2) |