1.\" 2.\" Copyright 2022 Oxide Computer Company 3.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. 4.\" Copyright 1989 AT&T 5.\" 6.\" The contents of this file are subject to the terms of the 7.\" Common Development and Distribution License (the "License"). 8.\" You may not use this file except in compliance with the License. 9.\" 10.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 11.\" or http://www.opensolaris.org/os/licensing. 12.\" See the License for the specific language governing permissions 13.\" and limitations under the License. 14.\" 15.\" When distributing Covered Code, include this CDDL HEADER in each 16.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. 17.\" If applicable, add the following below this CDDL HEADER, with the 18.\" fields enclosed by brackets "[]" replaced with your own identifying 19.\" information: Portions Copyright [yyyy] [name of copyright owner] 20.\" 21.Dd March 13, 2022 22.Dt MLOCK 3C 23.Os 24.Sh NAME 25.Nm mlock , 26.Nm munlock 27.Nd lock or unlock pages in memory 28.Sh SYNOPSIS 29.In sys/mman.h 30.Ft int 31.Fo mlock 32.Fa "const void *addr" 33.Fa "size_t len" 34.Fc 35.Ft int 36.Fo munlock 37.Fa "const void *addr" 38.Fa "size_t len" 39.Fc 40.Sh DESCRIPTION 41The 42.Fn mlock 43function uses the mappings established for the address range 44.Pf [ Fa addr , 45.Fa addr 46+ 47.Fa len Ns 48) to identify pages to be locked in memory. 49If the page identified by a mapping changes, such as occurs when a copy of a 50writable 51.Dv MAP_PRIVATE 52page is made upon the first store, the lock will be transferred to the newly 53copied private page. 54.Pp 55The 56.Fn munlock 57function removes locks established with 58.Fn mlock . 59.Pp 60A given page may be locked multiple times by executing an 61.Fn mlock 62through different mappings. 63That is, if two different processes lock the same page, then the page will 64remain locked until both processes remove their locks. 65However, within a given mapping, page locks do not nest \(em multiple 66.Fn mlock 67operations on the same address in the same process will all be removed with a 68single 69.Fn munlock . 70Of course, a page locked in one process and mapped in another 71.Pq or visible through a different mapping in the locking process 72is still locked in memory. 73This fact can be used to create applications that do nothing other than lock 74important data in memory, thereby avoiding page I/O faults on references from 75other processes in the system. 76.Pp 77The contents of the locked pages will not be transferred to or from disk except 78when explicitly requested by one of the locking processes. 79This guarantee applies only to the mapped data, and not to any associated data 80structures 81.Pq file descriptors and on-disk metadata, among others . 82.Pp 83If the mapping through which an 84.Fn mlock 85has been performed is removed, an 86.Fn munlock 87is implicitly performed. 88An 89.Fn munlock 90is also performed implicitly when a page is deleted through file removal or 91truncation. 92.Pp 93Locks established with 94.Fn mlock 95are not inherited by a child process after 96a 97.Xr fork 2 98and are not nested. 99.Pp 100Attempts to 101.Fn mlock 102more memory than a system-specific limit will fail. 103.Sh RETURN VALUES 104Upon successful completion, the 105.Fn mlock 106and 107.Fn munlock 108functions return 109.Sy 0 . 110Otherwise, no changes are made to any locks in the address space of the process, 111the functions return 112.Sy -1 113and set 114.Va errno 115to indicate the error. 116.Sh ERRORS 117The 118.Fn mlock 119and 120.Fn munlock 121functions will fail if: 122.Bl -tag -width Er 123.It Er EINVAL 124The 125.Fa addr 126argument is not a multiple of the page size as returned by 127.Xr sysconf 3C . 128.It Er ENOMEM 129Addresses in the range 130.Pf [ Fa addr , 131.Fa addr 132+ 133.Fa len Ns 134) are invalid for the address space of a process, or specify one or more pages 135which are not mapped. 136.It Er ENOSYS 137The system does not support this memory locking interface. 138.It Er EPERM 139The 140.Brq PRIV_PROC_LOCK_MEMORY 141privilege is not asserted in the effective set of the calling process. 142.El 143.Pp 144The 145.Fn mlock 146function will fail if: 147.Bl -tag -width Er 148.It Er EAGAIN 149.ad 150Some or all of the memory identified by the range 151.Pf [ Fa addr , 152.Fa addr 153+ 154.Fa len Ns 155) could not be locked because of insufficient system resources or because of a 156limit or resource control on locked memory. 157.El 158.Sh USAGE 159Because of the impact on system resources, the use of 160.Fn mlock 161and 162.Fn munlock 163is restricted to users with the 164.Brq PRIV_PROC_LOCK_MEMORY 165privilege. 166.Sh INTERFACE STABILITY 167.Sy Committed 168.Sh MT-LEVEL 169.Sy MT-Safe 170.Sh SEE ALSO 171.Xr fork 2 , 172.Xr memcntl 2 , 173.Xr mmap 2 , 174.Xr mlockall 3C , 175.Xr plock 3C , 176.Xr sysconf 3C , 177.Xr attributes 7 , 178.Xr standards 7 179