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.\" @(#)mlock.2 8.2 (Berkeley) 12/11/93 29.\" $FreeBSD$ 30.\" 31.Dd May 13, 2019 32.Dt MLOCK 2 33.Os 34.Sh NAME 35.Nm mlock , 36.Nm munlock 37.Nd lock (unlock) physical pages in memory 38.Sh LIBRARY 39.Lb libc 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 58system call unlocks pages previously locked by one or more 59.Fn mlock 60calls. 61For both, the 62.Fa addr 63argument should be aligned to a multiple of the page size. 64If the 65.Fa len 66argument 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 72system call, 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 physical pages. 82Unlocking is performed explicitly by 83.Fn munlock 84or implicitly by a call to 85.Fn munmap 86which deallocates the unmapped address range. 87Locked mappings are not inherited by the child process after a 88.Xr fork 2 . 89.Pp 90Since physical memory is a potentially scarce resource, processes are 91limited in how much they can lock down. 92The amount of memory that a single process can 93.Fn mlock 94is limited by both the per-process 95.Dv RLIMIT_MEMLOCK 96resource limit and the 97system-wide 98.Dq wired pages 99limit 100.Va vm.max_user_wired . 101.Va vm.max_user_wired 102applies to the system as a whole, so the amount available to a single 103process at any given time is the difference between 104.Va vm.max_user_wired 105and 106.Va vm.stats.vm.v_user_wire_count . 107.Pp 108If 109.Va security.bsd.unprivileged_mlock 110is set to 0 these calls are only available to the super-user. 111.Sh RETURN VALUES 112.Rv -std 113.Pp 114If the call succeeds, all pages in the range become locked (unlocked); 115otherwise the locked status of all pages in the range remains unchanged. 116.Sh ERRORS 117The 118.Fn mlock 119system call 120will fail if: 121.Bl -tag -width Er 122.It Bq Er EPERM 123.Va security.bsd.unprivileged_mlock 124is set to 0 and the caller is not the super-user. 125.It Bq Er EINVAL 126The address range given wraps around zero. 127.It Bq Er ENOMEM 128Some portion of the indicated address range is not allocated. 129There was an error faulting/mapping a page. 130Locking the indicated range would exceed the per-process or system-wide limits 131for locked memory. 132.El 133The 134.Fn munlock 135system call 136will fail if: 137.Bl -tag -width Er 138.It Bq Er EPERM 139.Va security.bsd.unprivileged_mlock 140is set to 0 and the caller is not the super-user. 141.It Bq Er EINVAL 142The address range given wraps around zero. 143.It Bq Er ENOMEM 144Some or all of the address range specified by the addr and len 145arguments does not correspond to valid mapped pages in the address space 146of the process. 147.It Bq Er ENOMEM 148Locking the pages mapped by the specified range would exceed a limit on 149the amount of memory that the process may lock. 150.El 151.Sh "SEE ALSO" 152.Xr fork 2 , 153.Xr mincore 2 , 154.Xr minherit 2 , 155.Xr mlockall 2 , 156.Xr mmap 2 , 157.Xr munlockall 2 , 158.Xr munmap 2 , 159.Xr setrlimit 2 , 160.Xr getpagesize 3 161.Sh HISTORY 162The 163.Fn mlock 164and 165.Fn munlock 166system calls first appeared in 167.Bx 4.4 . 168.Sh BUGS 169Allocating too much wired memory can lead to a memory-allocation deadlock 170which requires a reboot to recover from. 171.Pp 172The per-process and system-wide resource limits of locked memory apply 173to the amount of virtual memory locked, not the amount of locked physical 174pages. 175Hence two distinct locked mappings of the same physical page counts as 1762 pages aginst the system limit, and also against the per-process limit 177if both mappings belong to the same physical map. 178.Pp 179The per-process resource limit is not currently supported. 180