diff options
Diffstat (limited to 'contrib/libarchive/cpio/bsdcpio.1')
| -rw-r--r-- | contrib/libarchive/cpio/bsdcpio.1 | 405 |
1 files changed, 405 insertions, 0 deletions
diff --git a/contrib/libarchive/cpio/bsdcpio.1 b/contrib/libarchive/cpio/bsdcpio.1 new file mode 100644 index 0000000..79b6997 --- /dev/null +++ b/contrib/libarchive/cpio/bsdcpio.1 @@ -0,0 +1,405 @@ +.\" Copyright (c) 2003-2007 Tim Kientzle +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 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. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd December 21, 2007 +.Dt BSDCPIO 1 +.Os +.Sh NAME +.Nm cpio +.Nd copy files to and from archives +.Sh SYNOPSIS +.Nm +.Brq Fl i +.Op Ar options +.Op Ar pattern ... +.Op Ar < archive +.Nm +.Brq Fl o +.Op Ar options +.Ar < name-list +.Op Ar > archive +.Nm +.Brq Fl p +.Op Ar options +.Ar dest-dir +.Ar < name-list +.Sh DESCRIPTION +.Nm +copies files between archives and directories. +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. +.Pp +The first option to +.Nm +is a mode indicator from the following list: +.Bl -tag -compact -width indent +.It Fl i +Input. +Read an archive from standard input (unless overriden) and extract the +contents to disk or (if the +.Fl t +option is specified) +list the contents to standard output. +If one or more file patterns are specified, only files matching +one of the patterns will be extracted. +.It Fl o +Output. +Read a list of filenames from standard input and produce a new archive +on standard output (unless overriden) containing the specified items. +.It Fl p +Pass-through. +Read a list of filenames from standard input and copy the files to the +specified directory. +.El +.Pp +.Sh OPTIONS +Unless specifically stated otherwise, options are applicable in +all operating modes. +.Bl -tag -width indent +.It Fl 0 +Read filenames separated by NUL characters instead of newlines. +This is necessary if any of the filenames being read might contain newlines. +.It Fl A +(o mode only) +Append to the specified archive. +(Not yet implemented.) +.It Fl a +(o and p modes) +Reset access times on files after they are read. +.It Fl B +(o mode only) +Block output to records of 5120 bytes. +.It Fl C Ar size +(o mode only) +Block output to records of +.Ar size +bytes. +.It Fl c +(o mode only) +Use the old POSIX portable character format. +Equivalent to +.Fl -format Ar odc . +.It Fl d +(i and p modes) +Create directories as necessary. +.It Fl E Ar file +(i mode only) +Read list of file name patterns from +.Ar file +to list and extract. +.It Fl F Ar file +Read archive from or write archive to +.Ar file . +.It Fl f Ar pattern +(i mode only) +Ignore files that match +.Ar pattern . +.It Fl -format Ar format +(o mode only) +Produce the output archive in the specified format. +Supported formats include: +.Pp +.Bl -tag -width "iso9660" -compact +.It Ar cpio +Synonym for +.Ar odc . +.It Ar newc +The SVR4 portable cpio format. +.It Ar odc +The old POSIX.1 portable octet-oriented cpio format. +.It Ar pax +The POSIX.1 pax format, an extension of the ustar format. +.It Ar ustar +The POSIX.1 tar format. +.El +.Pp +The default format is +.Ar odc . +See +.Xr libarchive_formats 5 +for more complete information about the +formats currently supported by the underlying +.Xr libarchive 3 +library. +.It Fl H Ar format +Synonym for +.Fl -format . +.It Fl h , Fl -help +Print usage information. +.It Fl I Ar file +Read archive from +.Ar file . +.It Fl i +Input mode. +See above for description. +.It Fl -insecure +(i and p mode only) +Disable security checks during extraction or copying. +This allows extraction via symbolic links and path names containing +.Sq .. +in the name. +.It Fl J +(o mode only) +Compress the file with xz-compatible compression before writing it. +In input mode, this option is ignored; xz compression is recognized +automatically on input. +.It Fl j +Synonym for +.Fl y . +.It Fl L +(o and p modes) +All symbolic links will be followed. +Normally, symbolic links are archived and copied as symbolic links. +With this option, the target of the link will be archived or copied instead. +.It Fl l +(p mode only) +Create links from the target directory to the original files, +instead of copying. +.It Fl lzma +(o mode only) +Compress the file with lzma-compatible compression before writing it. +In input mode, this option is ignored; lzma compression is recognized +automatically on input. +.It Fl m +(i and p modes) +Set file modification time on created files to match +those in the source. +.It Fl n +(i mode, only with +.Fl t ) +Display numeric uid and gid. +By default, +.Nm +displays the user and group names when they are provided in the +archive, or looks up the user and group names in the system +password database. +.It Fl no-preserve-owner +(i mode only) +Do not attempt to restore file ownership. +This is the default when run by non-root users. +.It Fl O Ar file +Write archive to +.Ar file . +.It Fl o +Output mode. +See above for description. +.It Fl p +Pass-through mode. +See above for description. +.It Fl preserve-owner +(i mode only) +Restore file ownership. +This is the default when run by the root user. +.It Fl -quiet +Suppress unnecessary messages. +.It Fl R Oo user Oc Ns Oo : Oc Ns Oo group Oc +Set the owner and/or group on files in the output. +If group is specified with no user +(for example, +.Fl R Ar :wheel ) +then the group will be set but not the user. +If the user is specified with a trailing colon and no group +(for example, +.Fl R Ar root: ) +then the group will be set to the user's default group. +If the user is specified with no trailing colon, then +the user will be set but not the group. +In +.Fl i +and +.Fl p +modes, this option can only be used by the super-user. +(For compatibility, a period can be used in place of the colon.) +.It Fl r +(All modes.) +Rename files interactively. +For each file, a prompt is written to +.Pa /dev/tty +containing the name of the file and a line is read from +.Pa /dev/tty . +If the line read is blank, the file is skipped. +If the line contains a single period, the file is processed normally. +Otherwise, the line is taken to be the new name of the file. +.It Fl t +(i mode only) +List the contents of the archive to stdout; +do not restore the contents to disk. +.It Fl u +(i and p modes) +Unconditionally overwrite existing files. +Ordinarily, an older file will not overwrite a newer file on disk. +.It Fl v +Print the name of each file to stderr as it is processed. +With +.Fl t , +provide a detailed listing of each file. +.It Fl -version +Print the program version information and exit. +.It Fl y +(o mode only) +Compress the archive with bzip2-compatible compression before writing it. +In input mode, this option is ignored; +bzip2 compression is recognized automatically on input. +.It Fl Z +(o mode only) +Compress the archive with compress-compatible compression before writing it. +In input mode, this option is ignored; +compression is recognized automatically on input. +.It Fl z +(o mode only) +Compress the archive with gzip-compatible compression before writing it. +In input mode, this option is ignored; +gzip compression is recognized automatically on input. +.El +.Sh ENVIRONMENT +The following environment variables affect the execution of +.Nm : +.Bl -tag -width ".Ev BLOCKSIZE" +.It Ev LANG +The locale to use. +See +.Xr environ 7 +for more information. +.It Ev TZ +The timezone to use when displaying dates. +See +.Xr environ 7 +for more information. +.El +.Sh EXIT STATUS +.Ex -std +.Sh EXAMPLES +The +.Nm +command is traditionally used to copy file heirarchies in conjunction +with the +.Xr find 1 +command. +The first example here simply copies all files from +.Pa src +to +.Pa dest : +.Dl Nm find Pa src | Nm Fl pmud Pa dest +.Pp +By carefully selecting options to the +.Xr find 1 +command and combining it with other standard utilities, +it is possible to exercise very fine control over which files are copied. +This next example copies files from +.Pa src +to +.Pa dest +that are more than 2 days old and whose names match a particular pattern: +.Dl Nm find Pa src Fl mtime Ar +2 | Nm grep foo[bar] | Nm Fl pdmu Pa dest +.Pp +This example copies files from +.Pa src +to +.Pa dest +that are more than 2 days old and which contain the word +.Do foobar Dc : +.Dl Nm find Pa src Fl mtime Ar +2 | Nm xargs Nm grep -l foobar | Nm Fl pdmu Pa dest +.Sh COMPATIBILITY +The mode options i, o, and p and the options +a, B, c, d, f, l, m, r, t, u, and v comply with SUSv2. +.Pp +The old POSIX.1 standard specified that only +.Fl i , +.Fl o , +and +.Fl p +were interpreted as command-line options. +Each took a single argument of a list of modifier +characters. +For example, the standard syntax allows +.Fl imu +but does not support +.Fl miu +or +.Fl i Fl m Fl u , +since +.Ar m +and +.Ar u +are only modifiers to +.Fl i , +they are not command-line options in their own right. +The syntax supported by this implementation is backwards-compatible +with the standard. +For best compatibility, scripts should limit themselves to the +standard syntax. +.Sh SEE ALSO +.Xr bzip2 1 , +.Xr tar 1 , +.Xr gzip 1 , +.Xr mt 1 , +.Xr pax 1 , +.Xr libarchive 3 , +.Xr cpio 5 , +.Xr libarchive-formats 5 , +.Xr tar 5 +.Sh STANDARDS +There is no current POSIX standard for the cpio command; it appeared +in +.St -p1003.1-96 +but was dropped from +.St -p1003.1-2001 . +.Pp +The cpio, ustar, and pax interchange file formats are defined by +.St -p1003.1-2001 +for the pax command. +.Sh HISTORY +The original +.Nm cpio +and +.Nm find +utilities were written by Dick Haight +while working in AT&T's Unix Support Group. +They first appeared in 1977 in PWB/UNIX 1.0, the +.Dq Programmer's Work Bench +system developed for use within AT&T. +They were first released outside of AT&T as part of System III Unix in 1981. +As a result, +.Nm cpio +actually predates +.Nm tar , +even though it was not well-known outside of AT&T until some time later. +.Pp +This is a complete re-implementation based on the +.Xr libarchive 3 +library. +.Sh BUGS +The cpio archive format has several basic limitations: +It does not store user and group names, only numbers. +As a result, it cannot be reliably used to transfer +files between systems with dissimilar user and group numbering. +Older cpio formats limit the user and group numbers to +16 or 18 bits, which is insufficient for modern systems. +The cpio archive formats cannot support files over 4 gigabytes, +except for the +.Dq odc +variant, which can support files up to 8 gigabytes. |
