Debian Codegraph @

upstream/debian-unstable/man2/mincore.2

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