[various] Improve documentation

Output file must be preallocated.
This commit is contained in:
Joe Thornber 2016-07-11 14:53:03 +01:00
parent ceffa5f5c4
commit 4779fb9b80
16 changed files with 127 additions and 13 deletions

View File

@ -25,6 +25,7 @@ PROGRAMS=\
all: $(PROGRAMS)
SOURCE=\
base/output_file_requirements.cc \
base/application.cc \
base/base64.cc \
base/disk_units.cc \

View File

@ -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())
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";

View File

@ -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();
}
}
//----------------------------------------------------------------

View File

@ -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

View File

@ -2,6 +2,7 @@
#include <getopt.h>
#include <libgen.h>
#include "base/output_file_requirements.h"
#include "caching/commands.h"
#include "caching/metadata.h"
#include "caching/metadata_dump.h"
@ -105,7 +106,10 @@ cache_repair_cmd::run(int argc, char **argv)
return 1;
}
if (!output_path) {
if (output_path)
check_output_file_requirements(*output_path);
else {
cerr << "no output file provided" << endl;
usage(cerr);
return 1;

View File

@ -1,5 +1,6 @@
#include "version.h"
#include "base/output_file_requirements.h"
#include "caching/commands.h"
#include "caching/metadata.h"
#include "caching/restore_emitter.h"
@ -169,7 +170,10 @@ cache_restore_cmd::run(int argc, char **argv)
return 1;
}
if (!fs.output) {
if (fs.output)
check_output_file_requirements(*fs.output);
else {
cerr << "No output file provided." << endl << endl;
usage(cerr);
return 1;

View File

@ -1,5 +1,6 @@
#include "version.h"
#include "base/output_file_requirements.h"
#include "era/commands.h"
#include "era/metadata.h"
#include "era/restore_emitter.h"
@ -121,7 +122,10 @@ era_restore_cmd::run(int argc, char **argv)
return 1;
}
if (!fs.output) {
if (fs.output)
check_output_file_requirements(*fs.output);
else {
cerr << "No output file provided." << endl << endl;
usage(cerr);
return 1;

View File

@ -24,6 +24,11 @@ Given(/^a corrupt superblock$/) do
end
end
Given(/^a tiny file$/) do
run_simple("rm -f tiny")
run_simple("fallocate -l 123 tiny")
end
When(/^I run thin_check with (.*?)$/) do |opts|
run_simple("thin_check #{opts} #{dev_file}", false)
end

View File

@ -55,6 +55,18 @@ Feature: thin_restore
No output file provided.
"""
Scenario: tiny output file
Given a tiny file
When I run thin_restore with -i metadata.xml -o tiny
Then it should fail with:
"""
Output file too small.
The output file should either be a block device,
or an existing file. The file needs to be large
enough to hold the metadata.
"""
Scenario: --quiet is accepted
Given valid thin metadata
When I run thin_restore with -i metadata.xml -o metadata.bin --quiet

View File

@ -32,7 +32,8 @@ This tool cannot be run on live metadata.
Input file or device with binary metadata.
.IP "\fB\-o, \-\-output\fP \fI{device|file}\fP"
Output file or device for repaired binary metadata.
Output file or device for repaired binary metadata. If a file is used
then it must be preallocated, and large enough to hold the metadata.
.IP "\fB\-h, \-\-help\fP"
Print help and exit.

View File

@ -30,7 +30,8 @@ This tool cannot be run on live metadata.
Input file or device with metadata.
.IP "\fB\-o, \-\-output\fP \fI{device|file}\fP"
Output file or device.
Output file or device for repaired binary metadata. If a file is used
then it must be preallocated, and large enough to hold the metadata.
.IP "\fB{\-\-debug-override-metadata-version}\fP \fI<integer>\fP"
ONLY FOR DEBUGGING PURPOSES:

View File

@ -32,7 +32,8 @@ This tool cannot be run on live metadata.
Input file or device with binary metadata.
.IP "\fB\-o, \-\-output\fP \fI{device|file}\fP"
Output file or device for repaired binary metadata.
Output file or device for repaired binary metadata. If a file is used
then it must be preallocated, and large enough to hold the metadata.
.IP "\fB\-h, \-\-help\fP"
Print help and exit.

View File

@ -33,7 +33,8 @@ Suppress output messages, return only exit code.
Input file or device with metadata.
.IP "\fB\-o, \-\-output\fP \fI{device|file}\fP"
Output file or device.
Output file or device for repaired binary metadata. If a file is used
then it must be preallocated, and large enough to hold the metadata.
.IP "\fB\-h, \-\-help\fP"
Print help and exit.

View File

@ -22,8 +22,11 @@ persistent_data::get_nr_blocks(string const &path, block_address block_size)
block_address nr_blocks;
int r = ::stat(path.c_str(), &info);
if (r)
throw runtime_error("Couldn't stat dev path");
if (r) {
ostringstream out;
out << "Couldn't stat dev path '" << path << "'";
throw runtime_error(out.str());
}
if (S_ISREG(info.st_mode) && info.st_size)
nr_blocks = div_down<block_address>(info.st_size, block_size);

View File

@ -2,6 +2,7 @@
#include <getopt.h>
#include <libgen.h>
#include "base/output_file_requirements.h"
#include "persistent-data/file_utils.h"
#include "thin-provisioning/commands.h"
#include "human_readable_format.h"
@ -99,7 +100,10 @@ thin_repair_cmd::run(int argc, char **argv)
return 1;
}
if (!output_path) {
if (output_path)
check_output_file_requirements(*output_path);
else {
cerr << "no output file provided" << endl;
usage(cerr);
return 1;

View File

@ -16,6 +16,7 @@
// with thin-provisioning-tools. If not, see
// <http://www.gnu.org/licenses/>.
#include "base/output_file_requirements.h"
#include "persistent-data/file_utils.h"
#include "thin-provisioning/commands.h"
#include "thin-provisioning/emitter.h"
@ -138,7 +139,8 @@ thin_restore_cmd::run(int argc, char **argv)
cerr << "No output file provided." << endl << endl;
usage(cerr);
return 1;
}
} else
check_output_file_requirements(output);
return restore(input, output, quiet);
}