1.\" $OpenBSD: mlock.2,v 1.20 2019/01/11 18:46:30 deraadt Exp $ 2.\" $NetBSD: mlock.2,v 1.3 1995/06/24 10:42:03 cgd Exp $ 3.\" 4.\" Copyright (c) 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" @(#)mlock.2 8.2 (Berkeley) 12/11/93 32.\" 33.Dd $Mdocdate: January 11 2019 $ 34.Dt MLOCK 2 35.Os 36.Sh NAME 37.Nm mlock , 38.Nm munlock 39.Nd lock (unlock) physical pages in memory 40.Sh SYNOPSIS 41.In sys/mman.h 42.Ft int 43.Fn mlock "const void *addr" "size_t len" 44.Ft int 45.Fn munlock "const void *addr" "size_t len" 46.Sh DESCRIPTION 47The 48.Fn mlock 49system call 50locks into memory the physical pages associated with the virtual address 51range starting at 52.Fa addr 53for 54.Fa len 55bytes. 56The 57.Fn munlock 58call unlocks pages previously locked by one or more 59.Fn mlock 60calls. 61For both, the 62.Fa addr 63parameter should be aligned to a multiple of the page size. 64If the 65.Fa len 66parameter is not a multiple of the page size, it will be rounded up 67to be so. 68The entire range must be allocated. 69.Pp 70After an 71.Fn mlock 72call, the indicated pages will cause neither a non-resident page 73nor address-translation fault until they are unlocked. 74They may still cause protection-violation faults or TLB-miss faults on 75architectures with software-managed TLBs. 76The physical pages remain in memory until all locked mappings for the pages 77are removed. 78Multiple processes may have the same physical pages locked via their own 79virtual address mappings. 80A single process may likewise have pages multiply locked via different virtual 81mappings of the same pages or via nested 82.Fn mlock 83calls on the same address range. 84Unlocking is performed explicitly by 85.Fn munlock 86or implicitly by a call to 87.Xr munmap 2 88which deallocates the unmapped address range. 89Locked mappings are not inherited by the child process after a 90.Xr fork 2 . 91.Pp 92Since physical memory is a potentially scarce resource, processes are 93limited in how much they can lock down. 94A single process can 95.Fn mlock 96the minimum of 97a system-wide 98.Dq wired pages 99limit and the per-process 100.Li RLIMIT_MEMLOCK 101resource limit. 102.Sh RETURN VALUES 103.Rv -std mlock munlock 104.Sh ERRORS 105.Fn mlock 106will fail if: 107.Bl -tag -width Er 108.It Bq Er EINVAL 109The address given is not page aligned or the length is negative. 110.It Bq Er EAGAIN 111Locking the indicated range would exceed either the system or per-process 112limit for locked memory. 113.It Bq Er ENOMEM 114Some portion of the indicated address range is not allocated. 115There was an error faulting/mapping a page. 116.El 117.Pp 118.Fn munlock 119will fail if: 120.Bl -tag -width Er 121.It Bq Er EINVAL 122The address given is not page aligned or 123.Fa addr 124and 125.Fa size 126specify a region that would extend beyond the end of the address space. 127.It Bq Er ENOMEM 128Some portion of the indicated address range is not allocated. 129Some portion of the indicated address range is not locked. 130.El 131.Sh SEE ALSO 132.Xr fork 2 , 133.Xr minherit 2 , 134.Xr mlockall 2 , 135.Xr mmap 2 , 136.Xr munmap 2 , 137.Xr setrlimit 2 , 138.Xr getpagesize 3 139.Sh HISTORY 140The 141.Fn mlock 142and 143.Fn munlock 144functions first appeared in 145.Bx 4.4 . 146.Sh BUGS 147Unlike Sun's implementation, multiple 148.Fn mlock 149calls on the same address range require the corresponding number of 150.Fn munlock 151calls to actually unlock the pages, i.e., 152.Fn mlock 153nests. 154This should be considered a consequence of the implementation 155and not a feature. 156.Pp 157The per-process resource limit is a limit on the amount of virtual 158memory locked, while the system-wide limit is for the number of locked 159physical pages. 160Hence a process with two distinct locked mappings of the same physical page 161counts as 2 pages against the per-process limit and as only a single page 162in the system limit. 163