| blob | d04f4847bd961c9821e67bbbf436a4d47cc85d0c |
1 .\" $NetBSD: cpio.1,v 1.10 2007/04/23 18:41:11 christos 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 .\" OpenBSD: cpio.1,v 1.14 2000/11/10 17:52:02 aaron Exp
27 .\"
28 .Dd April 23, 2007
29 .Dt CPIO 1
30 .Os
31 .Sh NAME
32 .Nm cpio
33 .Nd copy file archives in and out
34 .Sh SYNOPSIS
35 .Nm cpio
36 .Fl o
37 .Op Fl AaBcLvZz
38 .Op Fl C Ar bytes
39 .Op Fl F Ar archive
40 .Op Fl H Ar format
41 .Op Fl O Ar archive
42 .Ar "\*[Lt] name-list"
43 .Op Ar "\*[Gt] archive"
44 .Nm cpio
45 .Fl i
46 .Op Fl 6BbcdfmrSstuvZz
47 .Op Fl C Ar bytes
48 .Op Fl E Ar file
49 .Op Fl F Ar archive
50 .Op Fl H Ar format
51 .Op Fl I Ar archive
52 .Op Ar "pattern ..."
53 .Op Ar "\*[Lt] archive"
54 .Nm cpio
55 .Fl p
56 .Op Fl adLlmuv
57 .Ar destination-directory
58 .Ar "\*[Lt] name-list"
59 .Sh DESCRIPTION
60 The
61 .Nm
62 command copies files to and from a
63 .Nm
64 archive.
65 If the archive is of the form:
66 .Ar [[user@]host:]file
67 then the archive will be processed using
68 .Xr rmt 8 .
69 .Pp
70 The options are as follows:
71 .Bl -tag -width Ds
72 .It Fl o , -create
73 Create an archive.
74 Reads the list of files to store in the
75 archive from standard input, and writes the archive on standard
76 output.
77 .Bl -tag -width Ds
78 .It Fl a , -reset-access-time
79 Reset the access times on files that have been copied to the
80 archive.
81 .It Fl A , -append
82 Append to the specified archive.
83 .It Fl B
84 Set block size of output to 5120 bytes.
85 .It Fl c
86 Use ASCII format for
87 .Nm
88 header for portability.
89 .It Fl C Ar bytes
90 Set the block size of output to
91 .Ar bytes .
92 .It Fl F Ar archive
93 .It Fl O Ar archive
94 Use the specified file name as the archive to write to.
95 .It Fl H Ar format
96 Write the archive in the specified format.
97 Recognized formats are:
98 .Pp
99 .Bl -tag -width sv4cpio -compact
100 .It Ar bcpio
101 Old binary
102 .Nm
103 format.
104 .It Ar cpio
105 Old octal character
106 .Nm
107 format.
108 .It Ar sv4cpio
109 SVR4 hex
110 .Nm
111 format.
112 .It Ar tar
113 Old tar format.
114 .It Ar ustar
115 POSIX ustar format.
116 .El
117 .It Fl L
118 Follow symbolic links.
119 .It Fl v
120 Be verbose about operations.
121 List filenames as they are written to the archive.
122 .It Fl z
123 Compress archive using
124 .Xr gzip 1
125 format.
126 .It Fl Z
127 Compress archive using
128 .Xr compress 1
129 format.
130 .El
131 .It Fl i , -extract
132 Restore files from an archive.
133 Reads the archive file from
134 standard input and extracts files matching the
135 .Ar patterns
136 that were specified on the command line.
137 .Bl -tag -width Ds
138 .It Fl b
139 Do byte and word swapping after reading in data from the
140 archive, for restoring archives created on systems with
141 a different byte order.
142 .It Fl B
143 Set the block size of the archive being read to 5120 bytes.
144 .It Fl c
145 Expect the archive headers to be in ASCII format.
146 .It Fl C Ar bytes
147 Read archive written with a block size of
148 .Ar bytes .
149 .It Fl d , -make-directories
150 Create any intermediate directories as needed during
151 restore.
152 .It Fl E Ar file , Fl -pattern-file Ar file
153 Read list of file name patterns to extract or list from
154 .Ar file .
155 .It Fl f , -nonmatching
156 Restore all files except those matching the
157 .Ar patterns
158 given on the command line.
159 .It Fl F Ar archive , Fl -file Ar archive
160 .It Fl I Ar archive
161 Use the specified file as the input for the archive.
162 .It Fl H Ar format , Fl -format Ar format
163 Read an archive of the specified format.
164 Recognized formats are:
165 .Pp
166 .Bl -tag -width sv4cpio -compact
167 .It Ar bcpio
168 Old binary
169 .Nm
170 format.
171 .It Ar cpio
172 Old octal character
173 .Nm
174 format.
175 .It Ar sv4cpio
176 SVR4 hex
177 .Nm
178 format.
179 .It Ar tar
180 Old tar format.
181 .It Ar ustar
182 POSIX ustar format.
183 .El
184 .It Fl m
185 Restore modification times on files.
186 .It Fl r , -rename
187 Rename restored files interactively.
188 .It Fl s
189 Swap bytes after reading data from the archive.
190 .It Fl S , -swap-halfwords
191 Swap words after reading data from the archive.
192 .It Fl t , -list
193 Only list the contents of the archive, no files or
194 directories will be created.
195 .It Fl u , -unconditional
196 Overwrite files even when the file in the archive is
197 older than the one that will be overwritten.
198 .It Fl v , -verbose
199 Be verbose about operations.
200 List filenames as they are copied in from the archive.
201 .It Fl z
202 Uncompress archive using
203 .Xr gzip 1
204 format.
205 .It Fl Z
206 Uncompress archive using
207 .Xr compress 1
208 format.
209 .It Fl 6
210 Process old-style
211 .Nm
212 format archives.
213 .El
214 .It Fl p , -pass-through
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 , -link
227 When possible, link files rather than creating an
228 extra copy.
229 .It Fl L , -dereference
230 Follow symbolic links.
231 .It Fl m , -preserve-modification-time
232 Restore modification times on files.
233 .It Fl u , -unconditional
234 Overwrite files even when the original file being copied is
235 older than the one that will be overwritten.
236 .It Fl v , -verbose
237 Be verbose about operations.
238 List filenames as they are copied.
239 .It Fl -force-local
240 Do not interpret filenames that contain a
241 .Sq \&:
242 as remote files.
243 .It Fl -insecure
244 Normally
245 .Nm
246 ignores filenames that contain
247 .Dq ..
248 as a path component.
249 With this option, files that contain
250 .Dq ..
251 can be processed.
252 .El
253 .El
254 .Sh EXIT STATUS
255 .Nm
256 will exit with one of the following values:
257 .Bl -tag -width 2n
258 .It 0
259 All files were processed successfully.
260 .It 1
261 An error occurred.
262 .El
263 .Pp
264 Whenever
265 .Nm
266 cannot create a file or a link when extracting an archive or cannot
267 find a file while writing an archive, or cannot preserve the user
268 ID, group ID, file mode, or access and modification times when the
269 .Fl p
270 option is specified, a diagnostic message is written to standard
271 error and a non-zero exit value will be returned, but processing
272 will continue.
273 In the case where
274 .Nm
275 cannot create a link to a file,
276 .Nm
277 will not create a second copy of the file.
278 .Pp
279 If the extraction of a file from an archive is prematurely terminated
280 by a signal or error,
281 .Nm
282 may have only partially extracted the file the user wanted.
283 Additionally, the file modes of extracted files and directories may
284 have incorrect file bits, and the modification and access times may
285 be wrong.
286 .Pp
287 If the creation of an archive is prematurely terminated by a signal
288 or error,
289 .Nm
290 may have only partially created the archive which may violate the
291 specific archive format specification.
292 .Sh SEE ALSO
293 .Xr pax 1 ,
294 .Xr tar 1
295 .Sh AUTHORS
296 Keith Muller at the University of California, San Diego.
297 .Sh BUGS
298 The
299 .Fl s
300 and
301 .Fl S
302 options are currently not implemented.