--- /dev/null
+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.
projects / scan-pagemap / commitdiff