1.\" $OpenBSD: mlockall.2,v 1.5 2008/06/26 05:42:05 ray Exp $ 2.\" $NetBSD: mlockall.2,v 1.6 2000/06/26 17:00:02 kleink Exp $ 3.\" 4.\" Copyright (c) 1999 The NetBSD Foundation, Inc. 5.\" All rights reserved. 6.\" 7.\" This code is derived from software contributed to The NetBSD Foundation 8.\" by Jason R. Thorpe of the Numerical Aerospace Simulation Facility, 9.\" NASA Ames Research Center. 10.\" 11.\" Redistribution and use in source and binary forms, with or without 12.\" modification, are permitted provided that the following conditions 13.\" are met: 14.\" 1. Redistributions of source code must retain the above copyright 15.\" notice, this list of conditions and the following disclaimer. 16.\" 2. Redistributions in binary form must reproduce the above copyright 17.\" notice, this list of conditions and the following disclaimer in the 18.\" documentation and/or other materials provided with the distribution. 19.\" 3. All advertising materials mentioning features or use of this software 20.\" must display the following acknowledgement: 21.\" This product includes software developed by the NetBSD 22.\" Foundation, Inc. and its contributors. 23.\" 4. Neither the name of The NetBSD Foundation nor the names of its 24.\" contributors may be used to endorse or promote products derived 25.\" from this software without specific prior written permission. 26.\" 27.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 28.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 29.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 30.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 31.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 32.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 33.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 34.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 35.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 36.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 37.\" POSSIBILITY OF SUCH DAMAGE. 38.\" 39.Dd May 16, 2022 40.Dt MLOCKALL 2 41.Os 42.Sh NAME 43.Nm mlockall , 44.Nm munlockall 45.Nd lock (unlock) the address space of a process 46.Sh LIBRARY 47.Lb libc 48.Sh SYNOPSIS 49.In sys/types.h 50.In sys/mman.h 51.Ft int 52.Fn mlockall "int flags" 53.Ft int 54.Fn munlockall "void" 55.Sh DESCRIPTION 56The 57.Fn mlockall 58system call locks into memory the physical pages associated with the 59address space of a process until the address space is unlocked, the 60process exits, fork()s, or execs another program image. Any pages which 61are copy-on-write at the time of the function call will be force faulted. 62Locked pages will not be paged to swap backing store. 63.Pp 64The following flags affect the behavior of 65.Fn mlockall : 66.Bl -tag -width ".Dv MCL_CURRENT" 67.It Dv MCL_CURRENT 68Lock all pages currently mapped into the process's address space. 69.It Dv MCL_FUTURE 70Lock all pages mapped into the process's address space in the future, 71at the time the mapping is established. 72Note that this may cause future mappings to fail if those mappings 73cause resource limits to be exceeded. 74.El 75.Pp 76Since physical memory is a potentially scarce resource, processes are 77limited in how much they can lock down. 78A single process can lock the minimum of a system-wide 79.Dq wired pages 80limit and the per-process 81.Dv RLIMIT_MEMLOCK 82resource limit. 83.Pp 84.Fn mlockall 85has two limitations, necessary to keep it functional on modern systems. 86The first is that writable file-backed MAP_PRIVATE pages (such as shared 87library mappings) which have not yet been write-faulted will retain their 88read-only mapping to the file backing store and not be force-copied. 89If we were to force copy these pages, it would cause immense unnecessary 90overheads for the program. 91So any unmodified but writable pages which are currently in 92the pmap read-only will still take a COW fault if written to. 93.Pp 94The second limitation is that when a fork() is issued, all writable pages 95will be made copy-on-write (COW) in both the parent and the child. The child 96of course does not inherit the locked memory state, but this action will 97cause any locked pages in the parent to become copy-on-write and they will 98be faulted if written to. So they will not be quite as locked as might have 99been intended in this situation. 100.Pp 101The 102.Fn munlockall 103call unlocks any locked memory regions in the process address space. 104Any regions mapped after an 105.Fn munlockall 106call will not be locked. 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 mlockall 117will fail if: 118.Bl -tag -width Er 119.It Bq Er EINVAL 120The 121.Fa flags 122argument is zero, or includes unimplemented flags. 123.It Bq Er ENOMEM 124Locking the indicated range would exceed either the system or per-process 125limit for locked memory. 126.It Bq Er EPERM 127The calling process does not have the appropriate privilege to perform 128the requested operation. 129.El 130.Sh SEE ALSO 131.Xr mincore 2 , 132.Xr mlock 2 , 133.Xr setrlimit 2 134.Sh STANDARDS 135The 136.Fn mlockall 137and 138.Fn munlockall 139functions are believed to conform to 140.St -p1003.1-2001 . 141.Sh HISTORY 142The 143.Fn mlockall 144and 145.Fn munlockall 146functions first appeared in 147.Dx 2.9 . 148.Sh BUGS 149How could there be any bugs? This is soooo simple... 150.Pp 151These system calls are not recommended for general use. They are obviously 152not thread-safe, and the larger application context from which they are 153called might be hostile to such actions due to non-deterministic resource 154limits in the system. In a modern system, even semi-realtime and interactive 155processes are already detected and handled by the system schedule. 156Please use 157.Fn mlock 158and 159.Fn munlock 160to lock specific address ranges instead of locking the entire address space. 161