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 MEMCNTL 2 23.Os 24.Sh NAME 25.Nm memcntl 26.Nd memory management control 27.Sh SYNOPSIS 28.In sys/types.h 29.In sys/mman.h 30.Ft int 31.Fo memcntl 32.Fa "void *addr" 33.Fa "size_t len" 34.Fa "int cmd" 35.Fa "void *arg" 36.Fa "int attr" 37.Fa "int mask" 38.Fc 39.Sh DESCRIPTION 40The 41.Fn memcntl 42function allows the calling process to apply a variety of control operations 43over the address space identified by the mappings established for the address 44range [ 45.Fa addr , 46.Fa addr 47+ 48.Fa len 49). 50.Pp 51The 52.Fa addr 53argument must be a multiple of the pagesize as returned by 54.Xr sysconf 3C . 55The scope of the control operations can be further defined with additional 56selection criteria 57.Pq in the form of attributes 58according to the bit pattern contained in 59.Fa attr . 60.Pp 61The following attributes specify page mapping selection criteria: 62.Bl -tag -width Ds -offset indent 63.It Dv MEMCNTL_SHARED 64Page is mapped shared. 65.It Dv MEMCNTL_PRIVATE 66Page is mapped private. 67.El 68.Pp 69The following attributes specify page protection selection criteria. 70The selection criteria are constructed by a bitwise OR operation on the 71attribute bits and must match exactly. 72.Bl -tag -width Ds -offset indent 73.It Dv PROT_READ 74Page can be read. 75.It Dv PROT_WRITE 76Page can be written. 77.It Dv PROT_EXEC 78Page can be executed. 79.El 80.Pp 81The following criteria may also be specified: 82.Bl -tag -width Ds -offset indent 83.It Dv PROC_TEXT 84Process text. 85.It Dv PROC_DATA 86Process data. 87.El 88.Pp 89The 90.Dv PROC_TEXT 91attribute specifies all privately mapped segments with read and execute 92permission, and the 93.Dv PROC_DATA 94attribute specifies all privately mapped segments with write permission. 95.Pp 96Selection criteria can be used to describe various abstract memory objects 97within the address space on which to operate. 98If an operation shall not be constrained by the selection criteria, 99.Fa attr 100must have the value 101.Sy 0 . 102.Pp 103The operation to be performed is identified by the argument 104.Fa cmd . 105The symbolic names for the operations are defined in 106.In sys/mman.h 107as follows: 108.Bl -tag -width Ds -offset indent 109.It Dv MC_LOCK 110Lock in memory all pages in the range with attributes 111.Fa attr . 112A given page may be locked multiple times through different mappings; however, 113within a given mapping, page locks do not nest. 114Multiple lock operations on the same address in the same process will all be 115removed with a single unlock operation. 116A page locked in one process and mapped in another 117.Pq or visible through a different mapping in the locking process 118is locked in memory as long as the locking process does neither an implicit nor 119explicit unlock operation. 120If a locked mapping is removed, or a page is deleted through file removal or 121truncation, an unlock operation is implicitly performed. 122If a writable 123.Dv MAP_PRIVATE 124page in the address range is changed, the lock will be transferred to the 125private page. 126.Pp 127The 128.Fa arg 129argument is not used, but must be 130.Dv NULL 131to ensure compatibility with potential future enhancements. 132.It Dv MC_LOCKAS 133Lock in memory all pages mapped by the address space with attributes 134.Fa attr . 135The 136.Fa addr 137and 138.Fa len 139arguments are not used, but must be 140.Dv NULL 141and 142.Sy 0 143respectively, to ensure compatibility with potential future enhancements. 144The 145.Fa arg 146argument is a bit pattern built from the flags: 147.Bl -tag -width Ds 148.It Dv MCL_CURRENT 149Lock current mappings. 150.It Dv MCL_FUTURE 151Lock future mappings. 152.El 153.Pp 154The value of 155.Fa arg 156determines whether the pages to be locked are those currently mapped by the 157address space, those that will be mapped in the future, or both. 158If 159.Dv MCL_FUTURE 160is specified, then all mappings subsequently added to the address space will be 161locked, provided sufficient memory is available. 162.It Dv MC_SYNC 163Write to their backing storage locations all modified pages in the range with 164attributes 165.Fa attr . 166Optionally, invalidate cache copies. 167The backing storage for a modified 168.Dv MAP_SHARED 169mapping is the file the page is mapped to; the backing storage for a modified 170.Dv MAP_PRIVATE 171mapping is its swap area. 172The 173.Fa arg 174argument is a bit pattern built from the flags used to control the behavior of 175the operation: 176.Bl -tag -width Ds 177.It Dv MS_ASYNC 178Perform asynchronous writes. 179The function returns immediately once all write operations are scheduled 180.Po unless 181.Dv MS_SYNC 182is also specified 183.Pc . 184.It Dv MS_SYNC 185Perform synchronous writes. 186The function will not return until all write operations are completed. 187.It Dv MS_INVALIDATE 188Invalidate all cached copies of data in memory, so that further references to 189the pages will be obtained by the system from their backing storage locations. 190This operation should be used by applications that require a memory object to be 191in a known state. 192.El 193.It Dv MC_UNLOCK 194Unlock all pages in the range with attributes 195.Fa attr . 196The 197.Fa arg 198argument is not used, but must be 199.Dv NULL 200to ensure compatibility with potential future enhancements. 201.It Dv MC_UNLOCKAS 202Remove address space memory locks and locks on all pages in the address space 203with attributes 204.Fa attr . 205The 206.Fa addr , 207.Fa len , 208and 209.Fa arg 210arguments are not used, but must be 211.Dv NULL , 2120, and 213.Dv NULL , 214respectively, to ensure compatibility with potential future enhancements. 215.It Dv MC_HAT_ADVISE 216Advise system how a region of user-mapped memory will be accessed. 217The 218.Fa arg 219argument is interpreted as a 220.Dq Vt struct memcntl_mha * . 221The following members are defined in a 222.Vt struct memcntl_mha : 223.Bd -literal -offset indent 224uint_t mha_cmd; 225uint_t mha_flags; 226size_t mha_pagesize; 227.Ed 228.Pp 229The accepted values for 230.Vt mha_cmd 231are: 232.Bd -literal -offset indent 233MHA_MAPSIZE_VA 234MHA_MAPSIZE_STACK 235MHA_MAPSIZE_BSSBRK 236.Ed 237.Pp 238The 239.Fa mha_flags 240member is reserved for future use and must always be set to 0. 241The 242.Fa mha_pagesize 243member must be a valid size as obtained from 244.Xr getpagesizes 3C 245or the constant value 0 to allow the system to choose an appropriate hardware 246address translation mapping size. 247.Pp 248.Dv MHA_MAPSIZE_VA 249sets the preferred hardware address translation mapping size of the region of 250memory from 251.Fa addr 252to 253.Fa addr 254+ 255.Fa len . 256Both 257.Fa addr 258and 259.Fa len 260must be aligned to an 261.Fa mha_pagesize 262boundary. 263The entire virtual address region from 264.Fa addr 265to 266.Fa addr 267+ 268.Fa len 269must not have any holes. 270Permissions within each 271.Fa mha_pagesize Ns -aligned 272portion of the region must be consistent. 273When a size of 0 is specified, the system selects an appropriate size based on 274the size and alignment of the memory region, type of processor, and other 275considerations. 276.Pp 277.Dv MHA_MAPSIZE_STACK 278sets the preferred hardware address translation mapping size of the process main 279thread stack segment. 280The 281.Fa addr 282and 283.Fa len 284arguments must be 285.Dv NULL 286and 0, respectively. 287.Pp 288.Dv MHA_MAPSIZE_BSSBRK 289sets the preferred hardware address translation mapping size of the process 290heap. 291The 292.Fa addr 293and 294.Fa len 295arguments must be 296.Dv NULL 297and 0, respectively. 298See the NOTES section of the 299.Xr ppgsz 1 300manual page for additional information on process heap alignment. 301.Pp 302The 303.Fa attr 304argument must be 0 for all 305.Dv MC_HAT_ADVISE 306operations. 307.El 308.Pp 309The 310.Fa mask 311argument must be 0; it is reserved for future use. 312.Pp 313Locks established with the lock operations are not inherited by a child process 314after 315.Xr fork 2 . 316The 317.Fn memcntl 318function fails if it attempts to lock more memory than a system-specific limit. 319.Pp 320Due to the potential impact on system resources, the operations 321.Dv MC_LOCKAS , 322.Dv MC_LOCK , 323.Dv MC_UNLOCKAS , 324and 325.Dv MC_UNLOCK 326are restricted to privileged processes. 327.Sh USAGE 328The 329.Fn memcntl 330function subsumes the operations of 331.Xr plock 3C . 332.Pp 333.Dv MC_HAT_ADVISE 334is intended to improve performance of applications that use large amounts of 335memory on processors that support multiple hardware address translation mapping 336sizes; however, it should be used with care. 337Not all processors support all sizes with equal efficiency. 338Use of larger sizes may also introduce extra overhead that could reduce 339performance or available memory. 340Using large sizes for one application may reduce available resources for other 341applications and result in slower system wide performance. 342.Sh RETURN VALUES 343Upon successful completion, 344.Fn memcntl 345returns 346.Sy 0 . 347Otherwise, it returns 348.Sy -1 349and sets 350.Va errno 351to indicate an error. 352.Sh ERRORS 353The 354.Fn memcntl 355function will fail if: 356.Bl -tag -width Er 357.It Er EAGAIN 358When the selection criteria match, some or all of the memory identified by the 359operation could not be locked when 360.Dv MC_LOCK 361or 362.Dv MC_LOCKAS 363was specified, some or all mappings in the address range 364.Pf [ Fa addr , 365.Fa addr 366+ 367.Fa len Ns 368) are locked for I/O when 369.Dv MC_HAT_ADVISE 370was specified, or the system has insufficient resources when 371.Dv MC_HAT_ADVISE 372was specified. 373.Pp 374The 375.Fa cmd 376is 377.Dv MC_LOCK 378or 379.Dv MC_LOCKAS 380and locking the memory identified by this operation would exceed a limit or 381resource control on locked memory. 382.It Er EBUSY 383When the selection criteria match, some or all of the addresses in the range 384.Pf [ Fa addr , 385.Fa addr 386+ 387.Fa len Ns 388) are locked and 389.Dv MC_SYNC with the 390.Dv MS_INVALIDATE 391option was specified. 392.It Er EINVAL 393The 394.Fa addr 395argument specifies invalid selection criteria or is not a multiple of the page 396size as returned by 397.Xr sysconf 3C ; 398the 399.Fa addr 400and/or 401.Fa len 402argument does not have the value 0 when 403.Dv MC_LOCKAS 404or 405.Dv MC_UNLOCKAS 406is specified; the 407.Fa arg 408argument is not valid for the function specified; 409.Fa mha_pagesize 410or 411.Fa mha_cmd 412is invalid; or 413.Dv MC_HAT_ADVISE 414is specified and not all pages in the specified region have the same access 415permissions within the given size boundaries. 416.It Er ENOMEM 417When the selection criteria match, some or all of the addresses in the range 418.Pf [ Fa addr , 419.Fa addr 420+ 421.Fa len Ns 422) are invalid for the address space of a process or specify one or more pages 423which are not mapped. 424.It Er EPERM 425The 426.Brq Dv PRIV_PROC_LOCK_MEMORY 427privilege is not asserted in the effective set of the calling process and 428.Dv MC_LOCK , 429.Dv MC_LOCKAS , 430.Dv MC_UNLOCK , 431or 432.Dv MC_UNLOCKAS 433was specified. 434.El 435.Sh MT-LEVEL 436.Sy MT-Safe 437.Sh SEE ALSO 438.Xr ppgsz 1 , 439.Xr fork 2 , 440.Xr mmap 2 , 441.Xr mprotect 2 , 442.Xr getpagesizes 3C , 443.Xr mlock 3C , 444.Xr mlockall 3C , 445.Xr msync 3C , 446.Xr plock 3C , 447.Xr sysconf 3C , 448.Xr attributes 7 , 449.Xr privileges 7 450