From 16f738ecee689c6feb2acb7e4ef4d9bb4144ae7d Mon Sep 17 00:00:00 2001 From: Tomas Bzatek Date: Sun, 8 Jun 2008 11:04:43 +0200 Subject: Initial commit --- libarchive/libarchive-2.4.17/doc/text/bsdtar.1 | 441 +++++++++++++++++++++++++ 1 file changed, 441 insertions(+) create mode 100644 libarchive/libarchive-2.4.17/doc/text/bsdtar.1 (limited to 'libarchive/libarchive-2.4.17/doc/text/bsdtar.1') diff --git a/libarchive/libarchive-2.4.17/doc/text/bsdtar.1 b/libarchive/libarchive-2.4.17/doc/text/bsdtar.1 new file mode 100644 index 0000000..9a62753 --- /dev/null +++ b/libarchive/libarchive-2.4.17/doc/text/bsdtar.1 @@ -0,0 +1,441 @@ +BSDTAR(1) FreeBSD General Commands Manual BSDTAR(1) + +NAME + tar -- manipulate tape archives + +SYNOPSIS + tar [bundled-flags ] [ | ...] + tar {-c} [options] [files | directories] + tar {-r | -u} -f archive-file [options] [files | directories] + tar {-t | -x} [options] [patterns] + +DESCRIPTION + tar creates and manipulates streaming archive files. This implementation + can extract from tar, pax, cpio, zip, jar, ar, and ISO 9660 cdrom images + and can create tar, pax, cpio, ar, and shar archives. + + The first synopsis form shows a ``bundled'' option word. This usage is + provided for compatibility with historical implementations. See COMPATI- + BILITY below for details. + + The other synopsis forms show the preferred usage. The first option to + tar is a mode indicator from the following list: + -c Create a new archive containing the specified items. + -r Like -c, but new entries are appended to the archive. Note that + this only works on uncompressed archives stored in regular files. + The -f option is required. + -t List archive contents to stdout. + -u Like -r, but new entries are added only if they have a modifica- + tion date newer than the corresponding entry in the archive. + Note that this only works on uncompressed archives stored in reg- + ular files. The -f option is required. + -x Extract to disk from the archive. If a file with the same name + appears more than once in the archive, each copy will be + extracted, with later copies overwriting (replacing) earlier + copies. + + In -c, -r, or -u mode, each specified file or directory is added to the + archive in the order specified on the command line. By default, the con- + tents of each directory are also archived. + + In extract or list mode, the entire command line is read and parsed + before the archive is opened. The pathnames or patterns on the command + line indicate which items in the archive should be processed. Patterns + are shell-style globbing patterns as documented in tcsh(1). + +OPTIONS + Unless specifically stated otherwise, options are applicable in all oper- + ating modes. + + @archive + (c and r mode only) The specified archive is opened and the + entries in it will be appended to the current archive. As a sim- + ple example, + tar -c -f - newfile @original.tar + writes a new archive to standard output containing a file newfile + and all of the entries from original.tar. In contrast, + tar -c -f - newfile original.tar + creates a new archive with only two entries. Similarly, + tar -czf - --format pax @- + reads an archive from standard input (whose format will be deter- + mined automatically) and converts it into a gzip-compressed pax- + format archive on stdout. In this way, tar can be used to con- + vert archives from one format to another. + + -b blocksize + Specify the block size, in 512-byte records, for tape drive I/O. + As a rule, this argument is only needed when reading from or + writing to tape drives, and usually not even then as the default + block size of 20 records (10240 bytes) is very common. + + -C directory + In c and r mode, this changes the directory before adding the + following files. In x mode, change directories after opening the + archive but before extracting entries from the archive. + + --check-links (-W check-links) + (c and r modes only) Issue a warning message unless all links to + each file are archived. + + --exclude pattern (-W exclude=pattern) + Do not process files or directories that match the specified pat- + tern. Note that exclusions take precedence over patterns or + filenames specified on the command line. + + --format format (-W format=format) + (c mode only) Use the specified format for the created archive. + Supported formats include ``cpio'', ``pax'', ``shar'', and + ``ustar''. Other formats may also be supported; see + libarchive-formats(5) for more information about currently-sup- + ported formats. + + -f file + Read the archive from or write the archive to the specified file. + The filename can be - for standard input or standard output. If + not specified, the default tape device will be used. (On + FreeBSD, the default tape device is /dev/sa0.) + + --fast-read (-W fast-read) + (x and t mode only) Extract or list only the first archive entry + that matches each pattern or filename operand. Exit as soon as + each specified pattern or filename has been matched. By default, + the archive is always read to the very end, since there can be + multiple entries with the same name and, by convention, later + entries overwrite earlier entries. This option is provided as a + performance optimization. + + -H (c and r mode only) Symbolic links named on the command line will + be followed; the target of the link will be archived, not the + link itself. + + -h (c and r mode only) Synonym for -L. + + -I Synonym for -T. + + --include pattern (-W include=pattern) + Process only files or directories that match the specified pat- + tern. Note that exclusions specified with --exclude take prece- + dence over inclusions. If no inclusions are explicitly speci- + fied, all entries are processed by default. The --include option + is especially useful when filtering archives. For example, the + command + tar -c -f new.tar --include='*foo*' @old.tgz + creates a new archive new.tar containing only the entries from + old.tgz containing the string `foo'. + + -j (c mode only) Compress the resulting archive with bzip2(1). In + extract or list modes, this option is ignored. Note that, unlike + other tar implementations, this implementation recognizes bzip2 + compression automatically when reading archives. + + -k (x mode only) Do not overwrite existing files. In particular, if + a file appears more than once in an archive, later copies will + not overwrite earlier copies. + + -L (c and r mode only) All symbolic links will be followed. Nor- + mally, symbolic links are archived as such. With this option, + the target of the link will be archived instead. + + -l This is a synonym for the --check-links option. + + -m (x mode only) Do not extract modification time. By default, the + modification time is set to the time stored in the archive. + + -n (c, r, u modes only) Do not recursively archive the contents of + directories. + + --newer date (-W newer=date) + (c, r, u modes only) Only include files and directories newer + than the specified date. This compares ctime entries. + + --newer-mtime date (-W newer-mtime=date) + (c, r, u modes only) Like --newer, except it compares mtime + entries instead of ctime entries. + + --newer-than file (-W newer-than=file) + (c, r, u modes only) Only include files and directories newer + than the specified file. This compares ctime entries. + + --newer-mtime-than file (-W newer-mtime-than=file) + (c, r, u modes only) Like --newer-than, except it compares mtime + entries instead of ctime entries. + + --nodump (-W nodump) + (c and r modes only) Honor the nodump file flag by skipping this + file. + + --null (-W null) + (use with -I, -T, or -X) Filenames or patterns are separated by + null characters, not by newlines. This is often used to read + filenames output by the -print0 option to find(1). + + -O (x, t modes only) In extract (-x) mode, files will be written to + standard out rather than being extracted to disk. In list (-t) + mode, the file listing will be written to stderr rather than the + usual stdout. + + -o (x mode only) Use the user and group of the user running the pro- + gram rather than those specified in the archive. Note that this + has no significance unless -p is specified, and the program is + being run by the root user. In this case, the file modes and + flags from the archive will be restored, but ACLs or owner infor- + mation in the archive will be discarded. + + --one-file-system (-W one-file-system) + (c, r, and u modes) Do not cross mount points. + + -P Preserve pathnames. By default, absolute pathnames (those that + begin with a / character) have the leading slash removed both + when creating archives and extracting from them. Also, tar will + refuse to extract archive entries whose pathnames contain .. or + whose target directory would be altered by a symlink. This + option suppresses these behaviors. + + -p (x mode only) Preserve file permissions. Attempt to restore the + full permissions, including owner, file modes, file flags and + ACLs, if available, for each item extracted from the archive. By + default, newly-created files are owned by the user running tar, + the file mode is restored for newly-created regular files, and + all other types of entries receive default permissions. If tar + is being run by root, the default is to restore the owner unless + the -o option is also specified. + + --strip-components count (-W strip-components=count) + (x and t mode only) Remove the specified number of leading path + elements. Pathnames with fewer elements will be silently + skipped. Note that the pathname is edited after checking inclu- + sion/exclusion patterns but before security checks. + + -T filename + In x or t mode, tar will read the list of names to be extracted + from filename. In c mode, tar will read names to be archived + from filename. The special name ``-C'' on a line by itself will + cause the current directory to be changed to the directory speci- + fied on the following line. Names are terminated by newlines + unless --null is specified. Note that --null also disables the + special handling of lines containing ``-C''. + + -U (x mode only) Unlink files before creating them. Without this + option, tar overwrites existing files, which preserves existing + hardlinks. With this option, existing hardlinks will be broken, + as will any symlink that would affect the location of an + extracted file. + + --use-compress-program program + Pipe the input (in x or t mode) or the output (in c mode) through + program instead of using the builtin compression support. + + -v Produce verbose output. In create and extract modes, tar will + list each file name as it is read from or written to the archive. + In list mode, tar will produce output similar to that of ls(1). + Additional -v options will provide additional detail. + + -W longopt=value + Long options (preceded by --) are only supported directly on sys- + tems that have the getopt_long(3) function. The -W option can be + used to access long options on systems that do not support this + function. + + -w Ask for confirmation for every action. + + -X filename + Read a list of exclusion patterns from the specified file. See + --exclude for more information about the handling of exclusions. + + -y (c mode only) Compress the resulting archive with bzip2(1). In + extract or list modes, this option is ignored. Note that, unlike + other tar implementations, this implementation recognizes bzip2 + compression automatically when reading archives. + + -z (c mode only) Compress the resulting archive with gzip(1). In + extract or list modes, this option is ignored. Note that, unlike + other tar implementations, this implementation recognizes gzip + compression automatically when reading archives. + +ENVIRONMENT + The following environment variables affect the execution of tar: + + LANG The locale to use. See environ(7) for more information. + + TAPE The default tape device. The -f option overrides this. + + TZ The timezone to use when displaying dates. See environ(7) for + more information. + +FILES + /dev/sa0 The default tape device, if not overridden by the TAPE envi- + ronment variable or the -f option. + +EXIT STATUS + The tar utility exits 0 on success, and >0 if an error occurs. + +EXAMPLES + The following creates a new archive called file.tar.gz that contains two + files source.c and source.h: + tar -czf file.tar.gz source.c source.h + + To view a detailed table of contents for this archive: + tar -tvf file.tar.gz + + To extract all entries from the archive on the default tape drive: + tar -x + + To examine the contents of an ISO 9660 cdrom image: + tar -tf image.iso + + To move file hierarchies, invoke tar as + tar -cf - -C srcdir . | tar -xpf - -C destdir + or more traditionally + cd srcdir ; tar -cf - . | (cd destdir ; tar -xpf -) + + In create mode, the list of files and directories to be archived can also + include directory change instructions of the form -Cfoo/baz and archive + inclusions of the form @archive-file. For example, the command line + tar -c -f new.tar foo1 @old.tgz -C/tmp foo2 + will create a new archive new.tar. tar will read the file foo1 from the + current directory and add it to the output archive. It will then read + each entry from old.tgz and add those entries to the output archive. + Finally, it will switch to the /tmp directory and add foo2 to the output + archive. + + The --newer and --newer-mtime switches accept a variety of common date + and time specifications, including ``12 Mar 2005 7:14:29pm'', + ``2005-03-12 19:14'', ``5 minutes ago'', and ``19:14 PST May 1''. + +COMPATIBILITY + The bundled-arguments format is supported for compatibility with historic + implementations. It consists of an initial word (with no leading - char- + acter) in which each character indicates an option. Arguments follow as + separate words. The order of the arguments must match the order of the + corresponding characters in the bundled command word. For example, + tar tbf 32 file.tar + specifies three flags t, b, and f. The b and f flags both require argu- + ments, so there must be two additional items on the command line. The 32 + is the argument to the b flag, and file.tar is the argument to the f + flag. + + The mode options c, r, t, u, and x and the options b, f, l, m, o, v, and + w comply with SUSv2. + + For maximum portability, scripts that invoke tar should use the bundled- + argument format above, should limit themselves to the c, t, and x modes, + and the b, f, m, v, and w options. + + On systems that support getopt_long(), additional long options are avail- + able to improve compatibility with other tar implementations. + +SECURITY + Certain security issues are common to many archiving programs, including + tar. In particular, carefully-crafted archives can request that tar + extract files to locations outside of the target directory. This can + potentially be used to cause unwitting users to overwrite files they did + not intend to overwrite. If the archive is being extracted by the supe- + ruser, any file on the system can potentially be overwritten. There are + three ways this can happen. Although tar has mechanisms to protect + against each one, savvy users should be aware of the implications: + + o Archive entries can have absolute pathnames. By default, tar + removes the leading / character from filenames before restoring + them to guard against this problem. + + o Archive entries can have pathnames that include .. components. + By default, tar will not extract files containing .. components + in their pathname. + + o Archive entries can exploit symbolic links to restore files to + other directories. An archive can restore a symbolic link to + another directory, then use that link to restore a file into that + directory. To guard against this, tar checks each extracted path + for symlinks. If the final path element is a symlink, it will be + removed and replaced with the archive entry. If -U is specified, + any intermediate symlink will also be unconditionally removed. + If neither -U nor -P is specified, tar will refuse to extract the + entry. + To protect yourself, you should be wary of any archives that come from + untrusted sources. You should examine the contents of an archive with + tar -tf filename + before extraction. You should use the -k option to ensure that tar will + not overwrite any existing files or the -U option to remove any pre- + existing files. You should generally not extract archives while running + with super-user privileges. Note that the -P option to tar disables the + security checks above and allows you to extract an archive while preserv- + ing any absolute pathnames, .. components, or symlinks to other directo- + ries. + +SEE ALSO + bzip2(1), cpio(1), gzip(1), mt(1), pax(1), shar(1), libarchive(3), + libarchive-formats(5), tar(5) + +STANDARDS + There is no current POSIX standard for the tar command; it appeared in + ISO/IEC 9945-1:1996 (``POSIX.1'') but was dropped from IEEE Std + 1003.1-2001 (``POSIX.1''). The options used by this implementation were + developed by surveying a number of existing tar implementations as well + as the old POSIX specification for tar and the current POSIX specifica- + tion for pax. + + The ustar and pax interchange file formats are defined by IEEE Std + 1003.1-2001 (``POSIX.1'') for the pax command. + +HISTORY + A tar command appeared in Seventh Edition Unix, which was released in + January, 1979. There have been numerous other implementations, many of + which extended the file format. John Gilmore's pdtar public-domain + implementation (circa November, 1987) was quite influential, and formed + the basis of GNU tar. GNU tar was included as the standard system tar in + FreeBSD beginning with FreeBSD 1.0. + + This is a complete re-implementation based on the libarchive(3) library. + +BUGS + This program follows ISO/IEC 9945-1:1996 (``POSIX.1'') for the definition + of the -l option. Note that GNU tar prior to version 1.15 treated -l as + a synonym for the --one-file-system option. + + The -C dir option may differ from historic implementations. + + All archive output is written in correctly-sized blocks, even if the out- + put is being compressed. Whether or not the last output block is padded + to a full block size varies depending on the format and the output + device. For tar and cpio formats, the last block of output is padded to + a full block size if the output is being written to standard output or to + a character or block device such as a tape drive. If the output is being + written to a regular file, the last block will not be padded. Many com- + pressors, including gzip(1) and bzip2(1), complain about the null padding + when decompressing an archive created by tar, although they still extract + it correctly. + + The compression and decompression is implemented internally, so there may + be insignificant differences between the compressed output generated by + tar -czf - file + and that generated by + tar -cf - file | gzip + + The default should be to read and write archives to the standard I/O + paths, but tradition (and POSIX) dictates otherwise. + + The r and u modes require that the archive be uncompressed and located in + a regular file on disk. Other archives can be modified using c mode with + the @archive-file extension. + + To archive a file called @foo or -foo you must specify it as ./@foo or + ./-foo, respectively. + + In create mode, a leading ./ is always removed. A leading / is stripped + unless the -P option is specified. + + There needs to be better support for file selection on both create and + extract. + + There is not yet any support for multi-volume archives or for archiving + sparse files. + + Converting between dissimilar archive formats (such as tar and cpio) + using the @- convention can cause hard link information to be lost. + (This is a consequence of the incompatible ways that different archive + formats store hardlink information.) + + There are alternative long options for many of the short options that are + deliberately not documented. + +FreeBSD 6.0 April 13, 2004 FreeBSD 6.0 -- cgit v1.2.3