xref: /freebsd/lib/libsys/mincore.2 (revision 8269e7673cf033aba67dab8264fe719920c70f87)
1*8269e767SBrooks Davis.\" Copyright (c) 1991, 1993
2*8269e767SBrooks Davis.\"	The Regents of the University of California.  All rights reserved.
3*8269e767SBrooks Davis.\"
4*8269e767SBrooks Davis.\" Redistribution and use in source and binary forms, with or without
5*8269e767SBrooks Davis.\" modification, are permitted provided that the following conditions
6*8269e767SBrooks Davis.\" are met:
7*8269e767SBrooks Davis.\" 1. Redistributions of source code must retain the above copyright
8*8269e767SBrooks Davis.\"    notice, this list of conditions and the following disclaimer.
9*8269e767SBrooks Davis.\" 2. Redistributions in binary form must reproduce the above copyright
10*8269e767SBrooks Davis.\"    notice, this list of conditions and the following disclaimer in the
11*8269e767SBrooks Davis.\"    documentation and/or other materials provided with the distribution.
12*8269e767SBrooks Davis.\" 3. Neither the name of the University nor the names of its contributors
13*8269e767SBrooks Davis.\"    may be used to endorse or promote products derived from this software
14*8269e767SBrooks Davis.\"    without specific prior written permission.
15*8269e767SBrooks Davis.\"
16*8269e767SBrooks Davis.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17*8269e767SBrooks Davis.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18*8269e767SBrooks Davis.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19*8269e767SBrooks Davis.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20*8269e767SBrooks Davis.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21*8269e767SBrooks Davis.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22*8269e767SBrooks Davis.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23*8269e767SBrooks Davis.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24*8269e767SBrooks Davis.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25*8269e767SBrooks Davis.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26*8269e767SBrooks Davis.\" SUCH DAMAGE.
27*8269e767SBrooks Davis.\"
28*8269e767SBrooks Davis.Dd August 23, 2020
29*8269e767SBrooks Davis.Dt MINCORE 2
30*8269e767SBrooks Davis.Os
31*8269e767SBrooks Davis.Sh NAME
32*8269e767SBrooks Davis.Nm mincore
33*8269e767SBrooks Davis.Nd determine residency of memory pages
34*8269e767SBrooks Davis.Sh LIBRARY
35*8269e767SBrooks Davis.Lb libc
36*8269e767SBrooks Davis.Sh SYNOPSIS
37*8269e767SBrooks Davis.In sys/mman.h
38*8269e767SBrooks Davis.Ft int
39*8269e767SBrooks Davis.Fn mincore "const void *addr" "size_t len" "char *vec"
40*8269e767SBrooks Davis.Sh DESCRIPTION
41*8269e767SBrooks DavisThe
42*8269e767SBrooks Davis.Fn mincore
43*8269e767SBrooks Davissystem call determines whether each of the pages in the region beginning at
44*8269e767SBrooks Davis.Fa addr
45*8269e767SBrooks Davisand continuing for
46*8269e767SBrooks Davis.Fa len
47*8269e767SBrooks Davisbytes is resident or mapped, depending on the value of sysctl
48*8269e767SBrooks Davis.Va vm.mincore_mapped .
49*8269e767SBrooks Davis.\"The beginning address,
50*8269e767SBrooks Davis.\".Fa addr ,
51*8269e767SBrooks Davis.\"is first rounded down to a multiple of the page size (see
52*8269e767SBrooks Davis.\".Xr getpagesize 3 ) .
53*8269e767SBrooks Davis.\"The end address,
54*8269e767SBrooks Davis.\".Fa addr No + Fa len ,
55*8269e767SBrooks Davis.\"is rounded up to a multiple of the page size.
56*8269e767SBrooks DavisThe status is returned in the
57*8269e767SBrooks Davis.Fa vec
58*8269e767SBrooks Davisarray, one character per page.
59*8269e767SBrooks DavisEach character is either 0 if the page is not resident, or a combination of
60*8269e767SBrooks Davisthe following flags (defined in
61*8269e767SBrooks Davis.In sys/mman.h ) :
62*8269e767SBrooks Davis.Bl -tag -width ".Dv MINCORE_REFERENCED_OTHER"
63*8269e767SBrooks Davis.It Dv MINCORE_INCORE
64*8269e767SBrooks DavisPage is in core (resident).
65*8269e767SBrooks Davis.It Dv MINCORE_REFERENCED
66*8269e767SBrooks DavisPage has been referenced by us.
67*8269e767SBrooks Davis.It Dv MINCORE_MODIFIED
68*8269e767SBrooks DavisPage has been modified by us.
69*8269e767SBrooks Davis.It Dv MINCORE_REFERENCED_OTHER
70*8269e767SBrooks DavisPage has been referenced.
71*8269e767SBrooks Davis.It Dv MINCORE_MODIFIED_OTHER
72*8269e767SBrooks DavisPage has been modified.
73*8269e767SBrooks Davis.It Dv MINCORE_PSIND(i)
74*8269e767SBrooks DavisPage is part of a large
75*8269e767SBrooks Davis.Pq Dq super
76*8269e767SBrooks Davispage with size given by index
77*8269e767SBrooks Davis.Dv i
78*8269e767SBrooks Davisin the array returned by
79*8269e767SBrooks Davis.Xr getpagesizes 3 .
80*8269e767SBrooks Davis.It Dv MINCORE_SUPER
81*8269e767SBrooks DavisA mask of the valid
82*8269e767SBrooks Davis.Dv MINCORE_PSIND()
83*8269e767SBrooks Davisvalues.
84*8269e767SBrooks DavisIf any bits in this mask are set, the page is part of a large
85*8269e767SBrooks Davis.Pq Dq super
86*8269e767SBrooks Davispage.
87*8269e767SBrooks Davis.El
88*8269e767SBrooks Davis.Pp
89*8269e767SBrooks DavisThe information returned by
90*8269e767SBrooks Davis.Fn mincore
91*8269e767SBrooks Davismay be out of date by the time the system call returns.
92*8269e767SBrooks DavisThe only way to ensure that a page is resident is to lock it into memory
93*8269e767SBrooks Daviswith the
94*8269e767SBrooks Davis.Xr mlock 2
95*8269e767SBrooks Davissystem call.
96*8269e767SBrooks Davis.Pp
97*8269e767SBrooks DavisIf the
98*8269e767SBrooks Davis.Va vm.mincore_mapped
99*8269e767SBrooks Davissysctl is set to a non-zero value (default), only the current process'
100*8269e767SBrooks Davismappings of the pages in the specified virtual address range are examined.
101*8269e767SBrooks DavisThis does not preclude the system from returning
102*8269e767SBrooks Davis.Dv MINCORE_REFERENCED_OTHER
103*8269e767SBrooks Davisand
104*8269e767SBrooks Davis.Dv MINCORE_MODIFIED_OTHER
105*8269e767SBrooks Davisstatuses.
106*8269e767SBrooks DavisOtherwise, if the sysctl value is zero, all resident pages backing the
107*8269e767SBrooks Davisspecified address range are examined, regardless of the mapping state.
108*8269e767SBrooks Davis.Sh IMPLEMENTATION NOTES
109*8269e767SBrooks DavisPrior to the introduction of
110*8269e767SBrooks Davis.Dv MINCORE_PSIND()
111*8269e767SBrooks Davisin
112*8269e767SBrooks Davis.Fx 13.0 ,
113*8269e767SBrooks Davis.Dv MINCORE_SUPER
114*8269e767SBrooks Davisconsisted of a single bit equal to
115*8269e767SBrooks Davis.Dv MINCORE_PSIND(1) .
116*8269e767SBrooks DavisIn particular, applications compiled using the old value of
117*8269e767SBrooks Davis.Dv MINCORE_SUPER
118*8269e767SBrooks Daviswill not identify large pages with size index 2 as being large pages.
119*8269e767SBrooks Davis.Sh RETURN VALUES
120*8269e767SBrooks Davis.Rv -std mincore
121*8269e767SBrooks Davis.Sh ERRORS
122*8269e767SBrooks DavisThe
123*8269e767SBrooks Davis.Fn mincore
124*8269e767SBrooks Davissystem call will fail if:
125*8269e767SBrooks Davis.Bl -tag -width Er
126*8269e767SBrooks Davis.It Bq Er ENOMEM
127*8269e767SBrooks DavisThe virtual address range specified by the
128*8269e767SBrooks Davis.Fa addr
129*8269e767SBrooks Davisand
130*8269e767SBrooks Davis.Fa len
131*8269e767SBrooks Davisarguments is not fully mapped.
132*8269e767SBrooks Davis.It Bq Er EFAULT
133*8269e767SBrooks DavisThe
134*8269e767SBrooks Davis.Fa vec
135*8269e767SBrooks Davisargument points to an illegal address.
136*8269e767SBrooks Davis.El
137*8269e767SBrooks Davis.Sh SEE ALSO
138*8269e767SBrooks Davis.Xr madvise 2 ,
139*8269e767SBrooks Davis.Xr mlock 2 ,
140*8269e767SBrooks Davis.Xr mprotect 2 ,
141*8269e767SBrooks Davis.Xr msync 2 ,
142*8269e767SBrooks Davis.Xr munmap 2 ,
143*8269e767SBrooks Davis.Xr getpagesize 3 ,
144*8269e767SBrooks Davis.Xr getpagesizes 3
145*8269e767SBrooks Davis.Sh HISTORY
146*8269e767SBrooks DavisThe
147*8269e767SBrooks Davis.Fn mincore
148*8269e767SBrooks Davissystem call first appeared in
149*8269e767SBrooks Davis.Bx 4.4 .
150