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