HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. |  |
NAME |LIBRARY |SYNOPSIS |DESCRIPTION |RETURN VALUE |ERRORS |STANDARDS |HISTORY |SEE ALSO |COLOPHON | |
process_madvise(2) System Calls Manualprocess_madvise(2)process_madvise - give advice about use of memory to a process
Standard C library (libc,-lc)
#include <sys/mman.h>ssize_t process_madvise(size_tn;intpidfd, const struct ioveciovec[n],size_tn, intadvice, unsigned intflags);
Theprocess_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 byiovec andn. The goal of such advice is to improve system or application performance. Thepidfd argument is a PID file descriptor (seepidfd_open(2)) that specifies the process to which the advice is to be applied. The pointeriovec points to an array ofiovec structures, described iniovec(3type).n specifies the number of elements in the array ofiovec structures. This value must be less than or equal toIOV_MAX (defined in<limits.h> or accessible via the callsysconf(_SC_IOV_MAX)). If manipulating another process, or before Linux 6.13, theadvice argument is one of the following values:MADV_COLD Seemadvise(2).MADV_COLLAPSE Seemadvise(2).MADV_PAGEOUT Seemadvise(2).MADV_WILLNEED Seemadvise(2). Since Linux 6.13, when manipulating the calling process, any advice flag is permitted. Theflags argument is reserved for future use; currently, this argument must be specified as 0. Then andiovec arguments are checked before applying any advice. Ifn is too big, oriovec is invalid, then an error will be returned immediately and no advice will be applied. The advice might be applied to only a part ofiovec 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.) Since Linux 5.12, permission to apply advice to another process is governed by ptrace access modePTRACE_MODE_READ_FSCREDScheck (seeptrace(2)); in addition, because of the performance implications of applying the advice, the caller must have theCAP_SYS_NICE capability (seecapabilities(7)).
On success,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 someiovec elements were already processed. The caller should check the return value to determine whether a partial advice occurred. On error, -1 is returned anderrno is set to indicate the error.
EBADFpidfd is not a valid PID file descriptor.EFAULTThe memory described byiovec is outside the accessible address space of the process referred to bypidfd.EINVALflags is not 0.EINVALThe sum of theiov_len values ofiovec overflows assize_t value.EINVALn is too large.ENOMEMCould not allocate memory for internal copies of theiovec structures.EPERMThe caller does not have permission to access the address space of the processpidfd.ESRCHThe target process does not exist (i.e., it has terminated and been waited on). Seemadvise(2) foradvice-specific errors.
Linux.
Linux 5.10. glibc 2.36. Support for this system call is optional, depending on the setting of theCONFIG_ADVISE_SYSCALLSconfiguration option. When this system call first appeared in Linux 5.10, permission to apply advice to another process was entirely governed by ptrace access modePTRACE_MODE_ATTACH_FSCREDScheck (seeptrace(2)). This requirement was relaxed in Linux 5.12 so that the caller didn't require full control over the target process.
madvise(2),pidfd_open(2),process_vm_readv(2),process_vm_write(2)
This page is part of theman-pages (Linux kernel and C library user-space interface documentation) project. Information about the project can be found at ⟨https://www.kernel.org/doc/man-pages/⟩. If you have a bug report for this manual page, see ⟨https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/CONTRIBUTING⟩. This page was obtained from the tarball man-pages-6.15.tar.gz fetched from ⟨https://mirrors.edge.kernel.org/pub/linux/docs/man-pages/⟩ on 2025-08-11. If you discover any rendering problems in this HTML version of the page, or you believe there is a better or more up- to-date source for the page, or you have corrections or improvements to the information in this COLOPHON (which isnot part of the original manual page), send a mail to man-pages@man7.orgLinux man-pages 6.15 2025-05-17process_madvise(2)Pages that refer to this page:madvise(2), pidfd_open(2), syscalls(2), iovec(3type)
HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. | |