+\1f
+File: tar.info, Node: Relative items in date strings, Next: Pure numbers in date strings, Prev: Day of week items, Up: Date input formats
+
+7.7 Relative items in date strings
+==================================
+
+"Relative items" adjust a date (or the current date if none) forward or
+backward. The effects of relative items accumulate. Here are some
+examples:
+
+ 1 year
+ 1 year ago
+ 3 years
+ 2 days
+
+ The unit of time displacement may be selected by the string `year'
+or `month' for moving by whole years or months. These are fuzzy units,
+as years and months are not all of equal duration. More precise units
+are `fortnight' which is worth 14 days, `week' worth 7 days, `day'
+worth 24 hours, `hour' worth 60 minutes, `minute' or `min' worth 60
+seconds, and `second' or `sec' worth one second. An `s' suffix on
+these units is accepted and ignored.
+
+ The unit of time may be preceded by a multiplier, given as an
+optionally signed number. Unsigned numbers are taken as positively
+signed. No number at all implies 1 for a multiplier. Following a
+relative item by the string `ago' is equivalent to preceding the unit
+by a multiplier with value -1.
+
+ The string `tomorrow' is worth one day in the future (equivalent to
+`day'), the string `yesterday' is worth one day in the past (equivalent
+to `day ago').
+
+ The strings `now' or `today' are relative items corresponding to
+zero-valued time displacement, these strings come from the fact a
+zero-valued time displacement represents the current time when not
+otherwise changed by previous items. They may be used to stress other
+items, like in `12:00 today'. The string `this' also has the meaning
+of a zero-valued time displacement, but is preferred in date strings
+like `this thursday'.
+
+ When a relative item causes the resulting date to cross a boundary
+where the clocks were adjusted, typically for daylight saving time, the
+resulting date and time are adjusted accordingly.
+
+ The fuzz in units can cause problems with relative items. For
+example, `2003-07-31 -1 month' might evaluate to 2003-07-01, because
+2003-06-31 is an invalid date. To determine the previous month more
+reliably, you can ask for the month before the 15th of the current
+month. For example:
+
+ $ date -R
+ Thu, 31 Jul 2003 13:02:39 -0700
+ $ date --date='-1 month' +'Last month was %B?'
+ Last month was July?
+ $ date --date="$(date +%Y-%m-15) -1 month" +'Last month was %B!'
+ Last month was June!
+
+ Also, take care when manipulating dates around clock changes such as
+daylight saving leaps. In a few cases these have added or subtracted
+as much as 24 hours from the clock, so it is often wise to adopt
+universal time by setting the `TZ' environment variable to `UTC0'
+before embarking on calendrical calculations.
+
+\1f
+File: tar.info, Node: Pure numbers in date strings, Next: Seconds since the Epoch, Prev: Relative items in date strings, Up: Date input formats
+
+7.8 Pure numbers in date strings
+================================
+
+The precise interpretation of a pure decimal number depends on the
+context in the date string.
+
+ If the decimal number is of the form YYYYMMDD and no other calendar
+date item (*note Calendar date items::) appears before it in the date
+string, then YYYY is read as the year, MM as the month number and DD as
+the day of the month, for the specified calendar date.
+
+ If the decimal number is of the form HHMM and no other time of day
+item appears before it in the date string, then HH is read as the hour
+of the day and MM as the minute of the hour, for the specified time of
+day. MM can also be omitted.
+
+ If both a calendar date and a time of day appear to the left of a
+number in the date string, but no relative item, then the number
+overrides the year.
+
+\1f
+File: tar.info, Node: Seconds since the Epoch, Next: Specifying time zone rules, Prev: Pure numbers in date strings, Up: Date input formats
+
+7.9 Seconds since the Epoch
+===========================
+
+If you precede a number with `@', it represents an internal time stamp
+as a count of seconds. The number can contain an internal decimal
+point (either `.' or `,'); any excess precision not supported by the
+internal representation is truncated toward minus infinity. Such a
+number cannot be combined with any other date item, as it specifies a
+complete time stamp.
+
+ Internally, computer times are represented as a count of seconds
+since an epoch--a well-defined point of time. On GNU and POSIX
+systems, the epoch is 1970-01-01 00:00:00 UTC, so `@0' represents this
+time, `@1' represents 1970-01-01 00:00:01 UTC, and so forth. GNU and
+most other POSIX-compliant systems support such times as an extension
+to POSIX, using negative counts, so that `@-1' represents 1969-12-31
+23:59:59 UTC.
+
+ Traditional Unix systems count seconds with 32-bit two's-complement
+integers and can represent times from 1901-12-13 20:45:52 through
+2038-01-19 03:14:07 UTC. More modern systems use 64-bit counts of
+seconds with nanosecond subcounts, and can represent all the times in
+the known lifetime of the universe to a resolution of 1 nanosecond.
+
+ On most hosts, these counts ignore the presence of leap seconds.
+For example, on most hosts `@915148799' represents 1998-12-31 23:59:59
+UTC, `@915148800' represents 1999-01-01 00:00:00 UTC, and there is no
+way to represent the intervening leap second 1998-12-31 23:59:60 UTC.
+
+\1f
+File: tar.info, Node: Specifying time zone rules, Next: Authors of parse_datetime, Prev: Seconds since the Epoch, Up: Date input formats
+
+7.10 Specifying time zone rules
+===============================
+
+Normally, dates are interpreted using the rules of the current time
+zone, which in turn are specified by the `TZ' environment variable, or
+by a system default if `TZ' is not set. To specify a different set of
+default time zone rules that apply just to one date, start the date
+with a string of the form `TZ="RULE"'. The two quote characters (`"')
+must be present in the date, and any quotes or backslashes within RULE
+must be escaped by a backslash.
+
+ For example, with the GNU `date' command you can answer the question
+"What time is it in New York when a Paris clock shows 6:30am on October
+31, 2004?" by using a date beginning with `TZ="Europe/Paris"' as shown
+in the following shell transcript:
+
+ $ export TZ="America/New_York"
+ $ date --date='TZ="Europe/Paris" 2004-10-31 06:30'
+ Sun Oct 31 01:30:00 EDT 2004
+
+ In this example, the `--date' operand begins with its own `TZ'
+setting, so the rest of that operand is processed according to
+`Europe/Paris' rules, treating the string `2004-10-31 06:30' as if it
+were in Paris. However, since the output of the `date' command is
+processed according to the overall time zone rules, it uses New York
+time. (Paris was normally six hours ahead of New York in 2004, but
+this example refers to a brief Halloween period when the gap was five
+hours.)
+
+ A `TZ' value is a rule that typically names a location in the `tz'
+database (http://www.twinsun.com/tz/tz-link.htm). A recent catalog of
+location names appears in the TWiki Date and Time Gateway
+(http://twiki.org/cgi-bin/xtra/tzdate). A few non-GNU hosts require a
+colon before a location name in a `TZ' setting, e.g.,
+`TZ=":America/New_York"'.
+
+ The `tz' database includes a wide variety of locations ranging from
+`Arctic/Longyearbyen' to `Antarctica/South_Pole', but if you are at sea
+and have your own private time zone, or if you are using a non-GNU host
+that does not support the `tz' database, you may need to use a POSIX
+rule instead. Simple POSIX rules like `UTC0' specify a time zone
+without daylight saving time; other rules can specify simple daylight
+saving regimes. *Note Specifying the Time Zone with `TZ': (libc)TZ
+Variable.
+
+\1f
+File: tar.info, Node: Authors of parse_datetime, Prev: Specifying time zone rules, Up: Date input formats
+
+7.11 Authors of `parse_datetime'
+================================
+
+`parse_datetime' started life as `getdate', as originally implemented
+by Steven M. Bellovin (<smb@research.att.com>) while at the University
+of North Carolina at Chapel Hill. The code was later tweaked by a
+couple of people on Usenet, then completely overhauled by Rich $alz
+(<rsalz@bbn.com>) and Jim Berets (<jberets@bbn.com>) in August, 1990.
+Various revisions for the GNU system were made by David MacKenzie, Jim
+Meyering, Paul Eggert and others, including renaming it to `get_date' to
+avoid a conflict with the alternative Posix function `getdate', and a
+later rename to `parse_datetime'. The Posix function `getdate' can
+parse more locale-specific dates using `strptime', but relies on an
+environment variable and external file, and lacks the thread-safety of
+`parse_datetime'.
+
+ This chapter was originally produced by Franc,ois Pinard
+(<pinard@iro.umontreal.ca>) from the `parse_datetime.y' source code,
+and then edited by K. Berry (<kb@cs.umb.edu>).
+
+\1f
+File: tar.info, Node: Formats, Next: Media, Prev: Date input formats, Up: Top
+
+8 Controlling the Archive Format
+********************************
+
+Due to historical reasons, there are several formats of tar archives.
+All of them are based on the same principles, but have some subtle
+differences that often make them incompatible with each other.
+
+ GNU tar is able to create and handle archives in a variety of
+formats. The most frequently used formats are (in alphabetical order):
+
+gnu
+ Format used by GNU `tar' versions up to 1.13.25. This format
+ derived from an early POSIX standard, adding some improvements
+ such as sparse file handling and incremental archives.
+ Unfortunately these features were implemented in a way
+ incompatible with other archive formats.
+
+ Archives in `gnu' format are able to hold file names of unlimited
+ length.
+
+oldgnu
+ Format used by GNU `tar' of versions prior to 1.12.
+
+v7
+ Archive format, compatible with the V7 implementation of tar. This
+ format imposes a number of limitations. The most important of them
+ are:
+
+ 1. The maximum length of a file name is limited to 99 characters.
+
+ 2. The maximum length of a symbolic link is limited to 99
+ characters.
+
+ 3. It is impossible to store special files (block and character
+ devices, fifos etc.)
+
+ 4. Maximum value of user or group ID is limited to 2097151
+ (7777777 octal)
+
+ 5. V7 archives do not contain symbolic ownership information
+ (user and group name of the file owner).
+
+ This format has traditionally been used by Automake when producing
+ Makefiles. This practice will change in the future, in the
+ meantime, however this means that projects containing file names
+ more than 99 characters long will not be able to use GNU `tar'
+ 1.27 and Automake prior to 1.9.
+
+ustar
+ Archive format defined by POSIX.1-1988 specification. It stores
+ symbolic ownership information. It is also able to store special
+ files. However, it imposes several restrictions as well:
+
+ 1. The maximum length of a file name is limited to 256
+ characters, provided that the file name can be split at a
+ directory separator in two parts, first of them being at most
+ 155 bytes long. So, in most cases the maximum file name
+ length will be shorter than 256 characters.
+
+ 2. The maximum length of a symbolic link name is limited to 100
+ characters.
+
+ 3. Maximum size of a file the archive is able to accommodate is
+ 8GB
+
+ 4. Maximum value of UID/GID is 2097151.
+
+ 5. Maximum number of bits in device major and minor numbers is
+ 21.
+
+star
+ Format used by Jo"rg Schilling `star' implementation. GNU `tar'
+ is able to read `star' archives but currently does not produce
+ them.
+
+posix
+ Archive format defined by POSIX.1-2001 specification. This is the
+ most flexible and feature-rich format. It does not impose any
+ restrictions on file sizes or file name lengths. This format is
+ quite recent, so not all tar implementations are able to handle it
+ properly. However, this format is designed in such a way that any
+ tar implementation able to read `ustar' archives will be able to
+ read most `posix' archives as well, with the only exception that
+ any additional information (such as long file names etc.) will in
+ such case be extracted as plain text files along with the files it
+ refers to.
+
+ This archive format will be the default format for future versions
+ of GNU `tar'.
+
+
+ The following table summarizes the limitations of each of these
+formats:
+
+Format UID File Size File Name Devn
+--------------------------------------------------------------------
+gnu 1.8e19 Unlimited Unlimited 63
+oldgnu 1.8e19 Unlimited Unlimited 63
+v7 2097151 8GB 99 n/a
+ustar 2097151 8GB 256 21
+posix Unlimited Unlimited Unlimited Unlimited
+
+ The default format for GNU `tar' is defined at compilation time.
+You may check it by running `tar --help', and examining the last lines
+of its output. Usually, GNU `tar' is configured to create archives in
+`gnu' format, however, future version will switch to `posix'.
+
+* Menu:
+
+* Compression:: Using Less Space through Compression
+* Attributes:: Handling File Attributes
+* Portability:: Making `tar' Archives More Portable
+* cpio:: Comparison of `tar' and `cpio'
+
+\1f
+File: tar.info, Node: Compression, Next: Attributes, Up: Formats
+
+8.1 Using Less Space through Compression
+========================================
+
+* Menu:
+
+* gzip:: Creating and Reading Compressed Archives
+* sparse:: Archiving Sparse Files
+
+\1f
+File: tar.info, Node: gzip, Next: sparse, Up: Compression
+
+8.1.1 Creating and Reading Compressed Archives
+----------------------------------------------
+
+GNU `tar' is able to create and read compressed archives. It supports
+a wide variety of compression programs, namely: `gzip', `bzip2',
+`lzip', `lzma', `lzop', `xz' and traditional `compress'. The latter is
+supported mostly for backward compatibility, and we recommend against
+using it, because it is by far less effective than the other
+compression programs(1).
+
+ Creating a compressed archive is simple: you just specify a
+"compression option" along with the usual archive creation commands.
+The compression option is `-z' (`--gzip') to create a `gzip' compressed
+archive, `-j' (`--bzip2') to create a `bzip2' compressed archive,
+`--lzip' to create an lzip compressed archive, `-J' (`--xz') to create
+an XZ archive, `--lzma' to create an LZMA compressed archive, `--lzop'
+to create an LSOP archive, and `-Z' (`--compress') to use `compress'
+program. For example:
+
+ $ tar czf archive.tar.gz .
+
+ You can also let GNU `tar' select the compression program based on
+the suffix of the archive file name. This is done using
+`--auto-compress' (`-a') command line option. For example, the
+following invocation will use `bzip2' for compression:
+
+ $ tar caf archive.tar.bz2 .
+
+whereas the following one will use `lzma':
+
+ $ tar caf archive.tar.lzma .
+
+ For a complete list of file name suffixes recognized by GNU `tar',
+see *note auto-compress::.
+
+ Reading compressed archive is even simpler: you don't need to specify
+any additional options as GNU `tar' recognizes its format
+automatically. Thus, the following commands will list and extract the
+archive created in previous example:
+
+ # List the compressed archive
+ $ tar tf archive.tar.gz
+ # Extract the compressed archive
+ $ tar xf archive.tar.gz
+
+ The format recognition algorithm is based on "signatures", a special
+byte sequences in the beginning of file, that are specific for certain
+compression formats. If this approach fails, `tar' falls back to using
+archive name suffix to determine its format (*note auto-compress::, for
+a list of recognized suffixes).
+
+ Some compression programs are able to handle different compression
+formats. GNU `tar' uses this, if the principal decompressor for the
+given format is not available. For example, if `compress' is not
+installed, `tar' will try to use `gzip'. As of version 1.27 the
+following alternatives are tried(2):
+
+Format Main decompressor Alternatives
+---------------------------------------------------------------------
+compress compress gzip
+lzma lzma xz
+bzip2 bzip2 lbzip2
+
+ The only case when you have to specify a decompression option while
+reading the archive is when reading from a pipe or from a tape drive
+that does not support random access. However, in this case GNU `tar'
+will indicate which option you should use. For example:
+
+ $ cat archive.tar.gz | tar tf -
+ tar: Archive is compressed. Use -z option
+ tar: Error is not recoverable: exiting now
+
+ If you see such diagnostics, just add the suggested option to the
+invocation of GNU `tar':
+
+ $ cat archive.tar.gz | tar tzf -
+
+ Notice also, that there are several restrictions on operations on
+compressed archives. First of all, compressed archives cannot be
+modified, i.e., you cannot update (`--update', alias `-u') them or
+delete (`--delete') members from them or add (`--append', alias `-r')
+members to them. Likewise, you cannot append another `tar' archive to
+a compressed archive using `--concatenate' (`-A'). Secondly,
+multi-volume archives cannot be compressed.
+
+ The following options allow to select a particular compressor
+program:
+
+`-z'
+`--gzip'
+`--ungzip'
+ Filter the archive through `gzip'.
+
+`-J'
+`--xz'
+ Filter the archive through `xz'.
+
+`-j'
+`--bzip2'
+ Filter the archive through `bzip2'.
+
+`--lzip'
+ Filter the archive through `lzip'.
+
+`--lzma'
+ Filter the archive through `lzma'.
+
+`--lzop'
+ Filter the archive through `lzop'.
+
+`-Z'
+`--compress'
+`--uncompress'
+ Filter the archive through `compress'.
+
+ When any of these options is given, GNU `tar' searches the compressor
+binary in the current path and invokes it. The name of the compressor
+program is specified at compilation time using a corresponding
+`--with-COMPNAME' option to `configure', e.g. `--with-bzip2' to select
+a specific `bzip2' binary. *Note lbzip2::, for a detailed discussion.
+
+ The output produced by `tar --help' shows the actual compressor
+names along with each of these options.
+
+ You can use any of these options on physical devices (tape drives,
+etc.) and remote files as well as on normal files; data to or from such
+devices or remote files is reblocked by another copy of the `tar'
+program to enforce the specified (or default) record size. The default
+compression parameters are used. Most compression programs let you
+override these by setting a program-specific environment variable. For
+example, with `gzip' you can set `GZIP':
+
+ $ GZIP='-9 -n' tar czf archive.tar.gz subdir
+ Another way would be to use the `-I' option instead (see below),
+e.g.:
+
+ $ tar -cf archive.tar.gz -I 'gzip -9 -n' subdir
+
+Finally, the third, traditional, way to do this is to use a pipe:
+
+ $ tar cf - subdir | gzip -9 -n > archive.tar.gz
+
+ Compressed archives are easily corrupted, because compressed files
+have little redundancy. The adaptive nature of the compression scheme
+means that the compression tables are implicitly spread all over the
+archive. If you lose a few blocks, the dynamic construction of the
+compression tables becomes unsynchronized, and there is little chance
+that you could recover later in the archive.
+
+ Other compression options provide better control over creating
+compressed archives. These are:
+
+`--auto-compress'
+`-a'
+ Select a compression program to use by the archive file name
+ suffix. The following suffixes are recognized:
+
+ Suffix Compression program
+ --------------------------------------------------------------
+ `.gz' `gzip'
+ `.tgz' `gzip'
+ `.taz' `gzip'
+ `.Z' `compress'
+ `.taZ' `compress'
+ `.bz2' `bzip2'
+ `.tz2' `bzip2'
+ `.tbz2' `bzip2'
+ `.tbz' `bzip2'
+ `.lz' `lzip'
+ `.lzma' `lzma'
+ `.tlz' `lzma'
+ `.lzo' `lzop'
+ `.xz' `xz'
+
+`--use-compress-program=COMMAND'
+`-I=COMMAND'
+ Use external compression program COMMAND. Use this option if you
+ are not happy with the compression program associated with the
+ suffix at compile time or if you have a compression program that
+ GNU `tar' does not support. The COMMAND argument is a valid
+ command invocation, as you would type it at the command line
+ prompt, with any additional options as needed. Enclose it in
+ quotes if it contains white space (see *note Running External
+ Commands: external, for more detail).
+
+ The COMMAND should follow two conventions:
+
+ First, when invoked without additional options, it should read data
+ from standard input, compress it and output it on standard output.
+
+ Secondly, if invoked with the additional `-d' option, it should do
+ exactly the opposite, i.e., read the compressed data from the
+ standard input and produce uncompressed data on the standard
+ output.
+
+ The latter requirement means that you must not use the `-d' option
+ as a part of the COMMAND itself.
+
+ The `--use-compress-program' option, in particular, lets you
+implement your own filters, not necessarily dealing with
+compression/decompression. For example, suppose you wish to implement
+PGP encryption on top of compression, using `gpg' (*note gpg:
+(gpg)Top.). The following script does that:
+
+ #! /bin/sh
+ case $1 in
+ -d) gpg --decrypt - | gzip -d -c;;
+ '') gzip -c | gpg -s;;
+ *) echo "Unknown option $1">&2; exit 1;;
+ esac
+
+ Suppose you name it `gpgz' and save it somewhere in your `PATH'.
+Then the following command will create a compressed archive signed with
+your private key:
+
+ $ tar -cf foo.tar.gpgz -Igpgz .
+
+Likewise, the command below will list its contents:
+
+ $ tar -tf foo.tar.gpgz -Igpgz .
+
+* Menu:
+
+* lbzip2:: Using lbzip2 with GNU `tar'.
+
+ ---------- Footnotes ----------
+
+ (1) It also had patent problems in the past.
+
+ (2) To verbosely trace the decompressor selection, use the
+`--warning=decompress-program' option (*note decompress-program:
+warnings.).
+
+\1f
+File: tar.info, Node: lbzip2, Up: gzip
+
+8.1.1.1 Using lbzip2 with GNU `tar'.
+....................................
+
+`Lbzip2' is a multithreaded utility for handling `bzip2' compression,
+written by Laszlo Ersek. It makes use of multiple processors to speed
+up its operation and in general works considerably faster than `bzip2'.
+For a detailed description of `lbzip2' see
+`http://freshmeat.net/projects/lbzip2' and lbzip2: parallel bzip2
+utility
+(http://www.linuxinsight.com/lbzip2-parallel-bzip2-utility.html).
+
+ Recent versions of `lbzip2' are mostly command line compatible with
+`bzip2', which makes it possible to automatically invoke it via the
+`--bzip2' GNU `tar' command line option. To do so, GNU `tar' must be
+configured with the `--with-bzip2' command line option, like this:
+
+ $ ./configure --with-bzip2=lbzip2 [OTHER-OPTIONS]
+
+ Once configured and compiled this way, `tar --help' will show the
+following:
+
+ $ tar --help | grep -- --bzip2
+ -j, --bzip2 filter the archive through lbzip2
+
+which means that running `tar --bzip2' will invoke `lbzip2'.
+