usr/src/man/man3c/mlock.3c

   1 '\" te
   2 .\" Copyright (c) 2007, Sun Microsystems, Inc.  All Rights Reserved.
   3 .\" Copyright 1989 AT&T
   4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH MLOCK 3C "Apr 10, 2007"
   8 .SH NAME
   9 mlock, munlock \- lock or unlock pages in memory
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <sys/mman.h>
  14
  15 \fBint\fR \fBmlock\fR(\fBcaddr_t\fR \fIaddr\fR, \fBsize_t\fR \fIlen\fR);
  16 .fi
  17
  18 .LP
  19 .nf
  20 \fBint\fR \fBmunlock\fR(\fBcaddr_t\fR \fIaddr\fR, \fBsize_t\fR \fIlen\fR);
  21 .fi
  22
  23 .SS "Standard conforming"
  24 .LP
  25 .nf
  26 #include <sys/mman.h>
  27
  28 \fBint\fR \fBmlock\fR(\fBconst void *\fR \fIaddr\fR, \fBsize_t\fR \fIlen\fR);
  29 .fi
  30
  31 .LP
  32 .nf
  33 \fBint\fR \fBmunlock\fR(\fBconst void *\fR \fIaddr\fR, \fBsize_t\fR \fIlen\fR);
  34 .fi
  35
  36 .SH DESCRIPTION
  37 .sp
  38 .LP
  39 The  \fBmlock()\fR function uses the mappings established for the address range
  40 [\fIaddr, addr + len\fR) to identify pages to be locked in memory. If the page
  41 identified by a mapping changes, such as occurs when a copy of a writable
  42 \fBMAP_PRIVATE\fR page is made upon the first store, the lock will be
  43 transferred to the newly copied private page.
  44 .sp
  45 .LP
  46 The \fBmunlock()\fR function removes locks established with \fBmlock()\fR.
  47 .sp
  48 .LP
  49 A given page may be locked multiple times by executing an \fBmlock()\fR through
  50 different mappings. That is, if two different processes lock the same page,
  51 then the page will remain locked until both processes remove their locks.
  52 However, within a given mapping, page locks do not nest \(mi multiple
  53 \fBmlock()\fR operations on the same address in the same process will all be
  54 removed with a single \fBmunlock()\fR. Of course, a page locked in one process
  55 and mapped in another (or visible through a different mapping in the locking
  56 process) is still locked in memory. This fact can be used to create
  57 applications that do nothing other than lock important data in memory, thereby
  58 avoiding page I/O faults on references from other processes in the system.
  59 .sp
  60 .LP
  61 The contents of the locked pages will not be transferred to or from disk except
  62 when explicitly requested by one of the locking processes. This guarantee
  63 applies only to the mapped data, and not to any associated data structures
  64 (file descriptors and on-disk metadata, among others).
  65 .sp
  66 .LP
  67 If the mapping through which an \fBmlock()\fR has been performed is removed, an
  68 \fBmunlock()\fR is implicitly performed. An \fBmunlock()\fR is also performed
  69 implicitly when a page is deleted through file removal or truncation.
  70 .sp
  71 .LP
  72 Locks established with \fBmlock()\fR are not inherited by a child process after
  73 a  \fBfork()\fR and are not nested.
  74 .sp
  75 .LP
  76 Attempts to \fBmlock()\fR more memory than a system-specific limit will fail.
  77 .SH RETURN VALUES
  78 .sp
  79 .LP
  80 Upon successful completion, the  \fBmlock()\fR and  \fBmunlock()\fR functions
  81 return \fB0\fR.  Otherwise, no changes are made to any locks in the address
  82 space of the process, the functions return \fB\(mi1\fR and set \fBerrno\fR to
  83 indicate the error.
  84 .SH ERRORS
  85 .sp
  86 .LP
  87 The \fBmlock()\fR and  \fBmunlock()\fR functions will fail if:
  88 .sp
  89 .ne 2
  90 .na
  91 \fB\fBEINVAL\fR\fR
  92 .ad
  93 .RS 10n
  94 The \fIaddr\fR argument is not a multiple of the page size as returned by
  95 \fBsysconf\fR(3C).
  96 .RE
  97
  98 .sp
  99 .ne 2
 100 .na
 101 \fB\fBENOMEM\fR\fR
 102 .ad
 103 .RS 10n
 104 Addresses in the range [\fIaddr, addr + len\fR) are invalid for the address
 105 space of a process, or specify one or more pages which are not mapped.
 106 .RE
 107
 108 .sp
 109 .ne 2
 110 .na
 111 \fB\fBENOSYS\fR\fR
 112 .ad
 113 .RS 10n
 114 The system does not support this memory locking interface.
 115 .RE
 116
 117 .sp
 118 .ne 2
 119 .na
 120 \fB\fBEPERM\fR\fR
 121 .ad
 122 .RS 10n
 123 The {\fBPRIV_PROC_LOCK_MEMORY\fR} privilege is not asserted in the effective
 124 set of the calling process.
 125 .RE
 126
 127 .sp
 128 .LP
 129 The \fBmlock()\fR function will fail if:
 130 .sp
 131 .ne 2
 132 .na
 133 \fB\fBEAGAIN\fR\fR
 134 .ad
 135 .RS 10n
 136 Some or all of the memory identified by the range [\fIaddr, addr + len\fR)
 137 could not be locked because of insufficient system resources or because of a
 138 limit or resource control on locked memory.
 139 .RE
 140
 141 .SH USAGE
 142 .sp
 143 .LP
 144 Because of the impact on system resources, the use of \fBmlock()\fR and
 145 \fBmunlock()\fR is restricted to users with the {\fBPRIV_PROC_LOCK_MEMORY\fR}
 146 privilege.
 147 .SH ATTRIBUTES
 148 .sp
 149 .LP
 150 See \fBattributes\fR(5) for descriptions of the following attributes:
 151 .sp
 152
 153 .sp
 154 .TS
 155 box;
 156 c | c
 157 l | l .
 158 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 159 _
 160 Interface Stability     Standard
 161 _
 162 MT-Level        MT-Safe
 163 .TE
 164
 165 .SH SEE ALSO
 166 .sp
 167 .LP
 168 \fBfork\fR(2), \fBmemcntl\fR(2), \fBmmap\fR(2), \fBplock\fR(3C),
 169 \fBmlockall\fR(3C), \fBsysconf\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5)