Adjust dsearch documentation

Author: kurahaupo

doc/doc-docbook/spec.xfpt

@@ -6778,20 +6778,28 @@ each element starting with a tag name and an equals.
 
 Two options are supported, for the return value and for filtering match
 candidates.
-The "ret" option requests an alternate result value of
-the entire path for the entry. Example:
+The "ret=" options request alternative result values: "ret=key" is the default,
+and just returns the key (filename), "ret=full" requests the entire path for
+the entry, and "ret=dir" requests the directory alone.
+Example:
 .code
+${lookup {passwd} dsearch,ret=key {/etc}}
 ${lookup {passwd} dsearch,ret=full {/etc}}
+${lookup {passwd} dsearch,ret=dir {/etc}}
 .endd
-The default result is just the requested entry.
-The "filter" option requests that only directory entries of a given type
-are matched. The match value is one of "file", "dir" or "subdir" (the latter
-not matching "." or ".."). Example:
-.code
-${lookup {passwd} dsearch,filter=file {/etc}}
-.endd
-The default matching is for any entry type, including directories
-and symlinks.
+gives "passwd", "/etc/passwd" and "/etc".
+
+By default all directory entries are matched, regardless of type. The "filter"
+option requests that only directory entries of the given type(s) are matched:
+"file", "dir", "symlink", "pipe", "socket", "tty", "bdev". The filter option
+may be repeated to allow multiple types.
+
+In addition, "filter=nodots" excludes "." and "..", and "filter=subdir" is
+shorthand for "filter=dir,filter=nodots".
+
+The "follow" option follows any symlinks before applies other checks, and
+dangling symlinks will report as nonexistent; otherwise symlinks are rejected
+if any other file-type filter is applied.
 
 An example of how this
 lookup can be used to support virtual domains is given in section

doc/doc-txt/ChangeLog

@@ -36,13 +36,11 @@ JH/08 Bug 2915: Fix use-after-free for $regex<n> variables. Previously when
       These variables were introduced in Exim 4.87.
       Debug help from Graeme Fowler.
 
-MK/08 Numerous changes to dsearch lookups: (a) now performs taint check before
-      other validations to prevent an attacker from making inferences from the
-      varying error messages; (b) no longer require "read" permission on the
-      directory (so you can now chmod a-r the dir to improve system security);
-      (c) uses fstatat on systems that support it (reducing the syscall count);
-      (d) additional filter options to support matching all inode types; (e)
-      new ret=dir option. See documentation for full list.
+MK/09 Bug 2916: dsearch lookups no longer requires "read" permission on the
+      directory.
+
+MK/10 New dsearch lookup features: (a) ret=dir option; (b) filter options for
+      all inode types; (c) can use fstatat(2) where supported.
 
 Exim version 4.96
 -----------------