src/src/lookups/README

   1 LOOKUPS
   2 -------
   3
   4 Each lookup type is implemented by 6 functions, xxx_open(), xxx_check(),
   5 xxx_find(), xxx_close(), xxx_tidy(), and xxx_quote(), where xxx is the name of
   6 the lookup type (e.g. lsearch, dbm, or whatever). In addition, there is
   7 a version reporting function used to trace compile-vs-runtime conflicts and
   8 to help administrators ensure that the modules from the correct build are
   9 in use by the main binary.
  10
  11 The xxx_check(), xxx_close(), xxx_tidy(), and xxx_quote() functions need not
  12 exist. There is a table in drtables.c which links the lookup names to the
  13 various sets of functions, with NULL entries for any that don't exist. When
  14 the code for a lookup type is omitted from the binary, all its entries are
  15 NULL.
  16
  17 One of the fields in the table contains flags describing the kind of lookup.
  18 These are
  19
  20   lookup_querystyle
  21
  22 This is a "query style" lookup without a file name, as opposed to the "single
  23 key" style, where the key is associated with a "file name".
  24
  25   lookup_absfile
  26
  27 For single key lookups, this means that the file name must be an absolute path.
  28 It is set for lsearch and dbm, but not for NIS, for example.
  29
  30   lookup_absfilequery
  31
  32 This is a query-style lookup that must start with an absolute file name. For
  33 example, the sqlite lookup is of this type.
  34
  35 When a single-key or absfilequery lookup file is opened, the handle returned by
  36 the xxx_open() function is saved, along with the file name and lookup type, in
  37 a tree. Traditionally, lookup_querystyle does not use this (just returning a
  38 dummy value, and doing the "open" work in the xxx_find() routine); but this is
  39 not enforced by the framework.
  40
  41 The xxx_close() function is not called when the first lookup is completed. If
  42 there are subsequent lookups of the same type that quote the same file name,
  43 xxx_open() isn't called; instead the cached handle is re-used.
  44
  45 Exim calls the function search_tidyup() at strategic points in its processing
  46 (e.g. after all routing and directing has been done) and this function walks
  47 the tree and calls the xxx_close() functions for all the cached handles.
  48
  49 Query-style lookups don't have the concept of an open file that can be cached
  50 this way. Of course, the local code for the lookup can manage its own caching
  51 information in any way it pleases. This means that the xxx_close()
  52 function, even it it exists, is never called. However, if an xxx_tidy()
  53 function exists, it is called once whenever Exim calls search_tidyup().
  54
  55 A single-key lookup type may also have an xxx_tidy() function, which is called
  56 by search_tidyup() after all cached handles have been closed via the
  57 xxx_close() function.
  58
  59 The lookup functions are wrapped into a special store pool (POOL_SEARCH). You
  60 can safely use store_get to allocate store for your handle caching. The store
  61 will be reset after all xxx_tidy() functions are called.
  62
  63 The function interfaces are as follows:
  64
  65
  66 xxx_open()
  67 ----------
  68
  69 This function is called to initiate the lookup. For things that involve files
  70 it should do a real open; for other kinds of lookup it may do nothing at all.
  71 The arguments are:
  72
  73   uschar *filename    the name of the "file" to open, for non-query-style
  74                         lookups; NULL for query-style lookups
  75   uschar **errmsg     where to put an error message if there is a problem
  76
  77 The yield of xxx_open() is a void * value representing the open file or
  78 database. For real files is is normally the FILE or DBM value. For other
  79 kinds of lookup, if there is no natural value to use, (-1) is recommended.
  80 The value should not be NULL (or 0) as that is taken to indicate failure of
  81 the xxx_open() function. For single-key lookups, the handle is cached along
  82 with the filename and type, and may be used for several lookups.
  83
  84
  85 xxx_check()
  86 -----------
  87
  88 If this function exists, it is called after a successful open to check on the
  89 ownership and mode of the file(s). The arguments are:
  90
  91   void *handle        the handle passed back from xxx_open()
  92   uschar *filename    the filename passed to xxx_open()
  93   int modemask        mode bits that must not be set
  94   int *owners         permitted owners of the file(s)
  95   int *owngroups      permitted group owners of the file(s)
  96   uschar **errmsg     where to put an error message if there is a problem
  97
  98 In the owners and owngroups vectors, the first element is the count of the
  99 remaining elements. There is a common function that can be called to check
 100 a file:
 101
 102 int search_check_file(int fd, char *filename, int modemask, int *owners,
 103   int *owngroups, char *type, char **errmsg);
 104
 105 If fd is >= 0, it is checked using fstat(), and filename is used only in
 106 error messages. If fd is < 0 then filename is checked using stat(). The yield
 107 is zero if all is well, +1 if the mode or uid or gid is wrong, or -1 if the
 108 stat() fails.
 109
 110 The yield of xxx_check() is TRUE if all is well, FALSE otherwise. The
 111 function should not close the file(s) on failure. That is done from outside
 112 by calling the xxx_close() function.
 113
 114
 115 xxx_find()
 116 ----------
 117
 118 This is called to search an open file/database. The result is OK, FAIL, or
 119 DEFER. The arguments are:
 120
 121   void *handle        the handle passed back from xxx_open()
 122   uschar *filename    the filename passed to xxx_open() (NULL for querystyle)
 123   uschar *keyquery    the key to look up, or query to process, zero-terminated
 124   int  length         the length of the key
 125   uschar **result     point to the yield, in dynamic store, on success
 126   uschar **errmsg     where to put an error message on failure;
 127                       this is initially set to "", and should be left
 128                       as that for a standard "entry not found" error
 129   uint *do_cache      the lookup should set this to 0 when it changes data.
 130                       This is MAXINT by default. When set to 0 the cache tree
 131                       of the current search handle will be cleaned and the
 132                       current result will NOT be cached. Currently the mysql
 133                       and pgsql lookups use this when UPDATE/INSERT queries are
 134                       executed.
 135                       If set to a nonzero number of seconds, the cached value
 136                       becomes unusable after this time. Currently the dnsdb
 137                       lookup uses this to support the TTL value.
 138   uschar *opts        options, a comma-separated list of tagged values for
 139                       modifying the search operation
 140
 141 Even though the key is zero-terminated, the length is passed because in the
 142 common case it has been computed already and is often needed.
 143
 144
 145 xxx_close()
 146 -----------
 147
 148 This is called for single-key lookups when a file is finished with. There is no
 149 yield, and the only argument is the handle that was passed back from
 150 xxx_open(). It is not called for query style lookups.
 151
 152
 153 xxx_tidy()
 154 ----------
 155
 156 This function is called once at the end of search_tidyup() for every lookup
 157 type for which it exists.
 158
 159
 160 xxx_quote()
 161 -----------
 162
 163 This is called by the string expansion code for expansions of the form
 164 ${quote_xxx:<string>}, if it exists. If not, the expansion code makes no change
 165 to the string. The function must apply any quoting rules that are specific to
 166 the lookup, and return a pointer to the revised string. If quoting is not
 167 needed, it can return its single argument, which is a uschar *. This function
 168 does NOT use the POOL_SEARCH store, because it's usually never called from any
 169 lookup code.
 170
 171 xxx_version_report()
 172 --------------------
 173
 174 This is called to report diagnostic information to a file stream.
 175 Typically it would report both compile-time and run-time version information.
 176 The arguments are:
 177
 178   FILE *stream    where to fprintf() the data to
 179
 180
 181 ****