1.\" $NetBSD: mlock.2,v 1.10 1999/12/02 21:42:37 kleink 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. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed by the University of 17.\" California, Berkeley and its contributors. 18.\" 4. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" @(#)mlock.2 8.2 (Berkeley) 12/11/93 35.\" 36.Dd June 2, 1993 37.Dt MLOCK 2 38.Os 39.Sh NAME 40.Nm mlock , 41.Nm munlock 42.Nd lock (unlock) physical pages in memory 43.Sh LIBRARY 44.Lb libc 45.Sh SYNOPSIS 46.Fd #include <sys/types.h> 47.Fd #include <sys/mman.h> 48.Ft int 49.Fn mlock "void *addr" "size_t len" 50.Ft int 51.Fn munlock "void *addr" "size_t len" 52.Sh DESCRIPTION 53The 54.Nm mlock 55system call 56locks into memory the physical pages associated with the virtual address 57range starting at 58.Fa addr 59for 60.Fa len 61bytes. 62The 63.Nm munlock 64call unlocks pages previously locked by one or more 65.Nm mlock 66calls. 67For both, the 68.Fa addr 69parameter should be aligned to a multiple of the page size. 70If the 71.Fa len 72parameter is not a multiple of the page size, it will be rounded up 73to be so. 74The entire range must be allocated. 75.Pp 76After an 77.Nm mlock 78call, the indicated pages will cause neither a non-resident page 79nor address-translation fault until they are unlocked. 80They may still cause protection-violation faults or TLB-miss faults on 81architectures with software-managed TLBs. 82The physical pages remain in memory until all locked mappings for the pages 83are removed. 84Multiple processes may have the same physical pages locked via their own 85virtual address mappings. 86A single process may likewise have pages multiply-locked via different virtual 87mappings of the same pages or via nested 88.Nm mlock 89calls on the same address range. 90Unlocking is performed explicitly by 91.Nm munlock 92or implicitly by a call to 93.Nm munmap 94which deallocates the unmapped address range. 95Locked mappings are not inherited by the child process after a 96.Xr fork 2 . 97.Pp 98Since physical memory is a potentially scarce resource, processes are 99limited in how much they can lock down. 100A single process can 101.Nm mlock 102the minimum of 103a system-wide ``wired pages'' limit and 104the per-process 105.Li RLIMIT_MEMLOCK 106resource limit. 107.Sh RETURN VALUES 108A return value of 0 indicates that the call 109succeeded and all pages in the range have either been locked or unlocked. 110A return value of -1 indicates an error occurred and the locked 111status of all pages in the range remains unchanged. 112In this case, the global location 113.Va errno 114is set to indicate the error. 115.Sh ERRORS 116.Fn mlock 117will fail if: 118.Bl -tag -width Er 119.It Bq Er EINVAL 120The address given is not page aligned or the length is negative. 121.It Bq Er EAGAIN 122Locking the indicated range would exceed either the system or per-process 123limit for locked memory. 124.It Bq Er ENOMEM 125Some portion of the indicated address range is not allocated. 126There was an error faulting/mapping a page. 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