[apple/xnu.git] / bsd / man / man2 / mlock.2

.\"	$NetBSD: mlock.2,v 1.3 1995/06/24 10:42:03 cgd Exp $
.\"
.\" Copyright (c) 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"	@(#)mlock.2	8.2 (Berkeley) 12/11/93
.\"
.Dd June 2, 1993
.Dt MLOCK 2
.Os
.Sh NAME
.Nm mlock ,
.Nm munlock
.Nd lock (unlock) physical pages in memory
.Sh SYNOPSIS
.Fd #include <sys/mman.h>
.Ft int
.Fo mlock
.Fa "const void *addr"
.Fa "size_t len"
.Fc
.Ft int
.Fo munlock
.Fa "const void *addr"
.Fa "size_t len"
.Fc
.Sh DESCRIPTION
The
.Nm mlock
system call
locks a set of physical pages into memory.
The pages are associated with a virtual address range
that starts at
.Fa addr
and extends for
.Fa len
bytes.
The
.Nm munlock
call unlocks pages that were previously locked by one or more
.Nm mlock
calls.
For both calls, the
.Fa addr
parameter should be aligned to a multiple of the page size.
If the
.Fa len
parameter is not a multiple of the page size,
it will be rounded up to be so.
The entire range must be allocated.
.Pp
After an
.Nm mlock
call, the indicated pages will cause neither a non-resident page
nor address-translation fault until they are unlocked.
They may still cause protection-violation faults or TLB-miss faults
on architectures with software-managed TLBs.
The physical pages remain in memory until all locked mappings
for the pages are removed.
.Pp
Multiple processes may have the same physical pages locked
via their own virtual address mappings.
Similarly, a single process may have pages multiply-locked
via different virtual mappings of the same pages or via nested
.Nm mlock
calls on the same address range.
Unlocking is performed explicitly by
.Nm munlock
or implicitly by a call to
.Nm munmap ,
which deallocates the unmapped address range.
Locked mappings are not inherited by the child process after a
.Xr fork 2 .
.Pp
Because physical memory is a potentially scarce resource,
processes are limited in how much memory they can lock down.
A single process can
.Nm mlock
the minimum of
a system-wide ``wired pages'' limit and
the per-process
.Li RLIMIT_MEMLOCK
resource limit.
.Sh RETURN VALUES
A return value of 0 indicates that the call succeeded
and all pages in the range have either been locked or unlocked,
as requested.
A return value of -1 indicates an error occurred
and the locked status of all pages in the range remains unchanged.
In this case, the global location
.Va errno
is set to indicate the error.
.Sh ERRORS
.Fn Mlock
and 
.Fn munlock
will fail if:
.Bl -tag -width Er
.\" ===========
.It Bq Er EINVAL
The address given is not page-aligned or the length is negative.
.\" ===========
.It Bq Er ENOMEM
Part or all of the specified address range
is not mapped to the process.
.El
.Pp
.Fn Mlock
will fail if:
.Bl -tag -width Er
.\" ===========
.It Bq Er EAGAIN
Locking the indicated range would exceed either the system or per-process
limit for locked memory.
.\" ===========
.It Bq Er ENOMEM
Some portion of the indicated address range is not allocated.
There was an error faulting/mapping a page.
.El
.Pp
.Fn Munlock
will fail if:
.Bl -tag -width Er
.\" ===========
.It Bq Er ENOMEM
Some portion of the indicated address range is not allocated.
Some portion of the indicated address range is not locked.
.El
.Sh LEGACY SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/mman.h>
.Pp
The include file
.In sys/types.h
is necessary.
.Pp
.Ft int
.br
.Fo mlock
.Fa "caddr_t addr"
.Fa "size_t len"
.Fc ;
.Pp
.Ft int
.br
.Fo munlock
.Fa "caddr_t addr"
.Fa "size_t len"
.Fc ;
.Pp
The variable type of
.Fa addr
has changed.
.Sh "SEE ALSO"
.Xr fork 2 ,
.Xr mincore 2 ,
.Xr minherit 2 ,
.Xr mmap 2 ,
.Xr munmap 2 ,
.Xr setrlimit 2 ,
.Xr getpagesize 3 ,
.Xr compat 5
.Sh BUGS
Unlike The Sun implementation, multiple
.Nm mlock
calls on the same address range require the corresponding number of
.Nm munlock
calls to actually unlock the pages, i.e.
.Nm mlock
nests.
This should be considered a consequence of the implementation
and not a feature.
.Pp
The per-process resource limit is a limit on the amount of virtual
memory locked, while the system-wide limit is for the number of locked
physical pages.
Hence a process with two distinct locked mappings of the same physical page
counts as 2 pages against the per-process limit and as only a single page
in the system limit.
.Sh HISTORY
The
.Fn mlock
and
.Fn munlock
functions first appeared in 4.4BSD.
Commit	Line	Data
9bccf70c A	1	.\" $NetBSD: mlock.2,v 1.3 1995/06/24 10:42:03 cgd Exp $
	2	.\"
	3	.\" Copyright (c) 1993
	4	.\" The Regents of the University of California. All rights reserved.
	5	.\"
	6	.\" Redistribution and use in source and binary forms, with or without
	7	.\" modification, are permitted provided that the following conditions
	8	.\" are met:
	9	.\" 1. Redistributions of source code must retain the above copyright
	10	.\" notice, this list of conditions and the following disclaimer.
	11	.\" 2. Redistributions in binary form must reproduce the above copyright
	12	.\" notice, this list of conditions and the following disclaimer in the
	13	.\" documentation and/or other materials provided with the distribution.
	14	.\" 3. All advertising materials mentioning features or use of this software
	15	.\" must display the following acknowledgement:
	16	.\" This product includes software developed by the University of
	17	.\" California, Berkeley and its contributors.
	18	.\" 4. Neither the name of the University nor the names of its contributors
	19	.\" may be used to endorse or promote products derived from this software
	20	.\" without specific prior written permission.
	21	.\"
	22	.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
	23	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	24	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	25	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
	26	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	27	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	28	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	29	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	30	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	31	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	32	.\" SUCH DAMAGE.
	33	.\"
	34	.\" @(#)mlock.2 8.2 (Berkeley) 12/11/93
	35	.\"
	36	.Dd June 2, 1993
	37	.Dt MLOCK 2
	38	.Os
	39	.Sh NAME
	40	.Nm mlock ,
	41	.Nm munlock
	42	.Nd lock (unlock) physical pages in memory
	43	.Sh SYNOPSIS
9bccf70c A	44	.Fd #include <sys/mman.h>
9bccf70c A	45	.Ft int
2d21ac55 A	46	.Fo mlock
	47	.Fa "const void *addr"
	48	.Fa "size_t len"
	49	.Fc
9bccf70c	50	.Ft int
2d21ac55 A	51	.Fo munlock
	52	.Fa "const void *addr"
	53	.Fa "size_t len"
	54	.Fc
9bccf70c A	55	.Sh DESCRIPTION
	56	The
	57	.Nm mlock
	58	system call
2d21ac55 A	59	locks a set of physical pages into memory.
	60	The pages are associated with a virtual address range
	61	that starts at
9bccf70c	62	.Fa addr
2d21ac55	63	and extends for
9bccf70c A	64	.Fa len
	65	bytes.
	66	The
	67	.Nm munlock
2d21ac55	68	call unlocks pages that were previously locked by one or more
9bccf70c A	69	.Nm mlock
9bccf70c A	70	calls.
2d21ac55	71	For both calls, the
9bccf70c A	72	.Fa addr
	73	parameter should be aligned to a multiple of the page size.
	74	If the
	75	.Fa len
2d21ac55 A	76	parameter is not a multiple of the page size,
2d21ac55 A	77	it will be rounded up to be so.
9bccf70c A	78	The entire range must be allocated.
	79	.Pp
	80	After an
	81	.Nm mlock
	82	call, the indicated pages will cause neither a non-resident page
	83	nor address-translation fault until they are unlocked.
2d21ac55 A	84	They may still cause protection-violation faults or TLB-miss faults
	85	on architectures with software-managed TLBs.
	86	The physical pages remain in memory until all locked mappings
	87	for the pages are removed.
	88	.Pp
	89	Multiple processes may have the same physical pages locked
	90	via their own virtual address mappings.
	91	Similarly, a single process may have pages multiply-locked
	92	via different virtual mappings of the same pages or via nested
9bccf70c A	93	.Nm mlock
	94	calls on the same address range.
	95	Unlocking is performed explicitly by
	96	.Nm munlock
	97	or implicitly by a call to
2d21ac55	98	.Nm munmap ,
9bccf70c A	99	which deallocates the unmapped address range.
	100	Locked mappings are not inherited by the child process after a
	101	.Xr fork 2 .
	102	.Pp
2d21ac55 A	103	Because physical memory is a potentially scarce resource,
2d21ac55 A	104	processes are limited in how much memory they can lock down.
9bccf70c A	105	A single process can
	106	.Nm mlock
	107	the minimum of
	108	a system-wide ``wired pages'' limit and
	109	the per-process
	110	.Li RLIMIT_MEMLOCK
	111	resource limit.
	112	.Sh RETURN VALUES
2d21ac55 A	113	A return value of 0 indicates that the call succeeded
	114	and all pages in the range have either been locked or unlocked,
	115	as requested.
	116	A return value of -1 indicates an error occurred
	117	and the locked status of all pages in the range remains unchanged.
9bccf70c A	118	In this case, the global location
	119	.Va errno
	120	is set to indicate the error.
	121	.Sh ERRORS
	122	.Fn Mlock
2d21ac55 A	123	and
2d21ac55 A	124	.Fn munlock
9bccf70c A	125	will fail if:
9bccf70c A	126	.Bl -tag -width Er
2d21ac55	127	.\" ===========
9bccf70c	128	.It Bq Er EINVAL
2d21ac55 A	129	The address given is not page-aligned or the length is negative.
	130	.\" ===========
	131	.It Bq Er ENOMEM
	132	Part or all of the specified address range
	133	is not mapped to the process.
	134	.El
	135	.Pp
	136	.Fn Mlock
	137	will fail if:
	138	.Bl -tag -width Er
	139	.\" ===========
9bccf70c A	140	.It Bq Er EAGAIN
	141	Locking the indicated range would exceed either the system or per-process
	142	limit for locked memory.
2d21ac55	143	.\" ===========
9bccf70c A	144	.It Bq Er ENOMEM
	145	Some portion of the indicated address range is not allocated.
	146	There was an error faulting/mapping a page.
	147	.El
2d21ac55	148	.Pp
9bccf70c A	149	.Fn Munlock
	150	will fail if:
	151	.Bl -tag -width Er
2d21ac55	152	.\" ===========
9bccf70c A	153	.It Bq Er ENOMEM
	154	Some portion of the indicated address range is not allocated.
	155	Some portion of the indicated address range is not locked.
	156	.El
2d21ac55 A	157	.Sh LEGACY SYNOPSIS
	158	.Fd #include <sys/types.h>
	159	.Fd #include <sys/mman.h>
	160	.Pp
	161	The include file
	162	.In sys/types.h
	163	is necessary.
	164	.Pp
	165	.Ft int
	166	.br
	167	.Fo mlock
	168	.Fa "caddr_t addr"
	169	.Fa "size_t len"
	170	.Fc ;
	171	.Pp
	172	.Ft int
	173	.br
	174	.Fo munlock
	175	.Fa "caddr_t addr"
	176	.Fa "size_t len"
	177	.Fc ;
	178	.Pp
	179	The variable type of
	180	.Fa addr
	181	has changed.
9bccf70c A	182	.Sh "SEE ALSO"
	183	.Xr fork 2 ,
	184	.Xr mincore 2 ,
	185	.Xr minherit 2 ,
	186	.Xr mmap 2 ,
	187	.Xr munmap 2 ,
	188	.Xr setrlimit 2 ,
2d21ac55 A	189	.Xr getpagesize 3 ,
2d21ac55 A	190	.Xr compat 5
9bccf70c A	191	.Sh BUGS
	192	Unlike The Sun implementation, multiple
	193	.Nm mlock
	194	calls on the same address range require the corresponding number of
	195	.Nm munlock
	196	calls to actually unlock the pages, i.e.
	197	.Nm mlock
	198	nests.
	199	This should be considered a consequence of the implementation
	200	and not a feature.
	201	.Pp
	202	The per-process resource limit is a limit on the amount of virtual
	203	memory locked, while the system-wide limit is for the number of locked
	204	physical pages.
	205	Hence a process with two distinct locked mappings of the same physical page
	206	counts as 2 pages against the per-process limit and as only a single page
	207	in the system limit.
	208	.Sh HISTORY
	209	The
	210	.Fn mlock
	211	and
	212	.Fn munlock
	213	functions first appeared in 4.4BSD.