Linux pcstat — Complete Learning Notes & Output Guide

pcstat stands for Page Cache Statistics. It is a command-line tool used to inspect which parts of a file or executable are currently loaded into the Linux kernel's RAM page cache.

---

1. What is pcstat?

pcstat queries the Linux kernel using the mincore(2) system call.

It answers critical performance questions:

• Is my large database file, index, or log file actually cached in RAM, or will reading it trigger a slow disk read?
• Did my application's pre-warming script successfully load files into memory?
• How much of a specific file is residing in the page cache versus sitting on disk?

---

2. Installation

pcstat is written in Go and can be installed via Go binaries or downloaded directly from GitHub releases.

Via Go Install

go install github.com/tobert/pcstat/v2@latest

Manual Binary Download (Linux x86_64)

sudo curl -Lo /usr/local/bin/pcstat https://github.com/tobert/pcstat/releases/download/v2.0.3/pcstat.linux.x86_64
sudo chmod +x /usr/local/bin/pcstat

Verify installation:

pcstat -v

---

3. Basic Syntax

pcstat [options] <file_path_1> [file_path_2 ...]

Example (checking a large SQLite database file):

pcstat /var/lib/postgresql/data/base.db

---

4. Anatomy of pcstat Output

When you run pcstat against a file, it outputs a formatted tabular report:

+------------------------+----------------+------------+-----------+---------+
| Path                   | Size           | Pages      | Cached    | Percent |
+------------------------+----------------+------------+-----------+---------+
| /var/lib/app/data.db   |     1073741824 |      262144|     131072|   50.00 |
+------------------------+----------------+------------+-----------+---------+

Component-by-Component Breakdown

Heading / Column	Example	Technical Meaning
Path	/var/lib/app/data.db	The absolute or relative file path being inspected.
Size	1073741824	Total size of the file in bytes (1 GB in the example).
Pages	262144	Total number of memory pages the file occupies. Calculated as $\frac{\text{File Size}}{\text{Page Size}}$ (where standard Linux page size is typically $4096$ bytes / 4 KB).
Cached	131072	Number of memory pages currently resident in the kernel's RAM page cache.
Percent	50.00	Percentage of the file's total size currently cached in RAM ($\frac{\text{Cached Pages}}{\text{Total Pages}} \times 100$).

---

5. Visual Page Map Output (Extended Mode)

When you run pcstat with text or graphical visualization flags, it outputs a visual map of the file blocks:

pcstat -text /var/log/app.log

Example Output:

[   0/ 256] [C][C][C][C][U][U][U][U] [ 50.00% cached ]

Understanding the Visual Map Markers

• [C] (Cached): That specific memory page block is currently loaded in RAM.
• [U] (Uncached): That memory page block is not present in RAM and resides only on physical disk storage. Reading it will trigger a block I/O fetch.

---

6. Essential Command Options & Cheat Sheet

Flag	Description	Practical Example
-text	Print a text-based block grid mapping cached vs. uncached pages.	pcstat -text /var/lib/mysql/ibdata1
-json	Output results in JSON format for automated log scraping and monitoring.	pcstat -json /var/log/*.log
-n	Suppress header printing (useful in shell scripts).	pcstat -n /app/data.db

---

7. Real-World Troubleshooting Scenarios

Scenario A: Verifying Database Cache Warming

After restarting a database service, query performance is slow because indices are cold. You run a pre-warming script and verify it with pcstat:

pcstat /var/lib/postgresql/data/base/16384/1255

Conclusion: If Percent reads 99.80%, the cache warm-up succeeded. If it reads 2.10%, the pages are still sitting on disk.

---

Scenario B: Debugging Uncached Disk Reads

An application experiences unexpected high await latency spikes in iostat. You check whether the target log or data file is missing from RAM:

pcstat /mnt/storage/heavy_index.idx

Conclusion: Confirms whether queries are suffering from cache misses and forcing physical disk seeks.

---

8. Important Interview Questions & Answers

Q: What kernel system call does pcstat rely on under the hood?

Answer: pcstat relies on the mincore(2) system call. mincore() allows user-space programs to query the kernel for a vector determining whether pages of a memory-mapped file (mmap) are resident in core memory (RAM) and thus will not trigger a disk access fault when read.

Q: Why can a file show 100% cached in pcstat, but the system still reports low free memory?

Answer: Linux aggressively utilizes unused RAM as a page cache to speed up disk reads and writes (Buffers / Cached in free output). When an application requests more memory for execution, the kernel instantly reclaims pages from the page cache. A 100% cached file does not mean memory is dangerously low; it means the kernel is efficiently caching file blocks until RAM is needed elsewhere.

---