.\" Copyright (C) 2001 Bert Hubert <ahu@ds9a.nl>
.\" and Copyright (C) 2007 Michael Kerrisk <mtk.manpages@gmail.com>
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
.\" 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 2024-05-02 "Linux man-pages (unreleased)"
.SH NAME
mincore \- determine whether pages are resident in memory
.SH LIBRARY
Standard C library
.RI ( libc ", " \-lc )
.SH SYNOPSIS
.nf
.B #include <sys/mman.h>
.P
.BI "int mincore(void " addr [. length "], size_t " length ", unsigned char *" vec );
.fi
.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
.P
.BR mincore ():
.nf
    Since glibc 2.19:
        _DEFAULT_SOURCE
    glibc 2.19 and earlier:
        _BSD_SOURCE || _SVID_SOURCE
.fi
.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.
.P
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) .
.P
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 to indicate the error.
.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 STANDARDS
None.
.SH HISTORY
Linux 2.3.99pre1,
glibc 2.2.
.P
First appeared in 4.4BSD.
.P
NetBSD, FreeBSD, OpenBSD, Solaris 8,
AIX 5.1, SunOS 4.1.
.SH BUGS
Before Linux 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)