man2/mincore.2

   1 .\" Copyright (C) 2001 Bert Hubert <ahu@ds9a.nl>
   2 .\" and Copyright (C) 2007 Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .\" Created Sun Jun 3 17:23:32 2001 by bert hubert <ahu@ds9a.nl>
   7 .\" Slightly adapted, following comments by Hugh Dickins, aeb, 2001-06-04.
   8 .\" Modified, 20 May 2003, Michael Kerrisk <mtk.manpages@gmail.com>
   9 .\" Modified, 30 Apr 2004, Michael Kerrisk <mtk.manpages@gmail.com>
  10 .\" 2005-04-05 mtk, Fixed error descriptions
  11 .\"     after message from <gordon.jin@intel.com>
  12 .\" 2007-01-08 mtk, rewrote various parts
  13 .\"
  14 .TH MINCORE 2 2021-03-22 "Linux man-pages (unreleased)"
  15 .SH NAME
  16 mincore \- determine whether pages are resident in memory
  17 .SH LIBRARY
  18 Standard C library
  19 .RI ( libc ", " \-lc )
  20 .SH SYNOPSIS
  21 .nf
  22 .B #include <sys/mman.h>
  23 .PP
  24 .BI "int mincore(void *" addr ", size_t " length ", unsigned char *" vec );
  25 .fi
  26 .PP
  27 .RS -4
  28 Feature Test Macro Requirements for glibc (see
  29 .BR feature_test_macros (7)):
  30 .RE
  31 .PP
  32 .BR mincore ():
  33 .nf
  34     Since glibc 2.19:
  35         _DEFAULT_SOURCE
  36     Glibc 2.19 and earlier:
  37         _BSD_SOURCE || _SVID_SOURCE
  38 .fi
  39 .SH DESCRIPTION
  40 .BR mincore ()
  41 returns a vector that indicates whether pages
  42 of the calling process's virtual memory are resident in core (RAM),
  43 and so will not cause a disk access (page fault) if referenced.
  44 The kernel returns residency information about the pages
  45 starting at the address
  46 .IR addr ,
  47 and continuing for
  48 .I length
  49 bytes.
  50 .PP
  51 The
  52 .I addr
  53 argument must be a multiple of the system page size.
  54 The
  55 .I length
  56 argument need not be a multiple of the page size,
  57 but since residency information is returned for whole pages,
  58 .I length
  59 is effectively rounded up to the next multiple of the page size.
  60 One may obtain the page size
  61 .RB ( PAGE_SIZE )
  62 using
  63 .IR sysconf(_SC_PAGESIZE) .
  64 .PP
  65 The
  66 .I vec
  67 argument must point to an array containing at least
  68 .I "(length+PAGE_SIZE\-1) / PAGE_SIZE"
  69 bytes.
  70 On return,
  71 the least significant bit of each byte will be set if
  72 the corresponding page is currently resident in memory,
  73 and be clear otherwise.
  74 (The settings of the other bits in each byte are undefined;
  75 these bits are reserved for possible later use.)
  76 Of course the information returned in
  77 .I vec
  78 is only a snapshot: pages that are not
  79 locked in memory can come and go at any moment, and the contents of
  80 .I vec
  81 may already be stale by the time this call returns.
  82 .SH RETURN VALUE
  83 On success,
  84 .BR mincore ()
  85 returns zero.
  86 On error, \-1 is returned, and
  87 .I errno
  88 is set to indicate the error.
  89 .SH ERRORS
  90 .B EAGAIN
  91 kernel is temporarily out of resources.
  92 .TP
  93 .B EFAULT
  94 .I vec
  95 points to an invalid address.
  96 .TP
  97 .B EINVAL
  98 .I addr
  99 is not a multiple of the page size.
 100 .TP
 101 .B ENOMEM
 102 .I length
 103 is greater than
 104 .RI ( TASK_SIZE " \- " addr ).
 105 (This could occur if a negative value is specified for
 106 .IR length ,
 107 since that value will be interpreted as a large
 108 unsigned integer.)
 109 In Linux 2.6.11 and earlier, the error
 110 .B EINVAL
 111 was returned for this condition.
 112 .TP
 113 .B ENOMEM
 114 .I addr
 115 to
 116 .I addr
 117 +
 118 .I length
 119 contained unmapped memory.
 120 .SH VERSIONS
 121 Available since Linux 2.3.99pre1 and glibc 2.2.
 122 .SH STANDARDS
 123 .BR mincore ()
 124 is not specified in POSIX.1,
 125 and it is not available on all UNIX implementations.
 126 .\" It is on at least NetBSD, FreeBSD, OpenBSD, Solaris 8,
 127 .\" AIX 5.1, SunOS 4.1
 128 .\" .SH HISTORY
 129 .\" The
 130 .\" .BR mincore ()
 131 .\" function first appeared in 4.4BSD.
 132 .SH BUGS
 133 Before kernel 2.6.21,
 134 .BR mincore ()
 135 did not return correct information for
 136 .B MAP_PRIVATE
 137 mappings, or for nonlinear mappings (established using
 138 .BR remap_file_pages (2)).
 139 .\" Linux (up to now, 2.6.5),
 140 .\" .B mincore
 141 .\" does not return correct information for MAP_PRIVATE mappings:
 142 .\" for a MAP_PRIVATE file mapping,
 143 .\" .B mincore
 144 .\" returns the residency of the file pages, rather than any
 145 .\" modified process-private pages that have been copied on write;
 146 .\" for a MAP_PRIVATE mapping of
 147 .\" .IR /dev/zero ,
 148 .\" .B mincore
 149 .\" always reports pages as nonresident;
 150 .\" and for a MAP_PRIVATE, MAP_ANONYMOUS mapping,
 151 .\" .B mincore
 152 .\" always fails with the error
 153 .\" .BR ENOMEM .
 154 .SH SEE ALSO
 155 .BR fincore (1),
 156 .BR madvise (2),
 157 .BR mlock (2),
 158 .BR mmap (2),
 159 .BR posix_fadvise (2),
 160 .BR posix_madvise (3)