| blob | 9cd10ad71cfddd4c9e9aeb1a7248e6a103284a12 |
1 .\" $OpenBSD: cpio.1,v 1.35 2014/09/08 01:27:54 schwarze Exp $
2 .\"
3 .\" Copyright (c) 1997 SigmaSoft, Th. Lockert
4 .\" All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\"
15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
16 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
17 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
18 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
19 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
20 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
21 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
22 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
23 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
24 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
25 .\"
26 .Dd $Mdocdate: September 8 2014 $
27 .Dt CPIO 1
28 .Os
29 .Sh NAME
30 .Nm cpio
31 .Nd copy file archives in and out
32 .Sh SYNOPSIS
33 .Nm cpio
34 .Fl o
35 .Op Fl AaBcjLvZz
36 .Op Fl C Ar bytes
37 .Op Fl F Ar archive
38 .Op Fl H Ar format
39 .Op Fl O Ar archive
40 .No \*(Lt Ar name-list
41 .Op \*(Gt Ar archive
42 .Nm cpio
43 .Fl i
44 .Op Fl 6BbcdfjmrSstuvZz
45 .Op Fl C Ar bytes
46 .Op Fl E Ar file
47 .Op Fl F Ar archive
48 .Op Fl H Ar format
49 .Op Fl I Ar archive
50 .Op Ar pattern ...
51 .Op \*(Lt Ar archive
52 .Nm cpio
53 .Fl p
54 .Op Fl adLlmuv
55 .Ar destination-directory
56 .No \*(Lt Ar name-list
57 .Sh DESCRIPTION
58 The
59 .Nm
60 command copies files to and from a
61 .Nm
62 archive.
63 .Pp
64 The options are as follows:
65 .Bl -tag -width Ds
66 .It Fl o
67 Create an archive.
68 Reads the list of files to store in the
69 archive from standard input, and writes the archive on standard
70 output.
71 .Bl -tag -width Ds
72 .It Fl A
73 Append to the specified archive.
74 .It Fl a
75 Reset the access times on files that have been copied to the
76 archive.
77 .It Fl B
78 Set block size of output to 5120 bytes.
79 .It Fl C Ar bytes
80 Set the block size of output to
81 .Ar bytes .
82 .It Fl c
83 Use ASCII format for
84 .Nm
85 header for portability.
86 .It Fl F Ar archive
87 Use the specified file as the input for the archive.
88 .It Fl H Ar format
89 Write the archive in the specified format.
90 Recognized formats are:
91 .Pp
92 .Bl -tag -width sv4cpio -compact
93 .It Ar bcpio
94 Old binary
95 .Nm
96 format.
97 .It Ar cpio
98 Old octal character
99 .Nm
100 format.
101 .It Ar sv4cpio
102 SVR4 hex
103 .Nm
104 format.
105 .It Ar tar
106 Old tar format.
107 .It Ar ustar
108 POSIX ustar format.
109 .El
110 .It Fl j
111 Compress archive using the bzip2 format.
112 The bzip2 utility must be installed separately.
113 .It Fl L
114 Follow symbolic links.
115 .It Fl O Ar archive
116 Use the specified file name as the archive to write to.
117 .It Fl v
118 Be verbose about operations.
119 List filenames as they are written to the archive.
120 .It Fl Z
121 Compress archive using
122 .Xr compress 1
123 format.
124 .It Fl z
125 Compress archive using
126 .Xr gzip 1
127 format.
128 .El
129 .It Fl i
130 Restore files from an archive.
131 Reads the archive file from
132 standard input and extracts files matching the
133 .Ar patterns
134 that were specified on the command line.
135 .Bl -tag -width Ds
136 .It Fl 6
137 Process old-style
138 .Nm
139 format archives.
140 .It Fl B
141 Set the block size of the archive being read to 5120 bytes.
142 .It Fl b
143 Do byte and word swapping after reading in data from the
144 archive, for restoring archives created on systems with
145 a different byte order.
146 .It Fl C Ar bytes
147 Read archive written with a block size of
148 .Ar bytes .
149 .It Fl c
150 Expect the archive headers to be in ASCII format.
151 .It Fl d
152 Create any intermediate directories as needed during
153 restore.
154 .It Fl E Ar file
155 Read list of file name patterns to extract or list from
156 .Ar file .
157 .It Fl F Ar archive , Fl I Ar archive
158 Use the specified file as the input for the archive.
159 .It Fl f
160 Restore all files except those matching the
161 .Ar patterns
162 given on the command line.
163 .It Fl H Ar format
164 Read an archive of the specified format.
165 Recognized formats are:
166 .Pp
167 .Bl -tag -width sv4cpio -compact
168 .It Ar bcpio
169 Old binary
170 .Nm
171 format.
172 .It Ar cpio
173 Old octal character
174 .Nm
175 format.
176 .It Ar sv4cpio
177 SVR4 hex
178 .Nm
179 format.
180 .It Ar tar
181 Old tar format.
182 .It Ar ustar
183 POSIX ustar format.
184 .El
185 .It Fl j
186 Uncompress archive using the bzip2 format.
187 The bzip2 utility must be installed separately.
188 .It Fl m
189 Restore modification times on files.
190 .It Fl r
191 Rename restored files interactively.
192 .It Fl S
193 Swap words after reading data from the archive.
194 .It Fl s
195 Swap bytes after reading data from the archive.
196 .It Fl t
197 Only list the contents of the archive, no files or
198 directories will be created.
199 .It Fl u
200 Overwrite files even when the file in the archive is
201 older than the one that will be overwritten.
202 .It Fl v
203 Be verbose about operations.
204 List filenames as they are copied in from the archive.
205 .It Fl Z
206 Uncompress archive using
207 .Xr compress 1
208 format.
209 .It Fl z
210 Uncompress archive using
211 .Xr gzip 1
212 format.
213 .El
214 .It Fl p
215 Copy files from one location to another in a single pass.
216 The list of files to copy are read from standard input and
217 written out to a directory relative to the specified
218 .Ar directory
219 argument.
220 .Bl -tag -width Ds
221 .It Fl a
222 Reset the access times on files that have been copied.
223 .It Fl d
224 Create any intermediate directories as needed to write
225 the files at the new location.
226 .It Fl L
227 Follow symbolic links.
228 .It Fl l
229 When possible, link files rather than creating an
230 extra copy.
231 .It Fl m
232 Restore modification times on files.
233 .It Fl u
234 Overwrite files even when the original file being copied is
235 older than the one that will be overwritten.
236 .It Fl v
237 Be verbose about operations.
238 List filenames as they are copied.
239 .El
240 .El
241 .Sh ENVIRONMENT
242 .Bl -tag -width Fl
243 .It Ev TMPDIR
244 Path in which to store temporary files.
245 .El
246 .Sh EXIT STATUS
247 The
248 .Nm
249 utility exits with one of the following values:
250 .Pp
251 .Bl -tag -width Ds -offset indent -compact
252 .It 0
253 All files were processed successfully.
254 .It 1
255 An error occurred.
256 .El
257 .Sh DIAGNOSTICS
258 Whenever
259 .Nm
260 cannot create a file or a link when extracting an archive or cannot
261 find a file while writing an archive, or cannot preserve the user
262 ID, group ID, file mode, or access and modification times when the
263 .Fl p
264 option is specified, a diagnostic message is written to standard
265 error and a non-zero exit value will be returned, but processing
266 will continue.
267 In the case where
268 .Nm
269 cannot create a link to a file,
270 .Nm
271 will not create a second copy of the file.
272 .Pp
273 If the extraction of a file from an archive is prematurely terminated
274 by a signal or error,
275 .Nm
276 may have only partially extracted the file the user wanted.
277 Additionally, the file modes of extracted files and directories may
278 have incorrect file bits, and the modification and access times may
279 be wrong.
280 .Pp
281 If the creation of an archive is prematurely terminated by a signal
282 or error,
283 .Nm
284 may have only partially created the archive, which may violate the
285 specific archive format specification.
286 .Sh SEE ALSO
287 .Xr pax 1 ,
288 .Xr tar 1
289 .Sh AUTHORS
290 .An Keith Muller
291 at the University of California, San Diego.
292 .Sh CAVEATS
293 Different file formats have different maximum file sizes.
294 It is recommended that a format such as cpio or ustar
295 be used for larger files.
296 .Bl -column "File format" "Maximum file size" -offset indent
297 .It Sy "File format" Ta Sy "Maximum file size"
298 .It bcpio Ta "4 Gigabytes"
299 .It sv4cpio Ta "4 Gigabytes"
300 .It cpio Ta "8 Gigabytes"
301 .It tar Ta "8 Gigabytes"
302 .It ustar Ta "8 Gigabytes"
303 .El
304 .Sh BUGS
305 The
306 .Fl s
307 and
308 .Fl S
309 options are currently not implemented.