Exmap - FAQ

Exmap does not build on current systems and should be considered obsolete. The code is still available on github.


What is exmap?

Exmap is a tool which allows you to see how much memory is in use by different processes, mapped files, ELF sections and ELF symbols at a given moment in time.

It accounts for shared memory in the following way: when a page of memory is found to be shared between N processes, the totals for each process are given a 1/N share of that page.

Exmap doesn't allow you to see details on how and where memory on the heap is allocated. Tools such as valgrind/massif and memprof are more use in this case.

On which platforms does exmap run?

Exmap is linux-specific, since it uses a linux kernel loadable module. Additionally, the kernel module requires a fairly recent kernel (2.6.8 works, as may some earlier 2.6) in order to successfully compile or run.

Exmap is built and tested on Ubuntu (i686), and most versions now receive testing on Ubuntu (amd64), Fedora Core (i686) and Debian (i686).

Exmap has been reported as building and running successfully on an OpenSuse 10.2 beta system.

Exmap is now also packaged for debian, so you should be able to find it with your favourite apt-related tool (if you're running testing or unstable).

If you're running debian sarge, you should know that:

From version 0.8, the perl-based 'exmap.pl' tool has been re-written in C++ (as 'gexmap'), for performance reasons. Prior to 0.9, the C++ version does not work on 64-bit processors, so the old perl version is still shipped. (in the perl-deprecated directory). With 0.9, the C++ tool is (or should be) 64-bit friendly - so the perl version may well disappear at some point.

Please let me know if you have problems running on a particular platform or can confirm that Exmap works on a particular platform not listed above.

What do I need to build exmap?

You'll need the basic development tools such as g++/gcc, make etc. g++ version 3.4 or higher is needed. Additionally, since part of exmap is a loadable kernel module, you'll need the kernel headers for your current kernel installed.

On Ubuntu, you can arrange this with:

sudo apt-get install build-essential linux-kernel-headers

I'm not sure of the Fedora Core equivalent, but a 'workstation' install seems to include the needed basics

The C++ version of exmap has some additional external dependencies. You'll also need:

Debian systems probably have the same package names as Ubuntu, but I haven't verified that.

What do I need to run exmap?

You'll need the run-time equivalents of the above development packages, but they should either already be on your system or be installed as a dependency when you installed the dev packages.

The earlier, perl-based versions of exmap required the GTK perl bindings, version 0.8 and higher do not.

Exmap just hangs on startup, chewing 100% CPU!

With the re-write to C++, the startup time should be down to a few-second pause, rather than a 30-second wait. If you get long startup times on your system, please let me know (I'm not sure how the startup time scales to large-RAM systems, for example).

My box just locked up!

Prior to version 0.6, the kernel module could deadlock under memory pressure. This shouldn't occur with recent versions.

Exmap uses too much memory

Again, the C++ rewrite should have mitigated this. The perl version consumed approx 90Mbytes to analyse my 512Mbyte desktop, the C++ version requires approx 30Mbyte for a similar setup.

At startup I get lots of warnings like: File::load - can't open file: /foo/bar

You may have a root-owned process running (on my system I get these warnings from file in /var/lib/samba) which is mmap()'ing files not readable by my userid. You can avoid them by running gexmap as root, but there isn't really any need to do this as the warnings are fairly harmless.

Should I run Exmap as root?

It depends. Different kernels/distributions appear to set different permissions on the /proc/X/maps files, which could result in less accurate numbers when running as non-root.

If you get similar numbers (e.g. for the TOTALS row) as root and non-root, then just run as your non-root user. Otherwise run as root.

Note: part of the exmap code runs in kernel space anyway, so you aren't protecting your system from any malicious intent on my part by running as non-root. All you'll do is protect yourself from any accidental stupidity on my part.

How do I use Exmap? What do the numbers mean?

The kernel module exports a per-page cookie for each page in each vma in each process. If the page is untouched, this is the zero cookie (no swap or RAM used for that VM range). Such a page contributes to the 'VM' measure but nothing else. A nonzero cookie contributes to 'Mapped'.

[The 'effective' measures use the fact that two pages in two procs with the same cookie are the same page - so it can apportion the memory use fairly between the procs.]

A cookie is either a page frame number (unique id for each page of physical RAM) or a swap cookie (unique id for each page of swap). A PFN contributes to 'Resident'.

Please take a look at the documentation for a longer (but not necessariy more clear) explanation.