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. All advertising materials mentioning features or use of this software 13.\" must display the following acknowledgement: 14.\" This product includes software developed by the University of 15.\" California, Berkeley and its contributors. 16.\" 4. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" @(#)mlock.2 8.2 (Berkeley) 12/11/93 33.\" $FreeBSD: src/lib/libc/sys/mlock.2,v 1.6.2.5 2001/12/14 18:34:01 ru Exp $ 34.\" $DragonFly: src/lib/libc/sys/mlock.2,v 1.4 2006/02/17 19:35:06 swildner Exp $ 35.\" 36.Dd May 18, 2004 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.In sys/types.h 47.In sys/mman.h 48.Ft int 49.Fn mlock "const void *addr" "size_t len" 50.Ft int 51.Fn munlock "const void *addr" "size_t len" 52.Sh DESCRIPTION 53The 54.Fn 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.Fn munlock 64call unlocks pages previously locked by one or more 65.Fn 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.Fn 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.Fn mlock 89calls on the same address range. 90Unlocking is performed explicitly by 91.Fn munlock 92or implicitly by a call to 93.Fn 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.Fn mlock 102the minimum of 103a system-wide ``wired pages'' limit and 104the per-process 105.Li RLIMIT_MEMLOCK 106resource limit. 107.Pp 108These calls are only available to the super-user. 109.Sh RETURN VALUES 110.Rv -std 111.Pp 112If the call succeeds, all pages in the range become locked (unlocked); 113otherwise the locked status of all pages in the range remains unchanged. 114.Sh ERRORS 115.Fn Mlock 116will fail if: 117.Bl -tag -width Er 118.It Bq Er EPERM 119The caller is not the super-user. 120.It Bq Er EINVAL 121The address given is not page aligned or the length is negative. 122.It Bq Er EAGAIN 123Locking the indicated range would exceed either the system or per-process 124limit for locked memory. 125.It Bq Er ENOMEM 126Some portion of the indicated address range is not allocated. 127There was an error faulting/mapping a page. 128.El 129.Fn Munlock 130will fail if: 131.Bl -tag -width Er 132.It Bq Er EPERM 133The caller is not the super-user. 134.It Bq Er EINVAL 135The address given is not page aligned or the length is negative. 136.It Bq Er ENOMEM 137Some portion of the indicated address range is not allocated. 138Some portion of the indicated address range is not locked. 139.El 140.Sh "SEE ALSO" 141.Xr fork 2 , 142.Xr mincore 2 , 143.Xr minherit 2 , 144.Xr mmap 2 , 145.Xr munmap 2 , 146.Xr setrlimit 2 , 147.Xr getpagesize 3 148.Sh HISTORY 149The 150.Fn mlock 151and 152.Fn munlock 153functions first appeared in 154.Bx 4.4 . 155.Sh BUGS 156The per-process resource limit is a limit on the amount of virtual 157memory locked, while the system-wide limit is for the number of locked 158physical pages. 159Hence a process with two distinct locked mappings of the same physical page 160counts as 2 pages against the per-process limit and as only a single page 161in the system limit. 162.Pp 163The per-process resource limit is not currently supported. 164