Commit | Line | Data |
---|---|---|
ad787160 C |
1 | .\" Copyright (c) 1993 |
2 | .\" The Regents of the University of California. All rights reserved. | |
17bc1c47 | 3 | .\" |
ad787160 C |
4 | .\" Redistribution and use in source and binary forms, with or without |
5 | .\" modification, are permitted provided that the following conditions | |
6 | .\" are met: | |
7 | .\" 1. Redistributions of source code must retain the above copyright | |
8 | .\" notice, this list of conditions and the following disclaimer. | |
9 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
10 | .\" notice, this list of conditions and the following disclaimer in the | |
11 | .\" documentation and/or other materials provided with the distribution. | |
12 | .\" 3. All advertising materials mentioning features or use of this software | |
13 | .\" must display the following acknowledgement: | |
14 | .\" This product includes software developed by the University of | |
15 | .\" California, Berkeley and its contributors. | |
16 | .\" 4. Neither the name of the University nor the names of its contributors | |
17 | .\" may be used to endorse or promote products derived from this software | |
18 | .\" without specific prior written permission. | |
17bc1c47 | 19 | .\" |
ad787160 C |
20 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND |
21 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
22 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
23 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
24 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
25 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
26 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
27 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
28 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
29 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
30 | .\" SUCH DAMAGE. | |
31 | .\" | |
ed554bc5 | 32 | .\" @(#)mlock.2 8.2 (Berkeley) 12/11/93 |
17bc1c47 MH |
33 | .\" |
34 | .Dd June 2, 1993 | |
35 | .Dt MLOCK 2 | |
36 | .Os | |
37 | .Sh NAME | |
38 | .Nm mlock , | |
39 | .Nm munlock | |
40 | .Nd lock (unlock) physical pages in memory | |
41 | .Sh SYNOPSIS | |
42 | .Fd #include <sys/types.h> | |
967901a4 | 43 | .Fd #include <sys/mman.h> |
17bc1c47 | 44 | .Ft int |
967901a4 | 45 | .Fn mlock "caddr_t addr" "size_t len" |
17bc1c47 | 46 | .Ft int |
967901a4 | 47 | .Fn munlock "caddr_t addr" "size_t len" |
17bc1c47 MH |
48 | .Sh DESCRIPTION |
49 | The | |
50 | .Nm mlock | |
51 | system call | |
52 | locks into memory the physical pages associated with the virtual address | |
53 | range starting at | |
54 | .Fa addr | |
55 | for | |
56 | .Fa len | |
57 | bytes. | |
58 | The | |
59 | .Nm munlock | |
967901a4 KM |
60 | call unlocks pages previously locked by one or more |
61 | .Nm mlock | |
62 | calls. | |
17bc1c47 MH |
63 | For both, the |
64 | .Fa addr | |
65 | parameter should be aligned to a multiple of the page size. | |
66 | If the | |
67 | .Fa len | |
68 | parameter is not a multiple of the page size, it will be rounded up | |
69 | to be so. | |
70 | The entire range must be allocated. | |
71 | .Pp | |
72 | After an | |
73 | .Nm mlock | |
74 | call, the indicated pages will cause neither a non-resident page | |
653ba8b6 | 75 | nor address-translation fault until they are unlocked. |
17bc1c47 MH |
76 | They may still cause protection-violation faults or TLB-miss faults on |
77 | architectures with software-managed TLBs. | |
78 | The physical pages remain in memory until all locked mappings for the pages | |
79 | are removed. | |
80 | Multiple processes may have the same physical pages locked via their own | |
81 | virtual address mappings. | |
82 | A single process may likewise have pages multiply-locked via different virtual | |
83 | mappings of the same pages or via nested | |
84 | .Nm mlock | |
85 | calls on the same address range. | |
86 | Unlocking is performed explicitly by | |
87 | .Nm munlock | |
967901a4 KM |
88 | or implicitly by a call to |
89 | .Nm munmap | |
90 | which deallocates the unmapped address range. | |
17bc1c47 MH |
91 | Locked mappings are not inherited by the child process after a |
92 | .Xr fork 2 . | |
93 | .Pp | |
94 | Since physical memory is a potentially scarce resource, processes are | |
95 | limited in how much they can lock down. | |
96 | A single process can | |
97 | .Nm mlock | |
98 | the minimum of | |
99 | a system-wide ``wired pages'' limit and | |
100 | the per-process | |
101 | .Li RLIMIT_MEMLOCK | |
102 | resource limit. | |
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 | |
17bc1c47 MH |
113 | will fail if: |
114 | .Bl -tag -width Er | |
115 | .It Bq Er EINVAL | |
116 | The address given is not page aligned or the length is negative. | |
117 | .It Bq Er EAGAIN | |
118 | Locking the indicated range would exceed either the system or per-process | |
967901a4 KM |
119 | limit for locked memory. |
120 | .It Bq Er ENOMEM | |
121 | Some portion of the indicated address range is not allocated. | |
122 | There was an error faulting/mapping a page. | |
123 | .El | |
124 | .Fn Munlock | |
125 | will fail if: | |
126 | .Bl -tag -width Er | |
127 | .It Bq Er EINVAL | |
128 | The address given is not page aligned or the length is negative. | |
17bc1c47 MH |
129 | .It Bq Er ENOMEM |
130 | Some portion of the indicated address range is not allocated. | |
967901a4 KM |
131 | Some portion of the indicated address range is not locked. |
132 | .El | |
17bc1c47 MH |
133 | .Sh "SEE ALSO" |
134 | .Xr fork 2 , | |
967901a4 KM |
135 | .Xr mmap 2 , |
136 | .Xr munmap 2 , | |
137 | .Xr setrlimit 2 , | |
138 | .Xr getpagesize 3 | |
17bc1c47 MH |
139 | .Sh BUGS |
140 | Unlike The Sun implementation, multiple | |
141 | .Nm mlock | |
142 | calls on the same address range require the corresponding number of | |
143 | .Nm munlock | |
144 | calls to actually unlock the pages, i.e. | |
145 | .Nm mlock | |
146 | nests. | |
147 | This should be considered a consequence of the implementation | |
148 | and not a feature. | |
149 | .Pp | |
150 | The per-process resource limit is a limit on the amount of virtual | |
151 | memory locked, while the system-wide limit is for the number of locked | |
152 | physical pages. | |
153 | Hence a process with two distinct locked mappings of the same physical page | |
154 | counts as 2 pages against the per-process limit and as only a single page | |
155 | in the system limit. | |
156 | .Sh HISTORY | |
157 | The | |
158 | .Fn mlock | |
159 | and | |
160 | .Fn munlock | |
ad787160 | 161 | functions first appeared in 4.4BSD. |