C99 initialisers
[exim.git] / src / src / lookups / README
CommitLineData
0756eb3c
PH
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
6545de78
PP
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.
0756eb3c
PH
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
13b685f9
PH
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
9f400174
JH
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.
0756eb3c
PH
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
14b3c5bc
JH
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
0756eb3c
PH
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.
14b3c5bc
JH
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.
0756eb3c
PH
138
139Even though the key is zero-terminated, the length is passed because in the
140common case it has been computed already and is often needed.
141
142
143xxx_close()
144-----------
145
146This is called for single-key lookups when a file is finished with. There is no
147yield, and the only argument is the handle that was passed back from
148xxx_open(). It is not called for query style lookups.
149
150
151xxx_tidy()
152----------
153
154This function is called once at the end of search_tidyup() for every lookup
155type for which it exists.
156
157
158xxx_quote()
159-----------
160
161This is called by the string expansion code for expansions of the form
162${quote_xxx:<string>}, if it exists. If not, the expansion code makes no change
163to the string. The function must apply any quoting rules that are specific to
164the lookup, and return a pointer to the revised string. If quoting is not
165needed, it can return its single argument, which is a uschar *. This function
166does NOT use the POOL_SEARCH store, because it's usually never called from any
167lookup code.
168
9f400174 169xxx_version_report()
6545de78
PP
170--------------------
171
172This is called to report diagnostic information to a file stream.
173Typically it would report both compile-time and run-time version information.
174The arguments are:
175
176 FILE *stream where to fprintf() the data to
177
178
0756eb3c 179****