1 |
.\" Copyright (c) 2003-2007 Tim Kientzle |
2 |
.\" All rights reserved. |
3 |
.\" |
4 |
.\" Redistribution and use in source and binary forms, with or without |
5 |
.\" modification, are permitted provided that the following conditions |
6 |
.\" are met: |
7 |
.\" 1. Redistributions of source code must retain the above copyright |
8 |
.\" notice, this list of conditions and the following disclaimer. |
9 |
.\" 2. Redistributions in binary form must reproduce the above copyright |
10 |
.\" notice, this list of conditions and the following disclaimer in the |
11 |
.\" documentation and/or other materials provided with the distribution. |
12 |
.\" |
13 |
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND |
14 |
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
15 |
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
16 |
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE |
17 |
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL |
18 |
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS |
19 |
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) |
20 |
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT |
21 |
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY |
22 |
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
23 |
.\" SUCH DAMAGE. |
24 |
.\" |
25 |
.\" $FreeBSD$ |
26 |
.\" |
27 |
.Dd September 16, 2014 |
28 |
.Dt CPIO 1 |
29 |
.Os |
30 |
.Sh NAME |
31 |
.Nm cpio |
32 |
.Nd copy files to and from archives |
33 |
.Sh SYNOPSIS |
34 |
.Nm |
35 |
.Fl i |
36 |
.Op Ar options |
37 |
.Op Ar pattern ... |
38 |
.Op Ar < archive |
39 |
.Nm |
40 |
.Fl o |
41 |
.Op Ar options |
42 |
.Ar < name-list |
43 |
.Op Ar > archive |
44 |
.Nm |
45 |
.Fl p |
46 |
.Op Ar options |
47 |
.Ar dest-dir |
48 |
.Ar < name-list |
49 |
.Sh DESCRIPTION |
50 |
.Nm |
51 |
copies files between archives and directories. |
52 |
This implementation can extract from tar, pax, cpio, zip, jar, ar, |
53 |
and ISO 9660 cdrom images and can create tar, pax, cpio, ar, |
54 |
and shar archives. |
55 |
.Pp |
56 |
The first option to |
57 |
.Nm |
58 |
is a mode indicator from the following list: |
59 |
.Bl -tag -compact -width indent |
60 |
.It Fl i |
61 |
Input. |
62 |
Read an archive from standard input (unless overridden) and extract the |
63 |
contents to disk or (if the |
64 |
.Fl t |
65 |
option is specified) |
66 |
list the contents to standard output. |
67 |
If one or more file patterns are specified, only files matching |
68 |
one of the patterns will be extracted. |
69 |
.It Fl o |
70 |
Output. |
71 |
Read a list of filenames from standard input and produce a new archive |
72 |
on standard output (unless overridden) containing the specified items. |
73 |
.It Fl p |
74 |
Pass-through. |
75 |
Read a list of filenames from standard input and copy the files to the |
76 |
specified directory. |
77 |
.El |
78 |
.Pp |
79 |
.Sh OPTIONS |
80 |
Unless specifically stated otherwise, options are applicable in |
81 |
all operating modes. |
82 |
.Bl -tag -width indent |
83 |
.It Fl 0 , Fl Fl null |
84 |
Read filenames separated by NUL characters instead of newlines. |
85 |
This is necessary if any of the filenames being read might contain newlines. |
86 |
.It Fl A |
87 |
(o mode only) |
88 |
Append to the specified archive. |
89 |
(Not yet implemented.) |
90 |
.It Fl a |
91 |
(o and p modes) |
92 |
Reset access times on files after they are read. |
93 |
.It Fl B |
94 |
(o mode only) |
95 |
Block output to records of 5120 bytes. |
96 |
.It Fl C Ar size |
97 |
(o mode only) |
98 |
Block output to records of |
99 |
.Ar size |
100 |
bytes. |
101 |
.It Fl c |
102 |
(o mode only) |
103 |
Use the old POSIX portable character format. |
104 |
Equivalent to |
105 |
.Fl Fl format Ar odc . |
106 |
.It Fl d , Fl Fl make-directories |
107 |
(i and p modes) |
108 |
Create directories as necessary. |
109 |
.It Fl E Ar file |
110 |
(i mode only) |
111 |
Read list of file name patterns from |
112 |
.Ar file |
113 |
to list and extract. |
114 |
.It Fl F Ar file , Fl Fl file Ar file |
115 |
Read archive from or write archive to |
116 |
.Ar file . |
117 |
.It Fl f Ar pattern |
118 |
(i mode only) |
119 |
Ignore files that match |
120 |
.Ar pattern . |
121 |
.It Fl H Ar format , Fl Fl format Ar format |
122 |
(o mode only) |
123 |
Produce the output archive in the specified format. |
124 |
Supported formats include: |
125 |
.Pp |
126 |
.Bl -tag -width "iso9660" -compact |
127 |
.It Ar cpio |
128 |
Synonym for |
129 |
.Ar odc . |
130 |
.It Ar newc |
131 |
The SVR4 portable cpio format. |
132 |
.It Ar odc |
133 |
The old POSIX.1 portable octet-oriented cpio format. |
134 |
.It Ar pax |
135 |
The POSIX.1 pax format, an extension of the ustar format. |
136 |
.It Ar ustar |
137 |
The POSIX.1 tar format. |
138 |
.El |
139 |
.Pp |
140 |
The default format is |
141 |
.Ar odc . |
142 |
See |
143 |
.Xr libarchive-formats 5 |
144 |
for more complete information about the |
145 |
formats currently supported by the underlying |
146 |
.Xr libarchive 3 |
147 |
library. |
148 |
.It Fl h , Fl Fl help |
149 |
Print usage information. |
150 |
.It Fl I Ar file |
151 |
Read archive from |
152 |
.Ar file . |
153 |
.It Fl i , Fl Fl extract |
154 |
Input mode. |
155 |
See above for description. |
156 |
.It Fl Fl insecure |
157 |
(i and p mode only) |
158 |
Disable security checks during extraction or copying. |
159 |
This allows extraction via symbolic links, absolute paths, |
160 |
and path names containing |
161 |
.Sq .. |
162 |
in the name. |
163 |
.It Fl J , Fl Fl xz |
164 |
(o mode only) |
165 |
Compress the file with xz-compatible compression before writing it. |
166 |
In input mode, this option is ignored; xz compression is recognized |
167 |
automatically on input. |
168 |
.It Fl j |
169 |
Synonym for |
170 |
.Fl y . |
171 |
.It Fl L |
172 |
(o and p modes) |
173 |
All symbolic links will be followed. |
174 |
Normally, symbolic links are archived and copied as symbolic links. |
175 |
With this option, the target of the link will be archived or copied instead. |
176 |
.It Fl l , Fl Fl link |
177 |
(p mode only) |
178 |
Create links from the target directory to the original files, |
179 |
instead of copying. |
180 |
.It Fl Fl lrzip |
181 |
(o mode only) |
182 |
Compress the resulting archive with |
183 |
.Xr lrzip 1 . |
184 |
In input mode, this option is ignored. |
185 |
.It Fl Fl lz4 |
186 |
(o mode only) |
187 |
Compress the archive with lz4-compatible compression before writing it. |
188 |
In input mode, this option is ignored; lz4 compression is recognized |
189 |
automatically on input. |
190 |
.It Fl Fl lzma |
191 |
(o mode only) |
192 |
Compress the file with lzma-compatible compression before writing it. |
193 |
In input mode, this option is ignored; lzma compression is recognized |
194 |
automatically on input. |
195 |
.It Fl Fl lzop |
196 |
(o mode only) |
197 |
Compress the resulting archive with |
198 |
.Xr lzop 1 . |
199 |
In input mode, this option is ignored. |
200 |
.It Fl Fl passphrase Ar passphrase |
201 |
The |
202 |
.Pa passphrase |
203 |
is used to extract or create an encrypted archive. |
204 |
Currently, zip is only a format that |
205 |
.Nm |
206 |
can handle encrypted archives. |
207 |
You shouldn't use this option unless you realize how insecure |
208 |
use of this option is. |
209 |
.It Fl m , Fl Fl preserve-modification-time |
210 |
(i and p modes) |
211 |
Set file modification time on created files to match |
212 |
those in the source. |
213 |
.It Fl n , Fl Fl numeric-uid-gid |
214 |
(i mode, only with |
215 |
.Fl t ) |
216 |
Display numeric uid and gid. |
217 |
By default, |
218 |
.Nm |
219 |
displays the user and group names when they are provided in the |
220 |
archive, or looks up the user and group names in the system |
221 |
password database. |
222 |
.It Fl Fl no-preserve-owner |
223 |
(i mode only) |
224 |
Do not attempt to restore file ownership. |
225 |
This is the default when run by non-root users. |
226 |
.It Fl O Ar file |
227 |
Write archive to |
228 |
.Ar file . |
229 |
.It Fl o , Fl Fl create |
230 |
Output mode. |
231 |
See above for description. |
232 |
.It Fl p , Fl Fl pass-through |
233 |
Pass-through mode. |
234 |
See above for description. |
235 |
.It Fl Fl preserve-owner |
236 |
(i mode only) |
237 |
Restore file ownership. |
238 |
This is the default when run by the root user. |
239 |
.It Fl Fl quiet |
240 |
Suppress unnecessary messages. |
241 |
.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 |
242 |
Set the owner and/or group on files in the output. |
243 |
If group is specified with no user |
244 |
(for example, |
245 |
.Fl R Ar :wheel ) |
246 |
then the group will be set but not the user. |
247 |
If the user is specified with a trailing colon and no group |
248 |
(for example, |
249 |
.Fl R Ar root: ) |
250 |
then the group will be set to the user's default group. |
251 |
If the user is specified with no trailing colon, then |
252 |
the user will be set but not the group. |
253 |
In |
254 |
.Fl i |
255 |
and |
256 |
.Fl p |
257 |
modes, this option can only be used by the super-user. |
258 |
(For compatibility, a period can be used in place of the colon.) |
259 |
.It Fl r |
260 |
(All modes.) |
261 |
Rename files interactively. |
262 |
For each file, a prompt is written to |
263 |
.Pa /dev/tty |
264 |
containing the name of the file and a line is read from |
265 |
.Pa /dev/tty . |
266 |
If the line read is blank, the file is skipped. |
267 |
If the line contains a single period, the file is processed normally. |
268 |
Otherwise, the line is taken to be the new name of the file. |
269 |
.It Fl t , Fl Fl list |
270 |
(i mode only) |
271 |
List the contents of the archive to stdout; |
272 |
do not restore the contents to disk. |
273 |
.It Fl u , Fl Fl unconditional |
274 |
(i and p modes) |
275 |
Unconditionally overwrite existing files. |
276 |
Ordinarily, an older file will not overwrite a newer file on disk. |
277 |
.It Fl V , Fl Fl dot |
278 |
Print a dot to stderr for each file as it is processed. |
279 |
Superseded by |
280 |
.Fl v . |
281 |
.It Fl v , Fl Fl verbose |
282 |
Print the name of each file to stderr as it is processed. |
283 |
With |
284 |
.Fl t , |
285 |
provide a detailed listing of each file. |
286 |
.It Fl Fl version |
287 |
Print the program version information and exit. |
288 |
.It Fl y |
289 |
(o mode only) |
290 |
Compress the archive with bzip2-compatible compression before writing it. |
291 |
In input mode, this option is ignored; |
292 |
bzip2 compression is recognized automatically on input. |
293 |
.It Fl Z |
294 |
(o mode only) |
295 |
Compress the archive with compress-compatible compression before writing it. |
296 |
In input mode, this option is ignored; |
297 |
compression is recognized automatically on input. |
298 |
.It Fl z |
299 |
(o mode only) |
300 |
Compress the archive with gzip-compatible compression before writing it. |
301 |
In input mode, this option is ignored; |
302 |
gzip compression is recognized automatically on input. |
303 |
.El |
304 |
.Sh EXIT STATUS |
305 |
.Ex -std |
306 |
.Sh ENVIRONMENT |
307 |
The following environment variables affect the execution of |
308 |
.Nm : |
309 |
.Bl -tag -width ".Ev BLOCKSIZE" |
310 |
.It Ev LANG |
311 |
The locale to use. |
312 |
See |
313 |
.Xr environ 7 |
314 |
for more information. |
315 |
.It Ev TZ |
316 |
The timezone to use when displaying dates. |
317 |
See |
318 |
.Xr environ 7 |
319 |
for more information. |
320 |
.El |
321 |
.Sh EXAMPLES |
322 |
The |
323 |
.Nm |
324 |
command is traditionally used to copy file hierarchies in conjunction |
325 |
with the |
326 |
.Xr find 1 |
327 |
command. |
328 |
The first example here simply copies all files from |
329 |
.Pa src |
330 |
to |
331 |
.Pa dest : |
332 |
.Dl Nm find Pa src | Nm Fl pmud Pa dest |
333 |
.Pp |
334 |
By carefully selecting options to the |
335 |
.Xr find 1 |
336 |
command and combining it with other standard utilities, |
337 |
it is possible to exercise very fine control over which files are copied. |
338 |
This next example copies files from |
339 |
.Pa src |
340 |
to |
341 |
.Pa dest |
342 |
that are more than 2 days old and whose names match a particular pattern: |
343 |
.Dl Nm find Pa src Fl mtime Ar +2 | Nm grep foo[bar] | Nm Fl pdmu Pa dest |
344 |
.Pp |
345 |
This example copies files from |
346 |
.Pa src |
347 |
to |
348 |
.Pa dest |
349 |
that are more than 2 days old and which contain the word |
350 |
.Do foobar Dc : |
351 |
.Dl Nm find Pa src Fl mtime Ar +2 | Nm xargs Nm grep -l foobar | Nm Fl pdmu Pa dest |
352 |
.Sh COMPATIBILITY |
353 |
The mode options i, o, and p and the options |
354 |
a, B, c, d, f, l, m, r, t, u, and v comply with SUSv2. |
355 |
.Pp |
356 |
The old POSIX.1 standard specified that only |
357 |
.Fl i , |
358 |
.Fl o , |
359 |
and |
360 |
.Fl p |
361 |
were interpreted as command-line options. |
362 |
Each took a single argument of a list of modifier |
363 |
characters. |
364 |
For example, the standard syntax allows |
365 |
.Fl imu |
366 |
but does not support |
367 |
.Fl miu |
368 |
or |
369 |
.Fl i Fl m Fl u , |
370 |
since |
371 |
.Ar m |
372 |
and |
373 |
.Ar u |
374 |
are only modifiers to |
375 |
.Fl i , |
376 |
they are not command-line options in their own right. |
377 |
The syntax supported by this implementation is backwards-compatible |
378 |
with the standard. |
379 |
For best compatibility, scripts should limit themselves to the |
380 |
standard syntax. |
381 |
.Sh SEE ALSO |
382 |
.Xr bzip2 1 , |
383 |
.Xr tar 1 , |
384 |
.Xr gzip 1 , |
385 |
.Xr mt 1 , |
386 |
.Xr pax 1 , |
387 |
.Xr libarchive 3 , |
388 |
.Xr cpio 5 , |
389 |
.Xr libarchive-formats 5 , |
390 |
.Xr tar 5 |
391 |
.Sh STANDARDS |
392 |
There is no current POSIX standard for the cpio command; it appeared |
393 |
in |
394 |
.St -p1003.1-96 |
395 |
but was dropped from |
396 |
.St -p1003.1-2001 . |
397 |
.Pp |
398 |
The cpio, ustar, and pax interchange file formats are defined by |
399 |
.St -p1003.1-2001 |
400 |
for the pax command. |
401 |
.Sh HISTORY |
402 |
The original |
403 |
.Nm cpio |
404 |
and |
405 |
.Nm find |
406 |
utilities were written by Dick Haight |
407 |
while working in AT&T's Unix Support Group. |
408 |
They first appeared in 1977 in PWB/UNIX 1.0, the |
409 |
.Dq Programmer's Work Bench |
410 |
system developed for use within AT&T. |
411 |
They were first released outside of AT&T as part of System III Unix in 1981. |
412 |
As a result, |
413 |
.Nm cpio |
414 |
actually predates |
415 |
.Nm tar , |
416 |
even though it was not well-known outside of AT&T until some time later. |
417 |
.Pp |
418 |
This is a complete re-implementation based on the |
419 |
.Xr libarchive 3 |
420 |
library. |
421 |
.Sh BUGS |
422 |
The cpio archive format has several basic limitations: |
423 |
It does not store user and group names, only numbers. |
424 |
As a result, it cannot be reliably used to transfer |
425 |
files between systems with dissimilar user and group numbering. |
426 |
Older cpio formats limit the user and group numbers to |
427 |
16 or 18 bits, which is insufficient for modern systems. |
428 |
The cpio archive formats cannot support files over 4 gigabytes, |
429 |
except for the |
430 |
.Dq odc |
431 |
variant, which can support files up to 8 gigabytes. |