mlock(3c) - osol9

1mlock(3C)                Standard C Library Functions                mlock(3C)
2
3
4

NAME

6       mlock, munlock - lock or unlock pages in memory
7

SYNOPSIS

9       #include <sys/mman.h>
10
11       int mlock(caddr_t addr, size_t len);
12
13
14       int munlock(caddr_t addr, size_t len);
15
16
17   Standard conforming
18       #include <sys/mman.h>
19
20       int mlock(const void * addr, size_t len);
21
22
23       int munlock(const void * addr, size_t len);
24
25

DESCRIPTION

27       The   mlock()  function  uses  the mappings established for the address
28       range [addr, addr + len) to identify pages to be locked in  memory.  If
29       the page identified by a mapping changes, such as occurs when a copy of
30       a writable MAP_PRIVATE page is made upon the first store, the lock will
31       be transferred to the newly copied private page.
32
33
34       The munlock() function removes locks established with mlock().
35
36
37       A  given  page  may  be  locked  multiple times by executing an mlock()
38       through different mappings. That is, if two  different  processes  lock
39       the  same  page,  then the page will remain locked until both processes
40       remove their locks. However, within a given mapping, page locks do  not
41       nest  −  multiple  mlock()  operations  on the same address in the same
42       process will all be removed with a single munlock(). Of course, a  page
43       locked  in one process and mapped in another (or visible through a dif‐
44       ferent mapping in the locking process) is still locked in memory.  This
45       fact can be used to create applications that do nothing other than lock
46       important data in memory, thereby avoiding page I/O  faults  on  refer‐
47       ences from other processes in the system.
48
49
50       The  contents  of  the  locked pages will not be transferred to or from
51       disk except when explicitly requested by one of the locking  processes.
52       This  guarantee applies only to the mapped data, and not to any associ‐
53       ated data structures (file descriptors and on-disk metadata, among oth‐
54       ers).
55
56
57       If  the mapping through which an mlock() has been performed is removed,
58       an munlock() is implicitly performed. An munlock()  is  also  performed
59       implicitly when a page is deleted through file removal or truncation.
60
61
62       Locks  established  with  mlock()  are not inherited by a child process
63       after a  fork() and are not nested.
64
65
66       Attempts to mlock() more memory than a system-specific limit will fail.
67

RETURN VALUES

69       Upon successful  completion,  the   mlock()  and   munlock()  functions
70       return  0.   Otherwise, no changes are made to any locks in the address
71       space of the process, the functions return −1 and set errno to indicate
72       the error.
73

ERRORS

75       The mlock() and  munlock() functions will fail if:
76
77       EINVAL    The  addr  argument  is  not  a  multiple of the page size as
78                 returned by sysconf(3C).
79
80
81       ENOMEM    Addresses in the range [addr, addr + len) are invalid for the
82                 address  space  of  a  process,  or specify one or more pages
83                 which are not mapped.
84
85
86       ENOSYS    The system does not support this memory locking interface.
87
88
89       EPERM     The {PRIV_PROC_LOCK_MEMORY} privilege is not asserted in  the
90                 effective set of the calling process.
91
92
93
94       The mlock() function will fail if:
95
96       EAGAIN    Some or all of the memory identified by the range [addr, addr
97                 + len) could not be locked  because  of  insufficient  system
98                 resources or because of a limit or resource control on locked
99                 memory.
100
101

USAGE

103       Because of the impact on system  resources,  the  use  of  mlock()  and
104       munlock() is restricted to users with the {PRIV_PROC_LOCK_MEMORY} priv‐
105       ilege.
106

ATTRIBUTES

108       See attributes(5) for descriptions of the following attributes:
109
110
111
112
113       ┌─────────────────────────────┬─────────────────────────────┐
114       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
115       ├─────────────────────────────┼─────────────────────────────┤
116       │Interface Stability          │Standard                     │
117       ├─────────────────────────────┼─────────────────────────────┤
118       │MT-Level                     │MT-Safe                      │
119       └─────────────────────────────┴─────────────────────────────┘
120