1 /* $Cambridge: exim/src/src/dbfn.c,v 1.3 2005/06/14 10:32:01 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 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
157 sprintf(CS buffer, "%s/db/%s", spool_directory, name);
158 EXIM_DBOPEN(buffer, flags, EXIMDB_MODE, &(dbblock->dbptr));
160 if (dbblock->dbptr == NULL && errno == ENOENT && flags == O_RDWR)
162 DEBUG(D_hints_lookup)
163 debug_printf("%s appears not to exist: trying to create\n", buffer);
165 EXIM_DBOPEN(buffer, flags|O_CREAT, EXIMDB_MODE, &(dbblock->dbptr));
170 /* If we are running as root and this is the first access to the database, its
171 files will be owned by root. We want them to be owned by exim. We detect this
172 situation by noting above when we had to create the lock file or the database
173 itself. Because the different dbm libraries use different extensions for their
174 files, I don't know of any easier way of arranging this than scanning the
175 directory for files with the appropriate base name. At least this deals with
176 the lock file at the same time. Also, the directory will typically have only
177 half a dozen files, so the scan will be quick.
179 This code is placed here, before the test for successful opening, because there
180 was a case when a file was created, but the DBM library still returned NULL
181 because of some problem. It also sorts out the lock file if that was created
182 but creation of the database file failed. */
184 if (created && geteuid() == root_uid)
188 uschar *lastname = Ustrrchr(buffer, '/') + 1;
189 int namelen = Ustrlen(name);
192 dd = opendir(CS buffer);
194 while ((ent = readdir(dd)) != NULL)
196 if (Ustrncmp(ent->d_name, name, namelen) == 0)
199 Ustrcpy(lastname, ent->d_name);
200 if (Ustat(buffer, &statbuf) >= 0 && statbuf.st_uid != exim_uid)
202 DEBUG(D_hints_lookup) debug_printf("ensuring %s is owned by exim\n", buffer);
203 Uchown(buffer, exim_uid, exim_gid);
211 /* If the open has failed, return NULL, leaving errno set. If lof is TRUE,
212 log the event - also for debugging - but not if the file just doesn't exist. */
214 if (dbblock->dbptr == NULL)
216 if (save_errno != ENOENT)
219 log_write(0, LOG_MAIN, "%s", string_open_failed(save_errno, "DB file %s",
222 DEBUG(D_hints_lookup)
223 debug_printf("%s", CS string_open_failed(save_errno, "DB file %s\n",
226 close(dbblock->lockfd);
231 DEBUG(D_hints_lookup)
232 debug_printf("opened hints database %s: flags=%x\n", buffer, flags);
234 /* Pass back the block containing the opened database handle and the open fd
243 /*************************************************
244 * Unlock and close a database file *
245 *************************************************/
247 /* Closing a file automatically unlocks it, so after closing the database, just
250 Argument: a pointer to an open database block
255 dbfn_close(open_db *dbblock)
257 EXIM_DBCLOSE(dbblock->dbptr);
258 close(dbblock->lockfd);
264 /*************************************************
265 * Read from database file *
266 *************************************************/
268 /* Passing back the pointer unchanged is useless, because there is
269 no guarantee of alignment. Since all the records used by Exim need
270 to be properly aligned to pick out the timestamps, etc., we might as
271 well do the copying centrally here.
273 Most calls don't need the length, so there is a macro called dbfn_read which
274 has two arguments; it calls this function adding NULL as the third.
277 dbblock a pointer to an open database block
278 key the key of the record to be read
279 length a pointer to an int into which to return the length, if not NULL
281 Returns: a pointer to the retrieved record, or
282 NULL if the record is not found
286 dbfn_read_with_length(open_db *dbblock, uschar *key, int *length)
289 EXIM_DATUM key_datum, result_datum;
291 DEBUG(D_hints_lookup) debug_printf("dbfn_read: key=%s\n", key);
293 EXIM_DATUM_INIT(key_datum); /* Some DBM libraries require the datum */
294 EXIM_DATUM_INIT(result_datum); /* to be cleared before use. */
295 EXIM_DATUM_DATA(key_datum) = CS key;
296 EXIM_DATUM_SIZE(key_datum) = Ustrlen(key) + 1;
298 if (!EXIM_DBGET(dbblock->dbptr, key_datum, result_datum)) return NULL;
300 yield = store_get(EXIM_DATUM_SIZE(result_datum));
301 memcpy(yield, EXIM_DATUM_DATA(result_datum), EXIM_DATUM_SIZE(result_datum));
302 if (length != NULL) *length = EXIM_DATUM_SIZE(result_datum);
304 EXIM_DATUM_FREE(result_datum); /* Some DBM libs require freeing */
310 /*************************************************
311 * Write to database file *
312 *************************************************/
316 dbblock a pointer to an open database block
317 key the key of the record to be written
318 ptr a pointer to the record to be written
319 length the length of the record to be written
321 Returns: the yield of the underlying dbm or db "write" function. If this
322 is dbm, the value is zero for OK.
326 dbfn_write(open_db *dbblock, uschar *key, void *ptr, int length)
328 EXIM_DATUM key_datum, value_datum;
329 dbdata_generic *gptr = (dbdata_generic *)ptr;
330 gptr->time_stamp = time(NULL);
332 DEBUG(D_hints_lookup) debug_printf("dbfn_write: key=%s\n", key);
334 EXIM_DATUM_INIT(key_datum); /* Some DBM libraries require the datum */
335 EXIM_DATUM_INIT(value_datum); /* to be cleared before use. */
336 EXIM_DATUM_DATA(key_datum) = CS key;
337 EXIM_DATUM_SIZE(key_datum) = Ustrlen(key) + 1;
338 EXIM_DATUM_DATA(value_datum) = CS ptr;
339 EXIM_DATUM_SIZE(value_datum) = length;
340 return EXIM_DBPUT(dbblock->dbptr, key_datum, value_datum);
345 /*************************************************
346 * Delete record from database file *
347 *************************************************/
351 dbblock a pointer to an open database block
352 key the key of the record to be deleted
354 Returns: the yield of the underlying dbm or db "delete" function.
358 dbfn_delete(open_db *dbblock, uschar *key)
360 EXIM_DATUM key_datum;
361 EXIM_DATUM_INIT(key_datum); /* Some DBM libraries require clearing */
362 EXIM_DATUM_DATA(key_datum) = CS key;
363 EXIM_DATUM_SIZE(key_datum) = Ustrlen(key) + 1;
364 return EXIM_DBDEL(dbblock->dbptr, key_datum);
369 /*************************************************
370 * Scan the keys of a database file *
371 *************************************************/
375 dbblock a pointer to an open database block
376 start TRUE if starting a new scan
377 FALSE if continuing with the current scan
378 cursor a pointer to a pointer to a cursor anchor, for those dbm libraries
379 that use the notion of a cursor
381 Returns: the next record from the file, or
382 NULL if there are no more
386 dbfn_scan(open_db *dbblock, BOOL start, EXIM_CURSOR **cursor)
388 EXIM_DATUM key_datum, value_datum;
390 value_datum = value_datum; /* dummy; not all db libraries use this */
392 /* Some dbm require an initialization */
394 if (start) EXIM_DBCREATE_CURSOR(dbblock->dbptr, cursor);
396 EXIM_DATUM_INIT(key_datum); /* Some DBM libraries require the datum */
397 EXIM_DATUM_INIT(value_datum); /* to be cleared before use. */
399 yield = (EXIM_DBSCAN(dbblock->dbptr, key_datum, value_datum, start, *cursor))?
400 US EXIM_DATUM_DATA(key_datum) : NULL;
402 /* Some dbm require a termination */
404 if (!yield) EXIM_DBDELETE_CURSOR(*cursor);
410 /*************************************************
411 **************************************************
412 * Stand-alone test program *
413 **************************************************
414 *************************************************/
419 main(int argc, char **cargv)
422 int max_db = sizeof(dbblock)/sizeof(open_db);
426 dbdata_wait *dbwait = NULL;
427 uschar **argv = USS cargv;
429 uschar structbuffer[1024];
433 printf("Usage: test_dbfn directory\n");
434 printf("The subdirectory called \"db\" in the given directory is used for\n");
435 printf("the files used in this test program.\n");
441 spool_directory = argv[1];
442 debug_selector = D_all - D_memory;
444 big_buffer = malloc(big_buffer_size);
446 for (i = 0; i < max_db; i++) dbblock[i].dbptr = NULL;
448 printf("\nExim's db functions tester: interface type is %s\n", EXIM_DBTYPE);
449 printf("DBM library: ");
451 #ifdef DB_VERSION_STRING
452 printf("Berkeley DB: %s\n", DB_VERSION_STRING);
453 #elif defined(BTREEVERSION) && defined(HASHVERSION)
455 printf("probably Berkeley DB version 1.8x (native mode)\n");
457 printf("probably Berkeley DB version 1.8x (compatibility mode)\n");
459 #elif defined(_DBM_RDONLY) || defined(dbm_dirfno)
460 printf("probably ndbm\n");
461 #elif defined(USE_TDB)
462 printf("using tdb\n");
465 printf("probably GDBM (native mode)\n");
467 printf("probably GDBM (compatibility mode)\n");
471 /* Test the functions */
473 printf("\nTest the functions\n> ");
475 while (Ufgets(buffer, 256, stdin) != NULL)
477 int len = Ustrlen(buffer);
481 uschar *cmd = buffer;
482 while (len > 0 && isspace((uschar)buffer[len-1])) len--;
485 if (isdigit((uschar)*cmd))
488 while (isdigit((uschar)*cmd)) cmd++;
489 while (isspace((uschar)*cmd)) cmd++;
492 if (Ustrncmp(cmd, "open", 4) == 0)
497 while (isspace((uschar)*s)) s++;
499 for (i = 0; i < max_db; i++)
500 if (dbblock[i].dbptr == NULL) break;
504 printf("Too many open databases\n> ");
509 odb = dbfn_open(s, O_RDWR, dbblock + i, TRUE);
515 printf("opened %d\n", current);
517 /* Other error cases will have written messages */
518 else if (errno == ENOENT)
520 printf("open failed: %s%s\n", strerror(errno),
522 " (or other Berkeley DB error)"
530 else if (Ustrncmp(cmd, "write", 5) == 0)
533 uschar *key = cmd + 5;
538 printf("No current database\n");
542 while (isspace((uschar)*key)) key++;
544 while (*data != 0 && !isspace((uschar)*data)) data++;
546 while (isspace((uschar)*data)) data++;
548 dbwait = (dbdata_wait *)(&structbuffer);
549 Ustrcpy(dbwait->text, data);
553 rc = dbfn_write(dbblock + current, key, dbwait,
554 Ustrlen(data) + sizeof(dbdata_wait));
556 if (rc != 0) printf("Failed: %s\n", strerror(errno));
559 else if (Ustrncmp(cmd, "read", 4) == 0)
561 uschar *key = cmd + 4;
564 printf("No current database\n");
567 while (isspace((uschar)*key)) key++;
570 dbwait = (dbdata_wait *)dbfn_read_with_length(dbblock+ current, key, NULL);
572 printf("%s\n", (dbwait == NULL)? "<not found>" : CS dbwait->text);
575 else if (Ustrncmp(cmd, "delete", 6) == 0)
577 uschar *key = cmd + 6;
580 printf("No current database\n");
583 while (isspace((uschar)*key)) key++;
584 dbfn_delete(dbblock + current, key);
587 else if (Ustrncmp(cmd, "scan", 4) == 0)
590 BOOL startflag = TRUE;
592 uschar keybuffer[256];
595 printf("No current database\n");
599 while ((key = dbfn_scan(dbblock + current, startflag, &cursor)) != NULL)
602 Ustrcpy(keybuffer, key);
603 dbwait = (dbdata_wait *)dbfn_read_with_length(dbblock + current,
605 printf("%s: %s\n", keybuffer, dbwait->text);
608 printf("End of scan\n");
611 else if (Ustrncmp(cmd, "close", 5) == 0)
614 while (isspace((uschar)*s)) s++;
616 if (i >= max_db || dbblock[i].dbptr == NULL) printf("Not open\n"); else
619 dbfn_close(dbblock + i);
621 dbblock[i].dbptr = NULL;
622 if (i == current) current = -1;
626 else if (Ustrncmp(cmd, "file", 4) == 0)
629 while (isspace((uschar)*s)) s++;
631 if (i >= max_db || dbblock[i].dbptr == NULL) printf("Not open\n");
635 else if (Ustrncmp(cmd, "time", 4) == 0)
637 showtime = ~showtime;
638 printf("Timing %s\n", showtime? "on" : "off");
641 else if (Ustrcmp(cmd, "q") == 0 || Ustrncmp(cmd, "quit", 4) == 0) break;
643 else if (Ustrncmp(cmd, "help", 4) == 0)
645 printf("close [<number>] close file [<number>]\n");
646 printf("delete <key> remove record from current file\n");
647 printf("file <number> make file <number> current\n");
648 printf("open <name> open db file\n");
649 printf("q[uit] exit program\n");
650 printf("read <key> read record from current file\n");
651 printf("scan scan current file\n");
652 printf("time time display on/off\n");
653 printf("write <key> <rest-of-line> write record to current file\n");
656 else printf("Eh?\n");
658 if (showtime && stop >= start)
659 printf("start=%d stop=%d difference=%d\n", (int)start, (int)stop,
660 (int)(stop - start));
665 for (i = 0; i < max_db; i++)
667 if (dbblock[i].dbptr != NULL)
669 printf("\nClosing %d", i);
670 dbfn_close(dbblock + i);