1 /* $Cambridge: exim/src/src/dbfn.c,v 1.7 2005/12/15 11:18:21 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.
84 There are some calls that use O_RDWR|O_CREAT for the flags. Having discovered
85 this in December 2005, I'm not sure if this is correct or not, but for the
86 moment I haven't changed them.
90 dbfn_open(uschar *name, int flags, open_db *dbblock, BOOL lof)
93 BOOL read_only = flags == O_RDONLY;
98 /* The first thing to do is to open a separate file on which to lock. This
99 ensures that Exim has exclusive use of the database before it even tries to
100 open it. Early versions tried to lock on the open database itself, but that
101 gave rise to mysterious problems from time to time - it was suspected that some
102 DB libraries "do things" on their open() calls which break the interlocking.
103 The lock file is never written to, but we open it for writing so we can get a
104 write lock if required. If it does not exist, we create it. This is done
105 separately so we know when we have done it, because when running as root we
106 need to change the ownership - see the bottom of this function. We also try to
107 make the directory as well, just in case. We won't be doing this many times
108 unnecessarily, because usually the lock file will be there. If the directory
109 exists, there is no error. */
111 sprintf(CS buffer, "%s/db/%s.lockfile", spool_directory, name);
113 if ((dbblock->lockfd = Uopen(buffer, O_RDWR, EXIMDB_LOCKFILE_MODE)) < 0)
116 (void)directory_make(spool_directory, US"db", EXIMDB_DIRECTORY_MODE, TRUE);
117 dbblock->lockfd = Uopen(buffer, O_RDWR|O_CREAT, EXIMDB_LOCKFILE_MODE);
120 if (dbblock->lockfd < 0)
122 log_write(0, LOG_MAIN, "%s",
123 string_open_failed(errno, "database lock file %s", buffer));
124 errno = 0; /* Indicates locking failure */
128 /* Now we must get a lock on the opened lock file; do this with a blocking
129 lock that times out. */
131 lock_data.l_type = read_only? F_RDLCK : F_WRLCK;
132 lock_data.l_whence = lock_data.l_start = lock_data.l_len = 0;
134 DEBUG(D_hints_lookup|D_retry|D_route|D_deliver)
135 debug_printf("locking %s\n", buffer);
137 sigalrm_seen = FALSE;
138 alarm(EXIMDB_LOCK_TIMEOUT);
139 rc = fcntl(dbblock->lockfd, F_SETLKW, &lock_data);
142 if (sigalrm_seen) errno = ETIMEDOUT;
145 log_write(0, LOG_MAIN, "Failed to get %s lock for %s: %s",
146 ((flags & O_RDONLY) != 0)? "read" : "write", buffer,
147 (errno == ETIMEDOUT)? "timed out" : strerror(errno));
148 (void)close(dbblock->lockfd);
149 errno = 0; /* Indicates locking failure */
153 DEBUG(D_hints_lookup) debug_printf("locked %s\n", buffer);
155 /* At this point we have an opened and locked separate lock file, that is,
156 exclusive access to the database, so we can go ahead and open it. If we are
157 expected to create it, don't do so at first, again so that we can detect
158 whether we need to change its ownership (see comments about the lock file
159 above.) There have been regular reports of crashes while opening hints
160 databases - often this is caused by non-matching db.h and the library. To make
161 it easy to pin this down, there are now debug statements on either side of the
164 sprintf(CS buffer, "%s/db/%s", spool_directory, name);
165 DEBUG(D_hints_lookup) debug_printf("EXIM_DBOPEN(%s)\n", buffer);
166 EXIM_DBOPEN(buffer, flags, EXIMDB_MODE, &(dbblock->dbptr));
167 DEBUG(D_hints_lookup) debug_printf("returned from EXIM_DBOPEN\n");
169 if (dbblock->dbptr == NULL && errno == ENOENT && flags == O_RDWR)
171 DEBUG(D_hints_lookup)
172 debug_printf("%s appears not to exist: trying to create\n", buffer);
174 EXIM_DBOPEN(buffer, flags|O_CREAT, EXIMDB_MODE, &(dbblock->dbptr));
175 DEBUG(D_hints_lookup) debug_printf("returned from EXIM_DBOPEN\n");
180 /* If we are running as root and this is the first access to the database, its
181 files will be owned by root. We want them to be owned by exim. We detect this
182 situation by noting above when we had to create the lock file or the database
183 itself. Because the different dbm libraries use different extensions for their
184 files, I don't know of any easier way of arranging this than scanning the
185 directory for files with the appropriate base name. At least this deals with
186 the lock file at the same time. Also, the directory will typically have only
187 half a dozen files, so the scan will be quick.
189 This code is placed here, before the test for successful opening, because there
190 was a case when a file was created, but the DBM library still returned NULL
191 because of some problem. It also sorts out the lock file if that was created
192 but creation of the database file failed. */
194 if (created && geteuid() == root_uid)
198 uschar *lastname = Ustrrchr(buffer, '/') + 1;
199 int namelen = Ustrlen(name);
202 dd = opendir(CS buffer);
204 while ((ent = readdir(dd)) != NULL)
206 if (Ustrncmp(ent->d_name, name, namelen) == 0)
209 Ustrcpy(lastname, ent->d_name);
210 if (Ustat(buffer, &statbuf) >= 0 && statbuf.st_uid != exim_uid)
212 DEBUG(D_hints_lookup) debug_printf("ensuring %s is owned by exim\n", buffer);
213 (void)Uchown(buffer, exim_uid, exim_gid);
221 /* If the open has failed, return NULL, leaving errno set. If lof is TRUE,
222 log the event - also for debugging - but not if the file just doesn't exist. */
224 if (dbblock->dbptr == NULL)
226 if (save_errno != ENOENT)
229 log_write(0, LOG_MAIN, "%s", string_open_failed(save_errno, "DB file %s",
232 DEBUG(D_hints_lookup)
233 debug_printf("%s", CS string_open_failed(save_errno, "DB file %s\n",
236 (void)close(dbblock->lockfd);
241 DEBUG(D_hints_lookup)
242 debug_printf("opened hints database %s: flags=%s\n", buffer,
243 (flags == O_RDONLY)? "O_RDONLY" : (flags == O_RDWR)? "O_RDWR" :
244 (flags == (O_RDWR|O_CREAT))? "O_RDWR|O_CREAT" : "??");
246 /* Pass back the block containing the opened database handle and the open fd
255 /*************************************************
256 * Unlock and close a database file *
257 *************************************************/
259 /* Closing a file automatically unlocks it, so after closing the database, just
262 Argument: a pointer to an open database block
267 dbfn_close(open_db *dbblock)
269 EXIM_DBCLOSE(dbblock->dbptr);
270 (void)close(dbblock->lockfd);
276 /*************************************************
277 * Read from database file *
278 *************************************************/
280 /* Passing back the pointer unchanged is useless, because there is
281 no guarantee of alignment. Since all the records used by Exim need
282 to be properly aligned to pick out the timestamps, etc., we might as
283 well do the copying centrally here.
285 Most calls don't need the length, so there is a macro called dbfn_read which
286 has two arguments; it calls this function adding NULL as the third.
289 dbblock a pointer to an open database block
290 key the key of the record to be read
291 length a pointer to an int into which to return the length, if not NULL
293 Returns: a pointer to the retrieved record, or
294 NULL if the record is not found
298 dbfn_read_with_length(open_db *dbblock, uschar *key, int *length)
301 EXIM_DATUM key_datum, result_datum;
303 DEBUG(D_hints_lookup) debug_printf("dbfn_read: key=%s\n", key);
305 EXIM_DATUM_INIT(key_datum); /* Some DBM libraries require the datum */
306 EXIM_DATUM_INIT(result_datum); /* to be cleared before use. */
307 EXIM_DATUM_DATA(key_datum) = CS key;
308 EXIM_DATUM_SIZE(key_datum) = Ustrlen(key) + 1;
310 if (!EXIM_DBGET(dbblock->dbptr, key_datum, result_datum)) return NULL;
312 yield = store_get(EXIM_DATUM_SIZE(result_datum));
313 memcpy(yield, EXIM_DATUM_DATA(result_datum), EXIM_DATUM_SIZE(result_datum));
314 if (length != NULL) *length = EXIM_DATUM_SIZE(result_datum);
316 EXIM_DATUM_FREE(result_datum); /* Some DBM libs require freeing */
322 /*************************************************
323 * Write to database file *
324 *************************************************/
328 dbblock a pointer to an open database block
329 key the key of the record to be written
330 ptr a pointer to the record to be written
331 length the length of the record to be written
333 Returns: the yield of the underlying dbm or db "write" function. If this
334 is dbm, the value is zero for OK.
338 dbfn_write(open_db *dbblock, uschar *key, void *ptr, int length)
340 EXIM_DATUM key_datum, value_datum;
341 dbdata_generic *gptr = (dbdata_generic *)ptr;
342 gptr->time_stamp = time(NULL);
344 DEBUG(D_hints_lookup) debug_printf("dbfn_write: key=%s\n", key);
346 EXIM_DATUM_INIT(key_datum); /* Some DBM libraries require the datum */
347 EXIM_DATUM_INIT(value_datum); /* to be cleared before use. */
348 EXIM_DATUM_DATA(key_datum) = CS key;
349 EXIM_DATUM_SIZE(key_datum) = Ustrlen(key) + 1;
350 EXIM_DATUM_DATA(value_datum) = CS ptr;
351 EXIM_DATUM_SIZE(value_datum) = length;
352 return EXIM_DBPUT(dbblock->dbptr, key_datum, value_datum);
357 /*************************************************
358 * Delete record from database file *
359 *************************************************/
363 dbblock a pointer to an open database block
364 key the key of the record to be deleted
366 Returns: the yield of the underlying dbm or db "delete" function.
370 dbfn_delete(open_db *dbblock, uschar *key)
372 EXIM_DATUM key_datum;
373 EXIM_DATUM_INIT(key_datum); /* Some DBM libraries require clearing */
374 EXIM_DATUM_DATA(key_datum) = CS key;
375 EXIM_DATUM_SIZE(key_datum) = Ustrlen(key) + 1;
376 return EXIM_DBDEL(dbblock->dbptr, key_datum);
381 /*************************************************
382 * Scan the keys of a database file *
383 *************************************************/
387 dbblock a pointer to an open database block
388 start TRUE if starting a new scan
389 FALSE if continuing with the current scan
390 cursor a pointer to a pointer to a cursor anchor, for those dbm libraries
391 that use the notion of a cursor
393 Returns: the next record from the file, or
394 NULL if there are no more
398 dbfn_scan(open_db *dbblock, BOOL start, EXIM_CURSOR **cursor)
400 EXIM_DATUM key_datum, value_datum;
402 value_datum = value_datum; /* dummy; not all db libraries use this */
404 /* Some dbm require an initialization */
406 if (start) EXIM_DBCREATE_CURSOR(dbblock->dbptr, cursor);
408 EXIM_DATUM_INIT(key_datum); /* Some DBM libraries require the datum */
409 EXIM_DATUM_INIT(value_datum); /* to be cleared before use. */
411 yield = (EXIM_DBSCAN(dbblock->dbptr, key_datum, value_datum, start, *cursor))?
412 US EXIM_DATUM_DATA(key_datum) : NULL;
414 /* Some dbm require a termination */
416 if (!yield) EXIM_DBDELETE_CURSOR(*cursor);
422 /*************************************************
423 **************************************************
424 * Stand-alone test program *
425 **************************************************
426 *************************************************/
431 main(int argc, char **cargv)
434 int max_db = sizeof(dbblock)/sizeof(open_db);
438 dbdata_wait *dbwait = NULL;
439 uschar **argv = USS cargv;
441 uschar structbuffer[1024];
445 printf("Usage: test_dbfn directory\n");
446 printf("The subdirectory called \"db\" in the given directory is used for\n");
447 printf("the files used in this test program.\n");
453 spool_directory = argv[1];
454 debug_selector = D_all - D_memory;
456 big_buffer = malloc(big_buffer_size);
458 for (i = 0; i < max_db; i++) dbblock[i].dbptr = NULL;
460 printf("\nExim's db functions tester: interface type is %s\n", EXIM_DBTYPE);
461 printf("DBM library: ");
463 #ifdef DB_VERSION_STRING
464 printf("Berkeley DB: %s\n", DB_VERSION_STRING);
465 #elif defined(BTREEVERSION) && defined(HASHVERSION)
467 printf("probably Berkeley DB version 1.8x (native mode)\n");
469 printf("probably Berkeley DB version 1.8x (compatibility mode)\n");
471 #elif defined(_DBM_RDONLY) || defined(dbm_dirfno)
472 printf("probably ndbm\n");
473 #elif defined(USE_TDB)
474 printf("using tdb\n");
477 printf("probably GDBM (native mode)\n");
479 printf("probably GDBM (compatibility mode)\n");
483 /* Test the functions */
485 printf("\nTest the functions\n> ");
487 while (Ufgets(buffer, 256, stdin) != NULL)
489 int len = Ustrlen(buffer);
493 uschar *cmd = buffer;
494 while (len > 0 && isspace((uschar)buffer[len-1])) len--;
497 if (isdigit((uschar)*cmd))
500 while (isdigit((uschar)*cmd)) cmd++;
501 while (isspace((uschar)*cmd)) cmd++;
504 if (Ustrncmp(cmd, "open", 4) == 0)
509 while (isspace((uschar)*s)) s++;
511 for (i = 0; i < max_db; i++)
512 if (dbblock[i].dbptr == NULL) break;
516 printf("Too many open databases\n> ");
521 odb = dbfn_open(s, O_RDWR, dbblock + i, TRUE);
527 printf("opened %d\n", current);
529 /* Other error cases will have written messages */
530 else if (errno == ENOENT)
532 printf("open failed: %s%s\n", strerror(errno),
534 " (or other Berkeley DB error)"
542 else if (Ustrncmp(cmd, "write", 5) == 0)
545 uschar *key = cmd + 5;
550 printf("No current database\n");
554 while (isspace((uschar)*key)) key++;
556 while (*data != 0 && !isspace((uschar)*data)) data++;
558 while (isspace((uschar)*data)) data++;
560 dbwait = (dbdata_wait *)(&structbuffer);
561 Ustrcpy(dbwait->text, data);
565 rc = dbfn_write(dbblock + current, key, dbwait,
566 Ustrlen(data) + sizeof(dbdata_wait));
568 if (rc != 0) printf("Failed: %s\n", strerror(errno));
571 else if (Ustrncmp(cmd, "read", 4) == 0)
573 uschar *key = cmd + 4;
576 printf("No current database\n");
579 while (isspace((uschar)*key)) key++;
582 dbwait = (dbdata_wait *)dbfn_read_with_length(dbblock+ current, key, NULL);
584 printf("%s\n", (dbwait == NULL)? "<not found>" : CS dbwait->text);
587 else if (Ustrncmp(cmd, "delete", 6) == 0)
589 uschar *key = cmd + 6;
592 printf("No current database\n");
595 while (isspace((uschar)*key)) key++;
596 dbfn_delete(dbblock + current, key);
599 else if (Ustrncmp(cmd, "scan", 4) == 0)
602 BOOL startflag = TRUE;
604 uschar keybuffer[256];
607 printf("No current database\n");
611 while ((key = dbfn_scan(dbblock + current, startflag, &cursor)) != NULL)
614 Ustrcpy(keybuffer, key);
615 dbwait = (dbdata_wait *)dbfn_read_with_length(dbblock + current,
617 printf("%s: %s\n", keybuffer, dbwait->text);
620 printf("End of scan\n");
623 else if (Ustrncmp(cmd, "close", 5) == 0)
626 while (isspace((uschar)*s)) s++;
628 if (i >= max_db || dbblock[i].dbptr == NULL) printf("Not open\n"); else
631 dbfn_close(dbblock + i);
633 dbblock[i].dbptr = NULL;
634 if (i == current) current = -1;
638 else if (Ustrncmp(cmd, "file", 4) == 0)
641 while (isspace((uschar)*s)) s++;
643 if (i >= max_db || dbblock[i].dbptr == NULL) printf("Not open\n");
647 else if (Ustrncmp(cmd, "time", 4) == 0)
649 showtime = ~showtime;
650 printf("Timing %s\n", showtime? "on" : "off");
653 else if (Ustrcmp(cmd, "q") == 0 || Ustrncmp(cmd, "quit", 4) == 0) break;
655 else if (Ustrncmp(cmd, "help", 4) == 0)
657 printf("close [<number>] close file [<number>]\n");
658 printf("delete <key> remove record from current file\n");
659 printf("file <number> make file <number> current\n");
660 printf("open <name> open db file\n");
661 printf("q[uit] exit program\n");
662 printf("read <key> read record from current file\n");
663 printf("scan scan current file\n");
664 printf("time time display on/off\n");
665 printf("write <key> <rest-of-line> write record to current file\n");
668 else printf("Eh?\n");
670 if (showtime && stop >= start)
671 printf("start=%d stop=%d difference=%d\n", (int)start, (int)stop,
672 (int)(stop - start));
677 for (i = 0; i < max_db; i++)
679 if (dbblock[i].dbptr != NULL)
681 printf("\nClosing %d", i);
682 dbfn_close(dbblock + i);