Adding upstream version 4.96.upstream/4.96upstream

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

1 files changed, 181 insertions, 0 deletions

diff --git a/src/lookups/README b/src/lookups/README
new file mode 100644
index 0000000..2e87eda
--- /dev/null
+++ b/src/lookups/README
@@ -0,0 +1,181 @@
+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). 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
+various sets of functions, with NULL entries for any that don't exist. When
+the code for a lookup type is omitted from the binary, all its entries are
+NULL.
+
+One of the fields in the table contains flags describing the kind of lookup.
+These are
+
+  lookup_querystyle
+
+This is a "query style" lookup without a file name, as opposed to the "single
+key" style, where the key is associated with a "file name".
+
+  lookup_absfile
+
+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.
+
+  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
+(e.g. after all routing and directing has been done) and this function walks
+the tree and calls the xxx_close() functions for all the cached handles.
+
+Query-style lookups don't have the concept of an open file that can be cached
+this way. Of course, the local code for the lookup can manage its own caching
+information in any way it pleases. This means that the xxx_close()
+function, even it it exists, is never called. However, if an xxx_tidy()
+function exists, it is called once whenever Exim calls search_tidyup().
+
+A single-key lookup type may also have an xxx_tidy() function, which is called
+by search_tidyup() after all cached handles have been closed via the
+xxx_close() function.
+
+The lookup functions are wrapped into a special store pool (POOL_SEARCH). You
+can safely use store_get to allocate store for your handle caching. The store
+will be reset after all xxx_tidy() functions are called.
+
+The function interfaces are as follows:
+
+
+xxx_open()
+----------
+
+This function is called to initiate the lookup. For things that involve files
+it should do a real open; for other kinds of lookup it may do nothing at all.
+The arguments are:
+
+  uschar *filename    the name of the "file" to open, for non-query-style
+                        lookups; NULL for query-style lookups
+  uschar **errmsg     where to put an error message if there is a problem
+
+The yield of xxx_open() is a void * value representing the open file or
+database. For real files is is normally the FILE or DBM value. For other
+kinds of lookup, if there is no natural value to use, (-1) is recommended.
+The value should not be NULL (or 0) as that is taken to indicate failure of
+the xxx_open() function. For single-key lookups, the handle is cached along
+with the filename and type, and may be used for several lookups.
+
+
+xxx_check()
+-----------
+
+If this function exists, it is called after a successful open to check on the
+ownership and mode of the file(s). The arguments are:
+
+  void *handle        the handle passed back from xxx_open()
+  uschar *filename    the filename passed to xxx_open()
+  int modemask        mode bits that must not be set
+  int *owners         permitted owners of the file(s)
+  int *owngroups      permitted group owners of the file(s)
+  uschar **errmsg     where to put an error message if there is a problem
+
+In the owners and owngroups vectors, the first element is the count of the
+remaining elements. There is a common function that can be called to check
+a file:
+
+int search_check_file(int fd, char *filename, int modemask, int *owners,
+  int *owngroups, char *type, char **errmsg);
+
+If fd is >= 0, it is checked using fstat(), and filename is used only in
+error messages. If fd is < 0 then filename is checked using stat(). The yield
+is zero if all is well, +1 if the mode or uid or gid is wrong, or -1 if the
+stat() fails.
+
+The yield of xxx_check() is TRUE if all is well, FALSE otherwise. The
+function should not close the file(s) on failure. That is done from outside
+by calling the xxx_close() function.
+
+
+xxx_find()
+----------
+
+This is called to search an open file/database. The result is OK, FAIL, or
+DEFER. The arguments are:
+
+  void *handle        the handle passed back from xxx_open()
+  uschar *filename    the filename passed to xxx_open() (NULL for querystyle)
+  uschar *keyquery    the key to look up, or query to process, zero-terminated
+  int  length         the length of the key
+  uschar **result     point to the yield, in dynamic store, on success
+  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
+  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.
+
+
+xxx_close()
+-----------
+
+This is called for single-key lookups when a file is finished with. There is no
+yield, and the only argument is the handle that was passed back from
+xxx_open(). It is not called for query style lookups.
+
+
+xxx_tidy()
+----------
+
+This function is called once at the end of search_tidyup() for every lookup
+type for which it exists.
+
+
+xxx_quote()
+-----------
+
+This is called by the string expansion code for expansions of the form
+${quote_xxx:<string>}, if it exists. If not, the expansion code makes no change
+to the string. The function must apply any quoting rules that are specific to
+the lookup, and return a pointer to the revised string. If quoting is not
+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_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
+
+
+****