Import sources from 2011-03-30 iso image - sys/man

1 files changed, 202 insertions, 0 deletions

diff --git a/sys/man/1/tar b/sys/man/1/tar
new file mode 100755
index 000000000..da79167dd
--- /dev/null
+++ b/sys/man/1/tar
@@ -0,0 +1,202 @@
+.TH TAR 1
+.SH NAME
+tar, dircp \- archiver
+.SH SYNOPSIS
+.B tar
+.I key
+[
+.I file ...
+]
+.PP
+.B dircp
+.I fromdir
+.I todir
+.SH DESCRIPTION
+.I Tar
+saves and restores file trees.
+It is most often used to transport a tree of files from one
+system to another.
+The
+.I key
+is a string that contains
+at most one function letter plus optional modifiers.
+Other arguments to the command are names of
+files or directories to be dumped or restored.
+A directory name implies all the contained
+files and subdirectories (recursively).
+.PP
+The function is one of the following letters:
+.TP
+.B  c
+Create a new archive with the given files as contents.
+.TP
+.B  r
+The named files
+are appended to the archive.
+.TP
+.B  t
+List all occurrences of each 
+.I file
+in the archive, or of all files if there are no
+.I file
+arguments.
+.TP
+.B  x
+Extract the named files from the archive.
+If a file is a directory, the directory is extracted recursively.
+Modes are restored if possible.
+If no file argument is given, extract the entire archive.
+If the archive contains multiple entries for a file,
+the latest one wins.
+.PP
+The modifiers are:
+.TP
+.B f
+Use the next argument as the name of the archive instead of
+the default standard input (for keys
+.B x
+and
+.BR t )
+or standard output (for keys
+.B c
+and
+.BR r ).
+.TP
+.B g
+Use the next (numeric) argument as the group id for files in
+the output archive.
+.TP
+.B i
+Ignore errors encountered when reading.
+Errors writing either produce a corrupt archive
+or indicate deeper file system problems.
+.TP
+.B k
+(keep)
+Modifies the behavior of
+.B x
+not to extract files which already exist.
+.TP
+.B m
+Do not set the modification time on extracted files.
+This is the default behavior; the flag exists only for compatibility with other tars.
+.TP
+.B p
+Create archive in POSIX ustar format,
+which raises the maximum pathname length from 100 to 256 bytes.
+Ustar archives are recognised automatically by
+.I tar
+when reading archives.
+This is the default behavior; the flag exists only for backwards compatibility
+with older versions of tar.
+.TP
+.B P
+Do not generate the POSIX ustar format.
+.TP
+.B R
+When extracting, respect leading slash on file names.
+By default, files are always extracted relative to the current directory.
+.TP
+.B s
+When extracting, attempt to resynchronise after not finding a tape header
+block where expected.
+.TP
+.B T
+Modifies the behavior of
+.B x
+to set the modified time,
+mode and, for POSIX archives and filesystem permitting,
+the user and group
+of each file to that specified in the archive.
+.TP
+.B u
+Use the next (numeric) argument as the user id for files in
+the output archive.  This is only useful when moving files to
+a non-Plan 9 system.
+.TP
+.B v
+(verbose)
+Print the name of each file as it is processed.
+With
+.BR t ,
+give more details about the
+archive entries.
+.TP
+.B z
+Operate on compressed
+.I tar
+archives.
+The type of compression is inferred from the file name extension:
+.IR gzip (1)
+for
+.B .tar.gz
+and
+.BR .tgz ;
+.I bzip2
+(see
+.IR gzip (1))
+for
+.BR .tar.bz ,
+.BR .tbz ,
+.BR .tar.bz2 ,
+and
+.BR .tbz2 ;
+.I compress
+for
+.B .tar.Z
+and
+.BR .tz .
+If no extension matches,
+.I gzip
+is used.
+The
+.B z
+flag is unnecessary (but allowed) when using the
+.B t
+and
+.B x
+verbs on archives with recognized extensions.
+.br
+.ne 6
+.SH EXAMPLES
+.I Tar
+can be used to copy hierarchies thus:
+.IP
+.EX
+@{cd fromdir && tar c .} | @{cd todir && tar xT}
+.EE
+.PP
+.I Dircp
+does this.
+.SH SOURCE
+.B /sys/src/cmd/tar.c
+.br
+.B /rc/bin/dircp
+.SH SEE ALSO
+.IR ar (1),
+.IR bundle (1),
+.IR tapefs (4),
+.IR mkfs (8)
+.SH BUGS
+There is no way to ask for any but the last
+occurrence of a file.
+.PP
+File path names are limited to
+100 characters
+(256 when using ustar format).
+.PP
+The
+.I tar
+format allows specification of links and symbolic links,
+concepts foreign to Plan 9: they are ignored.
+.PP
+The
+.B r
+key (append)
+cannot be used on compressed archives.
+.PP
+.IR Tar ,
+thus
+.IR dircp ,
+doesn't record Plan-9-specific metadata
+such as append-only and exclusive-open permission bits, so they aren't copied.