bsd/man/man2/mlock.2

   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/mman.h>
  45 .Ft int
  46 .Fo mlock
  47 .Fa "const void *addr"
  48 .Fa "size_t len"
  49 .Fc
  50 .Ft int
  51 .Fo munlock
  52 .Fa "const void *addr"
  53 .Fa "size_t len"
  54 .Fc
  55 .Sh DESCRIPTION
  56 The
  57 .Nm mlock
  58 system call
  59 locks a set of physical pages into memory.
  60 The pages are associated with a virtual address range
  61 that starts at
  62 .Fa addr
  63 and extends for
  64 .Fa len
  65 bytes.
  66 The
  67 .Nm munlock
  68 call unlocks pages that were previously locked by one or more
  69 .Nm mlock
  70 calls.
  71 For both calls, the
  72 .Fa addr
  73 parameter should be aligned to a multiple of the page size.
  74 If the
  75 .Fa len
  76 parameter is not a multiple of the page size,
  77 it will be rounded up to be so.
  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.
  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
  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
  98 .Nm munmap ,
  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
 103 Because physical memory is a potentially scarce resource,
 104 processes are limited in how much memory they can lock down.
 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
 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.
 118 In this case, the global location
 119 .Va errno
 120 is set to indicate the error.
 121 .Sh ERRORS
 122 .Fn Mlock
 123 and
 124 .Fn munlock
 125 will fail if:
 126 .Bl -tag -width Er
 127 .\" ===========
 128 .It Bq Er EINVAL
 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 .\" ===========
 140 .It Bq Er EAGAIN
 141 Locking the indicated range would exceed either the system or per-process
 142 limit for locked memory.
 143 .\" ===========
 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
 148 .Pp
 149 .Fn Munlock
 150 will fail if:
 151 .Bl -tag -width Er
 152 .\" ===========
 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
 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.
 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 ,
 189 .Xr getpagesize 3 ,
 190 .Xr compat 5
 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.