On Sat, Dec 22, 2012 at 20:43:16 -0800, Paul Eggert wrote:
> * src/incremen.c (read_incr_db_01, write_directory_file_entry):
> Allow negative time_t, dev_t, and ino_t.
As I tried to investigate the original "Unexpected field value in
snapshot file" error that eventually let to Paul's patch, I found that
it is rather difficult to figure out exactly what field ranges are
considered valid by a particular GNU tar binary on a particular system.
The attached patch attempts to solve that problem by adding a
--show-snapshot-field-ranges option, which simply prints to standard out
the compiled-in minimum and maximum allowed values for each field.
Nathan
----------------------------------------------------------------------------
Nathan Stratton Treadway - natha...@ontko.com - Mid-Atlantic region
Ray Ontko & Co. - Software consulting services - http://www.ontko.com/
GPG Key: http://www.ontko.com/~nathanst/gpg_key.txt ID: 1023D/ECFB6239
Key fingerprint = 6AD8 485E 20B9 5C71 231C 0C32 15F3 ADCD ECFB 6239
diff --git a/doc/snapshot.texi b/doc/snapshot.texi
index 03da663..1757960 100644
--- a/doc/snapshot.texi
+++ b/doc/snapshot.texi
@@ -108,7 +108,7 @@ records, separated by null (@acronym{ASCII} 0)
characters. Thus, in contrast to the previous formats, format 2
snapshot is a binary file.
- First two records are decimal numbers, representing the
+ First two records are decimal integers, representing the
time of the last backup. First number is the number of seconds, the
second one is the number of nanoseconds, since the beginning of the
epoch. These are followed by arbitrary number of directory records.
@@ -116,17 +116,18 @@ epoch. These are followed by arbitrary number of directory records.
Each @dfn{directory record} contains a set of metadata describing a
particular directory. Parts of a directory record are delimited with
@acronym{ASCII} 0 characters. The following table describes each
-part. The @dfn{Number} type in this table stands for a decimal number
-in @acronym{ASCII} notation.
+part. The @dfn{Number} type in this table stands for a decimal integer
+in @acronym{ASCII} notation. (Negative values are preceeded with a "-"
+character, while positive values have no leading punctuation.)
-@multitable @columnfractions 0.2 0.2 0.6
+@multitable @columnfractions 0.25 0.15 0.6
@headitem Field @tab Type @tab Description
@item nfs @tab Character @tab @samp{1} if the directory is located on
an @acronym{NFS}-mounted partition, or @samp{0} otherwise;
-@item mtime-sec @tab Number @tab Modification time, seconds;
-@item mtime-nano @tab Number @tab Modification time, nanoseconds;
-@item dev-no @tab Number @tab Device number;
-@item i-no @tab Number @tab I-node number;
+@item timestamp_sec @tab Number @tab Modification time, seconds;
+@item timestamp_nsec @tab Number @tab Modification time, nanoseconds;
+@item dev @tab Number @tab Device number;
+@item ino @tab Number @tab I-node number;
@item name @tab String @tab Directory name; in contrast to the
previous versions it is not quoted;
@item contents @tab Dumpdir @tab Contents of the directory;
@@ -137,6 +138,28 @@ previous versions it is not quoted;
Dumpdirs stored in snapshot files contain only records of types
@samp{Y}, @samp{N} and @samp{D}.
+@cindex snapshot file field ranges
+@opindex show-snapshot-field-ranges
+The specific range of values allowed in each of the @dfn{Number} fields
+depends on the underlying C datatypes as determined when @command{tar}
+is compiled. To see the specific ranges allowed for a particular
+@command{tar} binary, you can use the
+@option{--show-snapshot-field-ranges} option:
+
+@smallexample
+$ @kbd{tar --show-shapshot-field-ranges}
+This tar's snapshot file field ranges are
+ (field name => [ min, max ]):
+
+ nfs => [ 0, 1 ],
+ timestamp_sec => [ -9223372036854775808, 9223372036854775807 ],
+ timestamp_nsec => [ 0, 999999999 ],
+ dev => [ 0, 18446744073709551615 ],
+ ino => [ 0, 18446744073709551615 ],
+@end smallexample
+
+(This example is from a Linux x86_64 system.)
+
@end enumerate
@c End of snapshot.texi
diff --git a/doc/tar.texi b/doc/tar.texi
index 480fe89..30c55e3 100644
--- a/doc/tar.texi
+++ b/doc/tar.texi
@@ -3250,7 +3250,7 @@ $ @kbd{tar --show-defaults}
@noindent
Notice, that this option outputs only one line. The example output
-above has been split to fit page boundaries.
+above has been split to fit page boundaries. @xref{defaults}.
@opsummary{show-omitted-dirs}
@item --show-omitted-dirs
@@ -3258,6 +3258,13 @@ above has been split to fit page boundaries.
Instructs @command{tar} to mention the directories it is skipping when
operating on a @command{tar} archive. @xref{show-omitted-dirs}.
+@opsummary{show-snapshot-field-ranges}
+@item --show-snapshot-field-ranges
+
+Displays the range of values allowed by this version of @command{tar}
+for each field in the snapshot file, then exits successfully.
+@xref{Snapshot Files}.
+
@opsummary{show-transformed-names}
@opsummary{show-stored-names}
@item --show-transformed-names
diff --git a/src/common.h b/src/common.h
index 4f7c19f..1545e2c 100644
--- a/src/common.h
+++ b/src/common.h
@@ -529,6 +529,7 @@ void rebase_directory (struct directory *dir,
const char *repl, size_t rlen);
void append_incremental_renames (struct directory *dir);
+void show_snapshot_field_ranges (void);
void read_directory_file (void);
void write_directory_file (void);
void purge_directory (char const *directory_name);
diff --git a/src/incremen.c b/src/incremen.c
index 557df30..17db103 100644
--- a/src/incremen.c
+++ b/src/incremen.c
@@ -1268,6 +1268,50 @@ read_incr_db_2 (void)
_("Unexpected EOF in snapshot file")));
}
+/* Display (to stdout) the range of allowed values for each field
+ in the snapshot file. The array below should be kept in sync
+ with any changes made to the read_num() calls in the parsing
+ loop inside read_incr_db_2().
+
+ (This function is invoked via the --show-snapshot-field-ranges
+ command line option.) */
+
+struct field_range
+{
+ char const *fieldname;
+ intmax_t min_val;
+ uintmax_t max_val;
+};
+
+static struct field_range const field_ranges[] = {
+ { "nfs", 0, 1 },
+ { "timestamp_sec", TYPE_MINIMUM (time_t), TYPE_MAXIMUM (time_t) },
+ { "timestamp_nsec", 0, BILLION - 1 },
+ { "dev", TYPE_MINIMUM (dev_t), TYPE_MAXIMUM (dev_t) },
+ { "ino", TYPE_MINIMUM (ino_t), TYPE_MAXIMUM (ino_t) },
+ { NULL, 0, 0 }
+};
+
+void
+show_snapshot_field_ranges (void)
+{
+ struct field_range const *p;
+ char minbuf[max (SYSINT_BUFSIZE, INT_BUFSIZE_BOUND (intmax_t))];
+ char maxbuf[max (SYSINT_BUFSIZE, INT_BUFSIZE_BOUND (uintmax_t))];
+
+ printf("\nThis tar's snapshot file field ranges are\n");
+ printf (" (%-15s => [ %s, %s ]):\n\n", "field name", "min", "max");
+
+ for (p=field_ranges; p->fieldname != NULL; p++) {
+ printf (" %-15s => [ %s, %s ],\n", p->fieldname,
+ sysinttostr (p->min_val, p->min_val, p->max_val, minbuf),
+ sysinttostr (p->max_val, p->min_val, p->max_val, maxbuf));
+
+ }
+
+ printf("\n");
+}
+
/* Read incremental snapshot file (directory file).
If the file has older incremental version, make sure that it is processed
correctly and that tar will use the most conservative backup method among
diff --git a/src/tar.c b/src/tar.c
index c29b4fa..c4cb82e 100644
--- a/src/tar.c
+++ b/src/tar.c
@@ -337,6 +337,7 @@ enum
SELINUX_CONTEXT_OPTION,
SHOW_DEFAULTS_OPTION,
SHOW_OMITTED_DIRS_OPTION,
+ SHOW_SNAPSHOT_FIELD_RANGES_OPTION,
SHOW_TRANSFORMED_NAMES_OPTION,
SKIP_OLD_FILES_OPTION,
SPARSE_VERSION_OPTION,
@@ -805,6 +806,8 @@ static struct argp_option options[] = {
{"confirmation", 0, 0, OPTION_ALIAS, NULL, GRID+1 },
{"show-defaults", SHOW_DEFAULTS_OPTION, 0, 0,
N_("show tar defaults"), GRID+1 },
+ {"show-snapshot-field-ranges", SHOW_SNAPSHOT_FIELD_RANGES_OPTION, 0, 0,
+ N_("show valid ranges for snapshot-file fields"), GRID+1 },
{"show-omitted-dirs", SHOW_OMITTED_DIRS_OPTION, 0, 0,
N_("when listing or extracting, list each directory that does not match search criteria"), GRID+1 },
{"show-transformed-names", SHOW_TRANSFORMED_NAMES_OPTION, 0, 0,
@@ -2116,6 +2119,13 @@ parse_opt (int key, char *arg, struct argp_state *state)
exit (0);
}
+ case SHOW_SNAPSHOT_FIELD_RANGES_OPTION:
+ {
+ show_snapshot_field_ranges ();
+ close_stdout ();
+ exit (0);
+ }
+
case STRIP_COMPONENTS_OPTION:
{
uintmax_t u;
