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