1VMTOUCH(8)                  System Manager's Manual                 VMTOUCH(8)
2
3
4

NAME

6       vmtouch - the Virtual Memory Toucher
7

SYNOPSIS

9           vmtouch [OPTIONS] ... FILES OR DIRECTORIES ...
10

DESCRIPTION

12       Portable file system cache diagnostics and control.
13
14       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
19       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
24       -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
29           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
33       -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
37           Note: Even if the eviction is successful, pages may be paged back
38           into memory by the time the vmtouch command completes.
39
40           Note: This option is not portable to all systems. See PORTABILITY
41           below.
42
43       -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
49           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
54           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
62       -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
67       -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
71       -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
76       -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
83       -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
88       -F  During the crawl, don't recurse into directories that have separate
89           filesystems mounted on them. This is handy to avoid accidentally
90           touching other filesystems that have been mounted underneath your
91           target directory.
92
93       -i <pattern>
94           Can be specified multiple times. Ignores files and directories that
95           match any of the provided patterns. The pattern may include
96           wildcards (remember to escape them from your shell). This option
97           stops the crawl, so can be used to ignore directories and all their
98           contents. Example: vmtouch -i .git -i '*.bak' .
99
100       -I <pattern>
101           Can be specified multiple times. Only processes filenames matching
102           one or more of the provided patterns. The pattern may include
103           wildcards (remember to escape them from your shell). Example:
104           vmtouch -I '*.c' -I '*.h' .
105
106       -b <list file>
107           The list of files/directories to crawl is read from the specified
108           list file, which by default should be a newline-separated list, for
109           example the output from the find command. If the list file is "-"
110           then this list is read from standard input. Example: find /usr/lib
111           -type f | vmtouch -b -
112
113       -0  If -b ("batch mode") is in effect, assume the list file is
114           delimited with NUL bytes instead of newlines, for example the
115           output from find -print0. This is useful in case your filenames
116           contain newline characters themselves.
117
118       -P <pidfile>
119           Create a PID file. This option can only be provided in combination
120           with -l or -L. The PID file will be automatically deleted when
121           vmtouch gets a termination signal (SIGINT, SIGTERM, SIGQUIT).
122
123       -v  Verbose mode. While crawling, print out every file being processed
124           along with its total number of pages and the number of its pages
125           that are currently resident in memory to standard output.
126
127       -q  Quiet mode. Suppress the end of crawl summary and all warnings that
128           are normally printed to standard error. On success print nothing.
129           Fatal errors print a single error message line to standard error.
130
131       -h  Normally, if multiple files both point to the same inode then
132           vmtouch will ignore all but the first it finds so as to avoid
133           double-counting their pages. This option overrides this behaviour
134           and double-counts anyways.
135

PORTABILITY

137       The page residency summaries depend on mincore(2) which first appeared
138       in 4.4BSD but is not present on all unix systems.
139
140       The "-l" and "-L" locking options depends on mlock(2) or mlockall(2),
141       both of which are specified by POSIX.1b-1993, Real-Time Extensions.
142
143       The "-e" page eviction option is the least portable. On Linux it uses
144       posix_fadvise(2) with "POSIX_FADV_DONTNEED" advice to inform the kernel
145       that the file should be evicted from the file system cache.
146       posix_fadvise(2) is specified by POSIX.1-2003 TC1. On FreeBSD, the
147       pages are invalidated with msync(2)'s "MS_INVALIDATE" flag. msync(2) is
148       specified by POSIX.1b-1993, Real-Time Extensions, although this call is
149       not required to remove pages from the file system cache. Some systems
150       like OpenBSD 4.3 don't have posix_fadvise(2), don't evict the pages on
151       an msync(2)/"MS_INVALIDATE", and don't evict the pages with
152       madvise(2)/"MADV_DONTNEED" so "-e" isn't supported on those systems
153       yet. Using "-e" on systems that don't yet support it is a fatal error.
154

SUPPORTED SYSTEMS

156       All vmtouch features have been confirmed to work on the following
157       systems:
158
159       Linux 2.6+
160       FreeBSD 4.X
161       FreeBSD 7.X
162       Solaris 10
163       OS X 10.x
164       HP-UX 11.31+patches (see below)
165
166       Systems that support everything except eviction:
167
168       OpenBSD 4.3
169
170       CPUs that have been tested:
171
172       x86
173       amd64 (x86-64)
174       SPARC
175       ARMv7
176
177       We would like to support as many systems as possible so please send us
178       any success reports, failure reports or patches. Thanks!
179

SYSTEM NOTES

181       Shane Seymour did the HP-UX port and says that either 32-bit or 64-bit
182       binaries can be compiled (just use "+DD64" for 64-bit). However,
183       mincore(2) was added to HP-UX 11.31 via patches and at least the
184       following patches need to be installed: PHKL_38651, PHKL_38708,
185       PHKL_38686, PHKL_38688, and PHCO_38658 (or patches that supersede those
186       ones).
187

SEE ALSO

189       Not all the following manual pages may exist in every unix dialect to
190       which vmtouch has been ported.
191
192       vmstat(8), touch(1), mmap(2), mincore(2), mlock(2), mlockall(2),
193       msync(2), madvise(2), posix_fadvise(2)
194

AUTHOR

196       Written by Doug Hoyte <doug@hcsw.org>
197
198
199
200                                  2023-07-22                        VMTOUCH(8)
Impressum