VMTOUCH(8)

📦
version 1.3.1 · 7 versions
, in debian bookworm, ubuntu jammy, ubuntu noble

💖 VMTOUCH(8) 💖 — the Virtual Memory Toucher

okay so bestie, welcome to the System Manager's Manual section 8, aka where the big-kid system admin tools live, and today's main character is vmtouch. it's literally called the Virtual Memory Toucher. iconic name, no notes. 🫶

✨ NAME ✨

vmtouch — the Virtual Memory Toucher 💅

🌸 SYNOPSIS 🌸

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

🦋 DESCRIPTION 🦋

Portable file system cache diagnostics and control. periodt.

So here's the vibe: vmtouch opens every single file you hand it on the command line and maps it into virtual memory using mmap(2). those mappings? opened read-only, she's respectful like that. and if you give her a directory, she doesn't just shrug — she recursively crawls it and does the exact same thing to every file she finds inside. yes, all of them. she's thorough.

and if you run her with no options at all? she will not read from (touch) any memory pages. nope. she'll just use mincore(2) to figure out how many pages of each file are actually resident in memory. then, right before she dips, she prints a lil summary of the total pages she encountered and how many of them were resident. that's it, that's the whole job. 🎀

Now the options, bestie, and there are a lot of them, so buckle up:

  • -t — Touch virtual memory pages. She reads a byte from each page of the file. if that page isn't resident in memory yet, a page fault gets generated and the page gets read from disk straight into the file system's memory cache. 💥
Note: even though every page is guaranteed to have been brought into memory, the page might get evicted from memory by the time the vmtouch command completes. so like, she did her best, okay? 😭
  • -e — Evict the mapped pages from the file system cache. they'll need to be read in from disk the next time they're accessed. this is literally the inverse of "-t". bye girl, you're out of the cache 💀
Note: even if the eviction is successful, pages may be paged back into memory by the time the vmtouch command completes. the kernel has a mind of its own fr fr.
Note: this option is not portable to all systems. see PORTABILITY below.
  • -l — Lock pages into physical memory. works exactly the same as "-t" except she calls mlock(2) on all the memory mappings and doesn't close the descriptors when she's finished. and at the end of the crawl, if it was successful, vmtouch will just... block indefinitely. she's not leaving. the files stay locked in physical memory until the vmtouch process is killed. 👑
Note: while the vmtouch process is holding memory locks, any processes that access the locked pages will not cause non-resident page faults or address-translation faults — although they may still cause TLB misses.
Note: because vmtouch holds file descriptors open, it may reach the "RLIMIT_NOFILE" process file descriptor limit. when that happens she'll try to increase the descriptor limit, which will only work if the process is run with root privileges. similarly, root privileges are required to exceed the "RLIMIT_MEMLOCK" limit. and even with root privileges, "-l" is limited by both the system file descriptor limit and the system limit on "wired memory". so like, respect the limits bestie.
  • -L — same as "-l" except she uses mlockall(2) at the end of the crawl instead of individually mlock(2)-ing each file. because of that, other unrelated pages belonging to the vmtouch process will also get locked in memory. collateral locking, we love to see it.
  • -d — Daemon mode. after performing the crawl, she disassociates from the terminal and runs in the background as a daemon. 🧚 this option can only be used with the "-l" or "-L" locking modes. no freelancing.
  • -m <max file size> — Maximum file size to map into virtual memory. files bigger than this get skipped, sorry babe. examples: 4096, 4k, 100M, 1.5G. the default is 500M.
  • -p <size range> or <size> — Page mode. maps the portion of the file specified by a range instead of the entire file. size format is the same as for "-m". an omitted range start (end) value means the start (end) of the file. a single <size> value is equivalent to -<size>, i.e. map the first <size> bytes. examples: 4k-50k, 100M-2G, -5M, -. ✨
  • -f — Follow symbolic links. with this, vmtouch will descend into symbolic links that point to directories, and will touch regular files pointed to by symbolic links. symbolic link loops are detected and issue warnings. she's not falling for that trap, she's seen it before. 🌀
  • -F — During the crawl, don't recurse into directories that have separate filesystems mounted on them. this is handy to avoid accidentally touching other filesystems that have been mounted underneath your target directory. 🛑
  • -i <pattern> — Can be specified multiple times. Ignores files and directories that match any of the provided patterns. the pattern may include wildcards (remember to escape them from your shell!). this option stops the crawl, so it can be used to ignore directories and all their contents. example: vmtouch -i .git -i '*.bak' .
  • -I <pattern> — Can be specified multiple times. Only processes filenames matching one or more of the provided patterns. the pattern may include wildcards (remember to escape them from your shell!). example: vmtouch -I '*.c' -I '*.h' .
  • -b <list file> — The list of files/directories to crawl is read from the specified list file, which by default should be a newline-separated list, for example the output from the find command. if the list file is "-" then this list is read from standard input. example: find /usr/lib -type f | vmtouch -b -
  • -0 — If -b ("batch mode") is in effect, assume the list file is delimited with NUL bytes instead of newlines, for example the output from find -print0. this is useful in case your filenames contain newline characters themselves. chaos-proof filenames, we stan. 💜
  • -P <pidfile> — Create a PID file. this option can only be provided in combination with -l or -L. the PID file will be automatically deleted when vmtouch gets a termination signal (SIGINT, SIGTERM, SIGQUIT). she cleans up after herself, unlike some people. 🙈
  • -v — Verbose mode. while crawling, print out every file being processed along with its total number of pages and the number of its pages that are currently resident in memory to standard output. she will tell you everything. every. single. file.
  • -q — Quiet mode. Suppress the end of crawl summary and all warnings that are normally printed to standard error. on success, print nothing. fatal errors print a single error message line to standard error. she's giving mysterious, unbothered, moisturized. 💅
  • -h — Normally, if multiple files both point to the same inode then vmtouch will ignore all but the first it finds so as to avoid double-counting their pages. this option overrides this behaviour and double-counts anyways. she said "no thoughts, head empty, count it twice". 😭

