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 October 7, 2012 |
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 |
.Brq Fl i |
36 |
.Op Ar options |
37 |
.Op Ar pattern ... |
38 |
.Op Ar < archive |
39 |
.Nm |
40 |
.Brq Fl o |
41 |
.Op Ar options |
42 |
.Ar < name-list |
43 |
.Op Ar > archive |
44 |
.Nm |
45 |
.Brq 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 lzma |
186 |
(o mode only) |
187 |
Compress the file with lzma-compatible compression before writing it. |
188 |
In input mode, this option is ignored; lzma compression is recognized |
189 |
automatically on input. |
190 |
.It Fl Fl lzop |
191 |
(o mode only) |
192 |
Compress the resulting archive with |
193 |
.Xr lzop 1 . |
194 |
In input mode, this option is ignored. |
195 |
.It Fl m , Fl Fl preserve-modification-time |
196 |
(i and p modes) |
197 |
Set file modification time on created files to match |
198 |
those in the source. |
199 |
.It Fl n , Fl Fl numeric-uid-gid |
200 |
(i mode, only with |
201 |
.Fl t ) |
202 |
Display numeric uid and gid. |
203 |
By default, |
204 |
.Nm |
205 |
displays the user and group names when they are provided in the |
206 |
archive, or looks up the user and group names in the system |
207 |
password database. |
208 |
.It Fl Fl no-preserve-owner |
209 |
(i mode only) |
210 |
Do not attempt to restore file ownership. |
211 |
This is the default when run by non-root users. |
212 |
.It Fl O Ar file |
213 |
Write archive to |
214 |
.Ar file . |
215 |
.It Fl o , Fl Fl create |
216 |
Output mode. |
217 |
See above for description. |
218 |
.It Fl p , Fl Fl pass-through |
219 |
Pass-through mode. |
220 |
See above for description. |
221 |
.It Fl Fl preserve-owner |
222 |
(i mode only) |
223 |
Restore file ownership. |
224 |
This is the default when run by the root user. |
225 |
.It Fl Fl quiet |
226 |
Suppress unnecessary messages. |
227 |
.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 |
228 |
Set the owner and/or group on files in the output. |
229 |
If group is specified with no user |
230 |
(for example, |
231 |
.Fl R Ar :wheel ) |
232 |
then the group will be set but not the user. |
233 |
If the user is specified with a trailing colon and no group |
234 |
(for example, |
235 |
.Fl R Ar root: ) |
236 |
then the group will be set to the user's default group. |
237 |
If the user is specified with no trailing colon, then |
238 |
the user will be set but not the group. |
239 |
In |
240 |
.Fl i |
241 |
and |
242 |
.Fl p |
243 |
modes, this option can only be used by the super-user. |
244 |
(For compatibility, a period can be used in place of the colon.) |
245 |
.It Fl r |
246 |
(All modes.) |
247 |
Rename files interactively. |
248 |
For each file, a prompt is written to |
249 |
.Pa /dev/tty |
250 |
containing the name of the file and a line is read from |
251 |
.Pa /dev/tty . |
252 |
If the line read is blank, the file is skipped. |
253 |
If the line contains a single period, the file is processed normally. |
254 |
Otherwise, the line is taken to be the new name of the file. |
255 |
.It Fl t , Fl Fl list |
256 |
(i mode only) |
257 |
List the contents of the archive to stdout; |
258 |
do not restore the contents to disk. |
259 |
.It Fl u , Fl Fl unconditional |
260 |
(i and p modes) |
261 |
Unconditionally overwrite existing files. |
262 |
Ordinarily, an older file will not overwrite a newer file on disk. |
263 |
.It Fl V , Fl Fl dot |
264 |
Print a dot to stderr for each file as it is processed. |
265 |
Superseded by |
266 |
.Fl v . |
267 |
.It Fl v , Fl Fl verbose |
268 |
Print the name of each file to stderr as it is processed. |
269 |
With |
270 |
.Fl t , |
271 |
provide a detailed listing of each file. |
272 |
.It Fl Fl version |
273 |
Print the program version information and exit. |
274 |
.It Fl y |
275 |
(o mode only) |
276 |
Compress the archive with bzip2-compatible compression before writing it. |
277 |
In input mode, this option is ignored; |
278 |
bzip2 compression is recognized automatically on input. |
279 |
.It Fl Z |
280 |
(o mode only) |
281 |
Compress the archive with compress-compatible compression before writing it. |
282 |
In input mode, this option is ignored; |
283 |
compression is recognized automatically on input. |
284 |
.It Fl z |
285 |
(o mode only) |
286 |
Compress the archive with gzip-compatible compression before writing it. |
287 |
In input mode, this option is ignored; |
288 |
gzip compression is recognized automatically on input. |
289 |
.El |
290 |
.Sh EXIT STATUS |
291 |
.Ex -std |
292 |
.Sh ENVIRONMENT |
293 |
The following environment variables affect the execution of |
294 |
.Nm : |
295 |
.Bl -tag -width ".Ev BLOCKSIZE" |
296 |
.It Ev LANG |
297 |
The locale to use. |
298 |
See |
299 |
.Xr environ 7 |
300 |
for more information. |
301 |
.It Ev TZ |
302 |
The timezone to use when displaying dates. |
303 |
See |
304 |
.Xr environ 7 |
305 |
for more information. |
306 |
.El |
307 |
.Sh EXAMPLES |
308 |
The |
309 |
.Nm |
310 |
command is traditionally used to copy file hierarchies in conjunction |
311 |
with the |
312 |
.Xr find 1 |
313 |
command. |
314 |
The first example here simply copies all files from |
315 |
.Pa src |
316 |
to |
317 |
.Pa dest : |
318 |
.Dl Nm find Pa src | Nm Fl pmud Pa dest |
319 |
.Pp |
320 |
By carefully selecting options to the |
321 |
.Xr find 1 |
322 |
command and combining it with other standard utilities, |
323 |
it is possible to exercise very fine control over which files are copied. |
324 |
This next example copies files from |
325 |
.Pa src |
326 |
to |
327 |
.Pa dest |
328 |
that are more than 2 days old and whose names match a particular pattern: |
329 |
.Dl Nm find Pa src Fl mtime Ar +2 | Nm grep foo[bar] | Nm Fl pdmu Pa dest |
330 |
.Pp |
331 |
This example copies files from |
332 |
.Pa src |
333 |
to |
334 |
.Pa dest |
335 |
that are more than 2 days old and which contain the word |
336 |
.Do foobar Dc : |
337 |
.Dl Nm find Pa src Fl mtime Ar +2 | Nm xargs Nm grep -l foobar | Nm Fl pdmu Pa dest |
338 |
.Sh COMPATIBILITY |
339 |
The mode options i, o, and p and the options |
340 |
a, B, c, d, f, l, m, r, t, u, and v comply with SUSv2. |
341 |
.Pp |
342 |
The old POSIX.1 standard specified that only |
343 |
.Fl i , |
344 |
.Fl o , |
345 |
and |
346 |
.Fl p |
347 |
were interpreted as command-line options. |
348 |
Each took a single argument of a list of modifier |
349 |
characters. |
350 |
For example, the standard syntax allows |
351 |
.Fl imu |
352 |
but does not support |
353 |
.Fl miu |
354 |
or |
355 |
.Fl i Fl m Fl u , |
356 |
since |
357 |
.Ar m |
358 |
and |
359 |
.Ar u |
360 |
are only modifiers to |
361 |
.Fl i , |
362 |
they are not command-line options in their own right. |
363 |
The syntax supported by this implementation is backwards-compatible |
364 |
with the standard. |
365 |
For best compatibility, scripts should limit themselves to the |
366 |
standard syntax. |
367 |
.Sh SEE ALSO |
368 |
.Xr bzip2 1 , |
369 |
.Xr tar 1 , |
370 |
.Xr gzip 1 , |
371 |
.Xr mt 1 , |
372 |
.Xr pax 1 , |
373 |
.Xr libarchive 3 , |
374 |
.Xr cpio 5 , |
375 |
.Xr libarchive-formats 5 , |
376 |
.Xr tar 5 |
377 |
.Sh STANDARDS |
378 |
There is no current POSIX standard for the cpio command; it appeared |
379 |
in |
380 |
.St -p1003.1-96 |
381 |
but was dropped from |
382 |
.St -p1003.1-2001 . |
383 |
.Pp |
384 |
The cpio, ustar, and pax interchange file formats are defined by |
385 |
.St -p1003.1-2001 |
386 |
for the pax command. |
387 |
.Sh HISTORY |
388 |
The original |
389 |
.Nm cpio |
390 |
and |
391 |
.Nm find |
392 |
utilities were written by Dick Haight |
393 |
while working in AT&T's Unix Support Group. |
394 |
They first appeared in 1977 in PWB/UNIX 1.0, the |
395 |
.Dq Programmer's Work Bench |
396 |
system developed for use within AT&T. |
397 |
They were first released outside of AT&T as part of System III Unix in 1981. |
398 |
As a result, |
399 |
.Nm cpio |
400 |
actually predates |
401 |
.Nm tar , |
402 |
even though it was not well-known outside of AT&T until some time later. |
403 |
.Pp |
404 |
This is a complete re-implementation based on the |
405 |
.Xr libarchive 3 |
406 |
library. |
407 |
.Sh BUGS |
408 |
The cpio archive format has several basic limitations: |
409 |
It does not store user and group names, only numbers. |
410 |
As a result, it cannot be reliably used to transfer |
411 |
files between systems with dissimilar user and group numbering. |
412 |
Older cpio formats limit the user and group numbers to |
413 |
16 or 18 bits, which is insufficient for modern systems. |
414 |
The cpio archive formats cannot support files over 4 gigabytes, |
415 |
except for the |
416 |
.Dq odc |
417 |
variant, which can support files up to 8 gigabytes. |