Merge branch 'dmverity_options' of https://github.com/bluca/util-linux

[thirdparty/util-linux.git] / Documentation / howto-debug.txt

Debugging util-linux programs
=============================

How to deal libtool
-------------------

There are considerations to be made when profiling or debugging some programs
found in the util-linux package. Because wrapper scripts are used for the
binaries to make sure all library dependencies are met, you cannot use tools
such as gdb or valgrind directly with them.

Let's take for example the mount command:

	$> cd /path/to/util-linux
	$> file mount/mount
	mount/mount: Bourne-Again shell script text executable

The binary itself is located in the mount/.libs/ directory:

	$> file mount/.libs/mount
	mount/.libs/mount: ELF 64-bit LSB executable, x86-64, version 1 \
	(SYSV), dynamically linked (uses shared libs) [...]

When this command is run, there's a library dependency error:

	$> mount/.libs/mount
	mount/.libs/mount: /lib/libblkid.so.1: version `BLKID_2.20' not found \
	(required by mount/.libs/mount)

To overcome this we need set the LD_LIBRARY_PATH variable to read the path of
the shared lib found in the sources, and not system-wide:

	$> export LD_LIBRARY_PATH=$PWD/libblkid/src/.libs/:$LD_LIBRARY_PATH

Now external debugging tools can be run on the binary.

Happy hacking!
Davidlohr Bueso, August 2011


The libmount & libblkid
-----------------------

Both of the libraries can be debugged by setting an environment variable
consisting of a number. The number will be used as a bit mask, so the more 1 the
higher the debugging level. Search for `DEBUG' from files

	libblkid/src/blkidP.h
	libmount/src/mountP.h

to see what the different bits mean. At the time of writing this the following
enabled full debug.

	export LIBBLKID_DEBUG=all
	export LIBMOUNT_DEBUG=all
	export LIBFDISK_DEBUG=all
	export LIBSMARTCOLS_DEBUG=all

The libblkid reads by default /etc/blkid.conf which can be overridden by the
environment variable BLKID_CONF. See manual libblkid/libblkid.3 for details
about the configuration file.

Block device information is normally kept in a cache file (see blkid man page
for more information about the cache file location) that can be overridden by
the environment variable BLKID_FILE.

To libmount uses three paths, which can be overridden by using environment
variables. Notice that these environment variables are ignored for non-root
users.

	env variable		if not set defaults to
	LIBMOUNT_FSTAB		/etc/fstab
	LIBMOUNT_MTAB		/etc/mtab
	LIBMOUNT_UTAB		/run/mount/utab or /dev/.mount/utab