1 /* $Cambridge: exim/src/src/dbfn.c,v 1.2 2005/01/04 10:00:42 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. */
45 #if defined(USE_DB) && defined(DB_VERSION_STRING)
47 dbfn_bdb_error_callback(const char *pfx, char *msg)
50 log_write(0, LOG_MAIN, "Berkeley DB error: %s", msg);
57 /*************************************************
58 * Open and lock a database file *
59 *************************************************/
61 /* Used for accessing Exim's hints databases.
64 name The single-component name of one of Exim's database files.
65 flags Either O_RDONLY or O_RDWR, indicating the type of open required;
66 O_RDWR implies "create if necessary"
67 dbblock Points to an open_db block to be filled in.
68 lof If TRUE, write to the log for actual open failures (locking failures
71 Returns: NULL if the open failed, or the locking failed. After locking
72 failures, errno is zero.
74 On success, dbblock is returned. This contains the dbm pointer and
75 the fd of the locked lock file.
79 dbfn_open(uschar *name, int flags, open_db *dbblock, BOOL lof)
82 BOOL read_only = flags == O_RDONLY;
87 /* The first thing to do is to open a separate file on which to lock. This
88 ensures that Exim has exclusive use of the database before it even tries to
89 open it. Early versions tried to lock on the open database itself, but that
90 gave rise to mysterious problems from time to time - it was suspected that some
91 DB libraries "do things" on their open() calls which break the interlocking.
92 The lock file is never written to, but we open it for writing so we can get a
93 write lock if required. If it does not exist, we create it. This is done
94 separately so we know when we have done it, because when running as root we
95 need to change the ownership - see the bottom of this function. We also try to
96 make the directory as well, just in case. We won't be doing this many times
97 unnecessarily, because usually the lock file will be there. If the directory
98 exists, there is no error. */
100 sprintf(CS buffer, "%s/db/%s.lockfile", spool_directory, name);
102 if ((dbblock->lockfd = Uopen(buffer, O_RDWR, EXIMDB_LOCKFILE_MODE)) < 0)
105 (void)directory_make(spool_directory, US"db", EXIMDB_DIRECTORY_MODE, TRUE);
106 dbblock->lockfd = Uopen(buffer, O_RDWR|O_CREAT, EXIMDB_LOCKFILE_MODE);
109 if (dbblock->lockfd < 0)
111 log_write(0, LOG_MAIN, "%s",
112 string_open_failed(errno, "database lock file %s", buffer));
113 errno = 0; /* Indicates locking failure */
117 /* Now we must get a lock on the opened lock file; do this with a blocking
118 lock that times out. */
120 lock_data.l_type = read_only? F_RDLCK : F_WRLCK;
121 lock_data.l_whence = lock_data.l_start = lock_data.l_len = 0;
123 DEBUG(D_hints_lookup|D_retry|D_route|D_deliver)
124 debug_printf("locking %s\n", buffer);
126 sigalrm_seen = FALSE;
127 alarm(EXIMDB_LOCK_TIMEOUT);
128 rc = fcntl(dbblock->lockfd, F_SETLKW, &lock_data);
131 if (sigalrm_seen) errno = ETIMEDOUT;
134 log_write(0, LOG_MAIN, "Failed to get %s lock for %s: %s",
135 ((flags & O_RDONLY) != 0)? "read" : "write", buffer,
136 (errno == ETIMEDOUT)? "timed out" : strerror(errno));
137 close(dbblock->lockfd);
138 errno = 0; /* Indicates locking failure */
142 DEBUG(D_hints_lookup) debug_printf("locked %s\n", buffer);
144 /* At this point we have an opened and locked separate lock file, that is,
145 exclusive access to the database, so we can go ahead and open it. If we are
146 expected to create it, don't do so at first, again so that we can detect
147 whether we need to change its ownership (see comments about the lock file
150 sprintf(CS buffer, "%s/db/%s", spool_directory, name);
151 EXIM_DBOPEN(buffer, flags, EXIMDB_MODE, &(dbblock->dbptr));
153 if (dbblock->dbptr == NULL && errno == ENOENT && flags == O_RDWR)
155 DEBUG(D_hints_lookup)
156 debug_printf("%s appears not to exist: trying to create\n", buffer);
158 EXIM_DBOPEN(buffer, flags|O_CREAT, EXIMDB_MODE, &(dbblock->dbptr));
163 /* If we are running as root and this is the first access to the database, its
164 files will be owned by root. We want them to be owned by exim. We detect this
165 situation by noting above when we had to create the lock file or the database
166 itself. Because the different dbm libraries use different extensions for their
167 files, I don't know of any easier way of arranging this than scanning the
168 directory for files with the appropriate base name. At least this deals with
169 the lock file at the same time. Also, the directory will typically have only
170 half a dozen files, so the scan will be quick.
172 This code is placed here, before the test for successful opening, because there
173 was a case when a file was created, but the DBM library still returned NULL
174 because of some problem. It also sorts out the lock file if that was created
175 but creation of the database file failed. */
177 if (created && geteuid() == root_uid)
181 uschar *lastname = Ustrrchr(buffer, '/') + 1;
182 int namelen = Ustrlen(name);
185 dd = opendir(CS buffer);
187 while ((ent = readdir(dd)) != NULL)
189 if (Ustrncmp(ent->d_name, name, namelen) == 0)
192 Ustrcpy(lastname, ent->d_name);
193 if (Ustat(buffer, &statbuf) >= 0 && statbuf.st_uid != exim_uid)
195 DEBUG(D_hints_lookup) debug_printf("ensuring %s is owned by exim\n", buffer);
196 Uchown(buffer, exim_uid, exim_gid);
204 /* If the open has failed, return NULL, leaving errno set. If lof is TRUE,
205 log the event - also for debugging - but not if the file just doesn't exist. */
207 if (dbblock->dbptr == NULL)
209 if (save_errno != ENOENT)
212 log_write(0, LOG_MAIN, "%s", string_open_failed(save_errno, "DB file %s",
215 DEBUG(D_hints_lookup)
216 debug_printf("%s", CS string_open_failed(save_errno, "DB file %s\n",
219 close(dbblock->lockfd);
224 DEBUG(D_hints_lookup)
225 debug_printf("opened hints database %s: flags=%x\n", buffer, flags);
227 /* Pass back the block containing the opened database handle and the open fd
236 /*************************************************
237 * Unlock and close a database file *
238 *************************************************/
240 /* Closing a file automatically unlocks it, so after closing the database, just
243 Argument: a pointer to an open database block
248 dbfn_close(open_db *dbblock)
250 EXIM_DBCLOSE(dbblock->dbptr);
251 close(dbblock->lockfd);
257 /*************************************************
258 * Read from database file *
259 *************************************************/
261 /* Passing back the pointer unchanged is useless, because there is
262 no guarantee of alignment. Since all the records used by Exim need
263 to be properly aligned to pick out the timestamps, etc., we might as
264 well do the copying centrally here.
266 Most calls don't need the length, so there is a macro called dbfn_read which
267 has two arguments; it calls this function adding NULL as the third.
270 dbblock a pointer to an open database block
271 key the key of the record to be read
272 length a pointer to an int into which to return the length, if not NULL
274 Returns: a pointer to the retrieved record, or
275 NULL if the record is not found
279 dbfn_read_with_length(open_db *dbblock, uschar *key, int *length)
282 EXIM_DATUM key_datum, result_datum;
284 DEBUG(D_hints_lookup) debug_printf("dbfn_read: key=%s\n", key);
286 EXIM_DATUM_INIT(key_datum); /* Some DBM libraries require the datum */
287 EXIM_DATUM_INIT(result_datum); /* to be cleared before use. */
288 EXIM_DATUM_DATA(key_datum) = CS key;
289 EXIM_DATUM_SIZE(key_datum) = Ustrlen(key) + 1;
291 if (!EXIM_DBGET(dbblock->dbptr, key_datum, result_datum)) return NULL;
293 yield = store_get(EXIM_DATUM_SIZE(result_datum));
294 memcpy(yield, EXIM_DATUM_DATA(result_datum), EXIM_DATUM_SIZE(result_datum));
295 if (length != NULL) *length = EXIM_DATUM_SIZE(result_datum);
297 EXIM_DATUM_FREE(result_datum); /* Some DBM libs require freeing */
303 /*************************************************
304 * Write to database file *
305 *************************************************/
309 dbblock a pointer to an open database block
310 key the key of the record to be written
311 ptr a pointer to the record to be written
312 length the length of the record to be written
314 Returns: the yield of the underlying dbm or db "write" function. If this
315 is dbm, the value is zero for OK.
319 dbfn_write(open_db *dbblock, uschar *key, void *ptr, int length)
321 EXIM_DATUM key_datum, value_datum;
322 dbdata_generic *gptr = (dbdata_generic *)ptr;
323 gptr->time_stamp = time(NULL);
325 DEBUG(D_hints_lookup) debug_printf("dbfn_write: key=%s\n", key);
327 EXIM_DATUM_INIT(key_datum); /* Some DBM libraries require the datum */
328 EXIM_DATUM_INIT(value_datum); /* to be cleared before use. */
329 EXIM_DATUM_DATA(key_datum) = CS key;
330 EXIM_DATUM_SIZE(key_datum) = Ustrlen(key) + 1;
331 EXIM_DATUM_DATA(value_datum) = CS ptr;
332 EXIM_DATUM_SIZE(value_datum) = length;
333 return EXIM_DBPUT(dbblock->dbptr, key_datum, value_datum);
338 /*************************************************
339 * Delete record from database file *
340 *************************************************/
344 dbblock a pointer to an open database block
345 key the key of the record to be deleted
347 Returns: the yield of the underlying dbm or db "delete" function.
351 dbfn_delete(open_db *dbblock, uschar *key)
353 EXIM_DATUM key_datum;
354 EXIM_DATUM_INIT(key_datum); /* Some DBM libraries require clearing */
355 EXIM_DATUM_DATA(key_datum) = CS key;
356 EXIM_DATUM_SIZE(key_datum) = Ustrlen(key) + 1;
357 return EXIM_DBDEL(dbblock->dbptr, key_datum);
362 /*************************************************
363 * Scan the keys of a database file *
364 *************************************************/
368 dbblock a pointer to an open database block
369 start TRUE if starting a new scan
370 FALSE if continuing with the current scan
371 cursor a pointer to a pointer to a cursor anchor, for those dbm libraries
372 that use the notion of a cursor
374 Returns: the next record from the file, or
375 NULL if there are no more
379 dbfn_scan(open_db *dbblock, BOOL start, EXIM_CURSOR **cursor)
381 EXIM_DATUM key_datum, value_datum;
383 value_datum = value_datum; /* dummy; not all db libraries use this */
385 /* Some dbm require an initialization */
387 if (start) EXIM_DBCREATE_CURSOR(dbblock->dbptr, cursor);
389 EXIM_DATUM_INIT(key_datum); /* Some DBM libraries require the datum */
390 EXIM_DATUM_INIT(value_datum); /* to be cleared before use. */
392 yield = (EXIM_DBSCAN(dbblock->dbptr, key_datum, value_datum, start, *cursor))?
393 US EXIM_DATUM_DATA(key_datum) : NULL;
395 /* Some dbm require a termination */
397 if (!yield) EXIM_DBDELETE_CURSOR(*cursor);
403 /*************************************************
404 **************************************************
405 * Stand-alone test program *
406 **************************************************
407 *************************************************/
412 main(int argc, char **cargv)
415 int max_db = sizeof(dbblock)/sizeof(open_db);
419 dbdata_wait *dbwait = NULL;
420 uschar **argv = USS cargv;
422 uschar structbuffer[1024];
426 printf("Usage: test_dbfn directory\n");
427 printf("The subdirectory called \"db\" in the given directory is used for\n");
428 printf("the files used in this test program.\n");
434 spool_directory = argv[1];
435 debug_selector = D_all - D_memory;
437 big_buffer = malloc(big_buffer_size);
439 for (i = 0; i < max_db; i++) dbblock[i].dbptr = NULL;
441 printf("\nExim's db functions tester: interface type is %s\n", EXIM_DBTYPE);
442 printf("DBM library: ");
444 #ifdef DB_VERSION_STRING
445 printf("Berkeley DB: %s\n", DB_VERSION_STRING);
446 #elif defined(BTREEVERSION) && defined(HASHVERSION)
448 printf("probably Berkeley DB version 1.8x (native mode)\n");
450 printf("probably Berkeley DB version 1.8x (compatibility mode)\n");
452 #elif defined(_DBM_RDONLY) || defined(dbm_dirfno)
453 printf("probably ndbm\n");
454 #elif defined(USE_TDB)
455 printf("using tdb\n");
458 printf("probably GDBM (native mode)\n");
460 printf("probably GDBM (compatibility mode)\n");
464 /* Test the functions */
466 printf("\nTest the functions\n> ");
468 while (Ufgets(buffer, 256, stdin) != NULL)
470 int len = Ustrlen(buffer);
474 uschar *cmd = buffer;
475 while (len > 0 && isspace((uschar)buffer[len-1])) len--;
478 if (isdigit((uschar)*cmd))
481 while (isdigit((uschar)*cmd)) cmd++;
482 while (isspace((uschar)*cmd)) cmd++;
485 if (Ustrncmp(cmd, "open", 4) == 0)
490 while (isspace((uschar)*s)) s++;
492 for (i = 0; i < max_db; i++)
493 if (dbblock[i].dbptr == NULL) break;
497 printf("Too many open databases\n> ");
502 odb = dbfn_open(s, O_RDWR, dbblock + i, TRUE);
508 printf("opened %d\n", current);
510 /* Other error cases will have written messages */
511 else if (errno == ENOENT)
513 printf("open failed: %s%s\n", strerror(errno),
515 " (or other Berkeley DB error)"
523 else if (Ustrncmp(cmd, "write", 5) == 0)
526 uschar *key = cmd + 5;
531 printf("No current database\n");
535 while (isspace((uschar)*key)) key++;
537 while (*data != 0 && !isspace((uschar)*data)) data++;
539 while (isspace((uschar)*data)) data++;
541 dbwait = (dbdata_wait *)(&structbuffer);
542 Ustrcpy(dbwait->text, data);
546 rc = dbfn_write(dbblock + current, key, dbwait,
547 Ustrlen(data) + sizeof(dbdata_wait));
549 if (rc != 0) printf("Failed: %s\n", strerror(errno));
552 else if (Ustrncmp(cmd, "read", 4) == 0)
554 uschar *key = cmd + 4;
557 printf("No current database\n");
560 while (isspace((uschar)*key)) key++;
563 dbwait = (dbdata_wait *)dbfn_read_with_length(dbblock+ current, key, NULL);
565 printf("%s\n", (dbwait == NULL)? "<not found>" : CS dbwait->text);
568 else if (Ustrncmp(cmd, "delete", 6) == 0)
570 uschar *key = cmd + 6;
573 printf("No current database\n");
576 while (isspace((uschar)*key)) key++;
577 dbfn_delete(dbblock + current, key);
580 else if (Ustrncmp(cmd, "scan", 4) == 0)
583 BOOL startflag = TRUE;
585 uschar keybuffer[256];
588 printf("No current database\n");
592 while ((key = dbfn_scan(dbblock + current, startflag, &cursor)) != NULL)
595 Ustrcpy(keybuffer, key);
596 dbwait = (dbdata_wait *)dbfn_read_with_length(dbblock + current,
598 printf("%s: %s\n", keybuffer, dbwait->text);
601 printf("End of scan\n");
604 else if (Ustrncmp(cmd, "close", 5) == 0)
607 while (isspace((uschar)*s)) s++;
609 if (i >= max_db || dbblock[i].dbptr == NULL) printf("Not open\n"); else
612 dbfn_close(dbblock + i);
614 dbblock[i].dbptr = NULL;
615 if (i == current) current = -1;
619 else if (Ustrncmp(cmd, "file", 4) == 0)
622 while (isspace((uschar)*s)) s++;
624 if (i >= max_db || dbblock[i].dbptr == NULL) printf("Not open\n");
628 else if (Ustrncmp(cmd, "time", 4) == 0)
630 showtime = ~showtime;
631 printf("Timing %s\n", showtime? "on" : "off");
634 else if (Ustrcmp(cmd, "q") == 0 || Ustrncmp(cmd, "quit", 4) == 0) break;
636 else if (Ustrncmp(cmd, "help", 4) == 0)
638 printf("close [<number>] close file [<number>]\n");
639 printf("delete <key> remove record from current file\n");
640 printf("file <number> make file <number> current\n");
641 printf("open <name> open db file\n");
642 printf("q[uit] exit program\n");
643 printf("read <key> read record from current file\n");
644 printf("scan scan current file\n");
645 printf("time time display on/off\n");
646 printf("write <key> <rest-of-line> write record to current file\n");
649 else printf("Eh?\n");
651 if (showtime && stop >= start)
652 printf("start=%d stop=%d difference=%d\n", (int)start, (int)stop,
653 (int)(stop - start));
658 for (i = 0; i < max_db; i++)
660 if (dbblock[i].dbptr != NULL)
662 printf("\nClosing %d", i);
663 dbfn_close(dbblock + i);