-$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
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,
+ 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. Traditionally, lookup_querystyle does not use this (just returning a
+dummy value, and doing the "open" work in the xxx_find() routine); but this is
+not enforced by the framework.
+
+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
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.
+ uschar *opts options, a comma-separated list of tagged values for
+ modifying the search operation
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.
does NOT use the POOL_SEARCH store, because it's usually never called from any
lookup code.
+xxx_version_report()
+--------------------
+
+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
+
+
****
git://git.exim.org / exim.git / blobdiff