🌈 PORTABILITY 🌈

The page residency summaries depend on mincore(2), which first appeared in 4.4BSD but is not present on all unix systems. so your mileage may absolutely vary depending on which flavor of unix you're on, bestie.

The "-l" and "-L" locking options depend on mlock(2) or mlockall(2), both of which are specified by POSIX.1b-1993, Real-Time Extensions. official, standards-approved, the real deal.

The "-e" page eviction option is the least portable. here's the breakdown:

  • On Linux it uses posix_fadvise(2) with "POSIX_FADV_DONTNEED" advice to inform the kernel that the file should be evicted from the file system cache. posix_fadvise(2) is specified by POSIX.1-2003 TC1.
  • On FreeBSD, the pages are invalidated with msync(2)'s "MS_INVALIDATE" flag. msync(2) is specified by POSIX.1b-1993, Real-Time Extensions, although this call is not required to remove pages from the file system cache.
  • Some systems like OpenBSD 4.3 don't have posix_fadvise(2), don't evict the pages on an msync(2)/"MS_INVALIDATE", and don't evict the pages with madvise(2)/"MADV_DONTNEED" — so "-e" isn't supported on those systems yet.
Using "-e" on systems that don't yet support it is a fatal error. like, dead on arrival. don't do it.

⭐ SUPPORTED SYSTEMS ⭐

All vmtouch features have been confirmed to work on the following systems:

  • Linux 2.6+
  • FreeBSD 4.X
  • FreeBSD 7.X
  • Solaris 10
  • OS X 10.x
  • HP-UX 11.31+patches (see below 👀)

Systems that support everything except eviction:

  • OpenBSD 4.3

CPUs that have been tested:

  • x86
  • amd64 (x86-64)
  • SPARC
  • ARMv7

We would like to support as many systems as possible so please send us any success reports, failure reports or patches. Thanks! 🥺🫶 she's growing, she's evolving, help her out.

🎀 SYSTEM NOTES 🎀

Shane Seymour did the HP-UX port and says that either 32-bit or 64-bit binaries can be compiled (just use "+DD64" for 64-bit). however, mincore(2) was added to HP-UX 11.31 via patches, and at least the following patches need to be installed: PHKL_38651, PHKL_38708, PHKL_38686, PHKL_38688, and PHCO_38658 (or patches that supersede those ones). patch girlies, this one's for you. 🧚

🔥 SEE ALSO 🔥

Not all the following manual pages may exist in every unix dialect to which vmtouch has been ported. so like, don't come for her if one's missing.

vmstat(8), touch(1), mmap(2), mincore(2), mlock(2), mlockall(2), msync(2), madvise(2), posix_fadvise(2)

👑 AUTHOR 👑

Written by Doug Hoyte <doug@hcsw.org> 💌

and that's the whole page bestie!! this one's from the System Manager's Manual, dated 2021-01-11, and it's the VMTOUCH(8) you know and love. go touch some virtual memory, you've earned it. mwah 💋✨🌈

📦 where this page comes from