| .\" Copyright (C) 2001 Bert Hubert <ahu@ds9a.nl> |
| .\" and Copyright (C) 2007 Michael Kerrisk <mtk.manpages@gmail.com> |
| .\" |
| .\" %%%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 |
| .\" |
| .\" Created Sun Jun 3 17:23:32 2001 by bert hubert <ahu@ds9a.nl> |
| .\" Slightly adapted, following comments by Hugh Dickins, aeb, 2001-06-04. |
| .\" Modified, 20 May 2003, Michael Kerrisk <mtk.manpages@gmail.com> |
| .\" Modified, 30 Apr 2004, Michael Kerrisk <mtk.manpages@gmail.com> |
| .\" 2005-04-05 mtk, Fixed error descriptions |
| .\" after message from <gordon.jin@intel.com> |
| .\" 2007-01-08 mtk, rewrote various parts |
| .\" |
| .TH MINCORE 2 2017-09-15 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| mincore \- determine whether pages are resident in memory |
| .SH SYNOPSIS |
| .B #include <unistd.h> |
| .br |
| .B #include <sys/mman.h> |
| .PP |
| .BI "int mincore(void *" addr ", size_t " length ", unsigned char *" vec ); |
| .PP |
| .in -4n |
| Feature Test Macro Requirements for glibc (see |
| .BR feature_test_macros (7)): |
| .in |
| .PP |
| .BR mincore (): |
| Since glibc 2.19: |
| _DEFAULT_SOURCE |
| Glibc 2.19 and earlier: |
| _BSD_SOURCE || _SVID_SOURCE |
| .SH DESCRIPTION |
| .BR mincore () |
| returns a vector that indicates whether pages |
| of the calling process's virtual memory are resident in core (RAM), |
| and so will not cause a disk access (page fault) if referenced. |
| The kernel returns residency information about the pages |
| starting at the address |
| .IR addr , |
| and continuing for |
| .I length |
| bytes. |
| .PP |
| The |
| .I addr |
| argument must be a multiple of the system page size. |
| The |
| .I length |
| argument need not be a multiple of the page size, |
| but since residency information is returned for whole pages, |
| .I length |
| is effectively rounded up to the next multiple of the page size. |
| One may obtain the page size |
| .RB ( PAGE_SIZE ) |
| using |
| .IR sysconf(_SC_PAGESIZE) . |
| .PP |
| The |
| .I vec |
| argument must point to an array containing at least |
| .I "(length+PAGE_SIZE\-1) / PAGE_SIZE" |
| bytes. |
| On return, |
| the least significant bit of each byte will be set if |
| the corresponding page is currently resident in memory, |
| and be clear otherwise. |
| (The settings of the other bits in each byte are undefined; |
| these bits are reserved for possible later use.) |
| Of course the information returned in |
| .I vec |
| is only a snapshot: pages that are not |
| locked in memory can come and go at any moment, and the contents of |
| .I vec |
| may already be stale by the time this call returns. |
| .SH RETURN VALUE |
| On success, |
| .BR mincore () |
| returns zero. |
| On error, \-1 is returned, and |
| .I errno |
| is set appropriately. |
| .SH ERRORS |
| .B EAGAIN |
| kernel is temporarily out of resources. |
| .TP |
| .B EFAULT |
| .I vec |
| points to an invalid address. |
| .TP |
| .B EINVAL |
| .I addr |
| is not a multiple of the page size. |
| .TP |
| .B ENOMEM |
| .I length |
| is greater than |
| .RI ( TASK_SIZE " \- " addr ). |
| (This could occur if a negative value is specified for |
| .IR length , |
| since that value will be interpreted as a large |
| unsigned integer.) |
| In Linux 2.6.11 and earlier, the error |
| .B EINVAL |
| was returned for this condition. |
| .TP |
| .B ENOMEM |
| .I addr |
| to |
| .I addr |
| + |
| .I length |
| contained unmapped memory. |
| .SH VERSIONS |
| Available since Linux 2.3.99pre1 and glibc 2.2. |
| .SH CONFORMING TO |
| .BR mincore () |
| is not specified in POSIX.1, |
| and it is not available on all UNIX implementations. |
| .\" It is on at least NetBSD, FreeBSD, OpenBSD, Solaris 8, |
| .\" AIX 5.1, SunOS 4.1 |
| .\" .SH HISTORY |
| .\" The |
| .\" .BR mincore () |
| .\" function first appeared in 4.4BSD. |
| .SH BUGS |
| Before kernel 2.6.21, |
| .BR mincore () |
| did not return correct information for |
| .B MAP_PRIVATE |
| mappings, or for nonlinear mappings (established using |
| .BR remap_file_pages (2)). |
| .\" Linux (up to now, 2.6.5), |
| .\" .B mincore |
| .\" does not return correct information for MAP_PRIVATE mappings: |
| .\" for a MAP_PRIVATE file mapping, |
| .\" .B mincore |
| .\" returns the residency of the file pages, rather than any |
| .\" modified process-private pages that have been copied on write; |
| .\" for a MAP_PRIVATE mapping of |
| .\" .IR /dev/zero , |
| .\" .B mincore |
| .\" always reports pages as nonresident; |
| .\" and for a MAP_PRIVATE, MAP_ANONYMOUS mapping, |
| .\" .B mincore |
| .\" always fails with the error |
| .\" .BR ENOMEM . |
| .SH SEE ALSO |
| .BR fincore (1), |
| .BR madvise (2), |
| .BR mlock (2), |
| .BR mmap (2), |
| .BR posix_fadvise (2), |
| .BR posix_madvise (3) |