| blob | 0f0ea207056f70c54e1ba4aa4357f082197b29aa |
1 .\" $NetBSD: mlock.2,v 1.20 2011/02/28 07:17:02 wiz 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. Neither the name of the University nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" SUCH DAMAGE.
29 .\"
30 .\" @(#)mlock.2 8.2 (Berkeley) 12/11/93
31 .\"
32 .Dd February 28, 2011
33 .Dt MLOCK 2
34 .Os
35 .Sh NAME
36 .Nm mlock ,
37 .Nm munlock
38 .Nd lock (unlock) physical pages in memory
39 .Sh LIBRARY
40 .Lb libc
41 .Sh SYNOPSIS
42 .In sys/mman.h
43 .Ft int
44 .Fn mlock "void *addr" "size_t len"
45 .Ft int
46 .Fn munlock "void *addr" "size_t len"
47 .Sh DESCRIPTION
48 The
49 .Nm mlock
50 system call
51 locks into memory the physical pages associated with the virtual address
52 range starting at
53 .Fa addr
54 for
55 .Fa len
56 bytes.
57 The
58 .Nm munlock
59 call unlocks pages previously locked by one or more
60 .Nm mlock
61 calls.
62 The entire range of memory must be allocated.
63 .Pp
64 After an
65 .Nm mlock
66 call, the indicated pages will cause neither a non-resident page
67 nor address-translation fault until they are unlocked.
68 They may still cause protection-violation faults or TLB-miss faults on
69 architectures with software-managed TLBs.
70 The physical pages remain in memory until all locked mappings for the pages
71 are removed.
72 Multiple processes may have the same physical pages locked via their own
73 virtual address mappings.
74 A single process may likewise have pages multiply-locked via different virtual
75 mappings of the same pages or via nested
76 .Nm mlock
77 calls on the same address range.
78 Unlocking is performed explicitly by
79 .Nm munlock
80 or implicitly by a call to
81 .Nm munmap
82 which deallocates the unmapped address range.
83 Locked mappings are not inherited by the child process after a
84 .Xr fork 2 .
85 .Pp
86 Since physical memory is a potentially scarce resource, processes are
87 limited in how much they can lock down.
88 A single process can
89 .Nm mlock
90 the minimum of
91 a system-wide ``wired pages'' limit and
92 the per-process
93 .Li RLIMIT_MEMLOCK
94 resource limit.
95 .Pp
96 Portable code should ensure that the
97 .Fa addr
98 and
99 .Fa len
100 parameters are aligned to a multiple of the page size, even though the
101 .Nx
102 implementation will round as necessary.
103 .Sh RETURN VALUES
104 A return value of 0 indicates that the call
105 succeeded and all pages in the range have either been locked or unlocked.
106 A return value of \-1 indicates an error occurred and the locked
107 status of all pages in the range remains unchanged.
108 In this case, the global location
109 .Va errno
110 is set to indicate the error.
111 .Sh ERRORS
112 .Fn mlock
113 will fail if:
114 .Bl -tag -width Er
115 .It Bq Er EAGAIN
116 Locking the indicated range would exceed either the system or per-process
117 limit for locked memory.
118 .It Bq Er EINVAL
119 The length is negative; or the address or length given is not page
120 aligned and the implementation does not round.
121 .It Bq Er ENOMEM
122 Some portion of the indicated address range is not allocated.
123 There was an error faulting/mapping a page.
124 .It Bq Er EPERM
125 .Fn mlock
126 was called by non-root on an architecture where locked page accounting
127 is not implemented.
128 .Pp
129 .El
130 .Fn munlock
131 will fail if:
132 .Bl -tag -width Er
133 .It Bq Er EINVAL
134 The length is negative; or the address or length given is not page
135 aligned and the implementation does not round.
136 .It Bq Er ENOMEM
137 Some portion of the indicated address range is not allocated.
138 Some portion of the indicated address range is not locked.
139 .El
140 .Sh SEE ALSO
141 .Xr fork 2 ,
142 .Xr mincore 2 ,
143 .Xr mmap 2 ,
144 .Xr munmap 2 ,
145 .Xr setrlimit 2 ,
146 .Xr getpagesize 3
147 .Sh STANDARDS
148 The
149 .Fn mlock
150 and
151 .Fn munlock
152 functions conform to
153 .St -p1003.1b-93 .
154 .Sh HISTORY
155 The
156 .Fn mlock
157 and
158 .Fn munlock
159 functions first appeared in
160 .Bx 4.4 .
161 .Sh BUGS
162 The per-process resource limit is a limit on the amount of virtual
163 memory locked, while the system-wide limit is for the number of locked
164 physical pages.
165 Hence a process with two distinct locked mappings of the same physical page
166 counts as 2 pages against the per-process limit and as only a single page
167 in the system limit.