X-Git-Url: https://git.gag.com/?a=blobdiff_plain;f=tar.1;h=a411bc0c15a24c46914245f681fd1e220a7f9367;hb=636335dbb356165e1d3e7cf91c416696d8b93910;hp=907eb460aeed9f240c093e6c140d5e5487a71f78;hpb=def03712042d935b1238542b15d62f5121b9d5d2;p=debian%2Fpax diff --git a/tar.1 b/tar.1 index 907eb46..a411bc0 100644 --- a/tar.1 +++ b/tar.1 @@ -1,3 +1,4 @@ +.\" $OpenBSD: tar.1,v 1.50 2008/06/11 00:49:08 pvalchev Exp $ .\" .\" Copyright (c) 1996 SigmaSoft, Th. Lockert .\" All rights reserved. @@ -10,11 +11,6 @@ .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. -.\" 3. All advertising materials mentioning features or use of this software -.\" must display the following acknowledgement: -.\" This product includes software developed by SigmaSoft, Th. Lockert. -.\" 4. The name of the author may not be used to endorse or promote products -.\" derived from this software without specific prior written permission .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES @@ -27,79 +23,147 @@ .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.\" $OpenBSD: tar.1,v 1.17 1998/09/23 00:13:49 aaron Exp $ +.\" $OpenBSD: tar.1,v 1.50 2008/06/11 00:49:08 pvalchev Exp $ .\" -.Dd June 11, 1996 +.Dd $Mdocdate: June 11 2008 $ .Dt TAR 1 .Os .Sh NAME .Nm tar .Nd tape archiver .Sh SYNOPSIS -.Nm -.No [-]{crtux}[befhmopvwzHLPXZ014578] -.Op Ar archive -.Op Ar blocksize -.\" XXX how to do this right? -.No [-C -.Ar directory -.No ] -.No [-s -.Ar replstr -.No ] -.Ar file1 -.Op Ar file2 ... +.Nm tar +.Sm off +.No { Cm crtux No } Op Cm 014578befHhjLmOoPpqsvwXZz +.Sm on +.Bk -words +.Op Ar blocking-factor | archive | replstr +.Op Fl C Ar directory +.Op Fl I Ar file +.Op Ar file ... +.Ek +.Nm tar +.No { Ns Fl crtux Ns } +.Op Fl 014578eHhjLmOoPpqvwXZz +.Op Fl b Ar blocking-factor +.Op Fl C Ar directory +.Op Fl f Ar archive +.Op Fl I Ar file +.Op Fl s Ar replstr +.Op Ar file ... .Sh DESCRIPTION The .Nm command creates, adds files to, or extracts files from an -archive file in \*Qtar\*U format. A tar archive is often -stored on a magnetic tape, but can be a floppy or a regular -disk file. +archive file in +.Dq tar +format. +A tar archive is often stored on a magnetic tape, but can be +stored equally well on a floppy, CD-ROM, or in a regular disk file. +.Pp +In the first (legacy) form, all option flags except for +.Fl C +and +.Fl I +must be contained within the first argument to +.Nm +and must not be prefixed by a hyphen +.Pq Sq - . +Option arguments, if any, are processed as subsequent arguments to +.Nm +and are processed in the order in which their corresponding option +flags have been presented on the command line. +.Pp +In the second and preferred form, option flags may be given in any order +and are immediately followed by their corresponding option argument +values. .Pp One of the following flags must be present: -.Bl -tag -width Ar +.Bl -tag -width Ds .It Fl c Create new archive, or overwrite an existing archive, adding the specified files to it. .It Fl r -Append the named new files to existing archive. Note that -this will only work on media on which an end-of-file mark +Append the named new files to existing archive. +Note that this will only work on media on which an end-of-file mark can be overwritten. .It Fl t -List contents of archive. If any files are named on the +List contents of archive. +If any files are named on the command line, only those files will be listed. +The +.Ar file +arguments may be specified as glob patterns (see +.Xr glob 3 +for more information), in which case +.Nm +will list all archive members that match each pattern. .It Fl u Alias for .Fl r . .It Fl x -Extract files from archive. If any files are named on the +Extract files from archive. +If any files are named on the command line, only those files will be extracted from the -archive. If more than one copy of a file exists in the +archive. +The +.Ar file +arguments may be specified as glob patterns (see +.Xr glob 3 +for more information), in which case +.Nm +will extract all archive members that match each pattern. +.Pp +If more than one copy of a file exists in the archive, later copies will overwrite earlier copies during -extraction. The file mode and modification time are preserved -if possible. The file mode is subject to modification by the +extraction. +The file mode and modification time are preserved +if possible. +The file mode is subject to modification by the .Xr umask 2 . .El .Pp In addition to the flags mentioned above, any of the following flags may be used: -.Bl -tag -width Ar -.It Fl b Ar "blocking factor" +.Bl -tag -width Ds +.It Fl b Ar blocking-factor Set blocking factor to use for the archive. .Nm -uses 512 byte blocks. The default is 20, the maximum is 126. -Archives with a blocking factor larger 63 violate the +uses 512-byte blocks. +The default is 20, the maximum is 126. +Archives with a blocking factor larger than 63 violate the .Tn POSIX standard and will not be portable to all systems. +.It Fl C Ar directory +This is a positional argument which sets the working directory for the +following files. +When extracting, files will be extracted into +the specified directory; when creating, the specified files will be matched +from the directory. .It Fl e -Stop after first error. +Stop after the first error. .It Fl f Ar archive -Filename where the archive is stored. Defaults to +Filename where the archive is stored. +Defaults to .Pa /dev/rst0 . +.It Fl H +Follow symlinks given on the command line only. .It Fl h Follow symbolic links as if they were normal files or directories. +In extract mode this means that a directory entry in the archive +will not overwrite an existing symbolic link, but rather what the +link ultimately points to. +.It Fl I Ar file +This is a positional argument which reads the names of files to +archive or extract from the given file, one per line. +.It Fl j +Compress archive using bzip2. +The bzip2 utility must be installed separately. +.It Fl L +Synonym for the +.Fl h +option. .It Fl m Do not preserve modification time. .It Fl O @@ -111,104 +175,164 @@ is unable to decode. This implies the .Fl O flag. +.It Fl P +Do not strip leading slashes +.Pq Sq / +from pathnames. +The default is to strip leading slashes. .It Fl p Preserve user and group ID as well as file mode regardless of the current .Xr umask 2 . The setuid and setgid bits are only preserved if the user is -the superuser. Only meaningful in conjunction with the +the superuser. +Only meaningful in conjunction with the .Fl x flag. -.It Fl s Ar replstr -Modify the file or archive member names specified by the -.Ar pattern -or +.It Fl q +Select the first archive member that matches each .Ar file -operands according to the substitution expression +operand. +No more than one archive member is matched for each +.Ar file . +When members of type directory are matched, the file hierarchy rooted at that +directory is also matched. +.It Fl s Ar replstr +Modify the archive member names according to the substitution expression .Ar replstr , using the syntax of the .Xr ed 1 utility regular expressions. -The format of these regular expressions are: +.Ar file +arguments may be given to restrict the list of archive members to those +specified. +.Pp +The format of these regular expressions is +.Pp .Dl /old/new/[gp] +.Pp As in .Xr ed 1 , -.Cm old -is a basic regular expression and -.Cm new -can contain an ampersand (&), \\n (where n is a digit) back-references, +.Va old +is a basic regular expression (see +.Xr re_format 7 ) +and +.Va new +can contain an ampersand +.Pq Ql & , +.Ql \e Ns Em n +(where +.Em n +is a digit) back-references, or subexpression matching. The -.Cm old -string may also contain -.Dv -characters. -Any non-null character can be used as a delimiter (/ is shown here). +.Va old +string may also contain newline characters. +Any non-null character can be used as a delimiter +.Po +.Ql / +is shown here +.Pc . Multiple .Fl s expressions can be specified. The expressions are applied in the order they are specified on the command line, terminating with the first successful substitution. +.Pp The optional trailing .Cm g -continues to apply the substitution expression to the pathname substring +continues to apply the substitution expression to the pathname substring, which starts with the first character following the end of the last successful -substitution. The first unsuccessful substitution stops the operation of the +substitution. +The first unsuccessful substitution stops the operation of the .Cm g option. The optional trailing .Cm p will cause the final result of a successful substitution to be written to -.Dv standard error -in the following format: -.Dl >> +standard error in the following format: +.Pp +.D1 Em original-pathname No >> Em new-pathname +.Pp File or archive member names that substitute to the empty string are not selected and will be skipped. .It Fl v Verbose operation mode. .It Fl w -Interactively rename files. This option causes +Interactively rename files. +This option causes .Nm to prompt the user for the filename to use when storing or extracting files in an archive. -.It Fl z -Compress archive using gzip. -.It Fl C Ar directory -This is a positional argument which sets the working directory for the -following files. When extracting, files will be extracted into -the specified directory; when creating, the specified files will be matched -from the directory. -.It Fl H -Follow symlinks given on command line only. -.It Fl L -Follow all symlinks. -.It Fl P -Do not strip leading slashes (``/'') from pathnames. -The default is to strip leading slashes. .It Fl X Do not cross mount points in the file system. .It Fl Z -Compress archive using compress. +Compress archive using +.Xr compress 1 . +.It Fl z +Compress archive using +.Xr gzip 1 . .El .Pp The options .Op Fl 014578 can be used to select one of the compiled-in backup devices, .Pa /dev/rstN . +.Sh ENVIRONMENT +.Bl -tag -width Fl +.It Ev TMPDIR +Path in which to store temporary files. +.It Ev TAPE +Default tape device to use instead of +.Pa /dev/rst0 . +.El .Sh FILES .Bl -tag -width "/dev/rst0" .It Pa /dev/rst0 default archive name .El -.Sh SEE ALSO -.Xr cpio 1 , -.Xr pax 1 -.Sh AUTHOR -Keith Muller at the University of California, San Diego. -.Sh ERRORS +.Sh EXAMPLES +Create an archive on the default tape drive, containing the files named +.Pa bonvole +and +.Pa sekve : +.Pp +.Dl $ tar c bonvole sekve +.Pp +Output a +.Xr gzip 1 +compressed archive containing the files +.Pa bonvole +and +.Pa sekve +to a file called +.Pa foriru.tar.gz : +.Pp +.Dl $ tar zcf foriru.tar.gz bonvole sekve +.Pp +Verbosely create an archive, called +.Pa backup.tar.gz , +of all files matching the shell +.Xr glob 3 +function +.Pa *.c : +.Pp +.Dl $ tar zcvf backup.tar.gz *.c +.Pp +Verbosely list, but do not extract, all files ending in +.Pa .jpeg +from a compressed archive named +.Pa backup.tar.gz . +Note that the glob pattern has been quoted to avoid expansion by the shell: +.Pp +.Dl $ tar tvzf backup.tar.gz '*.jpeg' +.Pp +For more detailed examples, see +.Xr pax 1 . +.Sh DIAGNOSTICS .Nm will exit with one of the following values: -.Bl -tag -width 2n +.Bl -tag -width 2n -offset indent .It 0 All files were processed successfully. .It 1 @@ -219,11 +343,12 @@ Whenever .Nm cannot create a file or a link when extracting an archive or cannot find a file while writing an archive, or cannot preserve the user -ID, group ID, file mode or access and modification times when the +ID, group ID, file mode, or access and modification times when the .Fl p option is specified, a diagnostic message is written to standard error and a non-zero exit value will be returned, but processing -will continue. In the case where +will continue. +In the case where .Nm cannot create a link to a file, .Nm @@ -240,5 +365,23 @@ be wrong. If the creation of an archive is prematurely terminated by a signal or error, .Nm -may have only partially created the archive which may violate the +may have only partially created the archive, which may violate the specific archive format specification. +.Sh SEE ALSO +.Xr cpio 1 , +.Xr pax 1 +.Sh HISTORY +A +.Nm +command first appeared in +.At v7 . +.Sh AUTHORS +Keith Muller at the University of California, San Diego. +.Sh CAVEATS +The +.Fl j +and +.Fl L +flags are not portable to other versions of +.Nm +where they may have a different meaning.