src/fs/directory.cc

/***************************************************************************
 *                                                                         *
 *   This program is free software; you can redistribute it and/or modify  *
 *   it under the terms of the GNU General Public License as published by  *
 *   the Free Software Foundation; either version 2 of the License, or     *
 *   (at your option) any later version.                                   *
 *                                                                         *
 ***************************************************************************
 * fs/directory.cc -- part of ezbounce
 * (c) 2006-2008 Murat Deligonul
 */

#include "autoconf.h"

#include <vector>
#include <cstring>
#include <cstdlib>
#include <cstdio>
#include <ctime>
#include <cerrno>
#include <unistd.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
#include "util/strings.h"
#include "util/generic.h"
#include "fs/directory.h"
#include "fs/error.h"
#include "io/utility.h"
#include "debug.h"

using namespace util::strings;

namespace fs {

/**
 * Database file version.  History:
 *
 * 	201	-	(current) added permissions and file group data.
 * 			changed to three digit version numbers to handle minor changes.
 * 	  2	-	old format, used until 1.99.11
 */
const unsigned short  directory::DB_VERSION = 201;

const char directory::DB_FILE_NAME[] = "ezbfiles.db";

/**
 * Construct directory object from a parent directory
 * and entry structure.
 * Directory names and paths are stored without a trailing '/'
 *  unless they refer to a root directory.
 */
directory::directory(directory * p, file_entry * f)
	: _name(f->name()),
		_entry(f),
		fd(-1),
		batch_mode(false),
		last_mod(0), last_size(0),
		file_cache(CACHE_BUCKETS)
{
	assert(f->dir() == p);
	int plen = strlen(p->abs_path());

	a_path = my_strdup3(p->abs_path(), "/", _name);

	r_path = a_path + (plen - strlen(p->rel_path()));
	if (p->parent() == p) {
		++r_path;
	}

	dbfile = my_strdup3(a_path, "/", DB_FILE_NAME);

	parent()->inc_count();
	parent()->add_child(this);

	_entry->inc_count();

	assert(r_path[0] == '/');
	assert(r_path[strlen(r_path)-1] != '/');
	assert(_entry->dir() == parent());
}


/**
 * Construct directory object for virtual root directory.
 * Takes in parameter of absolute path this VFS resides in.
 */
directory::directory(const char * p, const char * owner, const char * group)
	: fd(-1),
		batch_mode(false),
		last_mod(0), last_size(0),
		file_cache(CACHE_BUCKETS)
{
	int plen = strlen(p);
	a_path = my_strdup(p);

	/* strip any trailing '/' characters, unless we are actually
	   setting up in '/' -- ( why the hell would someone do that ???? )*/
	while (a_path[plen-1] == '/' && plen > 1) {
		a_path[--plen] = 0;
	}

	dbfile = my_strdup3(a_path, "/", DB_FILE_NAME);
	_entry = new file_entry(this, "", owner, group);
	_name = _entry->name();
	r_path = "/";
	_entry->set_mode(0755);
	_entry->set_flags(FE_DIRECTORY);
	_entry->inc_count();
	cache_insert(_entry);
}

directory::~directory()
{
	DEBUG("%s: called for '%s'\n", __PRETTY_FUNCTION__, rel_path());

#ifdef __DEBUG__
	// NOTE: intense debug output here
	std::string obj;
	util::print_container(objects(), obj);
	DEBUG("%s: remaining dirs: %s\n", __PRETTY_FUNCTION__, obj.c_str());
	util::print_container(file_entry::objects(), obj);
	DEBUG("%s: remaining file entries: %s\n", __PRETTY_FUNCTION__, obj.c_str());
#endif

	cache_prune();
	_entry->dec_count();
	assert(_entry->usage_count() == 0);
	if (parent() != this) {
		parent()->dec_count();
		parent()->remove_child(this);
	}
	else {
		cache_remove(_entry->name());
		delete _entry;
	}

	assert(cache_num_open() == 0);

	delete[] a_path;
	delete[] dbfile;
	assert(fd == -1);
	assert(!batch_mode);
}

void directory::add_child(directory * d)
{
	using util::contains;
	assert(!contains(children.begin(), children.end(), d));
	children.push_back(d);
}

void directory::remove_child(directory * d)
{
	using util::contains;
	assert(contains(children.begin(), children.end(), d));
	children.erase(std::remove(children.begin(), children.end(),
					d),
			children.end());
}

/**
 * Begin a series of operations while database file is locked
 */
int directory::batch_start()
{
	DEBUG("directory::batch_start(): [%p]\n", this);
	if (batch_mode || fd > -1) {
		DEBUG("%s: oops, you screwed up\n", __PRETTY_FUNCTION__);
		abort();
	}

	int r = opendb();
	if (r < 0) {
		DEBUG("%s: opendb() failed: %d\n", __PRETTY_FUNCTION__, r);
		return r;
	}

	batch_mode = true;
	return 0;
}

/**
 * End the series of operations.
 */
int directory::batch_end()
{
	DEBUG("directory::batch_end(): [%p]\n", this);
	if (!batch_mode || fd < 0) {
		DEBUG("%s: oops, you screwed up\n", __PRETTY_FUNCTION__);
		abort();
	}

	batch_mode = false;
	return closedb();
}

/**
 * Get the database entry for a file.
 * Ensures that the file exists both in the database and on disk.  All other
 * checks and operations (e.g. checking permissions, opening) are
 * done at a higher level.
 *
 * Returns a new file_entry object upon success.  On error, returns null
 * and err is set to the appropriate error code.
 */
file_entry * directory::disk_lookup(const char * file, int * err)
{
	int r = opendb();
	if (r < 0) {
		*err = r;
		return 0;
	}

	/** ensure sanity of filename **/
	if (!is_legal_name(file)) {
		*err = ERR_ILLEGAL_NAME;
		closedb();
		return 0;
	}

	raw_entry e;
	memset(&e, 0, sizeof(e));
       	r = locate_entry(file, &e, MATCH_LITERAL);
	if (r < 0) {
		*err = r;
		delete[] e.string_data;
		closedb();
		return 0;
	}

	file_entry * fe = new file_entry(this);
	fill_file_entry(&e, fe);
	delete[] e.string_data;

	// TODO: check that we can read on disk entry
	r = closedb();
	if (r < 0) {
		*err = r;
		delete fe;
		return NULL;
	}
	return fe;
}

/**
 * Write entry to database file.
 * If 'create' is true, the entry is written even if it can't be found.
 */
int directory::write(const file_entry * fe, bool create)
{
	int r = opendb();
	if (r < 0) {
		return r;
	}

	/* ensure legality of name */
	if (!is_legal_name(fe->name())) {
		closedb();
		return ERR_ILLEGAL_NAME;
	}

	raw_entry e;
	memset(&e, 0, sizeof(e));

	r = locate_entry(fe->name(), &e, MATCH_LITERAL);
	delete[] e.string_data;
	e.string_data = NULL;

	if ((r == ERR_DOESNT_EXIST && !create)
	     || (r < 0 && r != ERR_DOESNT_EXIST)) {
		closedb();
		return r;
	}

	// save these
	off_t old_offset = e.offset;
	unsigned old_padding = e.header.padding_length;
	unsigned old_dyn     = calc_dynlen(&e.header);
	unsigned old_total   = calc_entry_len(&e.header);

	// assemble new structure
	size_t dyn_len = fill_header(fe, &e.header);
	e.string_data = new char[dyn_len];
	fill_dynamic(fe, e.string_data);

	// special case where entry is last one in the file.
	if (old_offset > 0 &&
		(old_offset + old_total) == (unsigned) last_size) {
		DEBUG("directory::write() [%p]: '%s': detected write to last entry in database\n",
				this, fe->name());
		off_t new_size = old_offset + dyn_len + sizeof(e.header);
		if (new_size != last_size) {
			ftruncate(fd, new_size);
			last_size = new_size;
		}
		e.header.padding_length = 0;
	}
	else if (dyn_len > (old_dyn + old_padding)) {
		// writing a brand new entry or we need more space
		lseek(fd, sizeof(dbfile_header), SEEK_SET);
		r = find_free_entry(dyn_len, &e);
		if (r < 0) {
			// failed: shouldn't happen unless there is
			// corruption or other serious problem.
			delete[] e.string_data;
			closedb();
			return r;
		}
		if (old_offset != 0) {
			free_entry(old_offset);
		}
		e.header.padding_length -= dyn_len;
	}
	else {
		// normal case: writing to sufficiently-spaced entry in the middle of the database
		e.header.padding_length = (old_padding + old_dyn) - dyn_len;
	}

	r = write_entry(&e);
	delete[] e.string_data;
	closedb();
	return r;
}

/**
 * Removes a file entry from the database, optionally removing it
 * from disk as well.
 */
int directory::unlink(const char * name, bool remove)
{
	int r = opendb();
	if (r < 0) {
		DEBUG("directory::unlink() [%p]: unlink of '%s' failed!\n", this, name);
		return r;
	}

	/** ensure legality of name **/
	if (!is_legal_name(name)) {
		closedb();
		return ERR_ILLEGAL_NAME;
	}

	raw_entry e;
	memset(&e, 0, sizeof(e));

	r = locate_entry(name, &e, MATCH_LITERAL);
	delete[] e.string_data;

	if (r < 0) {
		DEBUG("directory::unlink() [%p]: unable to find '%s'\n", this, name);
		closedb();
		return r;
	}
	free_entry(e.offset);
	closedb();

	DEBUG("directory::unlink() [%p]: erased entry '%s' at offset %ld\n", this, name, e.offset);

	if (remove) {
		char * file = NULL;
		my_asprintf(&file, "%s/%s", abs_path(), name);
		::unlink(file);
		delete[] file;
	}
	return 0;
}

/**
 * List files in the database that match pattern.  Return results in
 * an STL vector.
 */
int directory::ls(const char * pattern, std::vector<entry_data>& results)
{
	int r = opendb();
	if (r < 0) {
		DEBUG("directory::unlink() [%p]: ls of '%s' failed!\n", this, pattern);
		return r;
	}

	/**
	 * Ensure legality of pattern (really needed?)
	 */
	if (!is_legal_name(pattern)) {
		closedb();
		return ERR_ILLEGAL_NAME;
	}

	results.reserve(25);

	while (true) {
		raw_entry e;
		memset(&e, 0, sizeof(e));

		r = locate_entry(pattern, &e, MATCH_WILDCARD);
		if (r < 0) {
			closedb();
			delete[] e.string_data;
			/** check if error was from corruption, otherwise return 0 **/
			return (r == ERR_DOESNT_EXIST) ? 0 : r;
		}
		file_entry fe(this);
		fill_file_entry(&e, &fe);
		delete[] e.string_data;

		fe.update_size();

		// XXX: kind of wasteful; another copy of the data will be made
		// for storage in the vector (and potentially more for vector
		// resizes), but this is the simplest approach for now
		const entry_data * data = fe.raw_data();
		results.push_back(*data);
	}
	/* not reached! */
	return 0;
}

/**
 * Delete database file from disk.
 */
int directory::destroy()
{
	if (usage_count() > 1 || fd > -1) {
		return ERR_BUSY;
	}

	if (::unlink(dbfile) < 0) {
		DEBUG("directory::destroy() [%p]: Unable to delete '%s': %s\n", this, DB_FILE_NAME, strerror(errno));
		return ERR_DB_DESTROY;
	}
	DEBUG("directory::destroy() [%p]: database file '%s' deleted\n", this, dbfile);
	// FIXME: what else to do here?
	return 0;
}

/**
 * Checks if database file exists
 */
bool directory::exists()  const
{
	int j = access(dbfile, R_OK | W_OK);
	return (j == 0);
}

/**
 * Confirm legality of database file.
 */
int directory::validate()
{
	int r = opendb();
	if (r < 0) {
		return r;
	}
	closedb();
	return 0;
}

/**
 * Tests whether any files are listed in the database.
 * Return:
 *	< 0 : access error
 *       0 : false
 *       1 : true
 */
int directory::is_empty()
{
	int r = opendb();
	if (r < 0) {
		return r;
	}

	struct raw_entry e;
	memset(&e, 0, sizeof(e));
	r = locate_entry("*", &e, MATCH_WILDCARD);
	delete[] e.string_data;
	closedb();

	if (r == ERR_DOESNT_EXIST) {
		return 1;
	}
       	else if (r < 0) {
		return r;
	}
	/* files were found .. */
	return 0;
}

/**
 * Translate directory error codes.
 */
/* static */ const char * directory::strerror(int err)
{
	switch (err) {
	case ERR_ILLEGAL_NAME:
		return "Illegal filename";
	case ERR_DB_CORRUPTION:
		return "Corrupted database file detected";
	case ERR_BUSY:
		return "File or directory is in use";
	case ERR_FAILURE:
		return "Operation failed";
	case ERR_DB_VERSION:
		return "Incompatible database version";
	case ERR_DB_OPEN:
		return "Unable to open database";
	case ERR_DB_EXISTS:
		return "A database file already exists";
	case ERR_DB_DESTROY:
		return "Unable to delete database file";
	case ERR_BAD_WRITE:
		return "Tried to write invalid entry!";
	}
	return "Unknown error";
}

/**
 * Creates a new database file.
 */
int directory::create()
{
	if (exists()) {
		DEBUG("directory::create(): database file '%s' already exists!\n", dbfile);
		return ERR_DB_EXISTS;
	}

	fd = open(dbfile, O_CREAT | O_EXCL | O_WRONLY, 0600);
	if (fd < 0) {
		DEBUG("directory::create(): '%s': open() syscall failed!\n", dbfile);
		return ERR_IO_WRITE;
	}

	/** Write header and exit **/
	write_header(time(NULL));
	close(fd);
	fd = -1;
	DEBUG("directory::create(): '%s': new database file created\n", dbfile);
	return 0;
}
// implementation follows.

/**
 * Open database file in the directory & lock it.
 * Assumes database file has been created and updated to the current version!
 */
int directory::opendb()
{
	if (batch_mode) {
		lseek(fd, sizeof(dbfile_header), SEEK_SET);
		return fd;
	}

	fd = open(dbfile, O_RDWR);
	if (fd < 0) {
		DEBUG("directory::opendb(): unable to open database\n");
		fd = -1;
		return ERR_DB_OPEN;
	}

	/** lock it. **/
	lockf(fd, F_LOCK, 0);

	dbfile_header h;
	memset(&h, 0, sizeof(h));
	if (read_header(&h) < 0) {
		DEBUG("directory::opendb(): database is corrupted.\n");
		close(fd);
		fd = -1;
		return ERR_DB_CORRUPTION;
	}

	if (h.version > DB_VERSION) {
		DEBUG("directory::opendb(); incorrect version\n");
		close(fd);
		fd = -1;
		return ERR_DB_VERSION;
	}

	struct stat st;
	fstat(fd, &st);

	last_mod = st.st_mtime;
	last_size = st.st_size;

	/** success **/
	return fd;
}

/**
 * Closes and unlocks database file.  Writes the top header, but nothing else.
 */
int directory::closedb()
{
	if (batch_mode) {
		return 0;
	}

	write_header(time(NULL));
	fsync(fd);
	lockf(fd, F_ULOCK, 0);
	close(fd);
	fd = -1;
	return 0;
}

/**
 * Writes the header at the top of the database file.  Repositions file pointer
 * to the beginning of the file first.
 */
int directory::write_header(time_t timestamp)
{
	dbfile_header h;
	memset(&h, 0, sizeof(h));
	h.version = DB_VERSION;
	h.timestamp = timestamp;
	strcpy(h.hstring, "ezb fdbh");
	lseek(fd, SEEK_SET, 0);
	if (::write(fd, &h, sizeof(h)) == sizeof(h)) {
		return 0;
	}
	return -1;
}


/**
 * Return the number of files in the cache that are currently in use
 */
int directory::cache_num_open() const
{
	int count = 0;
	hash_table_t::const_iterator i = file_cache.begin(),
					e = file_cache.end();
	for (; i != e ; ++i) {
		file_entry * e = (*i).second;
		if (e->usage_count() > 0) {
			++count;
		}
	}
	return count;
}

/**
 * Remove unused entries from the open file cache.
 */
int directory::cache_prune()
{
	DEBUG("directory::cache_prune(): [%p] entering for %s\n", this, rel_path());
	hash_table_t::iterator i = file_cache.begin(),
					e = file_cache.end();
	while (i != e) {
		file_entry * e = (*i).second;
		if (e->usage_count() == 0) {
			i = file_cache.erase(i);
			delete e;
		}
		else {
			++i;
		}
	}
	return file_cache.size();
}

/**
 * Read header from top of the database file.  Assumes file pointer
 * is at the beginning of the file.
 */
int directory::read_header(dbfile_header * h)
{
	assert(h != NULL);
	assert(fd != -1);

	int r = read(fd, h, sizeof(dbfile_header));

	if (r < (signed) sizeof(dbfile_header)) {
		return -1;
	}

	if (strncmp(h->hstring, "ezb fdbh", 8)) {
		return -1;
	}

	return 0;
}

/**
 * Look for a entry on disk matching "pattern".
 * Return ERR_DOESNT_EXIST if not found.
 */
int directory::locate_entry(const char * pattern, struct raw_entry * r, int match_options)
{
	assert(fd > -1);
	int j = 0;
	int (*matcher)(const char *, const char *);

	matcher = (match_options & MATCH_LITERAL) ? &strcmp : &wild_match;
	off_t offset = lseek(fd, 0, SEEK_CUR);

	while (true) {
		j = read(fd, &r->header, sizeof(r->header));
		if (j == 0) {
			// EOF
			r->offset = 0;
			memset(&r->header, 0, sizeof(r->header));
			return ERR_DOESNT_EXIST;
		}
		else if (j < 0) {
			return ERR_IO_READ;
		}
		else if (j < (signed) sizeof(r->header)) {
			// premature eof
			return ERR_DB_CORRUPTION;
		}
		else if (validate_header(&r->header) != 0) {
			// bad header -- corrupted file?
			return ERR_DB_CORRUPTION;
		}

		// empty block?
		if (r->header.flags & FE_EMPTY_ENTRY) {
			offset = lseek(fd, r->header.padding_length, SEEK_CUR);
			continue;
		}

		// header ok, now read dynamic data
		unsigned short dyn_length = calc_dynlen(&r->header);
		r->offset = offset;
		r->string_data = new char[dyn_length];
		j = read(fd, r->string_data, dyn_length);
		if (j < (signed) dyn_length) {
			// premature EOF or read error.
			delete[] r->string_data;
			r->string_data = NULL;
			if (j < 0) {
				return ERR_IO_READ;
			}
			return ERR_DB_CORRUPTION;
		}
		if (validate_dynamic(&r->header, r->string_data) != 0) {
			delete[] r->string_data;
			r->string_data = NULL;
			return ERR_DB_CORRUPTION;
		}

		// goto end of record
		offset = lseek(fd, r->header.padding_length, SEEK_CUR);

		// make sure this is the file we're looking for
		const char * filename = &r->string_data[dyn_length - r->header.name_length];
		if (matcher(pattern, filename) != 0) {
			delete[] r->string_data;
			r->string_data = NULL;
			continue;
		}

		// found a match.
		break;
	}
	return 0;
}


/**
 * Find a free block in the database file of at least size 'size'.
 * Offset of found block is stored in r->offset.
 * Size of found block is stored in r->header.padding_length.
 * No other fields of 'r' are modified.
 * File pointer is positioned at the beginning of the free entry.
 * Consolidates sequences of empty blocks if possible.
 * If nothing is found, result offset is set to the end of the file.
 * Return 0 on success.
 *
 * FIXME: currently does not utilize padding as free space.
 * (i.e., only seeks entries marked as FE_EMPTY_ENTRY)
 */
int directory::find_free_entry(unsigned int size, raw_entry * r)
{
	struct raw_entry free_block, current;
	bool free_found = false;
	int  j = 0;
	off_t offset = lseek(fd, 0, SEEK_CUR);

	memset(&free_block, 0, sizeof (raw_entry));
	memset(&current, 0, sizeof (raw_entry));

	while (true) {
		current.offset = offset;
		j = read(fd, &current.header, sizeof (current.header));
		if (j == 0) {
			/** EOF **/
			break;
		}
		else if (j < 0) {
			return ERR_IO_READ;
		}
		else if (j < (signed) sizeof(current.header)) {
			return ERR_DB_CORRUPTION;
		}
		else if (validate_header(&current.header) != 0) {
			return ERR_DB_CORRUPTION;
		}
		offset += j;

		if (free_found) {
			if (current.header.flags & FE_EMPTY_ENTRY) {
				/**
				 * Found two empty blocks next to each other.
				 * Consolidate them -- but make sure the resultant free entry
				 * does not exceed any size limits.
				 */
				DEBUG("find_free_entry(): consolidating empty blocks:\n");
				DEBUG("                   block 1: %d bytes @ offset %ld  | block 2: %d bytes @ offset %ld\n",
							free_block.header.padding_length, free_block.offset,
							current.header.padding_length, current.offset);

				unsigned block1_size = calc_entry_len(&free_block.header);
				unsigned block2_size = calc_entry_len(&current.header);
				if (block1_size + block2_size <= MAX_ENTRY_SIZE) {
					free_block.header.padding_length += block2_size;
					lseek(fd, free_block.offset, SEEK_SET);
					// XXX: unchecked write
					::write(fd, &free_block.header, sizeof (free_block.header));
					offset = lseek(fd, free_block.header.padding_length, SEEK_CUR);
					continue;
				}
				// the resulting combined entry would have been too large ...
				DEBUG("find_free_entry(): skipped consolidation; total was %u (max %zd)\n",
								block1_size + block2_size, MAX_ENTRY_SIZE);
			}

			/**
			 * End of free space: check if it will fit here.
			 */
			if (free_block.header.padding_length >= size) {
				DEBUG("find_free_entry(): Using free block of %d bytes @ offset %ld\n",
						free_block.header.padding_length, free_block.offset);
				r->offset = free_block.offset;
				r->header.padding_length = free_block.header.padding_length;
				lseek(fd, free_block.offset, SEEK_SET);
				return 0;
			}
			// not big enough
			offset = lseek(fd, current.header.padding_length + calc_dynlen(&current.header), SEEK_CUR);
			free_found = false;
			continue;
		}

		// Still looking for a free block
		if (current.header.flags & FE_EMPTY_ENTRY) {
			free_block.offset = current.offset;
			free_block.header.padding_length = current.header.padding_length;
			free_block.header.flags = FE_EMPTY_ENTRY;
			free_found = true;
		}

		// Nothing
		offset = lseek(fd, current.header.padding_length + calc_dynlen(&current.header), SEEK_CUR);
	}

	/**
	 * EOF reached.
	 */
	if (free_found) {
		/**
		 * Last block was free one:
		 * just truncate to the start of the free block.
		 */
		DEBUG("find_free_entry(): found free space at end of file with offset=%ld, truncating file\n", free_block.offset);
		j = ftruncate(fd, free_block.offset);
		if (j < 0) {
			// This might happen if filesystem becomes full ?
			DEBUG("find_free_entry(): ftruncate() failed!\n");
			return ERR_IO_WRITE;
		}
	}
	r->offset = lseek(fd, 0, SEEK_END);
	r->header.padding_length = size;
	return 0;
}

/**
 * Zap the entry at 'offset', marking it as a free block.
 */
int directory::free_entry(off_t offset)
{
	assert(offset > 0);
	struct raw_entry e;
	memset(&e, 0, sizeof(e));
	lseek(fd, offset, SEEK_SET);
	int j = read(fd, &e.header, sizeof (e.header));
	if (j < 0) {
		return ERR_IO_READ;
	}
       	else if (j < (signed) sizeof(e.header)) {
		return ERR_DB_CORRUPTION;
	}
	else if (validate_header(&e.header) != 0) {
		return ERR_DB_CORRUPTION;
	}

	unsigned int new_padding = e.header.padding_length + calc_dynlen(&e.header);
	memset(&e, 0, sizeof(e));

	e.header.flags = FE_EMPTY_ENTRY;
	e.header.padding_length = new_padding;
	char * zeroes = new char[new_padding];
	memset(zeroes, 0, new_padding);

	lseek(fd, -(sizeof (e.header)), SEEK_CUR);
	// XXX: unchecked writes
	::write(fd, &e.header, sizeof(e.header));
	::write(fd, zeroes, new_padding);
	delete[] zeroes;
	return 0;
}

/**
 * Write this entry to database file.
 * raw_entry r determines what gets written where (at r->offset).
 * Overwrites any data at the spot and assumes there is sufficient space for
 * the entry.
 * NOTE: validates header and dynamic data block before writing.
 *
 * @param r 	pointer to raw_entry, which will be validated
 * @return 0 on success
 */
int directory::write_entry(const struct raw_entry * r)
{
	assert(r->offset > 0);
	int j = lseek(fd, r->offset, SEEK_SET);
	if (j < 0) {
		return ERR_DB_CORRUPTION;
	}
	if (validate_header(&r->header) != 0) {
		return ERR_BAD_WRITE;
	}
	if (validate_dynamic(&r->header, r->string_data) != 0) {
		return ERR_BAD_WRITE;
	}

	unsigned int dyn = calc_dynlen(&r->header);
	unsigned int padding = r->header.padding_length;
	unsigned int total = sizeof(r->header) + dyn + padding;

	// TODO: use writev() here?
	char * buffer = new char[total];
	memset(buffer, 0, total);
	memcpy(buffer, &r->header, sizeof(r->header));
	memcpy(buffer + sizeof(r->header), r->string_data, dyn);

	j = ::write(fd, buffer, total);
	delete[] buffer;

	if (j < (signed) total) {
		return ERR_IO_WRITE;
	}

	/** update known filesize **/
	if (r->offset + (signed) total > last_size) {
		last_size = r->offset + total;
	}
	DEBUG("write_entry(): wrote entry @ offset %ld size: %u bytes [%zd header, %d dyn, %d padding]\n",
			r->offset, total, sizeof(r->header), dyn, padding);
	return 0;
}

/* static */ bool directory::is_legal_name(const char * name)
{
	return (is_non_empty(name) && strcmp(name, DB_FILE_NAME) != 0
			&& !strchr(name, '/'));
}

/**
 * Fill a entry header with information from a file_entry -- creation time, flags,
 * downloads, and the string data.
 *
 * @param e	file_entry to read
 * @param h 	entry_header to populate
 * @return length of the string data.
 */
/* static */ size_t directory::fill_header(const file_entry * e, entry_header * h)
{
	assert(h);
	memset(h, 0, sizeof(entry_header));

	size_t dyn = 0;
	h->creation	= e->creation();
	h->flags	= e->flags();
	h->mode		= e->mode();

	// The owner and group are stored in the same field,
	// separated by a colon.
	if (is_non_empty(e->owner())) {
		h->owner_length = strlen(e->owner()) + 1;
		if (is_non_empty(e->group())) {
			// space set aside for owner's null byte will
			// be used for the colon
			h->owner_length += strlen(e->group()) + 1;
		}
		dyn += h->owner_length;
	}
	if (is_non_empty(e->misc())) {
		dyn += (h->misc_length = strlen(e->misc()) + 1);
	}
	if (is_non_empty(e->desc())) {
		dyn += (h->desc_length = strlen(e->desc()) + 1);
	}
	if (is_non_empty(e->name())) {
		dyn += (h->name_length = strlen(e->name()) + 1);
	}
	if (is_non_empty(e->from())) {
		dyn += (h->from_length = strlen(e->from()) + 1);
	}
	return dyn;
}

/**
 * Create raw data buffer to be written to the database file.
 * The buffer must be as large as all of the length fields
 * combined. (which fill_header() will return)
 * @param e 	file_entry to read
 * @param b 	buffer to fill
 * @return the number of bytes written
 */
/* static */ size_t directory::fill_dynamic(const file_entry * e, char * b)
{
	unsigned offset = 0;
	unsigned len = 0;
	char * user = NULL;

	my_asprintf(&user, "%s:%s", e->owner(), e->group());
	const char * table[] = {
		user, e->from(), e->misc(), e->desc(), e->name()
	};

	for (unsigned j = 0; j < 5; ++j) {
		len = (table[j] ? strlen(table[j]) : 0);
		if (len > 0) {
			memcpy(b + offset, table[j], len);
			*(b+offset + len) = 0;
			offset += len+1;
		}
	}

	delete[] user;
	return offset;
}

/**
 * Fill a file_entry with information from an entry in the database.
 * Assumes that the header and dynamic data portions of the raw_entry
 * have already been validated.  In particular, the string-terminating
 * null characters *must* be at the correct locations in the dynamic data block.
 *
 * @param r	raw_entry containg header and dynamic string data
 * @param e	file_entry to assign values to
 */
/* static */ void directory::fill_file_entry(const raw_entry * r, file_entry * e)
{
	assert(r != NULL);
	assert(e != NULL);
	DEBUG("%s [%p]\n", __PRETTY_FUNCTION__, e);

	const char * raw = r->string_data;
	const struct entry_header * h = &r->header;
	unsigned int offset = 0;
	bool old_version = false;

	/**
	 * First set user/group information.
	 * In older versions, group information did not exist.  Now, the group is appended
	 * to username, with a colon separating them.  If the older format is encountered,
	 * assign a default value to the group field.
	 */
	const char * colon = strchr(raw, ':');
	if (colon != NULL) {
		// new format
		int offset = colon - raw;
		char * user = my_strdup(raw);
		user[offset] = 0;

		const char * group = user+offset+1;

		assert(strlen(user) > 0);
		assert(strlen(group) > 0);
		e->set_owner(user);
		e->set_group(group);

		delete[] user;
	}
	else {
		// old format: set a default group
		old_version = true;
		e->set_owner(raw);
		e->set_group(raw);
	}
	offset += h->owner_length;

	if (h->from_length > 0) {
		e->set_from(&raw[offset]);
	}
	offset  += h->from_length;

	if (h->misc_length > 0) {
		e->set_misc(&raw[offset]);
	}
	offset += h->misc_length;

	if (h->desc_length > 0) {
		e->set_desc(&raw[offset]);
	}
	offset += h->desc_length;

	if (raw[offset]) {
		e->set_name(&raw[offset]);
	}

	e->set_creation(h->creation);
	e->set_flags(h->flags);
	e->set_mode(h->mode);

	// backward compatiblity hacks
	// assign sane permissions to file if it didn't have any
	if (old_version) {
		DEBUG("directory::fill_file_entry(): detected old format for entry '%s' (owner: '%s' mode: %d')\n",
					e->name(), e->owner(), e->mode());
		if (strcasecmp(e->owner(), "(system)") == 0) {
			e->set_owner("root");
			e->set_group("root");
		}
		if (!e->mode()) {
			if (e->flags() & FE_DIRECTORY) {
				e->set_mode(0755);
			}
			else {
				e->set_mode(0600);
			}
		}
	}
	//--------------------------------------------------
	// DEBUG("\t---> new entry: name: '%s' owner: %s\n", name(), owner());
	// DEBUG("\t  \\--> pass: %s desc: %s from: %s\n", misc(), desc(), from());
	// DEBUG("\t  \\--> creation: %ld flags: %d\n", _creation, _flags);
	//--------------------------------------------------
}

/**
 * Check legality of a entry header.
 * Header legality rules:
 * 	- Unfortunately there is no magic number for entry headers.
 * 	- The total advertised size of the entry must be <= MAX_ENTRY_SIZE.
 * 	- Each field's length must not exceed its limit.
 * 	- The name length must be >= 2
 * 	- The owner length cannot be >= 2
 * 	- Special exceptions for "Empty" entries
 *
 * Empty Entry header rules:
 * 	- Padding must be > 0 <= MAX_PADDING_LEN
 * 	- Creation field may be non-zero, all other fields must be zero.
 *
 * @param h 	pointer to entry_header struct to validate
 * @return 0 if the header appears legal
 */
/* static */ int directory::validate_header(const entry_header * h)
{
	using util::in_range;

	if (h->flags & FE_EMPTY_ENTRY) {
		// empty entry
		const bool padding_ok = h->padding_length > 0
						&& h->padding_length <= MAX_PADDING_LEN;
		const bool no_dyn = (calc_dynlen(h) == 0);
		const bool fields_ok = !h->mode && !h->reserved1;

		if (padding_ok && no_dyn && fields_ok) {
			assert(calc_entry_len(h) <= MAX_ENTRY_SIZE);
			return 0;
		}
		return -1;
	}
	// other entries
	if (calc_entry_len(h) > MAX_ENTRY_SIZE) {
		return -1;
	}

	const bool name_ok = in_range(h->name_length, MIN_NAME_LEN, MAX_NAME_LEN);
	const bool owner_ok = in_range(h->owner_length, MIN_OWNER_LEN, MAX_OWNER_LEN);
	const bool misc_ok = in_range(h->misc_length, MIN_MISC_LEN, MAX_MISC_LEN);
	const bool desc_ok = in_range(h->desc_length, MIN_DESC_LEN, MAX_DESC_LEN);
	const bool from_ok = in_range(h->from_length, MIN_FROM_LEN, MAX_FROM_LEN);
	const bool padding_ok = in_range(h->padding_length, MIN_PADDING_LEN, MAX_PADDING_LEN);

	// TODO: check value of reserved1 field?
	if (name_ok && owner_ok && misc_ok &&
			desc_ok && from_ok && padding_ok) {
		return 0;
	}
	return -1;
}

/**
 * Given a legal entry_header, determine if a dynamic data block
 * is legal.  Currently this only involves checking if the string
 * terminating null characters are at the right locations.
 */
/* static */ int directory::validate_dynamic(const entry_header * h, const char * data)
{
	const unsigned offsets[] = {
		h->owner_length,
		h->from_length,
		h->misc_length,
		h->desc_length,
		h->name_length
	};

	/**
	 * This is a bit tricky, since the length of a dynamic field may be zero,
	 * but if it's not zero, it always includes 1 byte for the terminating '\0'
	 */
	for (unsigned i = 0, j = 0; i < (sizeof offsets / sizeof(offsets[0])); ++i) {
		j += offsets[i];
		if (offsets[i] != 0) {
			if (data == NULL) {
				// XXX: is this necessary?
				return -1;
			}
			if (data[j-1] != 0) {
				return -1;
			}
		}
	}
	return 0;
}

#ifdef __DEBUG__
/**
  * Print listing of raw entries to a file descriptor
  */
int directory::dump(int out)
{
	using io::fdprintf;
	int j = opendb();
	if (j < 0) {
		fdprintf(out, "Unable to open database: %s\n", this->strerror(j));
		return j;
	}
	std::string ts;
	timestamp_full(ts, last_mod);

	fdprintf(out, "***************************************************************************\n");
	fdprintf(out, "Analyzing database file: %s\n", dbfile);
	fdprintf(out, "size: %u timestamp: %s\n", last_size, ts.c_str());
	fdprintf(out, "abs. path: %s\n", abs_path());
	fdprintf(out, "rel. path: %s\n", rel_path());
	fdprintf(out, "\nDumping entries...\n");

	off_t offset = lseek(fd, 0, SEEK_CUR);
	struct raw_entry r;

	while (true) {
		fdprintf(out, "\n---------------------------------------------------\n"
				"offset: %d [0x%x]\n", offset, offset);
		memset(&r, 0, sizeof(r));
		j = read(fd, &r.header, sizeof(r.header));
		if (j == 0) {
			// EOF
			break;
		}
		else if (j < (signed) sizeof(r.header)) {
			// premature eof or read error
			if (j < 0) {
				fdprintf(out, "* ERROR: read() failed: %s\n", ::strerror(errno));
			}
			else {
				fdprintf(out, "* ERROR: premature EOF: corruption detected!\n");
			}
			closedb();
			return ERR_DB_CORRUPTION;
		}
		else if (validate_header(&r.header) != 0) {
			return ERR_DB_CORRUPTION;
		}
		offset += j;

		unsigned short dyn_length = calc_dynlen(&r.header);
		if (r.header.flags & FE_EMPTY_ENTRY)  {
			offset = lseek(fd, dyn_length + r.header.padding_length, SEEK_CUR);
			fdprintf(out, "free block: %u bytes\n", r.header.padding_length);
			continue;
		}

		fdprintf(out, "file block    : %u bytes dynamic, %u bytes padding\n", dyn_length, r.header.padding_length);
		fdprintf(out, "flags         : 0x%x\n", r.header.flags);
		r.string_data = new char[dyn_length];
		j = read(fd, r.string_data, dyn_length);
		if (j < (signed) dyn_length) {
			// premature EOF or read error.
			delete[] r.string_data;
			if (j < 0) {
				fdprintf(out, "* ERROR: read error while reading dynamic data: %s\n", ::strerror(errno));
			}
			else {
				fdprintf(out, "* ERROR: premature EOF while reading dynamic data: corruption detected!\n");
			}
			closedb();
			return ERR_DB_CORRUPTION;
		}
		offset += j;
		file_entry * e = new file_entry(this);
		fill_file_entry(&r, e);
		timestamp_full(ts, e->creation());

		fdprintf(out, "file name     : %s\n", e->name());
		fdprintf(out, "owner         : %s\n", e->owner());
		fdprintf(out, "from          : %s\n", e->from());
		fdprintf(out, "misc          : %s\n", e->misc());
		fdprintf(out, "description   : %s\n", e->desc());
		fdprintf(out, "creation time : %d (%s)\n", e->creation(), ts.c_str());
		fdprintf(out, "padding       : %d\n", r.header.padding_length);

		delete e;
		delete[] r.string_data;
		offset = lseek(fd, r.header.padding_length, SEEK_CUR);
	}

	fdprintf(out, "\n\n *** END OF FILE ***\n");
	closedb();
	return 0;
}

#endif /* __DEBUG__ */

} // namespace fs