# process_madvise

## NAME



           process_madvise - give advice about use of memory to a process
    


## LIBRARY



           Standard C library (_libc_ , _-lc_)
    


## SYNOPSIS



           **#include <sys/mman.h>**
    
           **ssize_t process_madvise(size_t** _n_**;**
                                   **int** _pidfd_**, const struct iovec** _iovec_**[**_n_**],**
                                   **size_t** _n_**, int** _advice_**, unsigned int** _flags_**);**
    


## DESCRIPTION



           The **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 _iovec_ and _n_.  The goal of such advice
           is to improve system or application performance.
    
           The _pidfd_ argument is a PID file descriptor (see pidfd_open(2))
           that specifies the process to which the advice is to be applied.
    
           The pointer _iovec_ points to an array of _iovec_ structures,
           described in iovec(3type).
    
           _n_ specifies the number of elements in the array of _iovec_
           structures.  This value must be less than or equal to **IOV_MAX**
           (defined in _< limits.h>_ or accessible via the call
           _sysconf(_SC_IOV_MAX)_).
    
           If manipulating another process, or before Linux 6.13, the _advice_
           argument is one of the following values:
    
           **MADV_COLD**
                  See madvise(2).
    
           **MADV_COLLAPSE**
                  See madvise(2).
    
           **MADV_PAGEOUT**
                  See madvise(2).
    
           **MADV_WILLNEED**
                  See madvise(2).
    
           Since Linux 6.13, when manipulating the calling process, any
           advice flag is permitted.
    
           The _flags_ argument is reserved for future use; currently, this
           argument must be specified as 0.
    
           The _n_ and _iovec_ arguments are checked before applying any advice.
           If _n_ is too big, or _iovec_ is invalid, then an error will be
           returned immediately and no advice will be applied.
    
           The advice might be applied to only a part of _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.)
    
           Since Linux 5.12, permission to apply advice to another process is
           governed by ptrace access mode **PTRACE_MODE_READ_FSCREDS** check (see
           ptrace(2)); in addition, because of the performance implications
           of applying the advice, the caller must have the **CAP_SYS_NICE**
           capability (see capabilities(7)).
    


## RETURN VALUE



           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 some _iovec_ elements were already
           processed.  The caller should check the return value to determine
           whether a partial advice occurred.
    
           On error, -1 is returned and _errno_ is set to indicate the error.
    


## ERRORS



           **EBADF** _pidfd_ is not a valid PID file descriptor.
    
           **EFAULT** The memory described by _iovec_ is outside the accessible
                  address space of the process referred to by _pidfd_.
    
           **EINVAL** _flags_ is not 0.
    
           **EINVAL** The sum of the _iov_len_ values of _iovec_ overflows a _ssize_t_
                  value.
    
           **EINVAL** _n_ is too large.
    
           **ENOMEM** Could not allocate memory for internal copies of the _iovec_
                  structures.
    
           **EPERM** The caller does not have permission to access the address
                  space of the process _pidfd_.
    
           **ESRCH** The target process does not exist (i.e., it has terminated
                  and been waited on).
    
           See madvise(2) for _advice_ -specific errors.
    


## STANDARDS



           Linux.
    


* * *