[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/types.h>
.Fd #include <sys/mman.h>
.Ft int
.Fn mlock "caddr_t addr" "size_t len"
.Ft int
.Fn munlock "caddr_t addr" "size_t len"
.Sh DESCRIPTION
The
.Nm mlock
system call
locks into memory the physical pages associated with the virtual address
range starting at
.Fa addr
for
.Fa len
bytes.
The
.Nm munlock
call unlocks pages previously locked by one or more
.Nm mlock
calls.
For both, 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.
Multiple processes may have the same physical pages locked via their own
virtual address mappings.
A single process may likewise 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
Since physical memory is a potentially scarce resource, processes are
limited in how much 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.
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
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 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
.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
Some portion of the indicated address range is not allocated.
Some portion of the indicated address range is not locked.
.El
.Sh "SEE ALSO"
.Xr fork 2 ,
.Xr mincore 2 ,
.Xr minherit 2 ,
.Xr mmap 2 ,
.Xr munmap 2 ,
.Xr setrlimit 2 ,
.Xr getpagesize 3
.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
	44	.Fd #include <sys/types.h>
	45	.Fd #include <sys/mman.h>
	46	.Ft int
	47	.Fn mlock "caddr_t addr" "size_t len"
	48	.Ft int
	49	.Fn munlock "caddr_t addr" "size_t len"
	50	.Sh DESCRIPTION
	51	The
	52	.Nm mlock
	53	system call
	54	locks into memory the physical pages associated with the virtual address
	55	range starting at
	56	.Fa addr
	57	for
	58	.Fa len
	59	bytes.
	60	The
	61	.Nm munlock
	62	call unlocks pages previously locked by one or more
	63	.Nm mlock
	64	calls.
65	For both, the
66	.Fa addr
67	parameter should be aligned to a multiple of the page size.
68	If the
69	.Fa len
70	parameter is not a multiple of the page size, it will be rounded up
71	to be so.
72	The entire range must be allocated.
73	.Pp
74	After an
75	.Nm mlock
76	call, the indicated pages will cause neither a non-resident page
77	nor address-translation fault until they are unlocked.
78	They may still cause protection-violation faults or TLB-miss faults on
79	architectures with software-managed TLBs.
80	The physical pages remain in memory until all locked mappings for the pages
81	are removed.
82	Multiple processes may have the same physical pages locked via their own
83	virtual address mappings.
84	A single process may likewise have pages multiply-locked via different virtual
85	mappings of the same pages or via nested
86	.Nm mlock
87	calls on the same address range.
88	Unlocking is performed explicitly by
89	.Nm munlock
90	or implicitly by a call to
91	.Nm munmap
92	which deallocates the unmapped address range.
93	Locked mappings are not inherited by the child process after a
94	.Xr fork 2 .
95	.Pp
96	Since physical memory is a potentially scarce resource, processes are
97	limited in how much they can lock down.
98	A single process can
99	.Nm mlock
100	the minimum of
101	a system-wide ``wired pages'' limit and
102	the per-process
103	.Li RLIMIT_MEMLOCK
104	resource limit.
105	.Sh RETURN VALUES
106	A return value of 0 indicates that the call
107	succeeded and all pages in the range have either been locked or unlocked.
108	A return value of -1 indicates an error occurred and the locked
109	status of all pages in the range remains unchanged.
110	In this case, the global location
111	.Va errno
112	is set to indicate the error.
113	.Sh ERRORS
114	.Fn Mlock
115	will fail if:
116	.Bl -tag -width Er
117	.It Bq Er EINVAL
118	The address given is not page aligned or the length is negative.
119	.It Bq Er EAGAIN
120	Locking the indicated range would exceed either the system or per-process
121	limit for locked memory.
122	.It Bq Er ENOMEM
123	Some portion of the indicated address range is not allocated.
124	There was an error faulting/mapping a page.
125	.El
126	.Fn Munlock
127	will fail if:
128	.Bl -tag -width Er
129	.It Bq Er EINVAL
130	The address given is not page aligned or the length is negative.
131	.It Bq Er ENOMEM
132	Some portion of the indicated address range is not allocated.
133	Some portion of the indicated address range is not locked.
134	.El
135	.Sh "SEE ALSO"
136	.Xr fork 2 ,
137	.Xr mincore 2 ,
138	.Xr minherit 2 ,
139	.Xr mmap 2 ,
140	.Xr munmap 2 ,
141	.Xr setrlimit 2 ,
142	.Xr getpagesize 3
143	.Sh BUGS
144	Unlike The Sun implementation, multiple
145	.Nm mlock
146	calls on the same address range require the corresponding number of
147	.Nm munlock
148	calls to actually unlock the pages, i.e.
149	.Nm mlock
150	nests.
151	This should be considered a consequence of the implementation
152	and not a feature.
153	.Pp
154	The per-process resource limit is a limit on the amount of virtual
155	memory locked, while the system-wide limit is for the number of locked
156	physical pages.
157	Hence a process with two distinct locked mappings of the same physical page
158	counts as 2 pages against the per-process limit and as only a single page
159	in the system limit.
160	.Sh HISTORY
161	The
162	.Fn mlock
163	and
164	.Fn munlock
165	functions first appeared in 4.4BSD.