1 /* $Cambridge: exim/src/src/dbfn.c,v 1.6 2005/06/27 14:29:43 ph10 Exp $ */
3 /*************************************************
4 * Exim - an Internet mail transport agent *
5 *************************************************/
7 /* Copyright (c) University of Cambridge 1995 - 2005 */
8 /* See the file NOTICE for conditions of use and distribution. */
14 /* Functions for accessing Exim's hints database, which consists of a number of
15 different DBM files. This module does not contain code for reading DBM files
16 for (e.g.) alias expansion. That is all contained within the general search
17 functions. As Exim now has support for several DBM interfaces, all the relevant
18 functions are called as macros.
20 All the data in Exim's database is in the nature of *hints*. Therefore it
21 doesn't matter if it gets destroyed by accident. These functions are not
22 supposed to implement a "safe" database.
24 Keys are passed in as C strings, and the terminating zero *is* used when
25 building the dbm files. This just makes life easier when scanning the files
28 Synchronization is required on the database files, and this is achieved by
29 means of locking on independent lock files. (Earlier attempts to lock on the
30 DBM files themselves were never completely successful.) Since callers may in
31 general want to do more than one read or write while holding the lock, there
32 are separate open and close functions. However, the calling modules should
33 arrange to hold the locks for the bare minimum of time. */
37 /*************************************************
38 * Berkeley DB error callback *
39 *************************************************/
41 /* For Berkeley DB >= 2, we can define a function to be called in case of DB
42 errors. This should help with debugging strange DB problems, e.g. getting "File
43 exists" when you try to open a db file. The API for this function was changed
46 #if defined(USE_DB) && defined(DB_VERSION_STRING)
48 #if DB_VERSION_MAJOR > 4 || (DB_VERSION_MAJOR == 4 && DB_VERSION_MINOR >= 3)
49 dbfn_bdb_error_callback(const DB_ENV *dbenv, const char *pfx, const char *msg)
53 dbfn_bdb_error_callback(const char *pfx, char *msg)
57 log_write(0, LOG_MAIN, "Berkeley DB error: %s", msg);
64 /*************************************************
65 * Open and lock a database file *
66 *************************************************/
68 /* Used for accessing Exim's hints databases.
71 name The single-component name of one of Exim's database files.
72 flags Either O_RDONLY or O_RDWR, indicating the type of open required;
73 O_RDWR implies "create if necessary"
74 dbblock Points to an open_db block to be filled in.
75 lof If TRUE, write to the log for actual open failures (locking failures
78 Returns: NULL if the open failed, or the locking failed. After locking
79 failures, errno is zero.
81 On success, dbblock is returned. This contains the dbm pointer and
82 the fd of the locked lock file.
86 dbfn_open(uschar *name, int flags, open_db *dbblock, BOOL lof)
89 BOOL read_only = flags == O_RDONLY;
94 /* The first thing to do is to open a separate file on which to lock. This
95 ensures that Exim has exclusive use of the database before it even tries to
96 open it. Early versions tried to lock on the open database itself, but that
97 gave rise to mysterious problems from time to time - it was suspected that some
98 DB libraries "do things" on their open() calls which break the interlocking.
99 The lock file is never written to, but we open it for writing so we can get a
100 write lock if required. If it does not exist, we create it. This is done
101 separately so we know when we have done it, because when running as root we
102 need to change the ownership - see the bottom of this function. We also try to
103 make the directory as well, just in case. We won't be doing this many times
104 unnecessarily, because usually the lock file will be there. If the directory
105 exists, there is no error. */
107 sprintf(CS buffer, "%s/db/%s.lockfile", spool_directory, name);
109 if ((dbblock->lockfd = Uopen(buffer, O_RDWR, EXIMDB_LOCKFILE_MODE)) < 0)
112 (void)directory_make(spool_directory, US"db", EXIMDB_DIRECTORY_MODE, TRUE);
113 dbblock->lockfd = Uopen(buffer, O_RDWR|O_CREAT, EXIMDB_LOCKFILE_MODE);
116 if (dbblock->lockfd < 0)
118 log_write(0, LOG_MAIN, "%s",
119 string_open_failed(errno, "database lock file %s", buffer));
120 errno = 0; /* Indicates locking failure */
124 /* Now we must get a lock on the opened lock file; do this with a blocking
125 lock that times out. */
127 lock_data.l_type = read_only? F_RDLCK : F_WRLCK;
128 lock_data.l_whence = lock_data.l_start = lock_data.l_len = 0;
130 DEBUG(D_hints_lookup|D_retry|D_route|D_deliver)
131 debug_printf("locking %s\n", buffer);
133 sigalrm_seen = FALSE;
134 alarm(EXIMDB_LOCK_TIMEOUT);
135 rc = fcntl(dbblock->lockfd, F_SETLKW, &lock_data);
138 if (sigalrm_seen) errno = ETIMEDOUT;
141 log_write(0, LOG_MAIN, "Failed to get %s lock for %s: %s",
142 ((flags & O_RDONLY) != 0)? "read" : "write", buffer,
143 (errno == ETIMEDOUT)? "timed out" : strerror(errno));
144 (void)close(dbblock->lockfd);
145 errno = 0; /* Indicates locking failure */
149 DEBUG(D_hints_lookup) debug_printf("locked %s\n", buffer);
151 /* At this point we have an opened and locked separate lock file, that is,
152 exclusive access to the database, so we can go ahead and open it. If we are
153 expected to create it, don't do so at first, again so that we can detect
154 whether we need to change its ownership (see comments about the lock file
155 above.) There have been regular reports of crashes while opening hints
156 databases - often this is caused by non-matching db.h and the library. To make
157 it easy to pin this down, there are now debug statements on either side of the
160 sprintf(CS buffer, "%s/db/%s", spool_directory, name);
161 DEBUG(D_hints_lookup) debug_printf("EXIM_DBOPEN(%s)\n", buffer);
162 EXIM_DBOPEN(buffer, flags, EXIMDB_MODE, &(dbblock->dbptr));
163 DEBUG(D_hints_lookup) debug_printf("returned from EXIM_DBOPEN\n");
165 if (dbblock->dbptr == NULL && errno == ENOENT && flags == O_RDWR)
167 DEBUG(D_hints_lookup)
168 debug_printf("%s appears not to exist: trying to create\n", buffer);
170 EXIM_DBOPEN(buffer, flags|O_CREAT, EXIMDB_MODE, &(dbblock->dbptr));
171 DEBUG(D_hints_lookup) debug_printf("returned from EXIM_DBOPEN\n");
176 /* If we are running as root and this is the first access to the database, its
177 files will be owned by root. We want them to be owned by exim. We detect this
178 situation by noting above when we had to create the lock file or the database
179 itself. Because the different dbm libraries use different extensions for their
180 files, I don't know of any easier way of arranging this than scanning the
181 directory for files with the appropriate base name. At least this deals with
182 the lock file at the same time. Also, the directory will typically have only
183 half a dozen files, so the scan will be quick.
185 This code is placed here, before the test for successful opening, because there
186 was a case when a file was created, but the DBM library still returned NULL
187 because of some problem. It also sorts out the lock file if that was created
188 but creation of the database file failed. */
190 if (created && geteuid() == root_uid)
194 uschar *lastname = Ustrrchr(buffer, '/') + 1;
195 int namelen = Ustrlen(name);
198 dd = opendir(CS buffer);
200 while ((ent = readdir(dd)) != NULL)
202 if (Ustrncmp(ent->d_name, name, namelen) == 0)
205 Ustrcpy(lastname, ent->d_name);
206 if (Ustat(buffer, &statbuf) >= 0 && statbuf.st_uid != exim_uid)
208 DEBUG(D_hints_lookup) debug_printf("ensuring %s is owned by exim\n", buffer);
209 (void)Uchown(buffer, exim_uid, exim_gid);
217 /* If the open has failed, return NULL, leaving errno set. If lof is TRUE,
218 log the event - also for debugging - but not if the file just doesn't exist. */
220 if (dbblock->dbptr == NULL)
222 if (save_errno != ENOENT)
225 log_write(0, LOG_MAIN, "%s", string_open_failed(save_errno, "DB file %s",
228 DEBUG(D_hints_lookup)
229 debug_printf("%s", CS string_open_failed(save_errno, "DB file %s\n",
232 (void)close(dbblock->lockfd);
237 DEBUG(D_hints_lookup)
238 debug_printf("opened hints database %s: flags=%x\n", buffer, flags);
240 /* Pass back the block containing the opened database handle and the open fd
249 /*************************************************
250 * Unlock and close a database file *
251 *************************************************/
253 /* Closing a file automatically unlocks it, so after closing the database, just
256 Argument: a pointer to an open database block
261 dbfn_close(open_db *dbblock)
263 EXIM_DBCLOSE(dbblock->dbptr);
264 (void)close(dbblock->lockfd);
270 /*************************************************
271 * Read from database file *
272 *************************************************/
274 /* Passing back the pointer unchanged is useless, because there is
275 no guarantee of alignment. Since all the records used by Exim need
276 to be properly aligned to pick out the timestamps, etc., we might as
277 well do the copying centrally here.
279 Most calls don't need the length, so there is a macro called dbfn_read which
280 has two arguments; it calls this function adding NULL as the third.
283 dbblock a pointer to an open database block
284 key the key of the record to be read
285 length a pointer to an int into which to return the length, if not NULL
287 Returns: a pointer to the retrieved record, or
288 NULL if the record is not found
292 dbfn_read_with_length(open_db *dbblock, uschar *key, int *length)
295 EXIM_DATUM key_datum, result_datum;
297 DEBUG(D_hints_lookup) debug_printf("dbfn_read: key=%s\n", key);
299 EXIM_DATUM_INIT(key_datum); /* Some DBM libraries require the datum */
300 EXIM_DATUM_INIT(result_datum); /* to be cleared before use. */
301 EXIM_DATUM_DATA(key_datum) = CS key;
302 EXIM_DATUM_SIZE(key_datum) = Ustrlen(key) + 1;
304 if (!EXIM_DBGET(dbblock->dbptr, key_datum, result_datum)) return NULL;
306 yield = store_get(EXIM_DATUM_SIZE(result_datum));
307 memcpy(yield, EXIM_DATUM_DATA(result_datum), EXIM_DATUM_SIZE(result_datum));
308 if (length != NULL) *length = EXIM_DATUM_SIZE(result_datum);
310 EXIM_DATUM_FREE(result_datum); /* Some DBM libs require freeing */
316 /*************************************************
317 * Write to database file *
318 *************************************************/
322 dbblock a pointer to an open database block
323 key the key of the record to be written
324 ptr a pointer to the record to be written
325 length the length of the record to be written
327 Returns: the yield of the underlying dbm or db "write" function. If this
328 is dbm, the value is zero for OK.
332 dbfn_write(open_db *dbblock, uschar *key, void *ptr, int length)
334 EXIM_DATUM key_datum, value_datum;
335 dbdata_generic *gptr = (dbdata_generic *)ptr;
336 gptr->time_stamp = time(NULL);
338 DEBUG(D_hints_lookup) debug_printf("dbfn_write: key=%s\n", key);
340 EXIM_DATUM_INIT(key_datum); /* Some DBM libraries require the datum */
341 EXIM_DATUM_INIT(value_datum); /* to be cleared before use. */
342 EXIM_DATUM_DATA(key_datum) = CS key;
343 EXIM_DATUM_SIZE(key_datum) = Ustrlen(key) + 1;
344 EXIM_DATUM_DATA(value_datum) = CS ptr;
345 EXIM_DATUM_SIZE(value_datum) = length;
346 return EXIM_DBPUT(dbblock->dbptr, key_datum, value_datum);
351 /*************************************************
352 * Delete record from database file *
353 *************************************************/
357 dbblock a pointer to an open database block
358 key the key of the record to be deleted
360 Returns: the yield of the underlying dbm or db "delete" function.
364 dbfn_delete(open_db *dbblock, uschar *key)
366 EXIM_DATUM key_datum;
367 EXIM_DATUM_INIT(key_datum); /* Some DBM libraries require clearing */
368 EXIM_DATUM_DATA(key_datum) = CS key;
369 EXIM_DATUM_SIZE(key_datum) = Ustrlen(key) + 1;
370 return EXIM_DBDEL(dbblock->dbptr, key_datum);
375 /*************************************************
376 * Scan the keys of a database file *
377 *************************************************/
381 dbblock a pointer to an open database block
382 start TRUE if starting a new scan
383 FALSE if continuing with the current scan
384 cursor a pointer to a pointer to a cursor anchor, for those dbm libraries
385 that use the notion of a cursor
387 Returns: the next record from the file, or
388 NULL if there are no more
392 dbfn_scan(open_db *dbblock, BOOL start, EXIM_CURSOR **cursor)
394 EXIM_DATUM key_datum, value_datum;
396 value_datum = value_datum; /* dummy; not all db libraries use this */
398 /* Some dbm require an initialization */
400 if (start) EXIM_DBCREATE_CURSOR(dbblock->dbptr, cursor);
402 EXIM_DATUM_INIT(key_datum); /* Some DBM libraries require the datum */
403 EXIM_DATUM_INIT(value_datum); /* to be cleared before use. */
405 yield = (EXIM_DBSCAN(dbblock->dbptr, key_datum, value_datum, start, *cursor))?
406 US EXIM_DATUM_DATA(key_datum) : NULL;
408 /* Some dbm require a termination */
410 if (!yield) EXIM_DBDELETE_CURSOR(*cursor);
416 /*************************************************
417 **************************************************
418 * Stand-alone test program *
419 **************************************************
420 *************************************************/
425 main(int argc, char **cargv)
428 int max_db = sizeof(dbblock)/sizeof(open_db);
432 dbdata_wait *dbwait = NULL;
433 uschar **argv = USS cargv;
435 uschar structbuffer[1024];
439 printf("Usage: test_dbfn directory\n");
440 printf("The subdirectory called \"db\" in the given directory is used for\n");
441 printf("the files used in this test program.\n");
447 spool_directory = argv[1];
448 debug_selector = D_all - D_memory;
450 big_buffer = malloc(big_buffer_size);
452 for (i = 0; i < max_db; i++) dbblock[i].dbptr = NULL;
454 printf("\nExim's db functions tester: interface type is %s\n", EXIM_DBTYPE);
455 printf("DBM library: ");
457 #ifdef DB_VERSION_STRING
458 printf("Berkeley DB: %s\n", DB_VERSION_STRING);
459 #elif defined(BTREEVERSION) && defined(HASHVERSION)
461 printf("probably Berkeley DB version 1.8x (native mode)\n");
463 printf("probably Berkeley DB version 1.8x (compatibility mode)\n");
465 #elif defined(_DBM_RDONLY) || defined(dbm_dirfno)
466 printf("probably ndbm\n");
467 #elif defined(USE_TDB)
468 printf("using tdb\n");
471 printf("probably GDBM (native mode)\n");
473 printf("probably GDBM (compatibility mode)\n");
477 /* Test the functions */
479 printf("\nTest the functions\n> ");
481 while (Ufgets(buffer, 256, stdin) != NULL)
483 int len = Ustrlen(buffer);
487 uschar *cmd = buffer;
488 while (len > 0 && isspace((uschar)buffer[len-1])) len--;
491 if (isdigit((uschar)*cmd))
494 while (isdigit((uschar)*cmd)) cmd++;
495 while (isspace((uschar)*cmd)) cmd++;
498 if (Ustrncmp(cmd, "open", 4) == 0)
503 while (isspace((uschar)*s)) s++;
505 for (i = 0; i < max_db; i++)
506 if (dbblock[i].dbptr == NULL) break;
510 printf("Too many open databases\n> ");
515 odb = dbfn_open(s, O_RDWR, dbblock + i, TRUE);
521 printf("opened %d\n", current);
523 /* Other error cases will have written messages */
524 else if (errno == ENOENT)
526 printf("open failed: %s%s\n", strerror(errno),
528 " (or other Berkeley DB error)"
536 else if (Ustrncmp(cmd, "write", 5) == 0)
539 uschar *key = cmd + 5;
544 printf("No current database\n");
548 while (isspace((uschar)*key)) key++;
550 while (*data != 0 && !isspace((uschar)*data)) data++;
552 while (isspace((uschar)*data)) data++;
554 dbwait = (dbdata_wait *)(&structbuffer);
555 Ustrcpy(dbwait->text, data);
559 rc = dbfn_write(dbblock + current, key, dbwait,
560 Ustrlen(data) + sizeof(dbdata_wait));
562 if (rc != 0) printf("Failed: %s\n", strerror(errno));
565 else if (Ustrncmp(cmd, "read", 4) == 0)
567 uschar *key = cmd + 4;
570 printf("No current database\n");
573 while (isspace((uschar)*key)) key++;
576 dbwait = (dbdata_wait *)dbfn_read_with_length(dbblock+ current, key, NULL);
578 printf("%s\n", (dbwait == NULL)? "<not found>" : CS dbwait->text);
581 else if (Ustrncmp(cmd, "delete", 6) == 0)
583 uschar *key = cmd + 6;
586 printf("No current database\n");
589 while (isspace((uschar)*key)) key++;
590 dbfn_delete(dbblock + current, key);
593 else if (Ustrncmp(cmd, "scan", 4) == 0)
596 BOOL startflag = TRUE;
598 uschar keybuffer[256];
601 printf("No current database\n");
605 while ((key = dbfn_scan(dbblock + current, startflag, &cursor)) != NULL)
608 Ustrcpy(keybuffer, key);
609 dbwait = (dbdata_wait *)dbfn_read_with_length(dbblock + current,
611 printf("%s: %s\n", keybuffer, dbwait->text);
614 printf("End of scan\n");
617 else if (Ustrncmp(cmd, "close", 5) == 0)
620 while (isspace((uschar)*s)) s++;
622 if (i >= max_db || dbblock[i].dbptr == NULL) printf("Not open\n"); else
625 dbfn_close(dbblock + i);
627 dbblock[i].dbptr = NULL;
628 if (i == current) current = -1;
632 else if (Ustrncmp(cmd, "file", 4) == 0)
635 while (isspace((uschar)*s)) s++;
637 if (i >= max_db || dbblock[i].dbptr == NULL) printf("Not open\n");
641 else if (Ustrncmp(cmd, "time", 4) == 0)
643 showtime = ~showtime;
644 printf("Timing %s\n", showtime? "on" : "off");
647 else if (Ustrcmp(cmd, "q") == 0 || Ustrncmp(cmd, "quit", 4) == 0) break;
649 else if (Ustrncmp(cmd, "help", 4) == 0)
651 printf("close [<number>] close file [<number>]\n");
652 printf("delete <key> remove record from current file\n");
653 printf("file <number> make file <number> current\n");
654 printf("open <name> open db file\n");
655 printf("q[uit] exit program\n");
656 printf("read <key> read record from current file\n");
657 printf("scan scan current file\n");
658 printf("time time display on/off\n");
659 printf("write <key> <rest-of-line> write record to current file\n");
662 else printf("Eh?\n");
664 if (showtime && stop >= start)
665 printf("start=%d stop=%d difference=%d\n", (int)start, (int)stop,
666 (int)(stop - start));
671 for (i = 0; i < max_db; i++)
673 if (dbblock[i].dbptr != NULL)
675 printf("\nClosing %d", i);
676 dbfn_close(dbblock + i);