1.\" $NetBSD: mlock.2,v 1.18 2004/05/13 10:20:58 wiz Exp $ 2.\" 3.\" Copyright (c) 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" @(#)mlock.2 8.2 (Berkeley) 12/11/93 31.\" 32.Dd June 2, 1993 33.Dt MLOCK 2 34.Os 35.Sh NAME 36.Nm mlock , 37.Nm munlock 38.Nd lock (unlock) physical pages in memory 39.Sh LIBRARY 40.Lb libc 41.Sh SYNOPSIS 42.In 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.It Bq Er EPERM 123.Fn mlock 124was called by non-root on an architecture where locked page accounting 125is not implemented. 126.Pp 127.El 128.Fn munlock 129will fail if: 130.Bl -tag -width Er 131.It Bq Er EINVAL 132The address given is not page aligned or the length is negative. 133.It Bq Er ENOMEM 134Some portion of the indicated address range is not allocated. 135Some portion of the indicated address range is not locked. 136.El 137.Sh SEE ALSO 138.Xr fork 2 , 139.Xr mincore 2 , 140.Xr mmap 2 , 141.Xr munmap 2 , 142.Xr setrlimit 2 , 143.Xr getpagesize 3 144.Sh STANDARDS 145The 146.Fn mlock 147and 148.Fn munlock 149functions conform to 150.St -p1003.1b-93 . 151.Sh HISTORY 152The 153.Fn mlock 154and 155.Fn munlock 156functions first appeared in 157.Bx 4.4 . 158.Sh BUGS 159The per-process resource limit is a limit on the amount of virtual 160memory locked, while the system-wide limit is for the number of locked 161physical pages. 162Hence a process with two distinct locked mappings of the same physical page 163counts as 2 pages against the per-process limit and as only a single page 164in the system limit. 165