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