1BSDCPIO(1)                BSD General Commands Manual               BSDCPIO(1)
2

NAME

4     bsdcpio — copy files to and from archives
5

SYNOPSIS

7     bsdcpio -i [options] [pattern ...] [< archive]
8     bsdcpio -o [options] < name-list [> archive]
9     bsdcpio -p [options] dest-dir < name-list
10

DESCRIPTION

12     bsdcpio copies files between archives and directories.  This implementa‐
13     tion can extract from tar, pax, cpio, zip, jar, ar, and ISO 9660 cdrom
14     images and can create tar, pax, cpio, ar, and shar archives.
15
16     The first option to bsdcpio is a mode indicator from the following list:
17     -i      Input.  Read an archive from standard input (unless overridden)
18             and extract the contents to disk or (if the -t option is speci‐
19             fied) list the contents to standard output.  If one or more file
20             patterns are specified, only files matching one of the patterns
21             will be extracted.
22     -o      Output.  Read a list of filenames from standard input and produce
23             a new archive on standard output (unless overridden) containing
24             the specified items.
25     -p      Pass-through.  Read a list of filenames from standard input and
26             copy the files to the specified directory.
27

OPTIONS

29     Unless specifically stated otherwise, options are applicable in all oper‐
30     ating modes.
31
32     -0, --null
33             Read filenames separated by NUL characters instead of newlines.
34             This is necessary if any of the filenames being read might con‐
35             tain newlines.
36
37     -A      (o mode only) Append to the specified archive.  (Not yet imple‐
38             mented.)
39
40     -a      (o and p modes) Reset access times on files after they are read.
41
42     -B      (o mode only) Block output to records of 5120 bytes.
43
44     -C size
45             (o mode only) Block output to records of size bytes.
46
47     -c      (o mode only) Use the old POSIX portable character format.
48             Equivalent to --format odc.
49
50     -d, --make-directories
51             (i and p modes) Create directories as necessary.
52
53     -E file
54             (i mode only) Read list of file name patterns from file to list
55             and extract.
56
57     -F file, --file file
58             Read archive from or write archive to file.
59
60     -f pattern
61             (i mode only) Ignore files that match pattern.
62
63     -H format, --format format
64             (o mode only) Produce the output archive in the specified format.
65             Supported formats include:
66
67             cpio     Synonym for odc.
68             newc     The SVR4 portable cpio format.
69             odc      The old POSIX.1 portable octet-oriented cpio format.
70             pax      The POSIX.1 pax format, an extension of the ustar for‐
71                      mat.
72             ustar    The POSIX.1 tar format.
73
74             The default format is odc.  See libarchive-formats(5) for more
75             complete information about the formats currently supported by the
76             underlying libarchive(3) library.
77
78     -h, --help
79             Print usage information.
80
81     -I file
82             Read archive from file.
83
84     -i, --extract
85             Input mode.  See above for description.
86
87     --insecure
88             (i and p mode only) Disable security checks during extraction or
89             copying.  This allows extraction via symbolic links, absolute
90             paths, and path names containing ‘..’ in the name.
91
92     -J, --xz
93             (o mode only) Compress the file with xz-compatible compression
94             before writing it.  In input mode, this option is ignored; xz
95             compression is recognized automatically on input.
96
97     -j      Synonym for -y.
98
99     -L      (o and p modes) All symbolic links will be followed.  Normally,
100             symbolic links are archived and copied as symbolic links.  With
101             this option, the target of the link will be archived or copied
102             instead.
103
104     -l, --link
105             (p mode only) Create links from the target directory to the orig‐
106             inal files, instead of copying.
107
108     --lrzip
109             (o mode only) Compress the resulting archive with lrzip(1).  In
110             input mode, this option is ignored.
111
112     --lz4   (o mode only) Compress the archive with lz4-compatible compres‐
113             sion before writing it.  In input mode, this option is ignored;
114             lz4 compression is recognized automatically on input.
115
116     --zstd  (o mode only) Compress the archive with zstd-compatible compres‐
117             sion before writing it.  In input mode, this option is ignored;
118             zstd compression is recognized automatically on input.
119
120     --lzma  (o mode only) Compress the file with lzma-compatible compression
121             before writing it.  In input mode, this option is ignored; lzma
122             compression is recognized automatically on input.
123
124     --lzop  (o mode only) Compress the resulting archive with lzop(1).  In
125             input mode, this option is ignored.
126
127     --passphrase passphrase
128             The passphrase is used to extract or create an encrypted archive.
129             Currently, zip is only a format that bsdcpio can handle encrypted
130             archives.  You shouldn't use this option unless you realize how
131             insecure use of this option is.
132
133     -m, --preserve-modification-time
134             (i and p modes) Set file modification time on created files to
135             match those in the source.
136
137     -n, --numeric-uid-gid
138             (i mode, only with -t) Display numeric uid and gid.  By default,
139             bsdcpio displays the user and group names when they are provided
140             in the archive, or looks up the user and group names in the sys‐
141             tem password database.
142
143     --no-preserve-owner
144             (i mode only) Do not attempt to restore file ownership.  This is
145             the default when run by non-root users.
146
147     -O file
148             Write archive to file.
149
150     -o, --create
151             Output mode.  See above for description.
152
153     -p, --pass-through
154             Pass-through mode.  See above for description.
155
156     --preserve-owner
157             (i mode only) Restore file ownership.  This is the default when
158             run by the root user.
159
160     --quiet
161             Suppress unnecessary messages.
162
163     -R [user][:][group], --owner [user][:][group]
164             Set the owner and/or group on files in the output.  If group is
165             specified with no user (for example, -R :wheel) then the group
166             will be set but not the user.  If the user is specified with a
167             trailing colon and no group (for example, -R root:) then the
168             group will be set to the user's default group.  If the user is
169             specified with no trailing colon, then the user will be set but
170             not the group.  In -i and -p modes, this option can only be used
171             by the super-user.  (For compatibility, a period can be used in
172             place of the colon.)
173
174     -r      (All modes.)  Rename files interactively.  For each file, a
175             prompt is written to /dev/tty containing the name of the file and
176             a line is read from /dev/tty.  If the line read is blank, the
177             file is skipped.  If the line contains a single period, the file
178             is processed normally.  Otherwise, the line is taken to be the
179             new name of the file.
180
181     -t, --list
182             (i mode only) List the contents of the archive to stdout; do not
183             restore the contents to disk.
184
185     -u, --unconditional
186             (i and p modes) Unconditionally overwrite existing files.  Ordi‐
187             narily, an older file will not overwrite a newer file on disk.
188
189     -V, --dot
190             Print a dot to stderr for each file as it is processed.  Super‐
191             seded by -v.
192
193     -v, --verbose
194             Print the name of each file to stderr as it is processed.  With
195             -t, provide a detailed listing of each file.
196
197     --version
198             Print the program version information and exit.
199
200     -y      (o mode only) Compress the archive with bzip2-compatible compres‐
201             sion before writing it.  In input mode, this option is ignored;
202             bzip2 compression is recognized automatically on input.
203
204     -Z      (o mode only) Compress the archive with compress-compatible com‐
205             pression before writing it.  In input mode, this option is
206             ignored; compression is recognized automatically on input.
207
208     -z      (o mode only) Compress the archive with gzip-compatible compres‐
209             sion before writing it.  In input mode, this option is ignored;
210             gzip compression is recognized automatically on input.
211

