1VMTOUCH(8) System Manager's Manual VMTOUCH(8)
2
6 vmtouch - the Virtual Memory Toucher
7
9 vmtouch [OPTIONS] ... FILES OR DIRECTORIES ...
10
12 Portable file system cache diagnostics and control.
13 vmtouch opens every file provided on the command line and maps it into
15 virtual memory with mmap(2). The mappings are opened read-only. It
16 recursively crawls any directories and does the same to all files it
17 finds within them.
18 With no options, vmtouch will not read from (touch) any memory pages.
20 It will only use mincore(2) to determine how many pages of each file
21 are actually resident in memory. Before exiting, it will print a
22 summary of the total pages encountered and how many were resident.
23 -t Touch virtual memory pages. Reads a byte from each page of the
25 file. If the page is not resident in memory, a page fault will be
26 generated and the page will be read from disk into the file
27 system's memory cache.
28 Note: Although each page is guaranteed to have been brought into
30 memory, the page might be evicted from memory by the time the
31 vmtouch command completes.
32 -e Evict the mapped pages from the file system cache. They will need
34 to be read in from disk the next time they are accessed. This is
35 the inverse of "-t".
36 Note: Even if the eviction is successful, pages may be paged back
38 into memory by the time the vmtouch command completes.
39 Note: This option is not portable to all systems. See PORTABILITY
41 below.
42 -l Lock pages into physical memory. This option works the same as "-t"
44 except it calls mlock(2) on all the memory mappings and doesn't
45 close the descriptors when finished. At the end of the crawl, if
46 successful, vmtouch will block indefinitely. The files will be
47 locked in physical memory until the vmtouch process is killed.
48 Note: While the vmtouch process is holding memory locks, any
50 processes that access the locked pages will not cause non-resident
51 page faults or address-translation faults although they may still
52 cause TLB misses.
53 Note: Because vmtouch holds file descriptors open it may reach the
55 "RLIMIT_NOFILE" process file descriptor limit. In this case it will
56 try to increase the descriptor limit which will only work if the
57 process is run with root privileges. Similarly, root privileges are
58 required to exceed the "RLIMIT_MEMLOCK" limit. Even with root
59 privileges, "-l" is limited by both the system file descriptor
60 limit and the system limit on "wired memory".
61 -L This option is the same as "-l" except that it uses mlockall(2) at
63 the end of the crawl rather than individually mlock(2)ing each
64 file. Because of this, other unrelated pages belonging to the
65 vmtouch process will also be locked in memory.
66 -d Daemon mode. After performing the crawl, disassociate from the
68 terminal and run in the background as a daemon. This option can
69 only be used with the "-l" or "-L" locking modes.
70 -m <max file size>
72 Maximum file size to map into virtual memory. Files that are larger
73 than this will be skipped. Examples: 4096, 4k, 100M, 1.5G. The
74 default is 500M.
75 -p <size range> or <size>
77 Page mode. Maps the portion of the file specified by a range
78 instead of the entire file. Size format same as for "-m". Omitted
79 range start (end) value means start (end) of file. Single <size>
80 value is equivalent to -<size>, i.e. map the first <size> bytes.
81 Examples: 4k-50k, 100M-2G, -5M, -.
82 -f Follow symbolic links. With this option, vmtouch will descend into
84 symbolic links that point to directories and will touch regular
85 files pointed to by symbolic links. Symbolic link loops are
86 detected and issue warnings.
87 -i <pattern>
89 Can be specified multiple times. Ignores files and directories that
90 match any of the provided patterns. The pattern may include
91 wildcards (remember to escape them from your shell). This option
92 stops the crawl, so can be used to ignore directories and all their
93 contents. Example: vmtouch -i .git -i '*.bak' .
94 -I <pattern>
96 Can be specified multiple times. Only processes filenames matching
97 one or more of the provided patterns. The pattern may include
98 wildcards (remember to escape them from your shell). Example:
99 vmtouch -I '*.c' -I '*.h' .
100 -b <list file>
102 The list of files/directories to crawl is read from the specified
103 list file, which by default should be a newline-separated list, for
104 example the output from the find command. If the list file is "-"
105 then this list is read from standard input. Example: find /usr/lib
106 -type f | vmtouch -b -
107 -0 If -b ("batch mode") is in effect, assume the list file is
109 delimited with NUL bytes instead of newlines, for example the
110 output from find -print0. This is useful in case your filenames
111 contain newline characters themselves.
112 -v Verbose mode. While crawling, print out every file being processed
114 along with its total number of pages and the number of its pages
115 that are currently resident in memory to standard output.
116 -q Quiet mode. Suppress the end of crawl summary and all warnings that
118 are normally printed to standard error. On success print nothing.
119 Fatal errors print a single error message line to standard error.
120 -h Normally, if multiple files both point to the same inode then
122 vmtouch will ignore all but the first it finds so as to avoid
123 double-counting their pages. This option overrides this behaviour
124 and double-counts anyways.
125
127 The page residency summaries depend on mincore(2) which first appeared
128 in 4.4BSD but is not present on all unix systems.
129 The "-l" and "-L" locking options depends on mlock(2) or mlockall(2),
131 both of which are specified by POSIX.1b-1993, Real-Time Extensions.
132 The "-e" page eviction option is the least portable. On Linux it uses
134 posix_fadvise(2) with "POSIX_FADV_DONTNEED" advice to inform the kernel
135 that the file should be evicted from the file system cache.
136 posix_fadvise(2) is specified by POSIX.1-2003 TC1. On FreeBSD, the
137 pages are invalidated with msync(2)'s "MS_INVALIDATE" flag. msync(2) is
138 specified by POSIX.1b-1993, Real-Time Extensions, although this call is
139 not required to remove pages from the file system cache. Some systems
140 like OpenBSD 4.3 don't have posix_fadvise(2), don't evict the pages on
141 an msync(2)/"MS_INVALIDATE", and don't evict the pages with
142 madvise(2)/"MADV_DONTNEED" so "-e" isn't supported on those systems
143 yet. Using "-e" on systems that don't yet support it is a fatal error.
144
146 All vmtouch features have been confirmed to work on the following
147 systems:
148 Linux 2.6+
150 FreeBSD 4.X
151 FreeBSD 7.X
152 Solaris 10
153 OS X 10.x
154 HP-UX 11.31+patches (see below)
155 Systems that support everything except eviction:
157 OpenBSD 4.3
159 CPUs that have been tested:
161 x86
163 amd64 (x86-64)
164 SPARC
165 ARMv7
166 We would like to support as many systems as possible so please send us
168 any success reports, failure reports or patches. Thanks!
169
171 Shane Seymour did the HP-UX port and says that either 32-bit or 64-bit
172 binaries can be compiled (just use "+DD64" for 64-bit). However,
173 mincore(2) was added to HP-UX 11.31 via patches and at least the
174 following patches need to be installed: PHKL_38651, PHKL_38708,
175 PHKL_38686, PHKL_38688, and PHCO_38658 (or patches that supersede those
176 ones).
177
179 Not all the following manual pages may exist in every unix dialect to
180 which vmtouch has been ported.
181 vmstat(8), touch(1), mmap(2), mincore(2), mlock(2), mlockall(2),
183 msync(2), madvise(2), posix_fadvise(2)
184
186 Written by Doug Hoyte <doug@hcsw.org>
187 2020-07-29 VMTOUCH(8)