memtester(8)

💖 memtester — the manual, bestie edition 💖

okay so. this is memtester, section 8 of the maintenance commands, and it's literally the girlboss of memory stress testing. buckle up. 🎀

---

✨ NAME ✨

memtester — a stress test that goes hunting for faults in your memory subsystem. 🕵️♀️

---

✨ SYNOPSIS ✨

memtester [-p PHYSADDR [-d DEVICE] [-u]] <MEMORY> [ITERATIONS]

---

✨ DESCRIPTION ✨

okay so memtester is genuinely an effective userspace tester for stress-testing the memory subsystem. it is very good at catching those sneaky intermittent, non-deterministic faults — the ones that ghost you and then show up at 3am. 💀

but bestie, listen: problems in other hardware areas (overheating CPU, an out-of-specification power supply, etc.) can also cause intermittent memory faults. so it is still up to you to figure out where the fault actually lives, through normal hardware diagnostic procedures. memtester just helps you figure out whether a problem exists at all. no cap. 🫶

memtester will malloc(3) the amount of memory specified, if possible. if that fails, it will decrease the amount of memory requested until it succeeds. then it will attempt to mlock(3) that memory — and if it cannot do that, testing will be slower and much less effective. so run memtester as root so it can mlock the memory it tests. 👑

also, the maximum amount of memory memtester can test will be less than the total amount installed in the system — the operating system, libraries, and other system limits take some of the available memory. memtester is also limited to the amount of memory available to a single process. for example, on 32-bit machines with more than 4GB of memory, memtester is still limited to less than 4GB. it's giving "the math is not mathing" but it's just how processes work. 😭

and here's the part where you need to be a responsible main character: it is up to you to know how much memory you can safely allocate for testing. if you attempt to allocate more memory than is available, memtester should figure that out, reduce the amount slightly, and try again. however, this can lead to memtester successfully allocating and mlocking essentially all free memory on the system — and if other programs are running, this can lead to excessive swapping and slowing the system down to the point that it is difficult to use. 🙈

if the system allows allocation of more memory than is actually available (overcommit), it may lead to a deadlock, where the system halts. 💀 and if the system has an out-of-memory process killer (like Linux), memtester or another process may be killed by the OOM killer. 🔥

so choose wisely. 💅

---

✨ OPTIONS ✨

• -p PHYSADDR — tells memtester to test a specific region of memory starting at physical address PHYSADDR (given in hex), by mmap(2)ing a device specified by the -d option (below, or /dev/mem by default). this is mostly of use to hardware developers, for testing memory-mapped I/O devices and similar. ⚠️ note that the memory region will be overwritten during testing, so it is not safe to specify memory which is allocated for the system or for other applications — doing so will cause them to crash. 😭 if you absolutely must test a particular region of actual physical memory, arrange to have that memory allocated by your test software, and hold it in this allocated state, then run memtester on it with this option.
• -d DEVICE — specifies the device to open with the -p option above. if not supplied, /dev/mem is the default. 🎀
• -u — causes memtester to open the device specified by the -d option above without the O_SYNC flag, which causes the system to use uncached memory semantics on some systems. ✨
• MEMORY — the amount of memory to allocate and test, in megabytes by default. you can include a suffix of B, K, M, or G to indicate bytes, kilobytes, megabytes, or gigabytes respectively. 🦋
• ITERATIONS — (optional) number of loops to iterate through. default is infinite. ♾️ (she's committed.)

---

✨ ENVIRONMENT ✨

if the environment variable MEMTESTER_TEST_MASK is set, memtester treats the value as a bitmask of which tests (other than the stuck address test) to run. 🧚

the value can be specified in:

• decimal
• octal (with a leading 0)
• hexadecimal (with a leading 0x)

the specific bit values corresponding to particular tests may change from release to release — so consult the list of tests in the source for the appropriate index values for the version of memtester you are running. 👑

note that skipping some tests will reduce the time it takes for memtester to run, but also reduce memtester's effectiveness. so like… tradeoffs, bestie. 💅

---

✨ NOTE ✨

memtester must be run with root privileges to mlock(3) its pages. testing memory without locking the pages in place is mostly pointless and slow. 💀

---

✨ EXIT CODE ✨

memtester's exit code is 0 when everything works properly. otherwise, it is the logical OR of the following values:

• x01 — error allocating or locking memory, or invocation error
• x02 — error during stuck address test
• x04 — error during one of the other tests

---

✨ AUTHOR ✨

written by Charles Cazabon. 👑

---

✨ REPORTING BUGS ✨

report bugs to <charlesc-memtester-bugs@pyropus.ca>. 🐛

---

✨ COPYRIGHT ✨

Copyright © 2001-2024 Charles Cazabon

this is free software; see the file COPYING for copying conditions. there is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. ⚠️

---

and that's the whole thing, bestie. 🌈 this was memtester 4, from November 2024 — go lock some pages and find those faults. mwah. 💅✨🎀