X-Git-Url: https://vcs.fsf.org/?a=blobdiff_plain;f=src%2Fsrc%2Flookups%2FREADME;h=31fea64489398d6428da741b5220413cd4f7810f;hb=bfe645c1570343d3adca657ab67998e122ca8792;hp=7a16b83a286239dcacc92946c1906575a72a78c3;hpb=0756eb3cb50d73a77b486e47528f7cb1bffdb299;p=exim.git

diff --git a/src/src/lookups/README b/src/src/lookups/README
index 7a16b83a2..31fea6448 100644
--- a/src/src/lookups/README
+++ b/src/src/lookups/README
@@ -1,11 +1,12 @@
-$Cambridge: exim/src/src/lookups/README,v 1.1 2004/10/07 13:10:01 ph10 Exp $
-
 LOOKUPS
 -------
 
 Each lookup type is implemented by 6 functions, xxx_open(), xxx_check(),
 xxx_find(), xxx_close(), xxx_tidy(), and xxx_quote(), where xxx is the name of
-the lookup type (e.g. lsearch, dbm, or whatever).
+the lookup type (e.g. lsearch, dbm, or whatever). In addition, there is
+a version reporting function used to trace compile-vs-runtime conflicts and
+to help administrators ensure that the modules from the correct build are
+in use by the main binary.
 
 The xxx_check(), xxx_close(), xxx_tidy(), and xxx_quote() functions need not
 exist. There is a table in drtables.c which links the lookup names to the
@@ -26,11 +27,16 @@ key" style, where the key is associated with a "file name".
 For single key lookups, this means that the file name must be an absolute path.
 It is set for lsearch and dbm, but not for NIS, for example.
 
-When a single-key lookup file is opened, the handle returned by the xxx_open()
-function is saved, along with the file name and lookup type, in a tree. The
-xxx_close() function is not called when the first lookup is completed. If there
-are subsequent lookups of the same type that quote the same file name,
-xxx_open() isn't called; instead the cached handle is re-used.
+  lookup_absfilequery
+
+This is a query-style lookup that must start with an absolute file name. For
+example, the sqlite lookup is of this type.
+
+When a single-key or absfilequery lookup file is opened, the handle returned by
+the xxx_open() function is saved, along with the file name and lookup type, in
+a tree. The xxx_close() function is not called when the first lookup is
+completed. If there are subsequent lookups of the same type that quote the same
+file name, xxx_open() isn't called; instead the cached handle is re-used.
 
 Exim calls the function search_tidyup() at strategic points in its processing
 (e.g. after all routing and directing has been done) and this function walks
@@ -116,12 +122,15 @@ DEFER. The arguments are:
   uschar **errmsg     where to put an error message on failure;
                       this is initially set to "", and should be left
                       as that for a standard "entry not found" error
-  BOOL *do_cache      the lookup should set this to FALSE when it changes data.
-                      This is TRUE by default. When set to FALSE the cache tree
+  uint *do_cache      the lookup should set this to 0 when it changes data.
+                      This is MAXINT by default. When set to 0 the cache tree
                       of the current search handle will be cleaned and the
                       current result will NOT be cached. Currently the mysql
                       and pgsql lookups use this when UPDATE/INSERT queries are
                       executed.
+                      If set to a nonzero number of seconds, the cached value
+                      becomes unusable after this time. Currently the dnsdb
+                      lookup uses this to support the TTL value.
 
 Even though the key is zero-terminated, the length is passed because in the
 common case it has been computed already and is often needed.
@@ -153,4 +162,14 @@ needed, it can return its single argument, which is a uschar *. This function
 does NOT use the POOL_SEARCH store, because it's usually never called from any
 lookup code.
 
+xxx_report_version()
+--------------------
+
+This is called to report diagnostic information to a file stream.
+Typically it would report both compile-time and run-time version information.
+The arguments are:
+
+  FILE *stream    where to fprintf() the data to
+
+
 ****