Blame cpio/bsdcpio.1

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