Adding upstream version 2.38.1.upstream/2.38.1upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 74 insertions, 0 deletions

diff --git a/Documentation/howto-debug.txt b/Documentation/howto-debug.txt
new file mode 100644
index 0000000..6936eb5
--- /dev/null
+++ b/Documentation/howto-debug.txt
@@ -0,0 +1,74 @@
+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