1.\" Copyright (c) 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" %sccs.include.redist.roff% 5.\" 6.\" @(#)mlock.2 8.2 (Berkeley) 12/11/93 7.\" 8.Dd June 2, 1993 9.Dt MLOCK 2 10.Os 11.Sh NAME 12.Nm mlock , 13.Nm munlock 14.Nd lock (unlock) physical pages in memory 15.Sh SYNOPSIS 16.Fd #include <sys/types.h> 17.Fd #include <sys/mman.h> 18.Ft int 19.Fn mlock "caddr_t addr" "size_t len" 20.Ft int 21.Fn munlock "caddr_t addr" "size_t len" 22.Sh DESCRIPTION 23The 24.Nm mlock 25system call 26locks into memory the physical pages associated with the virtual address 27range starting at 28.Fa addr 29for 30.Fa len 31bytes. 32The 33.Nm munlock 34call unlocks pages previously locked by one or more 35.Nm mlock 36calls. 37For both, the 38.Fa addr 39parameter should be aligned to a multiple of the page size. 40If the 41.Fa len 42parameter is not a multiple of the page size, it will be rounded up 43to be so. 44The entire range must be allocated. 45.Pp 46After an 47.Nm mlock 48call, the indicated pages will cause neither a non-resident page 49nor address-translation fault until they are unlocked. 50They may still cause protection-violation faults or TLB-miss faults on 51architectures with software-managed TLBs. 52The physical pages remain in memory until all locked mappings for the pages 53are removed. 54Multiple processes may have the same physical pages locked via their own 55virtual address mappings. 56A single process may likewise have pages multiply-locked via different virtual 57mappings of the same pages or via nested 58.Nm mlock 59calls on the same address range. 60Unlocking is performed explicitly by 61.Nm munlock 62or implicitly by a call to 63.Nm munmap 64which deallocates the unmapped address range. 65Locked mappings are not inherited by the child process after a 66.Xr fork 2 . 67.Pp 68Since physical memory is a potentially scarce resource, processes are 69limited in how much they can lock down. 70A single process can 71.Nm mlock 72the minimum of 73a system-wide ``wired pages'' limit and 74the per-process 75.Li RLIMIT_MEMLOCK 76resource limit. 77.Sh RETURN VALUES 78A return value of 0 indicates that the call 79succeeded and all pages in the range have either been locked or unlocked. 80A return value of -1 indicates an error occurred and the locked 81status of all pages in the range remains unchanged. 82In this case, the global location 83.Va errno 84is set to indicate the error. 85.Sh ERRORS 86.Fn Mlock 87will fail if: 88.Bl -tag -width Er 89.It Bq Er EINVAL 90The address given is not page aligned or the length is negative. 91.It Bq Er EAGAIN 92Locking the indicated range would exceed either the system or per-process 93limit for locked memory. 94.It Bq Er ENOMEM 95Some portion of the indicated address range is not allocated. 96There was an error faulting/mapping a page. 97.El 98.Fn Munlock 99will fail if: 100.Bl -tag -width Er 101.It Bq Er EINVAL 102The address given is not page aligned or the length is negative. 103.It Bq Er ENOMEM 104Some portion of the indicated address range is not allocated. 105Some portion of the indicated address range is not locked. 106.El 107.Sh "SEE ALSO" 108.Xr fork 2 , 109.Xr mmap 2 , 110.Xr munmap 2 , 111.Xr setrlimit 2 , 112.Xr getpagesize 3 113.Sh BUGS 114Unlike The Sun implementation, multiple 115.Nm mlock 116calls on the same address range require the corresponding number of 117.Nm munlock 118calls to actually unlock the pages, i.e. 119.Nm mlock 120nests. 121This should be considered a consequence of the implementation 122and not a feature. 123.Pp 124The per-process resource limit is a limit on the amount of virtual 125memory locked, while the system-wide limit is for the number of locked 126physical pages. 127Hence a process with two distinct locked mappings of the same physical page 128counts as 2 pages against the per-process limit and as only a single page 129in the system limit. 130.Sh HISTORY 131The 132.Fn mlock 133and 134.Fn munlock 135functions first appeared in 4.4BSD. 136