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