NAME scan-pagemap - display process memory consumption information SYNOPSIS scan-pagemap [options] processes.. pids.. DESCRIPTION This is a tool that can analyze in detail the actual memory usage of processes. The /proc/pid/maps intrface is used to gather information about the files mapped in the process address space. The /proc/pid/pagemap interface is used to gather further information about the real physical page frame numbers allocated for the memory of process'es address space. -p, --pid Scan process with given pid numer -P, --process Scan processes with given name -m, --map When scanning processes, ignore all mapping names which don't cntain the given string in their name. -d, --dump Dump all mappings that belong to a process. The dump will contain following columns: size: The logical size of the mapping in process address space RSS: Resident Set Sise, the amount of allocated bytes in ram swapped: The amount of bytes residing in swap total: RSS + swapped name: Name of the mapping as in /proc/pid/maps file -s, --shared-mappings Only dump mappings that are shared with all the processes given as an argument. This option implies -d option. When -s option is given, all columns except 'size' will count only the pages that appear in the address space off all the processes given as an argumet to scan-pagemap. --with-threads Gather the data individually for each thread. This is usually not needed, as most threads are created with clone() syscall with CLONE_VM set. Therefore, all threads contain the same physical address space. EXAMPLES 1. The default mode of operation This mode consists of two phase scan. The first phase will scan through the processes user has given as an command line argument. The processes can be given as a list of names or pid numers. Each non-option argument is first tested if a matching pid numer is found on the system. If no pids are found for the argument, all running processes are scanned through and the argument is tested against the name of the process. All processes with a matching name are added to the list of processes to be scanned. For each of the processes, the file /proc/pid/maps is used to gather information about the mappings in its address space. Then the file /proc/pid/pagemaps is used to find out the physical page frame numbers used for each 4k page in the process address space. After this, in the second phase, all other processes in the system are scanned similar way. On this second scan only the references to the already known page frame numbers are recorded. When all processes are scanned through, the list of processes is then printed out. On this list, the processes marked with asterisk (*) are the ones which have been scanned fully during the initial scanning phase. The amount of memory printed for these processes reflect to their actual memory consumption. The rest of the processes which have not been marked only count the amount of memry they share with at least one of the marked processes. Example output: $ scan-pagemap emacs RSS swapped USS total pid name 29080 kB 80 kB 20964 kB 29160 kB 7343 * emacs 11472 kB 8 kB 7528 kB 11480 kB 9468 * emacs 4508 kB 0 B 0 B 4508 kB 3080 gkrellm 3212 kB 0 B 0 B 3212 kB 5020 evolution 3016 kB 0 B 0 B 3016 kB 27315 /usr/bin/python2.6 2580 kB 0 B 0 B 2580 kB 3039 kwin 1952 kB 0 B 0 B 1952 kB 3533 /usr/bin/urxvt Total 163 processes referenced pages: 2136, 8544 kB uptodate pages: 9165, 36660 kB dirty pages: 376, 1504 kB lru pages: 9165, 36660 kB active pages: 8720, 34880 kB mmap pages: 9159, 36636 kB anon pages: 7032, 28128 kB swapcache pages: 11, 44 kB swapbacked pages: 7176, 28704 kB present pages: 9155, 36620 kB swapped pages: 22, 88 kB unique pages: 7124, 28496 kB total pages: 9178, 36712 kB [the amount pf processes on the output has been shrinked] On this example, there were two processes which match the given arguments. They are marked with asterisk * in the beginning of the process name. For these processes, the columns reflect the entire process memory consumption. Every process without the mark only show the memory consumption they share with at least one of the processes marked with asterisk. The columns have following meaning: RSS: Resident set size. The amount of process memory currently in ram. swapped: The amount of bytes residing in swap USS: Unique Set Size. The amount of ram which has the reference count in kernel set to one. This means the data is not shared between the processes. total: RSS + swapped pid: The process ID number name: Name and the entire process command line In the end of the output there is some statistical information about the pages gathered during the initial scan. The /proc/kpageflags file is used to gather information about the kernel page flags for each recorded page reference. The occurrance of each page flag is counted and printed in the summary. The listed page flags is provided by the kernel. Documentation for the given page flags can be found in the Documentation/vm/pagemap.txt file in the linux kernel source tree. The last four entries on the summary listing are counted differently: present pages Total number of pages (among the initially scanned processes) that reside currently in ram. swapped pages Similarly to above, but pages in the swap unique pages: This is the number of pages that have kernel reference count set to 1. The value is obtained by reading file /proc/kpagecount total pages: The total number of physical page frames belonging to the processes scanned with the given arguments 2. Dump mode In this mode, only the processes listed in command line arguments are scanned through. After the initial scan, the mappings for each process are dumped out. The output is similar to the process listing, but each line represent a single mapping found in /proc/pid/maps file. This mode can be altered with the -s option. When that option is implied, the output is altered so that the memory consumption figures for each mapping reflect to the amount of pages shared between all of the processes given in the command line argument list. This option is useful for figuring out how two or more processes share memory between each others. Example output: scan-pagemap emacs -s make: `scan-pagemap' is up to date. process: [7343] emacs size RSS swapped total name 8424 kB 2092 kB 0 B 2092 kB /usr/bin/emacs-23 1392 kB 548 kB 0 B 548 kB /lib64/libc-2.12.1.so 1300 kB 172 kB 0 B 172 kB /usr/lib64/libxml2.so.2.7.7 1240 kB 116 kB 0 B 116 kB /usr/lib64/libX11.so.6.3.0 120 kB 92 kB 0 B 92 kB /lib64/ld-2.12.1.so 988 kB 88 kB 0 B 88 kB /usr/lib64/libglib-2.0.so.0.2400.1 288 kB 68 kB 0 B 68 kB /usr/lib64/libpango-1.0.so.0.2800.1 588 kB 56 kB 0 B 56 kB /usr/lib64/libfreetype.so.6.6.0 304 kB 56 kB 0 B 56 kB /lib64/libncurses.so.5.7 92 kB 56 kB 0 B 56 kB /lib64/libpthread-2.12.1.so 116 kB 36 kB 0 B 36 kB /usr/lib64/libxcb.so.1.1.0 [clip] On this example, all processe on the system with name 'emacs' were scanned. The list of mappings they all share has been printed. The 'size' column shows the logical size of the mapping in the process address space. The rest of the columns show only the amount of pages shared between all of the given processes. NOTES The scan-pagemap tool generally requires root permissions to run correctly. It will be able to scan the users' own processes even without root priviledges. But then it will not be able to get system wide process memory consumption statistics. Also the /proc/kpageflags and /proc/kpagecount files are inaccessible, thus the page statistics printed in the end are inaccurate or unavailable.