share/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(\fBconst void *\fR \fIaddr\fR, \fBsize_t\fR \fIlen\fR);
  16 .fi
  17
  18 .LP
  19 .nf
  20 \fBint\fR \fBmunlock\fR(\fBconst void *\fR \fIaddr\fR, \fBsize_t\fR \fIlen\fR);
  21 .fi
  22
  23 .SH DESCRIPTION
  24 .sp
  25 .LP
  26 The  \fBmlock()\fR function uses the mappings established for the address range
  27 [\fIaddr, addr + len\fR) to identify pages to be locked in memory. If the page
  28 identified by a mapping changes, such as occurs when a copy of a writable
  29 \fBMAP_PRIVATE\fR page is made upon the first store, the lock will be
  30 transferred to the newly copied private page.
  31 .sp
  32 .LP
  33 The \fBmunlock()\fR function removes locks established with \fBmlock()\fR.
  34 .sp
  35 .LP
  36 A given page may be locked multiple times by executing an \fBmlock()\fR through
  37 different mappings. That is, if two different processes lock the same page,
  38 then the page will remain locked until both processes remove their locks.
  39 However, within a given mapping, page locks do not nest \(mi multiple
  40 \fBmlock()\fR operations on the same address in the same process will all be
  41 removed with a single \fBmunlock()\fR. Of course, a page locked in one process
  42 and mapped in another (or visible through a different mapping in the locking
  43 process) is still locked in memory. This fact can be used to create
  44 applications that do nothing other than lock important data in memory, thereby
  45 avoiding page I/O faults on references from other processes in the system.
  46 .sp
  47 .LP
  48 The contents of the locked pages will not be transferred to or from disk except
  49 when explicitly requested by one of the locking processes. This guarantee
  50 applies only to the mapped data, and not to any associated data structures
  51 (file descriptors and on-disk metadata, among others).
  52 .sp
  53 .LP
  54 If the mapping through which an \fBmlock()\fR has been performed is removed, an
  55 \fBmunlock()\fR is implicitly performed. An \fBmunlock()\fR is also performed
  56 implicitly when a page is deleted through file removal or truncation.
  57 .sp
  58 .LP
  59 Locks established with \fBmlock()\fR are not inherited by a child process after
  60 a  \fBfork()\fR and are not nested.
  61 .sp
  62 .LP
  63 Attempts to \fBmlock()\fR more memory than a system-specific limit will fail.
  64 .SH RETURN VALUES
  65 .sp
  66 .LP
  67 Upon successful completion, the  \fBmlock()\fR and  \fBmunlock()\fR functions
  68 return \fB0\fR.  Otherwise, no changes are made to any locks in the address
  69 space of the process, the functions return \fB\(mi1\fR and set \fBerrno\fR to
  70 indicate the error.
  71 .SH ERRORS
  72 .sp
  73 .LP
  74 The \fBmlock()\fR and  \fBmunlock()\fR functions will fail if:
  75 .sp
  76 .ne 2
  77 .na
  78 \fB\fBEINVAL\fR\fR
  79 .ad
  80 .RS 10n
  81 The \fIaddr\fR argument is not a multiple of the page size as returned by
  82 \fBsysconf\fR(3C).
  83 .RE
  84
  85 .sp
  86 .ne 2
  87 .na
  88 \fB\fBENOMEM\fR\fR
  89 .ad
  90 .RS 10n
  91 Addresses in the range [\fIaddr, addr + len\fR) are invalid for the address
  92 space of a process, or specify one or more pages which are not mapped.
  93 .RE
  94
  95 .sp
  96 .ne 2
  97 .na
  98 \fB\fBENOSYS\fR\fR
  99 .ad
 100 .RS 10n
 101 The system does not support this memory locking interface.
 102 .RE
 103
 104 .sp
 105 .ne 2
 106 .na
 107 \fB\fBEPERM\fR\fR
 108 .ad
 109 .RS 10n
 110 The {\fBPRIV_PROC_LOCK_MEMORY\fR} privilege is not asserted in the effective
 111 set of the calling process.
 112 .RE
 113
 114 .sp
 115 .LP
 116 The \fBmlock()\fR function will fail if:
 117 .sp
 118 .ne 2
 119 .na
 120 \fB\fBEAGAIN\fR\fR
 121 .ad
 122 .RS 10n
 123 Some or all of the memory identified by the range [\fIaddr, addr + len\fR)
 124 could not be locked because of insufficient system resources or because of a
 125 limit or resource control on locked memory.
 126 .RE
 127
 128 .SH USAGE
 129 .sp
 130 .LP
 131 Because of the impact on system resources, the use of \fBmlock()\fR and
 132 \fBmunlock()\fR is restricted to users with the {\fBPRIV_PROC_LOCK_MEMORY\fR}
 133 privilege.
 134 .SH ATTRIBUTES
 135 .sp
 136 .LP
 137 See \fBattributes\fR(5) for descriptions of the following attributes:
 138 .sp
 139
 140 .sp
 141 .TS
 142 box;
 143 c | c
 144 l | l .
 145 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 146 _
 147 Interface Stability     Standard
 148 _
 149 MT-Level        MT-Safe
 150 .TE
 151
 152 .SH SEE ALSO
 153 .sp
 154 .LP
 155 \fBfork\fR(2), \fBmemcntl\fR(2), \fBmmap\fR(2), \fBplock\fR(3C),
 156 \fBmlockall\fR(3C), \fBsysconf\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5)