| 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. The xxx_close() function is not called when the first lookup is |
| 38 | completed. If there are subsequent lookups of the same type that quote the same |
| 39 | file name, xxx_open() isn't called; instead the cached handle is re-used. |
| 40 | |
| 41 | Exim calls the function search_tidyup() at strategic points in its processing |
| 42 | (e.g. after all routing and directing has been done) and this function walks |
| 43 | the tree and calls the xxx_close() functions for all the cached handles. |
| 44 | |
| 45 | Query-style lookups don't have the concept of an open file that can be cached |
| 46 | this way. Of course, the local code for the lookup can manage its own caching |
| 47 | information in any way it pleases. This means that the xxx_close() |
| 48 | function, even it it exists, is never called. However, if an xxx_tidy() |
| 49 | function exists, it is called once whenever Exim calls search_tidyup(). |
| 50 | |
| 51 | A single-key lookup type may also have an xxx_tidy() function, which is called |
| 52 | by search_tidyup() after all cached handles have been closed via the |
| 53 | xxx_close() function. |
| 54 | |
| 55 | The lookup functions are wrapped into a special store pool (POOL_SEARCH). You |
| 56 | can safely use store_get to allocate store for your handle caching. The store |
| 57 | will be reset after all xxx_tidy() functions are called. |
| 58 | |
| 59 | The function interfaces are as follows: |
| 60 | |
| 61 | |
| 62 | xxx_open() |
| 63 | ---------- |
| 64 | |
| 65 | This function is called to initiate the lookup. For things that involve files |
| 66 | it should do a real open; for other kinds of lookup it may do nothing at all. |
| 67 | The arguments are: |
| 68 | |
| 69 | uschar *filename the name of the "file" to open, for non-query-style |
| 70 | lookups; NULL for query-style lookups |
| 71 | uschar **errmsg where to put an error message if there is a problem |
| 72 | |
| 73 | The yield of xxx_open() is a void * value representing the open file or |
| 74 | database. For real files is is normally the FILE or DBM value. For other |
| 75 | kinds of lookup, if there is no natural value to use, (-1) is recommended. |
| 76 | The value should not be NULL (or 0) as that is taken to indicate failure of |
| 77 | the xxx_open() function. For single-key lookups, the handle is cached along |
| 78 | with the filename and type, and may be used for several lookups. |
| 79 | |
| 80 | |
| 81 | xxx_check() |
| 82 | ----------- |
| 83 | |
| 84 | If this function exists, it is called after a successful open to check on the |
| 85 | ownership and mode of the file(s). The arguments are: |
| 86 | |
| 87 | void *handle the handle passed back from xxx_open() |
| 88 | uschar *filename the filename passed to xxx_open() |
| 89 | int modemask mode bits that must not be set |
| 90 | int *owners permitted owners of the file(s) |
| 91 | int *owngroups permitted group owners of the file(s) |
| 92 | uschar **errmsg where to put an error message if there is a problem |
| 93 | |
| 94 | In the owners and owngroups vectors, the first element is the count of the |
| 95 | remaining elements. There is a common function that can be called to check |
| 96 | a file: |
| 97 | |
| 98 | int search_check_file(int fd, char *filename, int modemask, int *owners, |
| 99 | int *owngroups, char *type, char **errmsg); |
| 100 | |
| 101 | If fd is >= 0, it is checked using fstat(), and filename is used only in |
| 102 | error messages. If fd is < 0 then filename is checked using stat(). The yield |
| 103 | is zero if all is well, +1 if the mode or uid or gid is wrong, or -1 if the |
| 104 | stat() fails. |
| 105 | |
| 106 | The yield of xxx_check() is TRUE if all is well, FALSE otherwise. The |
| 107 | function should not close the file(s) on failure. That is done from outside |
| 108 | by calling the xxx_close() function. |
| 109 | |
| 110 | |
| 111 | xxx_find() |
| 112 | ---------- |
| 113 | |
| 114 | This is called to search an open file/database. The result is OK, FAIL, or |
| 115 | DEFER. The arguments are: |
| 116 | |
| 117 | void *handle the handle passed back from xxx_open() |
| 118 | uschar *filename the filename passed to xxx_open() (NULL for querystyle) |
| 119 | uschar *keyquery the key to look up, or query to process, zero-terminated |
| 120 | int length the length of the key |
| 121 | uschar **result point to the yield, in dynamic store, on success |
| 122 | uschar **errmsg where to put an error message on failure; |
| 123 | this is initially set to "", and should be left |
| 124 | as that for a standard "entry not found" error |
| 125 | BOOL *do_cache the lookup should set this to FALSE when it changes data. |
| 126 | This is TRUE by default. When set to FALSE the cache tree |
| 127 | of the current search handle will be cleaned and the |
| 128 | current result will NOT be cached. Currently the mysql |
| 129 | and pgsql lookups use this when UPDATE/INSERT queries are |
| 130 | executed. |
| 131 | |
| 132 | Even though the key is zero-terminated, the length is passed because in the |
| 133 | common case it has been computed already and is often needed. |
| 134 | |
| 135 | |
| 136 | xxx_close() |
| 137 | ----------- |
| 138 | |
| 139 | This is called for single-key lookups when a file is finished with. There is no |
| 140 | yield, and the only argument is the handle that was passed back from |
| 141 | xxx_open(). It is not called for query style lookups. |
| 142 | |
| 143 | |
| 144 | xxx_tidy() |
| 145 | ---------- |
| 146 | |
| 147 | This function is called once at the end of search_tidyup() for every lookup |
| 148 | type for which it exists. |
| 149 | |
| 150 | |
| 151 | xxx_quote() |
| 152 | ----------- |
| 153 | |
| 154 | This is called by the string expansion code for expansions of the form |
| 155 | ${quote_xxx:<string>}, if it exists. If not, the expansion code makes no change |
| 156 | to the string. The function must apply any quoting rules that are specific to |
| 157 | the lookup, and return a pointer to the revised string. If quoting is not |
| 158 | needed, it can return its single argument, which is a uschar *. This function |
| 159 | does NOT use the POOL_SEARCH store, because it's usually never called from any |
| 160 | lookup code. |
| 161 | |
| 162 | xxx_report_version() |
| 163 | -------------------- |
| 164 | |
| 165 | This is called to report diagnostic information to a file stream. |
| 166 | Typically it would report both compile-time and run-time version information. |
| 167 | The arguments are: |
| 168 | |
| 169 | FILE *stream where to fprintf() the data to |
| 170 | |
| 171 | |
| 172 | **** |