[various] Improve documentation

Output file must be preallocated.

base/application.cc

@@ -61,8 +61,14 @@ application::run(int argc, char **argv)
 
 	std::list<command::ptr>::const_iterator it;
 	for (it = cmds_.begin(); it != cmds_.end(); ++it) {
-		if (cmd == (*it)->get_name())
-			return (*it)->run(argc, argv);
+		if (cmd == (*it)->get_name()) {
+			try {
+				return (*it)->run(argc, argv);
+			} catch (std::exception const &e) {
+				cerr << e.what() << "\n";
+				return 1;
+			}
+		}
 	}
 
 	std::cerr << "Unknown command '" << cmd << "'\n";

base/output_file_requirements.cc

@@ -0,0 +1,51 @@
+#include "base/output_file_requirements.h"
+
+#include <iostream>
+#include <linux/fs.h>
+#include <sstream>
+#include <stdexcept>
+#include <sys/ioctl.h>
+#include <sys/stat.h>
+#include <sys/types.h>
+#include <unistd.h>
+
+using namespace base;
+using namespace std;
+
+//----------------------------------------------------------------
+
+namespace {
+	void explain_output_file_requirements() {
+		ostringstream out;
+		out << "The output file should either be a block device,\n"
+		    << "or an existing file.  The file needs to be large\n"
+		    << "enough to hold the metadata.";
+
+		throw runtime_error(out.str());
+	}
+
+	unsigned const MIN_SIZE = 32 * 1024;
+}
+
+void
+base::check_output_file_requirements(string const &path)
+{
+	struct stat info;
+	int r = ::stat(path.c_str(), &info);
+	if (r) {
+		cerr << "Output file does not exist.\n\n";
+		explain_output_file_requirements();
+	}
+
+	if (!info.st_size) {
+		cerr << "Zero size output file.\n\n";
+		explain_output_file_requirements();
+	}
+
+	if (info.st_size < MIN_SIZE) {
+		cerr << "Output file too small.\n\n";
+		explain_output_file_requirements();
+	}
+}
+
+//----------------------------------------------------------------

base/output_file_requirements.h

@@ -0,0 +1,14 @@
+#ifndef BASE_OUTPUT_FILE_REQUIREMENTS_H
+#define BASE_OUTPUT_FILE_REQUIREMENTS_H
+
+#include <string>
+
+//----------------------------------------------------------------
+
+namespace base {
+	void check_output_file_requirements(std::string const &path);
+}
+
+//----------------------------------------------------------------
+
+#endif