Debian Codegraph @

upstream/debian-trixie/man2/mincore.2

raw
1 .\" Copyright (C) 2001 Bert Hubert <[email protected]>
2 .\" and Copyright (C) 2007 Michael Kerrisk <[email protected]>
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .\" Created Sun Jun 3 17:23:32 2001 by bert hubert <[email protected]>
7 .\" Slightly adapted, following comments by Hugh Dickins, aeb, 2001-06-04.
8 .\" Modified, 20 May 2003, Michael Kerrisk <[email protected]>
9 .\" Modified, 30 Apr 2004, Michael Kerrisk <[email protected]>
10 .\" 2005-04-05 mtk, Fixed error descriptions
11 .\" after message from <[email protected]>
12 .\" 2007-01-08 mtk, rewrote various parts
13 .\"
14 .TH mincore 2 2024-05-02 "Linux man-pages 6.9.1"
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 .P
24 .BI "int mincore(void " addr [. length "], size_t " length ", unsigned char *" vec );
25 .fi
26 .P
27 .RS -4
28 Feature Test Macro Requirements for glibc (see
29 .BR feature_test_macros (7)):
30 .RE
31 .P
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 .P
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 .P
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 STANDARDS
121 None.
122 .SH HISTORY
123 Linux 2.3.99pre1,
124 glibc 2.2.
125 .P
126 First appeared in 4.4BSD.
127 .P
128 NetBSD, FreeBSD, OpenBSD, Solaris 8,
129 AIX 5.1, SunOS 4.1.
130 .SH BUGS
131 Before Linux 2.6.21,
132 .BR mincore ()
133 did not return correct information for
134 .B MAP_PRIVATE
135 mappings, or for nonlinear mappings (established using
136 .BR remap_file_pages (2)).
137 .\" Linux (up to now, 2.6.5),
138 .\" .B mincore
139 .\" does not return correct information for MAP_PRIVATE mappings:
140 .\" for a MAP_PRIVATE file mapping,
141 .\" .B mincore
142 .\" returns the residency of the file pages, rather than any
143 .\" modified process-private pages that have been copied on write;
144 .\" for a MAP_PRIVATE mapping of
145 .\" .IR /dev/zero ,
146 .\" .B mincore
147 .\" always reports pages as nonresident;
148 .\" and for a MAP_PRIVATE, MAP_ANONYMOUS mapping,
149 .\" .B mincore
150 .\" always fails with the error
151 .\" .BR ENOMEM .
152 .SH SEE ALSO
153 .BR fincore (1),
154 .BR madvise (2),
155 .BR mlock (2),
156 .BR mmap (2),
157 .BR posix_fadvise (2),
158 .BR posix_madvise (3)