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