doc: Further explanation for the PATH directive and lookup rules

The PATH directive can be quite confusing when coupled with the fact
that the current working directory is always searched first when
opening files.

Signed-off-by: Matt Fleming <matt.fleming@intel.com>

1 files changed, 29 insertions, 1 deletions

diff --git a/doc/syslinux.txt b/doc/syslinux.txt
index e9923a63..34dcb97a 100644
--- a/doc/syslinux.txt
+++ b/doc/syslinux.txt
@@ -455,7 +455,9 @@ PATH path
 	when attempting to load modules. This directive is useful for
 	specifying the directories containing the lib*.c32 library
 	files as other modules may be dependent on these files, but
-	may not reside in the same directory.
+	may not reside in the same directory. The list of directories
+	is searched in order. Please see the section below on PATH
+	RULES.
 
 Blank lines are ignored.
 
@@ -775,6 +777,32 @@ In recent versions of Linux, this ID is available as
 /proc/sys/kernel/bootloader_type.
 
 
+   ++++ PATH RULES ++++
+
+The current working directory is *always* searched first, before PATH,
+when attempting to open a filename. The current working directory is
+not affected when specifying a file with an absolute path. For
+example, given the following file system layout,
+
+	 /boot/
+		/bin/
+			ls.c32
+			libls.c32
+		/foo/
+			libls.c32
+
+assuming that the current working directory is /boot/foo, and assuming
+that libls.c32 is a dependency of ls.c32, executing /boot/bin/ls.c32
+will cause /boot/foo/libls.c32 to be loaded, not /boot/bin/libls.c32,
+even if /boot/bin is specified in the PATH directive of a config file.
+
+The reason that things work this way is that typically a user will
+install all library files in the Syslinux installation directory, as
+specified with the --directory installer option. This method allows
+the user to omit the PATH directive from their config file and still
+have things work correctly.
+
+
    ++++ BUG REPORTS ++++
 
 I would appreciate hearing of any problems you have with Syslinux.  I