1.\" $OpenBSD: mlock.2,v 1.14 2003/06/02 20:18:39 millert 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 June 2, 1993 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.Fd #include <sys/types.h> 42.Fd #include <sys/mman.h> 43.Ft int 44.Fn mlock "void *addr" "size_t len" 45.Ft int 46.Fn munlock "void *addr" "size_t len" 47.Sh DESCRIPTION 48The 49.Nm mlock 50system call 51locks into memory the physical pages associated with the virtual address 52range starting at 53.Fa addr 54for 55.Fa len 56bytes. 57The 58.Nm munlock 59call unlocks pages previously locked by one or more 60.Nm mlock 61calls. 62For both, the 63.Fa addr 64parameter should be aligned to a multiple of the page size. 65If the 66.Fa len 67parameter is not a multiple of the page size, it will be rounded up 68to be so. 69The entire range must be allocated. 70.Pp 71After an 72.Nm mlock 73call, the indicated pages will cause neither a non-resident page 74nor address-translation fault until they are unlocked. 75They may still cause protection-violation faults or TLB-miss faults on 76architectures with software-managed TLBs. 77The physical pages remain in memory until all locked mappings for the pages 78are removed. 79Multiple processes may have the same physical pages locked via their own 80virtual address mappings. 81A single process may likewise have pages multiply locked via different virtual 82mappings of the same pages or via nested 83.Nm mlock 84calls on the same address range. 85Unlocking is performed explicitly by 86.Nm munlock 87or implicitly by a call to 88.Nm munmap 89which deallocates the unmapped address range. 90Locked mappings are not inherited by the child process after a 91.Xr fork 2 . 92.Pp 93Since physical memory is a potentially scarce resource, processes are 94limited in how much they can lock down. 95A single process can 96.Nm mlock 97the minimum of 98a system-wide ``wired pages'' limit and 99the per-process 100.Li RLIMIT_MEMLOCK 101resource limit. 102.Sh RETURN VALUES 103A return value of 0 indicates that the call 104succeeded and all pages in the range have either been locked or unlocked. 105A return value of \-1 indicates an error occurred and the locked 106status of all pages in the range remains unchanged. 107In this case, the global location 108.Va errno 109is set to indicate the error. 110.Sh ERRORS 111.Fn mlock 112will fail if: 113.Bl -tag -width Er 114.It Bq Er EINVAL 115The address given is not page aligned or the length is negative. 116.It Bq Er EAGAIN 117Locking the indicated range would exceed either the system or per-process 118limit for locked memory. 119.It Bq Er ENOMEM 120Some portion of the indicated address range is not allocated. 121There was an error faulting/mapping a page. 122.El 123.Pp 124.Fn munlock 125will fail if: 126.Bl -tag -width Er 127.It Bq Er EINVAL 128The address given is not page aligned or the length is negative. 129.It Bq Er ENOMEM 130Some portion of the indicated address range is not allocated. 131Some portion of the indicated address range is not locked. 132.El 133.Sh SEE ALSO 134.Xr fork 2 , 135.Xr mincore 2 , 136.Xr minherit 2 , 137.Xr mlockall 2 , 138.Xr mmap 2 , 139.Xr munmap 2 , 140.Xr setrlimit 2 , 141.Xr getpagesize 3 142.Sh HISTORY 143The 144.Fn mlock 145and 146.Fn munlock 147functions first appeared in 148.Bx 4.4 . 149.Sh BUGS 150Unlike The Sun implementation, multiple 151.Nm mlock 152calls on the same address range require the corresponding number of 153.Nm munlock 154calls to actually unlock the pages, i.e., 155.Nm mlock 156nests. 157This should be considered a consequence of the implementation 158and not a feature. 159.Pp 160The per-process resource limit is a limit on the amount of virtual 161memory locked, while the system-wide limit is for the number of locked 162physical pages. 163Hence a process with two distinct locked mappings of the same physical page 164counts as 2 pages against the per-process limit and as only a single page 165in the system limit. 166