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