Minor doc nits re bug 1262.
[users/jgh/exim.git] / src / src / dbfn.c
1 /*************************************************
2 *     Exim - an Internet mail transport agent    *
3 *************************************************/
4
5 /* Copyright (c) University of Cambridge 1995 - 2009 */
6 /* See the file NOTICE for conditions of use and distribution. */
7
8
9 #include "exim.h"
10
11
12 /* Functions for accessing Exim's hints database, which consists of a number of
13 different DBM files. This module does not contain code for reading DBM files
14 for (e.g.) alias expansion. That is all contained within the general search
15 functions. As Exim now has support for several DBM interfaces, all the relevant
16 functions are called as macros.
17
18 All the data in Exim's database is in the nature of *hints*. Therefore it
19 doesn't matter if it gets destroyed by accident. These functions are not
20 supposed to implement a "safe" database.
21
22 Keys are passed in as C strings, and the terminating zero *is* used when
23 building the dbm files. This just makes life easier when scanning the files
24 sequentially.
25
26 Synchronization is required on the database files, and this is achieved by
27 means of locking on independent lock files. (Earlier attempts to lock on the
28 DBM files themselves were never completely successful.) Since callers may in
29 general want to do more than one read or write while holding the lock, there
30 are separate open and close functions. However, the calling modules should
31 arrange to hold the locks for the bare minimum of time. */
32
33
34
35 /*************************************************
36 *         Berkeley DB error callback             *
37 *************************************************/
38
39 /* For Berkeley DB >= 2, we can define a function to be called in case of DB
40 errors. This should help with debugging strange DB problems, e.g. getting "File
41 exists" when you try to open a db file. The API for this function was changed
42 at DB release 4.3. */
43
44 #if defined(USE_DB) && defined(DB_VERSION_STRING)
45 void
46 #if DB_VERSION_MAJOR > 4 || (DB_VERSION_MAJOR == 4 && DB_VERSION_MINOR >= 3)
47 dbfn_bdb_error_callback(const DB_ENV *dbenv, const char *pfx, const char *msg)
48 {
49 dbenv = dbenv;
50 #else
51 dbfn_bdb_error_callback(const char *pfx, char *msg)
52 {
53 #endif
54 pfx = pfx;
55 log_write(0, LOG_MAIN, "Berkeley DB error: %s", msg);
56 }
57 #endif
58
59
60
61
62 /*************************************************
63 *          Open and lock a database file         *
64 *************************************************/
65
66 /* Used for accessing Exim's hints databases.
67
68 Arguments:
69   name     The single-component name of one of Exim's database files.
70   flags    Either O_RDONLY or O_RDWR, indicating the type of open required;
71              O_RDWR implies "create if necessary"
72   dbblock  Points to an open_db block to be filled in.
73   lof      If TRUE, write to the log for actual open failures (locking failures
74            are always logged).
75
76 Returns:   NULL if the open failed, or the locking failed. After locking
77            failures, errno is zero.
78
79            On success, dbblock is returned. This contains the dbm pointer and
80            the fd of the locked lock file.
81
82 There are some calls that use O_RDWR|O_CREAT for the flags. Having discovered
83 this in December 2005, I'm not sure if this is correct or not, but for the
84 moment I haven't changed them.
85 */
86
87 open_db *
88 dbfn_open(uschar *name, int flags, open_db *dbblock, BOOL lof)
89 {
90 int rc, save_errno;
91 BOOL read_only = flags == O_RDONLY;
92 BOOL created = FALSE;
93 flock_t lock_data;
94 uschar buffer[256];
95
96 /* The first thing to do is to open a separate file on which to lock. This
97 ensures that Exim has exclusive use of the database before it even tries to
98 open it. Early versions tried to lock on the open database itself, but that
99 gave rise to mysterious problems from time to time - it was suspected that some
100 DB libraries "do things" on their open() calls which break the interlocking.
101 The lock file is never written to, but we open it for writing so we can get a
102 write lock if required. If it does not exist, we create it. This is done
103 separately so we know when we have done it, because when running as root we
104 need to change the ownership - see the bottom of this function. We also try to
105 make the directory as well, just in case. We won't be doing this many times
106 unnecessarily, because usually the lock file will be there. If the directory
107 exists, there is no error. */
108
109 sprintf(CS buffer, "%s/db/%s.lockfile", spool_directory, name);
110
111 if ((dbblock->lockfd = Uopen(buffer, O_RDWR, EXIMDB_LOCKFILE_MODE)) < 0)
112   {
113   created = TRUE;
114   (void)directory_make(spool_directory, US"db", EXIMDB_DIRECTORY_MODE, TRUE);
115   dbblock->lockfd = Uopen(buffer, O_RDWR|O_CREAT, EXIMDB_LOCKFILE_MODE);
116   }
117
118 if (dbblock->lockfd < 0)
119   {
120   log_write(0, LOG_MAIN, "%s",
121     string_open_failed(errno, "database lock file %s", buffer));
122   errno = 0;      /* Indicates locking failure */
123   return NULL;
124   }
125
126 /* Now we must get a lock on the opened lock file; do this with a blocking
127 lock that times out. */
128
129 lock_data.l_type = read_only? F_RDLCK : F_WRLCK;
130 lock_data.l_whence = lock_data.l_start = lock_data.l_len = 0;
131
132 DEBUG(D_hints_lookup|D_retry|D_route|D_deliver)
133   debug_printf("locking %s\n", buffer);
134
135 sigalrm_seen = FALSE;
136 alarm(EXIMDB_LOCK_TIMEOUT);
137 rc = fcntl(dbblock->lockfd, F_SETLKW, &lock_data);
138 alarm(0);
139
140 if (sigalrm_seen) errno = ETIMEDOUT;
141 if (rc < 0)
142   {
143   log_write(0, LOG_MAIN|LOG_PANIC, "Failed to get %s lock for %s: %s",
144     read_only? "read" : "write", buffer,
145     (errno == ETIMEDOUT)? "timed out" : strerror(errno));
146   (void)close(dbblock->lockfd);
147   errno = 0;       /* Indicates locking failure */
148   return NULL;
149   }
150
151 DEBUG(D_hints_lookup) debug_printf("locked %s\n", buffer);
152
153 /* At this point we have an opened and locked separate lock file, that is,
154 exclusive access to the database, so we can go ahead and open it. If we are
155 expected to create it, don't do so at first, again so that we can detect
156 whether we need to change its ownership (see comments about the lock file
157 above.) There have been regular reports of crashes while opening hints
158 databases - often this is caused by non-matching db.h and the library. To make
159 it easy to pin this down, there are now debug statements on either side of the
160 open call. */
161
162 sprintf(CS buffer, "%s/db/%s", spool_directory, name);
163 DEBUG(D_hints_lookup) debug_printf("EXIM_DBOPEN(%s)\n", buffer);
164 EXIM_DBOPEN(buffer, flags, EXIMDB_MODE, &(dbblock->dbptr));
165 DEBUG(D_hints_lookup) debug_printf("returned from EXIM_DBOPEN\n");
166
167 if (dbblock->dbptr == NULL && errno == ENOENT && flags == O_RDWR)
168   {
169   DEBUG(D_hints_lookup)
170     debug_printf("%s appears not to exist: trying to create\n", buffer);
171   created = TRUE;
172   EXIM_DBOPEN(buffer, flags|O_CREAT, EXIMDB_MODE, &(dbblock->dbptr));
173   DEBUG(D_hints_lookup) debug_printf("returned from EXIM_DBOPEN\n");
174   }
175
176 save_errno = errno;
177
178 /* If we are running as root and this is the first access to the database, its
179 files will be owned by root. We want them to be owned by exim. We detect this
180 situation by noting above when we had to create the lock file or the database
181 itself. Because the different dbm libraries use different extensions for their
182 files, I don't know of any easier way of arranging this than scanning the
183 directory for files with the appropriate base name. At least this deals with
184 the lock file at the same time. Also, the directory will typically have only
185 half a dozen files, so the scan will be quick.
186
187 This code is placed here, before the test for successful opening, because there
188 was a case when a file was created, but the DBM library still returned NULL
189 because of some problem. It also sorts out the lock file if that was created
190 but creation of the database file failed. */
191
192 if (created && geteuid() == root_uid)
193   {
194   DIR *dd;
195   struct dirent *ent;
196   uschar *lastname = Ustrrchr(buffer, '/') + 1;
197   int namelen = Ustrlen(name);
198
199   *lastname = 0;
200   dd = opendir(CS buffer);
201
202   while ((ent = readdir(dd)) != NULL)
203     {
204     if (Ustrncmp(ent->d_name, name, namelen) == 0)
205       {
206       struct stat statbuf;
207       Ustrcpy(lastname, ent->d_name);
208       if (Ustat(buffer, &statbuf) >= 0 && statbuf.st_uid != exim_uid)
209         {
210         DEBUG(D_hints_lookup) debug_printf("ensuring %s is owned by exim\n", buffer);
211         (void)Uchown(buffer, exim_uid, exim_gid);
212         }
213       }
214     }
215
216   closedir(dd);
217   }
218
219 /* If the open has failed, return NULL, leaving errno set. If lof is TRUE,
220 log the event - also for debugging - but not if the file just doesn't exist. */
221
222 if (dbblock->dbptr == NULL)
223   {
224   if (save_errno != ENOENT)
225     {
226     if (lof)
227       log_write(0, LOG_MAIN, "%s", string_open_failed(save_errno, "DB file %s",
228         buffer));
229     else
230       DEBUG(D_hints_lookup)
231         debug_printf("%s", CS string_open_failed(save_errno, "DB file %s\n",
232           buffer));
233     }
234   (void)close(dbblock->lockfd);
235   errno = save_errno;
236   return NULL;
237   }
238
239 DEBUG(D_hints_lookup)
240   debug_printf("opened hints database %s: flags=%s\n", buffer,
241     (flags == O_RDONLY)? "O_RDONLY" : (flags == O_RDWR)? "O_RDWR" :
242     (flags == (O_RDWR|O_CREAT))? "O_RDWR|O_CREAT" : "??");
243
244 /* Pass back the block containing the opened database handle and the open fd
245 for the lock. */
246
247 return dbblock;
248 }
249
250
251
252
253 /*************************************************
254 *         Unlock and close a database file       *
255 *************************************************/
256
257 /* Closing a file automatically unlocks it, so after closing the database, just
258 close the lock file.
259
260 Argument: a pointer to an open database block
261 Returns:  nothing
262 */
263
264 void
265 dbfn_close(open_db *dbblock)
266 {
267 EXIM_DBCLOSE(dbblock->dbptr);
268 (void)close(dbblock->lockfd);
269 }
270
271
272
273
274 /*************************************************
275 *             Read from database file            *
276 *************************************************/
277
278 /* Passing back the pointer unchanged is useless, because there is
279 no guarantee of alignment. Since all the records used by Exim need
280 to be properly aligned to pick out the timestamps, etc., we might as
281 well do the copying centrally here.
282
283 Most calls don't need the length, so there is a macro called dbfn_read which
284 has two arguments; it calls this function adding NULL as the third.
285
286 Arguments:
287   dbblock   a pointer to an open database block
288   key       the key of the record to be read
289   length    a pointer to an int into which to return the length, if not NULL
290
291 Returns: a pointer to the retrieved record, or
292          NULL if the record is not found
293 */
294
295 void *
296 dbfn_read_with_length(open_db *dbblock, uschar *key, int *length)
297 {
298 void *yield;
299 EXIM_DATUM key_datum, result_datum;
300
301 DEBUG(D_hints_lookup) debug_printf("dbfn_read: key=%s\n", key);
302
303 EXIM_DATUM_INIT(key_datum);         /* Some DBM libraries require the datum */
304 EXIM_DATUM_INIT(result_datum);      /* to be cleared before use. */
305 EXIM_DATUM_DATA(key_datum) = CS key;
306 EXIM_DATUM_SIZE(key_datum) = Ustrlen(key) + 1;
307
308 if (!EXIM_DBGET(dbblock->dbptr, key_datum, result_datum)) return NULL;
309
310 yield = store_get(EXIM_DATUM_SIZE(result_datum));
311 memcpy(yield, EXIM_DATUM_DATA(result_datum), EXIM_DATUM_SIZE(result_datum));
312 if (length != NULL) *length = EXIM_DATUM_SIZE(result_datum);
313
314 EXIM_DATUM_FREE(result_datum);    /* Some DBM libs require freeing */
315 return yield;
316 }
317
318
319
320 /*************************************************
321 *             Write to database file             *
322 *************************************************/
323
324 /*
325 Arguments:
326   dbblock   a pointer to an open database block
327   key       the key of the record to be written
328   ptr       a pointer to the record to be written
329   length    the length of the record to be written
330
331 Returns:    the yield of the underlying dbm or db "write" function. If this
332             is dbm, the value is zero for OK.
333 */
334
335 int
336 dbfn_write(open_db *dbblock, uschar *key, void *ptr, int length)
337 {
338 EXIM_DATUM key_datum, value_datum;
339 dbdata_generic *gptr = (dbdata_generic *)ptr;
340 gptr->time_stamp = time(NULL);
341
342 DEBUG(D_hints_lookup) debug_printf("dbfn_write: key=%s\n", key);
343
344 EXIM_DATUM_INIT(key_datum);         /* Some DBM libraries require the datum */
345 EXIM_DATUM_INIT(value_datum);       /* to be cleared before use. */
346 EXIM_DATUM_DATA(key_datum) = CS key;
347 EXIM_DATUM_SIZE(key_datum) = Ustrlen(key) + 1;
348 EXIM_DATUM_DATA(value_datum) = CS ptr;
349 EXIM_DATUM_SIZE(value_datum) = length;
350 return EXIM_DBPUT(dbblock->dbptr, key_datum, value_datum);
351 }
352
353
354
355 /*************************************************
356 *           Delete record from database file     *
357 *************************************************/
358
359 /*
360 Arguments:
361   dbblock    a pointer to an open database block
362   key        the key of the record to be deleted
363
364 Returns: the yield of the underlying dbm or db "delete" function.
365 */
366
367 int
368 dbfn_delete(open_db *dbblock, uschar *key)
369 {
370 EXIM_DATUM key_datum;
371 EXIM_DATUM_INIT(key_datum);         /* Some DBM libraries require clearing */
372 EXIM_DATUM_DATA(key_datum) = CS key;
373 EXIM_DATUM_SIZE(key_datum) = Ustrlen(key) + 1;
374 return EXIM_DBDEL(dbblock->dbptr, key_datum);
375 }
376
377
378
379 /*************************************************
380 *         Scan the keys of a database file       *
381 *************************************************/
382
383 /*
384 Arguments:
385   dbblock  a pointer to an open database block
386   start    TRUE if starting a new scan
387            FALSE if continuing with the current scan
388   cursor   a pointer to a pointer to a cursor anchor, for those dbm libraries
389            that use the notion of a cursor
390
391 Returns:   the next record from the file, or
392            NULL if there are no more
393 */
394
395 uschar *
396 dbfn_scan(open_db *dbblock, BOOL start, EXIM_CURSOR **cursor)
397 {
398 EXIM_DATUM key_datum, value_datum;
399 uschar *yield;
400 value_datum = value_datum;    /* dummy; not all db libraries use this */
401
402 /* Some dbm require an initialization */
403
404 if (start) EXIM_DBCREATE_CURSOR(dbblock->dbptr, cursor);
405
406 EXIM_DATUM_INIT(key_datum);         /* Some DBM libraries require the datum */
407 EXIM_DATUM_INIT(value_datum);       /* to be cleared before use. */
408
409 yield = (EXIM_DBSCAN(dbblock->dbptr, key_datum, value_datum, start, *cursor))?
410   US EXIM_DATUM_DATA(key_datum) : NULL;
411
412 /* Some dbm require a termination */
413
414 if (!yield) EXIM_DBDELETE_CURSOR(*cursor);
415 return yield;
416 }
417
418
419
420 /*************************************************
421 **************************************************
422 *             Stand-alone test program           *
423 **************************************************
424 *************************************************/
425
426 #ifdef STAND_ALONE
427
428 int
429 main(int argc, char **cargv)
430 {
431 open_db dbblock[8];
432 int max_db = sizeof(dbblock)/sizeof(open_db);
433 int current = -1;
434 int showtime = 0;
435 int i;
436 dbdata_wait *dbwait = NULL;
437 uschar **argv = USS cargv;
438 uschar buffer[256];
439 uschar structbuffer[1024];
440
441 if (argc != 2)
442   {
443   printf("Usage: test_dbfn directory\n");
444   printf("The subdirectory called \"db\" in the given directory is used for\n");
445   printf("the files used in this test program.\n");
446   return 1;
447   }
448
449 /* Initialize */
450
451 spool_directory = argv[1];
452 debug_selector = D_all - D_memory;
453 debug_file = stderr;
454 big_buffer = malloc(big_buffer_size);
455
456 for (i = 0; i < max_db; i++) dbblock[i].dbptr = NULL;
457
458 printf("\nExim's db functions tester: interface type is %s\n", EXIM_DBTYPE);
459 printf("DBM library: ");
460
461 #ifdef DB_VERSION_STRING
462 printf("Berkeley DB: %s\n", DB_VERSION_STRING);
463 #elif defined(BTREEVERSION) && defined(HASHVERSION)
464   #ifdef USE_DB
465   printf("probably Berkeley DB version 1.8x (native mode)\n");
466   #else
467   printf("probably Berkeley DB version 1.8x (compatibility mode)\n");
468   #endif
469 #elif defined(_DBM_RDONLY) || defined(dbm_dirfno)
470 printf("probably ndbm\n");
471 #elif defined(USE_TDB)
472 printf("using tdb\n");
473 #else
474   #ifdef USE_GDBM
475   printf("probably GDBM (native mode)\n");
476   #else
477   printf("probably GDBM (compatibility mode)\n");
478   #endif
479 #endif
480
481 /* Test the functions */
482
483 printf("\nTest the functions\n> ");
484
485 while (Ufgets(buffer, 256, stdin) != NULL)
486   {
487   int len = Ustrlen(buffer);
488   int count = 1;
489   clock_t start = 1;
490   clock_t stop = 0;
491   uschar *cmd = buffer;
492   while (len > 0 && isspace((uschar)buffer[len-1])) len--;
493   buffer[len] = 0;
494
495   if (isdigit((uschar)*cmd))
496     {
497     count = Uatoi(cmd);
498     while (isdigit((uschar)*cmd)) cmd++;
499     while (isspace((uschar)*cmd)) cmd++;
500     }
501
502   if (Ustrncmp(cmd, "open", 4) == 0)
503     {
504     int i;
505     open_db *odb;
506     uschar *s = cmd + 4;
507     while (isspace((uschar)*s)) s++;
508
509     for (i = 0; i < max_db; i++)
510       if (dbblock[i].dbptr == NULL) break;
511
512     if (i >= max_db)
513       {
514       printf("Too many open databases\n> ");
515       continue;
516       }
517
518     start = clock();
519     odb = dbfn_open(s, O_RDWR, dbblock + i, TRUE);
520     stop = clock();
521
522     if (odb != NULL)
523       {
524       current = i;
525       printf("opened %d\n", current);
526       }
527     /* Other error cases will have written messages */
528     else if (errno == ENOENT)
529       {
530       printf("open failed: %s%s\n", strerror(errno),
531         #ifdef USE_DB
532         " (or other Berkeley DB error)"
533         #else
534         ""
535         #endif
536         );
537       }
538     }
539
540   else if (Ustrncmp(cmd, "write", 5) == 0)
541     {
542     int rc = 0;
543     uschar *key = cmd + 5;
544     uschar *data;
545
546     if (current < 0)
547       {
548       printf("No current database\n");
549       continue;
550       }
551
552     while (isspace((uschar)*key)) key++;
553     data = key;
554     while (*data != 0 && !isspace((uschar)*data)) data++;
555     *data++ = 0;
556     while (isspace((uschar)*data)) data++;
557
558     dbwait = (dbdata_wait *)(&structbuffer);
559     Ustrcpy(dbwait->text, data);
560
561     start = clock();
562     while (count-- > 0)
563       rc = dbfn_write(dbblock + current, key, dbwait,
564         Ustrlen(data) + sizeof(dbdata_wait));
565     stop = clock();
566     if (rc != 0) printf("Failed: %s\n", strerror(errno));
567     }
568
569   else if (Ustrncmp(cmd, "read", 4) == 0)
570     {
571     uschar *key = cmd + 4;
572     if (current < 0)
573       {
574       printf("No current database\n");
575       continue;
576       }
577     while (isspace((uschar)*key)) key++;
578     start = clock();
579     while (count-- > 0)
580       dbwait = (dbdata_wait *)dbfn_read_with_length(dbblock+ current, key, NULL);
581     stop = clock();
582     printf("%s\n", (dbwait == NULL)? "<not found>" : CS dbwait->text);
583     }
584
585   else if (Ustrncmp(cmd, "delete", 6) == 0)
586     {
587     uschar *key = cmd + 6;
588     if (current < 0)
589       {
590       printf("No current database\n");
591       continue;
592       }
593     while (isspace((uschar)*key)) key++;
594     dbfn_delete(dbblock + current, key);
595     }
596
597   else if (Ustrncmp(cmd, "scan", 4) == 0)
598     {
599     EXIM_CURSOR *cursor;
600     BOOL startflag = TRUE;
601     uschar *key;
602     uschar keybuffer[256];
603     if (current < 0)
604       {
605       printf("No current database\n");
606       continue;
607       }
608     start = clock();
609     while ((key = dbfn_scan(dbblock + current, startflag, &cursor)) != NULL)
610       {
611       startflag = FALSE;
612       Ustrcpy(keybuffer, key);
613       dbwait = (dbdata_wait *)dbfn_read_with_length(dbblock + current,
614         keybuffer, NULL);
615       printf("%s: %s\n", keybuffer, dbwait->text);
616       }
617     stop = clock();
618     printf("End of scan\n");
619     }
620
621   else if (Ustrncmp(cmd, "close", 5) == 0)
622     {
623     uschar *s = cmd + 5;
624     while (isspace((uschar)*s)) s++;
625     i = Uatoi(s);
626     if (i >= max_db || dbblock[i].dbptr == NULL) printf("Not open\n"); else
627       {
628       start = clock();
629       dbfn_close(dbblock + i);
630       stop = clock();
631       dbblock[i].dbptr = NULL;
632       if (i == current) current = -1;
633       }
634     }
635
636   else if (Ustrncmp(cmd, "file", 4) == 0)
637     {
638     uschar *s = cmd + 4;
639     while (isspace((uschar)*s)) s++;
640     i = Uatoi(s);
641     if (i >= max_db || dbblock[i].dbptr == NULL) printf("Not open\n");
642       else current = i;
643     }
644
645   else if (Ustrncmp(cmd, "time", 4) == 0)
646     {
647     showtime = ~showtime;
648     printf("Timing %s\n", showtime? "on" : "off");
649     }
650
651   else if (Ustrcmp(cmd, "q") == 0 || Ustrncmp(cmd, "quit", 4) == 0) break;
652
653   else if (Ustrncmp(cmd, "help", 4) == 0)
654     {
655     printf("close  [<number>]              close file [<number>]\n");
656     printf("delete <key>                   remove record from current file\n");
657     printf("file   <number>                make file <number> current\n");
658     printf("open   <name>                  open db file\n");
659     printf("q[uit]                         exit program\n");
660     printf("read   <key>                   read record from current file\n");
661     printf("scan                           scan current file\n");
662     printf("time                           time display on/off\n");
663     printf("write  <key> <rest-of-line>    write record to current file\n");
664     }
665
666   else printf("Eh?\n");
667
668   if (showtime && stop >= start)
669     printf("start=%d stop=%d difference=%d\n", (int)start, (int)stop,
670      (int)(stop - start));
671
672   printf("> ");
673   }
674
675 for (i = 0; i < max_db; i++)
676   {
677   if (dbblock[i].dbptr != NULL)
678     {
679     printf("\nClosing %d", i);
680     dbfn_close(dbblock + i);
681     }
682   }
683
684 printf("\n");
685 return 0;
686 }
687
688 #endif
689
690 /* End of dbfn.c */