From a65f01ac35beba07525fba70dc5d3212f1a73e46 Mon Sep 17 00:00:00 2001 From: Sergey Poznyakoff Date: Thu, 29 Dec 2022 16:34:45 +0200 Subject: Optionally warn about missing zero blocks at the end of the archive (In response to savannah bug #63574) * doc/intern.texi: Document actual tar behaviour in regard to missing end-of-file marker. * doc/tar.texi: Rewrite the "warnings" section. Document --warning=missing-zero-blocks * src/common.h (WARN_MISSING_ZERO_BLOCKS): New constant. (WARN_ALL): Include all warning bits. * src/list.c (read_and): If EOF is reached without seeing end-of-file blocks and the "missing-zero-blocks" warning is requested, warn about the fact. * src/warning.c: New warnings: "missing-zero-blocks", "verbose". (warning_option): Change definition to reflect changes in common.h --- doc/intern.texi | 5 +- doc/tar.texi | 317 +++++++++++++++++++++++++++++++++++++++----------------- src/common.h | 3 +- src/list.c | 7 ++ src/warning.c | 8 +- 5 files changed, 243 insertions(+), 97 deletions(-) diff --git a/doc/intern.texi b/doc/intern.texi index 554fd616..fbe7e9c1 100644 --- a/doc/intern.texi +++ b/doc/intern.texi @@ -51,7 +51,10 @@ of the file. At the end of the archive file there are two 512-byte blocks filled with binary zeros as an end-of-file marker. A reasonable system should write such end-of-file marker at the end of an archive, but must not assume that such a block exists when reading an archive. In -particular @GNUTAR{} always issues a warning if it does not encounter it. +particular, @GNUTAR{} does not treat missing end-of-file marker as an +error and silently ignores the fact. You can instruct it to issue +a warning, however, by using the @option{--warning=missing-zero-blocks} +option (@pxref{General Warnings, missing-zero-blocks}). The blocks may be @dfn{blocked} for physical I/O operations. Each record of @var{n} blocks (where @var{n} is set by the diff --git a/doc/tar.texi b/doc/tar.texi index edce69a3..56ae6185 100644 --- a/doc/tar.texi +++ b/doc/tar.texi @@ -185,13 +185,14 @@ Invoking @GNUTAR{} * Synopsis:: * using tar options:: * Styles:: -* All Options:: -* help:: -* defaults:: -* verbose:: -* checkpoints:: -* warnings:: -* interactive:: +* All Options:: All @command{tar} Options. +* help:: Where to Get Help. +* defaults:: What are the Default Values. +* verbose:: Checking @command{tar} progress. +* checkpoints:: Checkpoints. +* warnings:: Controlling Warning Messages. +* interactive:: Asking for Confirmation During Operations. +* external:: Running External Commands. The Three Option Styles @@ -207,6 +208,15 @@ All @command{tar} Options * Short Option Summary:: * Position-Sensitive Options:: +Controlling Warning Messages + +* General Warnings:: Keywords applicable for @command{tar --create}. +* Archive Creation Warnings:: Keywords applicable for @command{tar --create}. +* Archive Extraction Warnings:: Keywords applicable for @command{tar --extract}. +* Incremental Extraction Warnings:: Keywords controlling incremental extraction. +* Warning Classes:: Convenience keywords control multiple warnings. +* Warning Defaults:: Default settings for warnings. + @GNUTAR{} Operations * Basic tar:: @@ -319,16 +329,17 @@ Crossing File System Boundaries Date input formats -* General date syntax:: Common rules. -* Calendar date items:: 19 Dec 1994. -* Time of day items:: 9:20pm. -* Time zone items:: @sc{est}, @sc{pdt}, @sc{gmt}. -* Day of week items:: Monday and others. -* Relative items in date strings:: next tuesday, 2 years ago. -* Pure numbers in date strings:: 19931219, 1440. -* Seconds since the Epoch:: @@1078100502. -* Specifying time zone rules:: TZ="America/New_York", TZ="UTC0". -* Authors of parse_datetime:: Bellovin, Eggert, Salz, Berets, et al. +* General date syntax:: Common rules +* Calendar date items:: 21 Jul 2020 +* Time of day items:: 9:20pm +* Time zone items:: UTC, -0700, +0900, @dots{} +* Combined date and time of day items:: 2020-07-21T20:02:00,000000-0400 +* Day of week items:: Monday and others +* Relative items in date strings:: next tuesday, 2 years ago +* Pure numbers in date strings:: 20200721, 1440 +* Seconds since the Epoch:: @@1595289600 +* Specifying time zone rules:: TZ="America/New_York", TZ="UTC0" +* Authors of parse_datetime:: Bellovin, Eggert, Salz, Berets, et al. Controlling the Archive Format @@ -398,6 +409,29 @@ Using Multiple Tapes * Tarcat:: Concatenate Volumes into a Single Archive +Reliability and Security + +* Reliability:: +* Security:: + +Reliability + +* Permissions problems:: +* Data corruption and repair:: +* Race conditions:: + +Security + +* Privacy:: +* Integrity:: +* Live untrusted data:: +* Security rules of thumb:: + +Recipes + +* copy directory hierarchy:: +* intermediate directories:: + Tar Internals * Standard:: Basic Tar Format @@ -420,7 +454,7 @@ Genfile Copying This Manual -* GNU Free Documentation License:: License for copying this manual +* GNU Free Documentation License:: License for copying this manual. @end detailmenu @end menu @@ -964,6 +998,19 @@ Note that you must double the hyphens properly each time. Later in the tutorial, we will give examples using @w{@option{--verbose --verbose}}. +The @option{--verbose} option also enables several @dfn{warning +messages}, that tar does not issue otherwise, such as the +warning about record size being used (@pxref{Blocking Factor}), selecting +the decompress program and the like. If these are of no interest to +you, you can suppress them using the @option{--warning} option +@emph{after} @option{--verbose}, e.g.: + +@example +$ @kbd{tar -c -v --warning=no-verbose -f afiles.tar apple angst aspic} +@end example + +@xref{Warning Classes, verbose}, for details. + @anchor{verbose member listing} The full output consists of six fields: @@ -1041,9 +1088,6 @@ hrw-r--r-- gray/staff 0 2006-06-09 12:06 music link to blues @end group @end smallexample -@smallexample -@end smallexample - @node help tutorial @unnumberedsubsec Getting Help: Using the @option{--help} Option @@ -2867,7 +2911,9 @@ Do not exit unsuccessfully merely because reading failed. @itemx -i With this option, @command{tar} will ignore zeroed blocks in the -archive, which normally signals EOF. @xref{Reading}. +archive, which normally signals EOF. This option also suppresses +warnings about missing or incomplete zero blocks at the end of the +archive. @xref{Ignore Zeros}. @opsummary{incremental} @item --incremental @@ -4578,109 +4624,154 @@ Control display of the warning messages identified by @var{keyword}. If @var{keyword} starts with the prefix @samp{no-}, such messages are suppressed. Otherwise, they are enabled. -Multiple @option{--warning} messages accumulate. +Multiple @option{--warning} options accumulate. +@end table + +By default, @GNUTAR enables all messages, except those that are +enabled in verbose mode (@pxref{verbose tutorial}). @xref{Warning +Defaults}, for details. -The tables below list allowed values for @var{keyword} along with the +The subsections below discuss allowed values for @var{keyword} along with the warning messages they control. -@end table -@subheading Keywords controlling @command{tar} operation -@table @asis -@kwindex all -@item all -Enable all warning messages. This is the default. -@kwindex none -@item none -Disable all warning messages. -@kwindex filename-with-nuls +@menu +* General Warnings:: Keywords applicable for @command{tar --create}. +* Archive Creation Warnings:: Keywords applicable for @command{tar --create}. +* Archive Extraction Warnings:: Keywords applicable for @command{tar --extract}. +* Incremental Extraction Warnings:: Keywords controlling incremental extraction. +* Warning Classes:: Convenience keywords control multiple warnings. +* Warning Defaults:: Default settings for warnings. +@end menu + +@node General Warnings +@subsection Keywords controlling @command{tar} operation + +These keywords control warnings that may appear in any @GNUTAR{} +operation mode: + +@defvr {warning} filename-with-nuls +@cindex @samp{file name read contains nul character}, warning message +@samp{file name read contains nul character} +@end defvr + +@defvr {warning} filename-with-nuls @cindex @samp{file name read contains nul character}, warning message -@item filename-with-nuls @samp{%s: file name read contains nul character} -@kwindex alone-zero-block +@end defvr + +@defvr {warning} alone-zero-block @cindex @samp{A lone zero block at}, warning message -@item alone-zero-block -@samp{A lone zero block at %s} -@end table +@samp{A lone zero block at %s}. Notice, that this warning is +suppressed if @option{--ignore-zeros} is in effect (@pxref{Ignore +Zeros}). +@end defvr -@subheading Keywords applicable for @command{tar --create} -@table @asis -@kwindex cachedir +@defvr {warning} missing-zero-blocks +@cindex @samp{Terminating zero blocks missing}, warning message. +@samp{Terminating zero blocks missing at %s}. This warning is +suppressed if @option{--ignore-zeros} is in effect (@pxref{Ignore +Zeros}). +@end defvr + +@node Archive Creation Warnings +@subsection Keywords applicable for @command{tar --create} + +The following keywords control messages that can be issued while +creating archives. + +@defvr {warning} cachedir @cindex @samp{contains a cache directory tag}, warning message -@item cachedir @samp{%s: contains a cache directory tag %s; %s} -@kwindex file-shrank +@end defvr + +@defvr {warning} file-shrank @cindex @samp{File shrank by %s bytes}, warning message -@item file-shrank @samp{%s: File shrank by %s bytes; padding with zeros} -@kwindex xdev +@end defvr + +@defvr {warning} xdev @cindex @samp{file is on a different filesystem}, warning message -@item xdev @samp{%s: file is on a different filesystem; not dumped} -@kwindex file-ignored +@end defvr + +@defvr {warning} file-ignored @cindex @samp{Unknown file type; file ignored}, warning message @cindex @samp{socket ignored}, warning message @cindex @samp{door ignored}, warning message -@item file-ignored @samp{%s: Unknown file type; file ignored} @*@samp{%s: socket ignored} @*@samp{%s: door ignored} -@kwindex file-unchanged +@end defvr + +@defvr {warning} file-unchanged @cindex @samp{file is unchanged; not dumped}, warning message -@item file-unchanged @samp{%s: file is unchanged; not dumped} -@kwindex ignore-archive +@end defvr + +@defvr {warning} ignore-archive @cindex @samp{archive cannot contain itself; not dumped}, warning message -@item ignore-archive @samp{%s: archive cannot contain itself; not dumped} -@kwindex file-removed +@end defvr + +@defvr {warning} file-removed @cindex @samp{File removed before we read it}, warning message -@item file-removed @samp{%s: File removed before we read it} -@kwindex file-changed +@end defvr + +@defvr {warning} file-changed @cindex @samp{file changed as we read it}, warning message -@item file-changed @samp{%s: file changed as we read it} -@item failed-read + Suppresses warnings about read failures, which can occur if files or directories are unreadable, or if they change while being read. This keyword applies only if used together with the @option{--ignore-failed-read} option. @xref{Ignore Failed Read}. -@end table +@end defvr -@subheading Keywords applicable for @command{tar --extract} -@table @asis -@kwindex existing-file +@node Archive Extraction Warnings +@subsection Keywords applicable for @command{tar --extract} + +The following keywords control warnings that can be issued during +archive extraction. + +@defvr {warning} existing-file @cindex @samp{%s: skipping existing file}, warning message -@item existing-file @samp{%s: skipping existing file} -@kwindex timestamp +@end defvr + +@defvr {warning} timestamp @cindex @samp{implausibly old time stamp %s}, warning message @cindex @samp{time stamp %s is %s s in the future}, warning message -@item timestamp @samp{%s: implausibly old time stamp %s} @*@samp{%s: time stamp %s is %s s in the future} -@kwindex contiguous-cast +@end defvr + +@defvr {warning} contiguous-cast @cindex @samp{Extracting contiguous files as regular files}, warning message -@item contiguous-cast @samp{Extracting contiguous files as regular files} -@kwindex symlink-cast -@cindex @samp{Attempting extraction of symbolic links as hard links}, warning message -@item symlink-cast +@end defvr + +@defvr {warning} symlink-cast +@samp{Attempting extraction of symbolic links as hard links}, warning message @samp{Attempting extraction of symbolic links as hard links} -@kwindex unknown-cast +@end defvr + +@defvr {warning} unknown-cast @cindex @samp{Unknown file type '%c', extracted as normal file}, warning message -@item unknown-cast @samp{%s: Unknown file type '%c', extracted as normal file} -@kwindex ignore-newer +@end defvr + +@defvr {warning} ignore-newer @cindex @samp{Current %s is newer or same age}, warning message -@item ignore-newer @samp{Current %s is newer or same age} -@kwindex unknown-keyword +@end defvr + +@defvr {warning} unknown-keyword @cindex @samp{Ignoring unknown extended header keyword '%s'}, warning message -@item unknown-keyword @samp{Ignoring unknown extended header keyword '%s'} -@kwindex decompress-program -@item decompress-program +@end defvr + +@defvr {warning} decompress-program Controls verbose description of failures occurring when trying to run alternative decompressor programs (@pxref{alternative decompression programs}). This warning is disabled by default (unless @@ -4696,33 +4787,69 @@ tar (child): trying gzip This means that @command{tar} first tried to decompress @file{archive.Z} using @command{compress}, and, when that failed, switched to @command{gzip}. -@kwindex record-size +@end defvr + +@defvr {warning} record-size @cindex @samp{Record size = %lu blocks}, warning message -@item record-size @samp{Record size = %lu blocks} -@end table +@end defvr -@subheading Keywords controlling incremental extraction: -@table @asis -@kwindex rename-directory +@node Incremental Extraction Warnings +@subsection Keywords controlling incremental extraction + +These keywords control warnings that may appear when extracting from +incremental archives. + +@defvr {warning} rename-directory @cindex @samp{%s: Directory has been renamed from %s}, warning message @cindex @samp{%s: Directory has been renamed}, warning message -@item rename-directory @samp{%s: Directory has been renamed from %s} @*@samp{%s: Directory has been renamed} -@kwindex new-directory +@end defvr + +@defvr {warning} new-directory @cindex @samp{%s: Directory is new}, warning message -@item new-directory @samp{%s: Directory is new} -@kwindex xdev +@end defvr + +@defvr {warning} xdev @cindex @samp{%s: directory is on a different device: not purging}, warning message -@item xdev @samp{%s: directory is on a different device: not purging} -@kwindex bad-dumpdir +@end defvr + +@defvr {warning} bad-dumpdir @cindex @samp{Malformed dumpdir: 'X' never used}, warning message -@item bad-dumpdir @samp{Malformed dumpdir: 'X' never used} -@end table +@end defvr + +@node Warning Classes +@subsection Warning Classes + +These convenience keywords define @dfn{warning classes}. When used, +they affect several warnings at once. + +@defvr {warning} all +Enable all warning messages. +@end defvr + +@defvr {warning} none +Disable all warning messages. +@end defvr + +@defvr {warning} verbose +A shorthand for all messages enabled when @option{--verbose} +(@pxref{verbose tutorial}) is in effect. These are: +@code{decompress-program}, @code{existing-file}, @code{new-directory}, +@code{record-size}, @code{rename-directory}. +@end defvr + +@node Warning Defaults +@subsection Default Warning Settings +@GNUTAR default settings correspond to: + +@example +--warning=all --warning=no-verbose --warning=no-missing-zero-blocks +@end example @node interactive @section Asking for Confirmation During Operations @@ -5857,7 +5984,11 @@ between file entries (which usually indicates the end of the archive). @option{--ignore-zeros} (@option{-i}) allows @command{tar} to completely read an archive which contains a block of zeros before the end (i.e., a damaged archive, or one that was created by concatenating -several archives together). +several archives together). This option also suppresses warnings +about missing or incomplete zero blocks at the end of the archive. +This can be turned on, if the need be, using the +@option{--warning=alone-zero-block --warning=missing-zero-blocks} +options (@pxref{warnings}). The @option{--ignore-zeros} (@option{-i}) option is turned off by default because many versions of @command{tar} write garbage after the end-of-archive entry, diff --git a/src/common.h b/src/common.h index 7471820e..528f7936 100644 --- a/src/common.h +++ b/src/common.h @@ -987,12 +987,13 @@ void checkpoint_flush_actions (void); #define WARN_XATTR_WRITE 0x00200000 #define WARN_RECORD_SIZE 0x00400000 #define WARN_FAILED_READ 0x00800000 +#define WARN_MISSING_ZERO_BLOCKS 0x01000000 /* These warnings are enabled by default in verbose mode: */ #define WARN_VERBOSE_WARNINGS (WARN_RENAME_DIRECTORY|WARN_NEW_DIRECTORY|\ WARN_DECOMPRESS_PROGRAM|WARN_EXISTING_FILE|\ WARN_RECORD_SIZE) -#define WARN_ALL (~WARN_VERBOSE_WARNINGS) +#define WARN_ALL 0xffffffff void set_warning_option (const char *arg); diff --git a/src/list.c b/src/list.c index cbc0e31e..702d272d 100644 --- a/src/list.c +++ b/src/list.c @@ -256,6 +256,13 @@ read_and (void (*do_something) (void)) continue; case HEADER_END_OF_FILE: + if (!ignore_zeros_option) + { + char buf[UINTMAX_STRSIZE_BOUND]; + WARNOPT (WARN_MISSING_ZERO_BLOCKS, + (0, 0, _("Terminating zero blocks missing at %s"), + STRINGIFY_BIGINT (current_block_ordinal (), buf))); + } if (block_number_option) { char buf[UINTMAX_STRSIZE_BOUND]; diff --git a/src/warning.c b/src/warning.c index ce688be6..be46faac 100644 --- a/src/warning.c +++ b/src/warning.c @@ -48,6 +48,8 @@ static char const *const warning_args[] = { "xattr-write", "record-size", "failed-read", + "missing-zero-blocks", + "verbose", NULL }; @@ -76,12 +78,14 @@ static int warning_types[] = { WARN_EXISTING_FILE, WARN_XATTR_WRITE, WARN_RECORD_SIZE, - WARN_FAILED_READ + WARN_FAILED_READ, + WARN_MISSING_ZERO_BLOCKS, + WARN_VERBOSE_WARNINGS, }; ARGMATCH_VERIFY (warning_args, warning_types); -int warning_option = WARN_ALL; +int warning_option = WARN_ALL & ~(WARN_VERBOSE_WARNINGS|WARN_MISSING_ZERO_BLOCKS); void set_warning_option (const char *arg) -- cgit v1.2.1