.\" This file is in the public domain. .de BL .br .nf .fi .br .. .de QL .ti +0.5i .nf .. .de QE .fi .br .. .TH TAR 1 "9 December 1994" .UC 4 .SH NAME tar \- tape archiver .SH SYNOPSIS \fBtar\fP [ key ] [ name ... ] .SH DESCRIPTION .PP \fItar\fP saves and restores multiple files on a single file (traditionally on magtape, but it can be any file). \fItar\fP's actions are controlled by the \fIkey\fP argument. The \fIkey\fP is a string of characters containing at most one function letter and possibly one or more function modifiers. Other arguments to \fItar\fP are file or directory names specifying which files to dump or restore. In all cases, appearance of a directory name refers to the files and (recursively) subdirectories of that directory. .PP The function portion of the key is specified by one of the following letters: .TP 8 .B x The named files are extracted from the tape. If the named file matches a directory whose contents had been written onto the tape, this directory is (recursively) extracted. The owner, modification time, and mode are restored, if possible (the mode has the current umask (see \fIumask(2)\fP) applied, unless the \fBp\fP keyletter is given). If no file argument is given, the entire content of the tape is extracted. Note that if multiple entries specifying the same file are on the tape, the last one overwrites all earlier. .TP 8 .B t The names of the specified files are listed each time they occur on the tape. If no file argument is given, all of the names on the tape are listed. Note that the argument must precisely match the name on the tape; in particular, a leading ./ is often necessary. (But see the section below titled ARGUMENT LIST PROCESSING.) .TP 8 .B c Create a new archive. The named files are packaged up into an archive. .TP 8 .B C Compare an archive with files on disk. An archive is read, as if for an \fBx\fP operation, but rather than writing anything to disk, \fItar\fP compares the data that would be extracted with what's in the corresponding file on disk, reporting any discrepancies. Note that while files present on the tape but not on disk will be mentioned, files on disk but not on the tape will not be noticed. .TP 8 .B P This causes \fItar\fP to act as a filter. It will read a tar canister from its standard input and write another to its standard output. What else is done depends on any other action letter specified: \fBt\fP causes a listing to be produced on \fItar\fP's standard error, \fBc\fP causes named files to be appended to the archive, and \fBx\fP causes the output archive to contain only the named files from the input archive. If no other operation letter is given, nothing is done but copy the archive. (The output is always on the standard output; the input is read from the place(s) specified by any \fBf\fP options, or the standard input if \fBf\fP is not given. But see the \fBP-to\fP long key, below.) The output archive is regenerated, not just copied from the input; thus, for example, the \fBo\fP flag can be used to strip directory information, or the \fBM\fP keyletter can be used to merge multiple input canisters. See the \fBS\fP keyletter for how this option interacts with sparse files in the archive. .PP The following characters may be used in addition to the letter which selects the function desired. .TP 8 .B o On output, tar normally places information specifying owner and modes of directories in the archive. Some really old versions of tar, when encountering this information, will give error messages of the form .QL /: cannot create .QE This modifier will suppress the directory information. (It is ignored when the operation does not call for creating an archive.) .TP 8 .B p This modifier says to restore files to their original modes, ignoring the present \fIumask(2)\fP. Setuid and sticky information will also be restored to the super-user. (If files are not being restored, this flag has no effect.) Normally, \fItar\fP never touches the set-gid bit on a directory under any circumstances, assuming that it's performing the Berkeley/SysV group-ID semantics function SunOS gives it. But if \fBp\fP is given twice, this is suppressed: the extracted directory's mode is literally the mode on the tape, even down to the setgid bit. .TP 8 .B v Normally \fItar\fP does its work silently. The \fBv\fP (verbose) option makes \fItar\fP print the name of each file it treats preceded by the function letter. With the \fBt\fP function, the verbose option gives more information about the tape entries than just their names. .TP 8 .B f \fItar\fP uses the next argument as the name of the archive. \fItar\fP can be used as the head or tail of a filter chain this way; see the section below titled PATHNAME INTERPRETATION. For example, \fItar\fP can be used to copy directory hierarchies with a command such as .QL tar cf - -C fromdir . | (cd todir; tar xf -) .QE This keyletter must be given, except when the \fBP\fP keyletter is used. Traditionally, \fItar\fP has used a tape device name (typically /dev/rmt8) if \fBf\fP is not used; however, tape device names are sufficiently nonstandardized now that the danger of root accidentally creating a large plain file in \fI/dev\fP seems to me to override the slight inconvenience of having to specify the tape name explicitly when it would match the default. .BL When using an operation that reads archives (\fBx\fP, \fBt\fP, \fBP\fP, or \fBC\fP), \fBf\fP can be given multiple times. Each archive thus specified is assumed to be a complete archive; \fItar\fP does not simply concatenate the data streams, but rather treats each archive as a stream of archive entries and concatenates those streams. Each archive can potentially produce a ``premature EOT'' error, for example, and the \fBM\fP keyletter is not needed (or desirable) unless one or more of the data streams contains multiple canisters. .TP 8 .B K Causes \fItar\fP to skip parts of an archive based on the sequential order of items in it. You can use this to, for example, restart an extract that crashed due to a full disk at the point where it failed, without re-extracting everything before that point. The \fBK\fP flag takes an argument, which is an operation character followed by a path name. As \fItar\fP processes archive entries (as it creates them, for a \fBc\fP operation, or as it reads entries from an input archive for a \fBt\fP, \fBx\fP, \fBC\fP, or \fBP\fP operation), it compares the archive member names with the argument path. When a match is found, action is taken according to the operation character. If the path string is zero-length (if the argument argument is just the operation character), then any archive member will match. .BL If you give no \fBK\fP options, no part of the archive is skipped. If you give one or more \fBK\fP options, the initial state is ``skipping'', which causes archive members to be discarded. \fBK\fP options are processed left-to-right; each operation character can be ``@'', ``='', ``+'', or ``\-''; the actions taken when the corresponding path is matched are as follows: .BL @ .br If this is the last \fBK\fP option, treat it as a ``+'', otherwise, as a ``\-''. .BL = .br Don't change the state. This is useful largely to constrain a later \fBK\fP option to match only after the current one. .BL + .br Set the state to ``not skipping'', that is, process archive members as normal. .BL \&\- .br Set the state to ``skipping'', so that archive members are ignored. .BL If the first character of the \fBK\fP argument is not one of those listed, then ``@'' is supplied. .BL When using \fBPc\fP, the stream of archive members for purposes of matching \fBK\fP arguments is first the items in the input archive, then items (potentially) written to the output archive due to the \fBc\fP operation. Non-skipped items are packaged up to form the output archive. .BL The stream of archive members is not affected by any selection performed by filename arguments given to a \fBt\fP or \fBx\fP operation; only the members in the archive matter. The argument-list selection occurs after the \fBK\fP filter is applied. .BL As a special case, if the first \fBK\fP argument has a zero-length path, it is processed before the first archive member is seen. (This allows you to override the default initial state if desired.) This applies to only the first \fBK\fP option; the second one will never be processed before the first archive member, even if both the first two have zero-length paths. .TP 8 .B e Causes \fItar\fP to redo the \fIstat(2)\fP system call after dumping a plain file, to see if the file appears to have changed during the dump. Size changes will normally be noticed without this, but most other changes will not. In most circumstances, other changes do not matter, so this is not the default. .TP 8 .B d Causes \fItar\fP to restrict its dumping to entities residing on the same filesystem as the argument; things that appear to reside on other filesystems will simply be omitted from the output archive. (This modifier affects operation only when \fIc\fP is used.) The output archive may still contain things from different filesystems if multiple arguments are given; \fBd\fP merely limits what is dumped for each argument to things on the same filesystem as that argument. (If \fBI\fP is used, an ``argument'' should be interpreted as referring to one of the names read from stdin.) .TP 8 .B A This affects how \fItar\fP treats kill entries in input archives. See the description of the \fBk\fP keyletter, just below, for a description of its function. .TP 8 .B k When specified in conjunction with a \fBc\fP operation, creates a ``kill archive'', consisting of headers of a private ``kill'' type. When \fItar\fP sees a header of this type when reading archives, it remembers the name in the header, and when it finds a later archive member with that same name, it silently skips over it, discarding the remembered name. (If the same name appears in multiple kill entries, it is remembered once for each such kill entry; each (non-kill) entry with that name will consume exactly one of the remembered names.) .BL When creating a kill archive, the names on the command line (or on the input, with \fBI\fP) are used directly to create the kill entries; \fItar\fP makes no attempt to recurse into directories, interpret the \fBi\fP or \fBd\fP keyletters, or any other such filesystem operations. .BL When reading an archive with kill entries, if the \fBA\fP keyletter is not given, the kill entry editing is done before all other operations; in particular, the stream of entries seen by the logic described under the \fBK\fP keyletter has already had the kill entries, and the entries they kill, removed. If \fBA\fP is given, the stream of entries includes the kill entries; they cannot be extracted, of course, but they can be copied by a \fBP\fP operation or listed by a \fBt\fP operation. .BL It is not an error for a kill entry to go unmatched by any ``real'' entry when reading archives. .TP 8 .B i When given \fBi\fP, \fItar\fP will dump plain files by reading the filesystem directly from the disk device. (This option may have been disabled when \fItar\fP was compiled.) Note that this will work only when \fItar\fP is being run by a user with read access to the disk devices. When \fBS\fP is also given, the archive will describe exactly what portions of the file really exist on disk, regardless of the contents of those partitions; no attempt is made to optimize storage in the archive by squeezing out chunks of NULs which are actually on-disk (this is a feature, not a bug). .TP 8 .B r When used in conjunction with \fBi\fP, \fBr\fP gives the number of times \fItar\fP should try rereading the on-disk inode if an error is noticed while dumping the file. A \fIsync(2)\fP is done before each reread; before the second and later rereads \fIsleep(3)\fP is called (after the \fIsync()\fP) to sleep for one second. Because of the system overhead it incurs, this is not the default. (The number is taken from the next argument.) .TP 8 .B u When used in conjunction with \fBi\fP, \fBu\fP tells \fItar\fP to use the raw (``\fIu\fPncooked'') disk device for filesystem access (otherwise it uses the block device). .TP 8 .B U Superseding \fBu\fP, this specifies what disk device to use. Note that this device is used regardless of what filesystem the file being dumped is on, so you probably want to specify \fBd\fP as well. .TP 8 .B b \fItar\fP uses the next argument as the blocking factor for tape records. The default is 20; the maximum is 2048. This option should be used only with raw magnetic tape archives (see the \fBf\fP modifier above). The block size is determined automatically when reading tapes (key letters `x' and `t'). .TP 8 .B l tells \fItar\fP to complain if it does not see all of the links to files dumped. If this is not specified, no such messages are printed. .TP 8 .B m tells \fItar\fP not to restore the modification times. The modification time will be the time of extraction. .TP 8 .B h Force \fItar\fP to follow symbolic links as if they were normal files or directories. Normally, \fItar\fP does not follow symbolic links, but instead puts the link itself into the archive. Note that when this option is used, symbolic links that point upwards in the directory hierarchy can cause \fItar\fP to repeatedly descend into that portion of the hierarchy, producing an effectively infinite archive. .TP 8 .B B Causes \fItar\fP to treat its input and output as byte streams rather than record streams. When this option is used with operations that produce output, the result is not guaranteed to be usefully blocked; see \fIdd(1)\fP for one way to re-block such a stream. .TP 8 .B F Causes \fItar\fP to check the consistency of its header blocks (see \fItar(5)\fP) less strictly. Normally, when \fItar\fP sees a header block which appears to be corrupted in any way, it will print a message and skip input blocks until it finds a block which looks like a valid header block. In the presence of the \fBF\fP modifier, certain consistency checks are relaxed: if they fail, a message is produced, but the header block is accepted as valid. If this modifer is present twice, even the complaints are suppressed. This allows \fItar\fP to read tapes produced by `foreign' versions of tar which have defined extra fields or alternative values for some of the existing fields. Certain errors, such as a checksum error, are always considered to be real errors and are not affected by \fBF\fP. .TP 8 .B R The \fBR\fP modifier is used to extract files from tapes which were carelessly written with absolute pathnames. Normally, \fItar\fP will complain if it is asked to extract a file whose name begins with a /. If the \fBR\fP key is given, the next argument is taken as a string to be prepended to the name in the archive, thus extracting the files into a hierarchy rooted at the argument path. Thus, if the file contains paths beginning /usr/..., these files could be extracted into /tmp/usr/... with .QL tar xR /tmp .QE To extract the files to the names under which they were archived, for example, use .QL tar xR "" .QE or, for most systems (those for which a leading // is equivalent to /), .QL tar xR / .QE The \fBR\fP modifier has no effect when restoring files not archived under names beginning with a / - even if the archive contains both kinds of names, the \fBR\fP modifier affects only those beginning with a /. .TP 8 .B I The \fBI\fP modifier causes \fItar\fP to read filenames for a \fBc\fP operation from its standard input, rather than from the argument list. (With other operations, the \fBI\fP keyletter is ignored.) This is intended largely for use with \fIfind(1)\fP, as in .QL find /u1 -mtime +7 -user karels -print | tar cvfI /dev/rmt12 .QE (note that if you just want to dump files newer than a certain time, the \fBs\fP keyletter is probably what you want). It is also useful in conjunction with \fBck\fP and \fBE list=\fP output from another run. .BL If \fBI\fP is given multiple times, the second (and later) occurrences need an argument. The first character of this argument is used as the filename terminator in the input (when \fBI\fP is given only once, a newline is used as the terminator). If the argument is zero characters long, the terminator is taken to be a NUL character. (See the \fBI\-source\fP long key, below, for more.) .TP 8 .B E The \fBE\fP keyletter describes what to do with files that did not dump correctly. In many cases, particularly when \fBe\fP or \fBi\fP is given, \fItar\fP can detect when a file was dumped incorrectly. This option specifies how to handle such files. It can be given multiple times; each option is processed separately. It takes an argument, which is a comma-separated list of options (whitespace is ignored after, but not before, the comma). Except as noted, they are independent. .BL now=\fIN\fP .br Specifies that the file is to be retried up to \fIN\fP times immediately after the failure, when the failure is one that can be retried (see below). .BL later=\fIN\fP .br Specifies that the file is to be retried up to \fIN\fP times at the end of the dump (after all normal dumping operations are complete), when the failure is one that can be retried (see below). .BL list=\fIpath\fP .br Specifies that the file's pathname is to be sent to the specified \fIpath\fP. No checking is done when the writes are attempted; errors such as ``disk full'' will not be noticed by \fItar\fP. Each failure to dump produces an entry (which can mean multiple entries for a given pathname, if retries are specified with \fBnow=\fP or \fBlater=\fP); each entry consists of a pathname followed by a NUL (not a newline). If multiple \fBlist=\fP specs are given, the last one silently overrides all others. See also the section below titled PATHNAME INTERPRETATION. .BL file=\fIkeyword\fP .br Allows another file, of the same name, to be written to the archive following the failed file (so as to overwrite it when extracted). The \fIkeyword\fP can be ``none'', which turns this feature off, ``empty'', which specifies that an empty file is to be written, or ``msg'', which specifies that a file containing an explanatory message is to be written. If multiple \fBfile=\fP values are given, the last one silently overrides all others. .BL log=\fIpath\fP .br Causes all complaints about files being dumped incorrectly to be sent to the specified \fIpath\fP as well as to stderr. If multiple \fBlog=\fP specs are given, the last one silently overrides all others. See also the section below titled PATHNAME INTERPRETATION. .BL Some failures can be retried (such as a file that changed size while being dumped); some failures cannot (such as an error opening the file). When a failure can be retried, the \fBnow=\fP and \fBlater=\fP options control how many retries happen and when; when all the specified retries have failed, or if the failure is one that cannot be retried, the \fBfile=\fP option controls what (if anything) is done. \fBlist=\fP is intended to be used to obtain a list of everything that made it to the tape but isn't correct; this can be used directly with a \fBcIIk \'\'\fP run to produce a kill archive appropriate for use when reading the tape. .TP 8 .B s \fItar\fP will archive files only whey they are newer than the time specified by the next argument. This argument can be a numeric time of the form YYYYMMDDhhmmss, where trailing components can be omitted (and default to the earliest possible value for that component). The month can also be given as the usual three-letter (English) abbreviations. If the argument does not have this form, it is assumed to be a pathname, and the mtime of that path is used. Note that this affects only plain files; all other entities are dumped regardless of their timestamps. .TP 8 .B M Normally, \fItar\fP stops when it sees a header block which indicates the end of the tape. The \fBM\fP modifier causes it to assume that another canister follows immediately; \fItar\fP effectively ignores the end-of-tape header and continues reading. .TP 8 .B O The \fBO\fP modifier causes \fItar\fP to write extracted files to \fItar\fP's standard output, rather than to disk files. If multiple files are being extracted, they are concatenated, with no indication where one file ends and the next begins. (The \fBO\fP keyletter will be ignored unless the operation indicator is \fBx\fP.) If you wish to just select some files from an archive, consider using \fBPx\fP rather than \fBO\fP. Note that directories, device special files, and other non-file entities cannot be extracted with \fBO\fP. .TP 8 .B W The presence of the \fBW\fP flag indicates that the ``filename'' arguments are actually filename patterns. When used with \fBc\fP operations, this affects only how arguments marked with \fB\-I\fP and \fB\-X\fP are matched; it does not affect processing of arguments that name files to go on the tape. With \fBt\fP or \fBx\fP, filenames from the tape are not matched literally against the argument list but rather the arguments are considered to be patterns, much like what the shell does. (Note that the pattern will normally have to be quoted to protect it from the shell. Note also that slashes must be explicitly represented; they cannot be match wildcards.) .TP 8 .B L The \fItar\fP format imposes a maximum length of 100 bytes on pathnames in an archive. Normally, this version of \fItar\fP uses a private header block format to handle longer names transparently. The \fBL\fP keyletter modifies this: if given once, names longer than 100 characters produce a warning message, but the archive is generated just as usual; if given twice, such items are omitted entirely from the generated archive. .TP 8 .B S The \fBS\fP flag indicates that \fItar\fP should take special actions to deal intelligently with sparse files. When copying files from disk to an archive, this flag indicates that the generated header should use a private format to store files, if they can benefit from it. When extracting files from an archive to disk, this causes \fItar\fP to create holes in the disk file whenever possible (regardless of whether the file in the archive is stored as a sparse file or not). When extracting a sparse file, the created file will have all the holes described by the archive format (sparse files are always recognized in an archive, even in the absence of the \fBS\fP flag); if \fBS\fP was given, it will also have all other possible holes. When a \fBP\fP operation is being performed, non-sparse files in the input archive are always output as non-sparse files, because the format used for sparse files is incompatible with the one-pass nature of \fBP\fP; if \fBS\fP is not given, all files in the output archive will be non-sparse, even if they were sparse in the input archive. When \fBS\fP is given with \fBP\fP, files that are sparse on input are sparse on output (and any files added due to the \fBc\fP keyletter may or may not be sparse, depending on the file contents). .TP 8 .B T Makes \fItar\fP paranoid about \fIftruncate(2)\fP. This is equivalent to the long key \fBftruncate paranoid\fP; see the \fBftruncate\fP long key for more. .TP 8 .B V \fItar\fP uses the next argument to specify where log-style output (output generated by the v or t keyletters) goes. .BL By default, such output goes to stdout if nothing else is going there, otherwise to stderr. See the \fBV\-toc\fP and \fBV\-info\fP keys, below, for finer-grained control. .BL See also the section below titled PATHNAME INTERPRETATION. .TP 8 .B X The \fBX\fP keyletter reverses the sense of the test \fItar\fP uses to determine whether a file is of interest during any operation that selects files from an archive based on the argument list. For precise details, see the section below on argument list processing. .TP 8 .B j Causes \fItar\fP to be paranoid when extracting an archive. This option enables checking to ensure that the extraction operation does not affect anything outside the directory \fItar\fP is running in. This is intended for use when extracting archives of unknown or untrusted origin. There are numerous things an archive normally does not contain, but could, which would cause damage; as a simple example, consider the following archive: .QL % tar tvf evil.tar rwxr-xr-x 0/0 0 Dec 10 09:47 1995 foo/ rwxrwxrwx 0/0 0 Dec 10 09:47 1995 foo/bar symbolic link to /etc rw-r--r-- 0/0 546 Dec 10 09:48 1995 foo/bar/passwd % .QE Such a thing would not be created by a simple \fItar\fP run, but could easily be constructed by a malicious person. The \fBj\fP keyletter checks each item being extracted to ensure it would not write outside the current directory, by walking the path and following any symlinks found. If a symlink to an absolute path is found, or if sufficient \fI\&../\fP components to ascend out of \fItar\fP's working directory are found, a complaint is printed and the item is skipped. (This option will also suppress the extraction of absolute pathnames even if \fBR\fP is given; this is arguably the wrong thing to do.) .TP 8 .B D Turns on internal debugging. Takes an argument, which is one or more debugging keywords, separated by one or more commas and/or spaces, each possibly prefixed with `!' to turn it off rather than on. One can also specify `\fBout=\fP\fIpath\fP' to redirect debugging output (no provision is made for paths containing spaces or commas), or `\fBhelp\fP' to get a list of valid keywords. The output is usually cryptic and useless for anything but debugging, and changes too often in any case, so this document makes no attempt to describe it. See also the section below titled PATHNAME INTERPRETATION. .PP An additional, more general, syntax is available for arguments. A \fB+\fP in the key argument directs \fItar\fP to read keys from the argument list; any keys that take arguments are followed immediately by those arguments. All the single-character keys that can appear in the first argument (except \fB+\fP itself) are valid on their own as keys under this syntax; in addition, many multi-character keys can appear. The list of keys is terminated by a \fB+\fP key; this terminates the list of arguments to the \fB+\fP in the first argument, and processing picks up with the next character following it, if any. For example, .QL tar cfiUvVr - /dev/rz0h /backup/logs/current 5 -C /home . .QE could (perhaps more comprehensibly) be written .QL tar + c f - i U /dev/rz0h v V /backup/logs/current r 5 + -C /home . .QE or .QL tar ci+v f - U /dev/rz0h V /backup/logs/current r 5 + -C /home . .QE or even .QL tar cUi+vr /dev/rz0h f - V /backup/logs/current + 5 -C /home . .QE or any of many other similar ways. If the terminating \fB+\fP would be the last argument to \fItar\fP, it can be omitted. .PP The permitted multi-character keys are as follows. For many of them, refer to the section below titled PATHNAME INTERPRETATION. .BL .TP 8 .B I\-source Turns on \fBI\fP-style archive creation, specifying an alternative input source. The \fBI\fP keyletter specifies that archive member names are to come from stdin; this allows them to come from anywhere, and also allows multiple streams to be read. Two arguments are used. The first specifies where the input is to come from; the second, what character is to be used to terminate arguments. C-style backslash escapes are accepted for the terminator, but are not necessary; if the second argument is only one character long, or if it doesn't begin with a backslash, its first character is the terminator (if it's zero characters long, NUL is used). Thus, \fBI\fP (given once) is equivalent to \fBI\-source \- \\n\fP. Input sources are read in the order they're specified. .TP 8 .B O\-to Turns on \fBO\fP-style extraction, but specifies an alternative place for the extracted output to go. Takes one argument. Plain \fBO\fP is equivalent to \fBO\-to \-\fP. .TP 8 .B P\-to Turns on \fBP\fP-style archive filtering, but specifies an alternative place for the output archive to go. Takes one argument. Plain \fBP\fP is equivalent to \fBP\-to \-\fP. (To specify where input comes from, use the \fBf\fP keyletter.) .TP 8 .B V\-toc Redirects \fBv\fP and \fBt\fP output, like \fBV\fP, but redirects only just enough of it to accumulate a list of what's actually on the tape. Other informational messages are not redirected, and continue to go where they would have gone (unless \fBV\-info\fP is also given). .TP 8 .B V\-info Redirects all output that \fBV\fP would redirect, except that which is controlled by \fBV\-toc\fP. (This doesn't control much. At present, it covers just reports of GNU-tar private or kill entries under \fBx\fP or \fBC\fP, difference reports from the \fBC\fP operation, and warnings from the \fBd\fP key.) .TP 8 .B i\-file Equivalent to \fBi\fP: dumps plain files by direct filesystem access. .TP 8 .B i\-full Takes one argument, which is a disk device name. Causes \fItar\fP to do direct-to-disk I/O for all filesystem access necessary for obtaining stuff to dump. In this mode, all pathnames of files to dump, directories to change to, etc, are treated as though rooted in the filesystem being dumped (the initial current directory is the root of the filesystem). The \fBd\fP key is implicitly in force as well, since the disk is being read at such a low level that mount points will not be noticed. The disk device being dumped does not have to be mounted; indeed, if it is mounted read/write, there is some danger that filesystem writes will change the filesystem while \fItar\fP is running. (The \fBe\fP, \fBr\fP, and \fBE\fP keyletters are designed to help deal with such situations.) The `disk device' does not even have to be a real disk device; it can be a filesystem image contained in an ordinary file. .TP 8 .B f\-stream\-term Takes two arguments. Causes \fItar\fP to read a list of strings from the place specified by the first argument (see PATHNAME INTERPRETATION, below); the second argument specifies a terminator character, as for the \fBI\-source\fP key, above. \fItar\fP reads these strings once, at startup, and behaves as though each one had been provided as an \fBf\fP keyletter argument. (Note that strings beginning with \- signs will be taken as requesting input from or output to a file descriptor, as described below.) This is wholly equivalent to specifying a separate \fBf\fP keyletter for each string, and can be used with any operation that \fBf\fP can be. .TP 8 .B f\-stream Equivalent to \fBf\-stream\-term\fP except that it provides a newline terminator automatically, and thus takes only one argument, not two. .TP 8 .B align Takes one argument, \fIN\fP, which is a tape block count. \fItar\fP will pad the output archive (with a private ``idling'' header block) as necessary so that no \fIN\fP-block boundary falls partway through an archive member (unless a single member requires more than \fIN\fP tape blocks, in which case that member will overlap an \fIN\fP-block boundary). These ``idling'' headers silently disappear on read; not even the \fBA\fP keyletter will make them visible. When \fBP\fP is used, the output archive will not contain any unless \fBalign\fP is given, regardless of what's in the input archive and what other flags are given. .BL Note that \fBalign\fP does not cause \fItar\fP to pad the end of the archive out to an alignment boundary, and it takes no notice of the output blocking factor (see the \fBb\fP and \fBB\fP keys), treating the output as a stream of tape blocks. It is designed for creating an archive which is split up into multiple tapes (or other pieces) of equal size, with reasonable confidence that no tape begins partway through an archive entry. (For this use, the \fBalign\fP argument will need to be a multiple of the tape blocking factor used when writing the archive pieces to tape.) .TP 8 .B ftruncate Takes one argument, which can be `unknown', `can\-grow', `shrink\-only', or `paranoid'. This affects \fItar\fP's behavior with respect to \fIftruncate(2)\fP. Some systems' versions of \fIftruncate\fP will extend files; others will only shrink them. By default, \fItar\fP's notion of \fIftruncate\fP's behavior is `unknown'; in this state, \fItar\fP will notice whether \fIftruncate\fP is willing to extend files or not, and will shift into 'can\-grow' or `shrink\-only' as appropriate; in the latter two states, it assumes that the behavior is as described. `paranoid' is a state in which \fItar\fP tries to use \fIftruncate\fP to extend, and if that fails, falls back on the `shrink\-only' behavior, but does not actually change state. See also the \fBT\fP keyletter. .BL This affects \fItar\fP's operation when doing a sparse file extract that wants to put a hole at the end of a file. The `paranoid' state is intended for cases (such as extractions across multiple heterogenous NFS servers) where \fIftruncate\fP may sometimes behave as `can\-grow' and sometimes as `shrink\-only', in a way too complicated for \fItar\fP to try to predict. .BL If multiple \fBftruncate\fP keys are given, the last one silently overrides all others. They affect only the initial state; if it's set to `unknown', it will automatically shift to `can\-grow' or `shrink\-only' at the first opportunity (the first time \fItar\fP wants to put a hole at the end of a file). .BL To generate a hole at the end of a file under `shrink\-only' behavior, \fItar\fP does an \fIlseek(2)\fP to a point one megabyte past the desired end-of-file, writes one byte, and then makes an \fIftruncate\fP call to truncate the file to the desired size. The intent is that any data blocks allocated for the write will be wholly discarded by the truncate. This is not perfect; it is still possible to end up allocating an ultimately unnecessary indirect block or two, but it's about as good as we can do without real kernel support for creating a hole at the end of a file. .TP 8 .B config Takes no arguments. Causes \fItar\fP to dump out a list of C preprocessor definitions used to build it, and then exit without examining any further arguments or taking any other actions. This is normally used only by people working with the source code, as when trying to debug or port \fItar\fP. .TP 8 .B sortdirs Takes no arguments. Normally, when creating an archive, \fItar\fP processes directory entries in the order it finds them in the directory. This option causes it to read the entire directory, sort the names, and process them in sorted order. It has no effect when not creating archives. .TP 8 .B unlink Takes no arguments. Causes \fItar\fP to use \fIunlink(2)\fP (or \fIrmdir(2)\fP, as appropriate) on filesystem objects as soon as they have been successfully appended to the archive. \fBThis is a dangerous option\fP; even after \fItar\fP has successfully appended an object to the archive, the archived version could be lost for any of many reasons: \fItar\fP could crash or be killed before flushing all of the buffered data to the place the archive is going; the archive could be going to a disk file on a partition which fills up unexpectedly; or the archive could be going to a tape drive which gets a write error, to name just three. .BL Note when using this option with \fBE\fP: \fItar\fP will not unlink files that failed to dump. If later= is used with \fBE\fP, and a file that fails to dump then successfully dumps on the `later' retry, \fItar\fP will attempt to unlink it at that point. The major implication of this is that the non-unlinked file can cause attempts to remove directories to fail with ``not empty'' errors; \fItar\fP is not capable of retrying the removal of the directories after dumping the file. This does not strike me as a heavy price, especially since the situations \fBE\fP is designed for are not ones where \fBunlink\fP would be appropriate. .TP 8 .B debug Equivalent to the \fBD\fP key. .PP There are also some options that can appear in the argument list: .TP 8 .B \-Q The \fB\-Q\fP (``quote'') flag indicates that the next argument is to be taken as a pathname, even if it looks like a flag, thus allowing files with names like \-H to be handled. .TP 8 .B \-C If a file name is preceded by \fB\-C\fP during a \fBc\fP operation, then \fItar\fP will perform a \fIchdir(2)\fP to that file name before processing the rest of the argument list. This allows multiple directories not related by a close common parent to be archived using short relative path names. For example, to archive files from /usr/include and from /etc, one might use .QL tar c -C /usr include -C / etc .QE which would put files on the tape with names like include/stdio.h and etc/fstab. Unlike some other tars, a \fB\-C\fP applies to all further filename arguments, not just the next one. .TP 8 .B \-X If a file name is preceded by \fB\-X\fP, the following name (or names matching the following pattern, with the \fBW\fP modifier) will be excluded from the operation. This allows the extraction of everything except a given file, for example. Note that the argument list is scanned left-to-right when determining whether a file should be included. For precise details, including how \fB\-X\fP interacts with the \fBX\fP keyletter, see the section below on argument list processing. .TP 8 .B \-I For a \fBc\fP operation, an argument may be preceded by \fB\-I\fP to suppress a later \fB\-X\fP that would otherwise exclude it. For example, one could exclude all .o files except those in a particular directory with something like .QL tar cf - src -I src/lib -X -T .o .QE See the section below on argument list processing for full details. .TP 8 .B \-H If an argument is preceded by \fB\-H\fP, that argument is considered to be matched if the argument is a prefix (`head') of the pathname under consideration. Normally, the argument must match exactly, or else match an initial string with a slash immediately following it. With this option, it need only be an initial string. For example, .QL tar xf - ./foo .QE would normally extract a file called ./foo/think.c, but would not extract a file called ./food.c. But if the command were .QL tar xf - -H ./foo .QE both would be extracted. .TP 8 .B \-T If an argument is preceded by \fB\-T\fP, that argument is considered to be matched if the argument is a suffix (``tail'') of the pathname under consideration. This is most useful to match extensions, as in .QL tar xf - -X -T .o ./src .QE but its use is not restricted to that. (For example, one could use .QL tar PxX -T / .QE to get an effect similar to that of .QL tar Po .QE \&.) .TP 8 .B \-F If an argument is preceded by \fB\-F\fP (``full''), that argument is considered to be matched only when it matches the pathname under consideration exactly (as opposed to normal processing, which will also match when the argument matches a prefix of the argument which is immediately followed by a slash). .TP 8 .B \-N Similar to \fB\-H\fP, \fB\-T\fP, and \fB\-F\fP, but restores normal processing: the argument must match exactly, or else match an initial string with a slash immediately following it. .TP 8 .B \-S Produces `synthetic' entries, that is, entries that do not necessarily match anything present on the archiving system. The argument is a structured string describing the entry to be synthesized. First can appear various prefixes which, when present, specify aspects of the synthetic entry: .TP 16 .B mode:xxxx:... The mode bits of the created entry will be xxxx, which must be an octal number, only the low 12 bits (four digits) of which will be used. .TP 16 .B uid:xxxx:... The owner UID in the archive entry will be xxxx, which must be a number. .TP 16 .B gid:xxxx:... The owner GID in the archive entry will be xxxx, which must be a number. .TP 16 .B mtime:xxxx:... The modify time in the archive entry will be xxxx, which must be a number giving the time in seconds-since-the-epoch. .TP 8 .B \& The defaults for these values are usually 0666 modified by the umask for the mode, the UID and GID of the \fItar\fP process for the uid and gid, and the current time for the mtime. However, for \fBfile:\fP synthesis, the defaults are those of the actual file, and for \fBdir:\fP, the default mode bits are 0777 modified by the umask. The entry, after any prefixes, can be: .TP 16 .B file:tape-name:actual-path Creates a plain-file entry, just as if actual-path (which must be a plain file) were being archived, except that the name used for it on the tape is tape-name. The defaults, as mentioned above, are those of actual-path. Note that actual-path is treated as it would be if it were simply given as a file to add at this point; in particular, \fB\-C\fP will affect relative paths and if \fBi-full\fP is in effect then the path will be followed in the filesystem being read. Also, if \fBh\fP is in effect, symlinks to plain files will be accepted. .TP 16 .B link:tape-name:linkto Creates a hard-link entry, just as if tape-name were being archived and it were a hard link to linkto. There is no requirement that linkto exist either on disk or in the archive (though the resulting archive may fail when extracted). .TP 16 .B symlink:tape-name:linkto Creates a symbolic-link entry, showing tape-name as a symbolic link pointing to linkto. .TP 16 .B bdev:tape-name:major:minor Creates a block-special device entry, showing tape-name as the name and major and minor as the major and minor numbers. This works even if \fItar\fP was compiled without device support. .TP 16 .B cdev:tape-name:major:minor Creates a character-special device entry, showing tape-name as the name and major and minor as the major and minor numbers. This works even if \fItar\fP was compiled without device support. .TP 16 .B fifo:tape-name Creates a FIFO-special device entry, showing tape-name as the name. This works even if \fItar\fP was compiled without FIFO support. .TP 16 .B dir:tape-name Creates a directory entry, showing tape-name as the name. Note that it does not create any entries for anything in the directory; they must be created separately if desired. A slash will always be appended to the name specified. As noted above, the default mode bits are 0777, not 0666 (but the umask is still applied). .TP 8 .B \& There is no way to `rename' directories, that is, to archive the contents of an existing directory as if its name were something else (as \fBfile:\fP does for files). .TP 8 .B \& Note that the above descriptions show `:' as a separator. This can actually be any non-letter character; the first non-letter after the keyword will be used as the delimiter for the rest of the entry (or, if it's one of the prefix keywords, the rest of that prefix). This allows names containing colons. .PP If more than one of \fB\-H\fP, \fB\-T\fP, \fB\-F\fP, and \fB\-N\fP are specified for a given argument, the last one given supersedes the rest. .SH "DIRECTORY CREATION" \fItar\fP will create directories as necessary when extracting archives. Directories are created with mode 700 to ensure that files can be extracted into them even if the mode in the archive would prohibit this; the modes are changed as soon as \fItar\fP sees something outside the directory. If the archive later contains more things within the directory, errors may occur. .PP Intermediate directories that do not appear on the archive are also possible; for example, assuming the existence of the necessary directories, .QL tar cf - dir1/dir2/dir3/file .QE will create an archive that calls for the creation of three directories that do not have corresponding archive entries. Such directories are created mode 700 like any others; when resetting the modes on them, \fItar\fP leaves them set to mode 777 modified by the umask, regardless of the \fBp\fP keyletter, and does not touch their ownership, leaving them owned by the user extracting the archive. The intent is to leave them as they would be if they had been created with \fImkdir(1)\fP. .SH "PATHNAME INTERPRETATION" There are several places where \fItar\fP takes a pathname to tell it where to read from or write to. At this writing, they are .nf \- archive filenames \- The \fBout=\fP argument to \fBD\fP or \fBdebug\fP \- The argument to \fBI\-source\fP \- The \fBlist=\fP or \fBlog=\fP argument to \fBE\fP \- The argument to \fBO-to\fP \- The argument to \fBV\fP, \fBV\-toc\fP, or \fBV\-info\fP \- The argument to \fBf\-stream\fP \- The first argument to \fBf\-stream\-term\fP .fi .br In these places, the string can be a lone \-, which means to use stdin or stdout as appropriate, a \- with a number appended, which means to read from or write to the specified descriptor (eg, \-2 to use stderr), or a pathname. When the first syntax is used (a bare \-), \fItar\fP performs checks to make sure that neither stdin nor stdout is in use for more than one thing. If you really want to overload stdin or stdout, use \-0 or \-1, as appropriate; this will not trigger these checks. (If you want to use \- or \-\fIn\fP as a pathname, simply prefix it with ./ so the \- is not the first character.) .BL When \- or \-\fIn\fP is used and the thing being read or written is an archive, the \fBB\fP key is effectively enabled for that archive automatically. .SH "ARGUMENT LIST PROCESSING" For \fBt\fP, \fBx\fP, and \fBC\fP operations, and \fBP\fP when \fBx\fP is also used, the argument list is taken to specify files of interest from an archive. In this case, the \fBX\fP and \fBW\fP keyletters, and the \fB\-X\fP, \fB\-W\fP, \fB\-H\fP, and \fB\-T\fP flags, control whether a given file is of interest. This is done as follows: .TP 4 \- If \fB\-W\fP is given, it means that the next argument is treated as if the \fBW\fP flag were given if it is actually absent, or vice versa. Note that giving \fB\-W\fP twice is equivalent to giving it once; it sets a flag that effectively toggles \fBW\fP, rather than itself being a toggle. .TP 4 \- \fB\-X\fP effectively toggles the \fBX\fP flag for the next argument, as \fB\-W\fP does for \fBW\fP. (This applies to \fBt\fP, \fBx\fP, \fBC\fP, and \fBP\fP when \fBx\fP is also given. See below for the effect of \fB\-X\fP on \fBc\fP operations.) .TP 4 \- If \fB\-H\fP is used, the argument must match a prefix (`head') of the pathname; if \fB\-T\fP, a suffix (`tail'); if \fB\-F\fP, it must match in its entirety (`full'); \fB\-N\fP (`normal') restores the default behavior, which is that the argument must either match the whole pathname or must match a prefix which is immediately followed by a slash. (If more than one of these options is given for some argument, the last one given takes precedence.) .TP 4 \- If no filename arguments at all are given, everything is considered to be of interest (even if the \fBX\fP keyletter is given); however, if at least one filename argument is given, but no argument matches, then the pathname is considered to be of interest iff the \fBX\fP keyletter was given. .PP For \fBc\fP operations, the argument list is scanned left-to-right. Each argument with no \fB\-C\fP, \fB\-X\fP, or \fB\-I\fP flag is considered for addition to the archive. When a directory is added to the archive, everything in it is considered for addition as well. For every thing that's being considered for addition, all arguments marked with \fB\-I\fP or \fB\-X\fP are scanned, left to right; the first match stops the scan. If the matching file is marked with \fB\-I\fP, the file is included; if \fB\-X\fP, it is not included. (If no such arguments match - for example, if no \fB\-I\fP or \fB\-X\fP options are present - it is included.) Note that the \fBX\fP keyletter is ignored. Arguments marked with \fB\-C\fP cause \fItar\fP to perform a \fBchdir(2)\fP call at that point in its pass through the argument list. If both \fB\-X\fP and \fB\-I\fP are given for the same argument, the last one given takes precedence. \fB\-W\fP, \fB\-H\fP, and \fB\-T\fP function as described above for \fBc\fP operations. Note that arguments marked with \fB\-I\fP and \fB\-X\fP describe pathnames as they would go on the tape, regardless of where they appear in the argument list; with \fB\-C\fP, the result can sometimes be counterintuitive. For example, .QL tar cf - -C / vmunix -X usr/include/stdio.h -C /usr include .QE will not work, because /usr/include/stdio.h would be archived under the name include/stdio.h, not usr/include/stdio.h. .SH FILES /dev/rmt? .SH "SEE ALSO" tar(5) .SH DIAGNOSTICS Complaints about bad key characters and failing system calls. .SH AUTHOR Mike Parker, at the time mouse@mcrcim.mcgill.edu. The impetus for, and the initial implementation of, the raw-filesystem code (the \fBi\fP keyletter and related options) is due to Concordia, in particular Steven Winikoff (then smw@alcor.concordia.ca) and Anne Bennett (then anne@alcor.concordia.ca). .SH BUGS There is no direct way to ask for the \fIn\fP-th occurrence of a file, though it can be done by prepending a appropriate kill archive or using \fBK\fP carefully. .BL Tape errors are handled ungracefully. .BL There is no way to selectively follow symbolic links. .BL Running out of memory usually means a coredump. .BL Some corrupted archives can cause \fItar\fP to crash. .BL There is no way to turn options like \fBM\fP on for only some of the \fBf\fP arguments.