EXIT STATUS

213     The bsdcpio utility exits 0 on success, and >0 if an error occurs.
214

ENVIRONMENT

216     The following environment variables affect the execution of bsdcpio:
217
218     LANG       The locale to use.  See environ(7) for more information.
219
220     TZ         The timezone to use when displaying dates.  See environ(7) for
221                more information.
222

EXAMPLES

224     The bsdcpio command is traditionally used to copy file hierarchies in
225     conjunction with the find(1) command.  The first example here simply
226     copies all files from src to dest:
227           find src | bsdcpio -pmud dest
228
229     By carefully selecting options to the find(1) command and combining it
230     with other standard utilities, it is possible to exercise very fine con‐
231     trol over which files are copied.  This next example copies files from
232     src to dest that are more than 2 days old and whose names match a partic‐
233     ular pattern:
234           find src -mtime +2 | grep foo[bar] | bsdcpio -pdmu dest
235
236     This example copies files from src to dest that are more than 2 days old
237     and which contain the word “foobar”:
238           find src -mtime +2 | xargs grep -l foobar | bsdcpio -pdmu dest
239

COMPATIBILITY

241     The mode options i, o, and p and the options a, B, c, d, f, l, m, r, t,
242     u, and v comply with SUSv2.
243
244     The old POSIX.1 standard specified that only -i, -o, and -p were inter‐
245     preted as command-line options.  Each took a single argument of a list of
246     modifier characters.  For example, the standard syntax allows -imu but
247     does not support -miu or -i -m -u, since m and u are only modifiers to
248     -i, they are not command-line options in their own right.  The syntax
249     supported by this implementation is backwards-compatible with the stan‐
250     dard.  For best compatibility, scripts should limit themselves to the
251     standard syntax.
252

SEE ALSO

254     bzip2(1), tar(1), gzip(1), mt(1), pax(1), libarchive(3), cpio(5),
255     libarchive-formats(5), tar(5)
256

STANDARDS

258     There is no current POSIX standard for the cpio command; it appeared in
259     ISO/IEC 9945-1:1996 (“POSIX.1”) but was dropped from IEEE Std 1003.1-2001
260     (“POSIX.1”).
261
262     The cpio, ustar, and pax interchange file formats are defined by IEEE Std
263     1003.1-2001 (“POSIX.1”) for the pax command.
264

HISTORY

266     The original cpio and find utilities were written by Dick Haight while
267     working in AT&T's Unix Support Group.  They first appeared in 1977 in
268     PWB/UNIX 1.0, the “Programmer's Work Bench” system developed for use
269     within AT&T.  They were first released outside of AT&T as part of System
270     III Unix in 1981.  As a result, cpio actually predates tar, even though
271     it was not well-known outside of AT&T until some time later.
272
273     This is a complete re-implementation based on the libarchive(3) library.
274

BUGS

276     The cpio archive format has several basic limitations: It does not store
277     user and group names, only numbers.  As a result, it cannot be reliably
278     used to transfer files between systems with dissimilar user and group
279     numbering.  Older cpio formats limit the user and group numbers to 16 or
280     18 bits, which is insufficient for modern systems.  The cpio archive for‐
281     mats cannot support files over 4 gigabytes, except for the “odc” variant,
282     which can support files up to 8 gigabytes.
283
284BSD                           September 16, 2014                           BSD
Impressum