Commit | Line | Data |
---|---|---|
9f2cbfc9 KM |
1 | .\" Copyright (c) 1992 Keith Muller. |
2 | .\" Copyright (c) 1992 The Regents of the University of California. | |
3 | .\" All rights reserved. | |
4 | .\" | |
5 | .\" This code is derived from software contributed to Berkeley by | |
6 | .\" Keith Muller of the University of California, San Diego. | |
7 | .\" | |
8 | .\" %sccs.include.redist.man% | |
9 | .\" | |
f7d3c69d | 10 | .\" @(#)pax.1 1.2 (Berkeley) %G% |
9f2cbfc9 KM |
11 | .\" |
12 | .Dd | |
13 | .Dt PAX 1 | |
14 | .Os BSD 4.4 | |
15 | .Sh NAME | |
16 | .Nm pax | |
17 | .Nd read and write file archives and copy directory hierarchies | |
18 | .Sh SYNOPSIS | |
19 | .Nm pax | |
20 | .Op Fl cdnv | |
21 | .Bk -words | |
22 | .Op Fl f Ar archive | |
23 | .Ek | |
24 | .Bk -words | |
25 | .Op Fl s Ar replstr | |
26 | .Ar ... | |
27 | .Ek | |
28 | .Bk -words | |
29 | .Op Fl U Ar user | |
30 | .Ar ... | |
31 | .Ek | |
32 | .Bk -words | |
33 | .Op Fl G Ar group | |
34 | .Ar ... | |
35 | .Ek | |
36 | .Bk -words | |
37 | .Oo | |
38 | .Fl T | |
39 | .Op Ar from_date | |
40 | .Op Ar ,to_date | |
41 | .Oc | |
42 | .Ar ... | |
43 | .Ek | |
44 | .Op Ar pattern ... | |
45 | .Nm pax | |
46 | .Fl r | |
f7d3c69d | 47 | .Op Fl cdiknuvDYZ |
9f2cbfc9 KM |
48 | .Bk -words |
49 | .Op Fl f Ar archive | |
50 | .Ek | |
51 | .Bk -words | |
52 | .Op Fl o Ar options | |
53 | .Ar ... | |
54 | .Ek | |
55 | .Bk -words | |
56 | .Op Fl p Ar string | |
57 | .Ar ... | |
58 | .Ek | |
59 | .Bk -words | |
60 | .Op Fl s Ar replstr | |
61 | .Ar ... | |
62 | .Ek | |
63 | .Op Fl E Ar limit | |
64 | .Bk -words | |
65 | .Op Fl U Ar user | |
66 | .Ar ... | |
67 | .Ek | |
68 | .Bk -words | |
69 | .Op Fl G Ar group | |
70 | .Ar ... | |
71 | .Ek | |
72 | .Bk -words | |
73 | .Oo | |
74 | .Fl T | |
75 | .Op Ar from_date | |
76 | .Op Ar ,to_date | |
77 | .Oc | |
78 | .Ar ... | |
79 | .Ek | |
80 | .Op Ar pattern ... | |
81 | .Nm pax | |
82 | .Fl w | |
83 | .Op Fl dituvHLX | |
84 | .Bk -words | |
85 | .Op Fl b Ar blocksize | |
86 | .Ek | |
87 | .Oo | |
88 | .Op Fl a | |
89 | .Op Fl f Ar archive | |
90 | .Oc | |
91 | .Bk -words | |
92 | .Op Fl x Ar format | |
93 | .Ek | |
94 | .Bk -words | |
95 | .Op Fl s Ar replstr | |
96 | .Ar ... | |
97 | .Ek | |
98 | .Bk -words | |
99 | .Op Fl o Ar options | |
100 | .Ar ... | |
101 | .Ek | |
102 | .Bk -words | |
103 | .Op Fl U Ar user | |
104 | .Ar ... | |
105 | .Ek | |
106 | .Bk -words | |
107 | .Op Fl G Ar group | |
108 | .Ar ... | |
109 | .Ek | |
110 | .Bk -words | |
111 | .Op Fl B Ar bytes | |
112 | .Ek | |
113 | .Bk -words | |
114 | .Oo | |
115 | .Fl T | |
116 | .Op Ar from_date | |
117 | .Op Ar ,to_date | |
f7d3c69d | 118 | .Op Ar /[c][m] |
9f2cbfc9 KM |
119 | .Oc |
120 | .Ar ... | |
121 | .Ek | |
122 | .Op Ar file ... | |
123 | .Nm pax | |
124 | .Fl r | |
125 | .Fl w | |
f7d3c69d | 126 | .Op Fl diklntuvDHLXYZ |
9f2cbfc9 KM |
127 | .Bk -words |
128 | .Op Fl p Ar string | |
129 | .Ar ... | |
130 | .Ek | |
131 | .Bk -words | |
132 | .Op Fl s Ar replstr | |
133 | .Ar ... | |
134 | .Ek | |
135 | .Bk -words | |
136 | .Op Fl U Ar user | |
137 | .Ar ... | |
138 | .Ek | |
139 | .Bk -words | |
140 | .Op Fl G Ar group | |
141 | .Ar ... | |
142 | .Ek | |
143 | .Bk -words | |
144 | .Oo | |
145 | .Fl T | |
146 | .Op Ar from_date | |
147 | .Op Ar ,to_date | |
f7d3c69d | 148 | .Op Ar /[c][m] |
9f2cbfc9 KM |
149 | .Oc |
150 | .Ar ... | |
151 | .Ek | |
152 | .Op Ar file ... | |
153 | .Ar directory | |
154 | .Sh DESCRIPTION | |
155 | .Nm Pax | |
156 | will read, write, and list the members of an archive file, | |
157 | and will copy directory hierarchies. | |
158 | .Nm Pax | |
159 | supports a wide variety of different archive formats. | |
f7d3c69d | 160 | These archive formats are described in more detail under the |
9f2cbfc9 | 161 | .Fl x |
f7d3c69d | 162 | option. |
9f2cbfc9 | 163 | .Pp |
f7d3c69d | 164 | The operand |
9f2cbfc9 KM |
165 | .Ar directory |
166 | specifies a destination directory pathname. | |
167 | .Nm Pax | |
f7d3c69d | 168 | will exit with a non-zero exit status |
9f2cbfc9 KM |
169 | if the |
170 | .Ar directory | |
171 | operand does not exist, or it is not writable by the user, | |
172 | or it is not of type directory. | |
173 | .Pp | |
f7d3c69d | 174 | The operand |
9f2cbfc9 KM |
175 | .Ar pattern |
176 | is used to select one or more pathnames of archive members using the pattern | |
177 | matching notation described by | |
178 | .Xr fnmatch 3 . | |
179 | When no | |
180 | .Ar patterns | |
181 | are specified, all members of the archive will be selected. | |
182 | When a | |
183 | .Ar pattern | |
184 | matches a directory, the entire file hierarchy rooted at that directory will | |
185 | be selected. | |
186 | If at the completion of operation a | |
187 | .Ar pattern | |
188 | operand did not select at least one archive member, | |
189 | .Nm pax | |
190 | will write these | |
191 | .Ar pattern | |
192 | operands in a diagnostic message to | |
193 | .Dv standard error | |
194 | and then exit with a non-zero exit status. | |
195 | .Pp | |
f7d3c69d | 196 | The operand |
9f2cbfc9 KM |
197 | .Ar file |
198 | specifies the pathname of a file to be copied or archived. | |
199 | If at the completion of operation a | |
200 | .Ar file | |
201 | operand did not select at least one archived file, | |
202 | .Nm pax | |
203 | will write these | |
204 | .Ar file | |
205 | operand pathnames in a diagnostic message to | |
206 | .Dv standard error | |
207 | and then exit with a non-zero exit status. | |
208 | .Pp | |
209 | .Nm Pax | |
210 | operates in one of four operational modes based on the presence of | |
211 | the | |
212 | .Fl r | |
f7d3c69d | 213 | and the |
9f2cbfc9 KM |
214 | .Fl w |
215 | options. | |
216 | These operational modes are: | |
217 | .Em list , read , write , | |
218 | and | |
219 | .Em copy. | |
220 | .Bl -tag -width 6n | |
221 | .It <none> | |
222 | .Em List . | |
223 | .Nm Pax | |
224 | will write to | |
225 | .Dv standard output | |
226 | a table of contents of the members of the | |
227 | archive file read from | |
228 | .Dv standard input , | |
229 | whose pathnames match the specified | |
230 | .Ar patterns. | |
231 | The table of contents is written with one filename per line and is not buffered | |
232 | more than a single line at a time. | |
233 | .It Fl r | |
234 | .Em Read . | |
235 | .Nm Pax | |
236 | extracts the members of the archive file read from the | |
237 | .Dv standard input , | |
238 | with pathnames matching the specified | |
239 | .Ar patterns. | |
240 | The format and the blocking of the archive is automatically determined on | |
241 | input. | |
242 | When an extracted file is a directory, the entire file hierarchy | |
243 | rooted at that directory is extracted. | |
244 | All extracted files are created relative to the current file hierarchy. | |
245 | The ownership, access and modification times, and file mode of | |
246 | the extracted files are discussed in more detail under the | |
247 | .Fl p | |
248 | option. | |
249 | .It Fl w | |
250 | .Em Write . | |
251 | .Nm Pax | |
252 | writes an archive containing the | |
253 | .Ar file | |
254 | operands to | |
255 | .Dv standard output | |
256 | using the specified archive format. | |
257 | When no | |
258 | .Ar file | |
259 | operands are specified, a list of files to copy, one per line, is read from | |
260 | .Dv standard input . | |
261 | A | |
262 | .Ar file | |
263 | operand that is also a directory will include the entire file hierarchy rooted | |
264 | at that directory. | |
265 | .It Fl r Fl w | |
266 | .Em Copy . | |
267 | .Nm Pax | |
268 | copies the | |
269 | .Ar file | |
270 | operands to the destination | |
271 | .Ar directory . | |
272 | When no | |
273 | .Ar file | |
274 | operands are specified, a list of files to copy, one per line, is read from | |
275 | the | |
276 | .Dv standard input . | |
277 | A | |
278 | .Ar file | |
279 | operand that is also a directory will include the entire file | |
280 | hierarchy rooted at that directory. | |
281 | The effect of the | |
282 | .Em copy | |
283 | is as if the copied files were | |
284 | written to an archive file and then subsequently extracted, | |
285 | except that there may be hard links between the original and the | |
286 | copied files (see the | |
287 | .Fl l | |
288 | option below). | |
f7d3c69d KM |
289 | .Pp |
290 | .Em Warning : | |
9f2cbfc9 KM |
291 | The destination |
292 | .Ar directory | |
293 | must not be one of the | |
f7d3c69d KM |
294 | .Ar file |
295 | operands or a member of a file hierarchy rooted at one of the | |
296 | .Ar file | |
297 | operands. | |
298 | The result of a | |
299 | .Em copy | |
300 | under these conditions is unpredictable. | |
9f2cbfc9 KM |
301 | .El |
302 | .Pp | |
f7d3c69d | 303 | While processing a damaged archive during a |
9f2cbfc9 KM |
304 | .Em read |
305 | or | |
306 | .Em list | |
307 | operation, | |
308 | .Nm pax | |
f7d3c69d KM |
309 | will attempt to recover from media defects and will search through the archive |
310 | to locate and process the largest number of archive members possible (see the | |
311 | .Fl E | |
312 | option for more details on error handling). | |
9f2cbfc9 KM |
313 | .Sh OPTIONS |
314 | .Pp | |
315 | The following options are supported: | |
316 | .Bl -tag -width 4n | |
317 | .It Fl r | |
318 | Read an archive file from | |
319 | .Dv standard input | |
320 | and extract the specified | |
321 | .Ar files . | |
322 | If any intermediate directories are needed in order to extract an archive | |
f7d3c69d | 323 | member, these directories will be created as if |
9f2cbfc9 KM |
324 | .Xr mkdir 2 |
325 | was called with the bitwise inclusive | |
326 | .Dv OR | |
327 | of | |
328 | .Dv S_IRWXU , S_IRWXG , | |
329 | and | |
330 | .Dv S_IRWXO | |
331 | as the mode argument. | |
332 | When the selected archive format supports the specification of linked | |
333 | files and these files cannot be linked while the archive is being extracted, | |
334 | .Nm pax | |
335 | will write a diagnostic message to | |
336 | .Dv standard error | |
f7d3c69d | 337 | and exit with a non-zero exit status at the completion of operation. |
9f2cbfc9 KM |
338 | .It Fl w |
339 | Write files to the | |
340 | .Dv standard output | |
341 | in the specified archive format. | |
342 | When no | |
343 | .Ar file | |
344 | operands are specified, | |
345 | .Dv standard input | |
346 | is read for a list of pathnames, one per line, without any leading or trailing | |
347 | .Aq blanks . | |
348 | .It Fl a | |
349 | Append | |
350 | .Ar files | |
351 | to the end of an archive that was previously written. | |
352 | If an archive format is not specified with a | |
353 | .Fl x | |
354 | option, the format currently being used in the archive will be selected. | |
355 | Any attempt to append to an archive in a format different from the | |
356 | format already used in the archive will cause | |
357 | .Nm pax | |
358 | to exit immediately | |
359 | with a non-zero exit status. | |
360 | The blocking size used in the archive volume where writing starts | |
361 | will continue to be used for the remainder of that archive volume. | |
f7d3c69d KM |
362 | .Pp |
363 | .Em Warning : | |
364 | Many storage devices are not able to support the operations necessary | |
365 | to perform an append operation. | |
366 | Any attempt to append to an archive stored on such a device may damage the | |
367 | archive or have other unpredictable results. | |
368 | Tape drives in particular are more likely to not support an append operation. | |
369 | An archive stored in a regular file system file or on a disk device will | |
370 | usually support an append operation. | |
9f2cbfc9 KM |
371 | .It Fl b Ar blocksize |
372 | When | |
373 | .Em writing | |
374 | an archive, | |
375 | block the output at a positive decimal integer number of | |
376 | bytes per write to the archive file. | |
377 | The | |
378 | .Ar blocksize | |
379 | must be a multiple of 512 bytes with a maximum of 32256 bytes. | |
380 | A | |
381 | .Ar blocksize | |
382 | can end with | |
383 | .Li k | |
384 | or | |
385 | .Li b | |
386 | to specify multiplication by 1024 (1K) or 512, respectively. | |
387 | A pair of | |
388 | .Ar blocksizes | |
389 | can be separated by | |
390 | .Li x | |
391 | to indicate a product. | |
392 | A specific archive device may impose additional restrictions on the size | |
393 | of blocking it will support. | |
394 | When blocking is not specified, | |
395 | the default | |
396 | .Ar blocksize | |
f7d3c69d | 397 | is dependent on the specific archive format being used (see the |
9f2cbfc9 KM |
398 | .Fl x |
399 | option). | |
400 | .It Fl c | |
f7d3c69d KM |
401 | Match all file or archive members |
402 | .Em except | |
403 | those specified by the | |
9f2cbfc9 KM |
404 | .Ar pattern |
405 | and | |
406 | .Ar file | |
407 | operands. | |
408 | .It Fl d | |
f7d3c69d KM |
409 | Cause files of type directory being copied or archived, or archive members of |
410 | type directory being extracted, to match only the directory file or archive | |
9f2cbfc9 KM |
411 | member and not the file hierarchy rooted at the directory. |
412 | .It Fl f Ar archive | |
413 | Specify | |
414 | .Ar archive | |
415 | as the pathname of the input or output archive, overriding the default | |
416 | .Dv standard input | |
417 | (for | |
418 | .Em list | |
419 | and | |
420 | .Em read ) | |
421 | or | |
422 | .Dv standard output | |
423 | (for | |
424 | .Em write ) . | |
425 | A single archive may span multiple files and different archive devices. | |
f7d3c69d | 426 | When required, |
9f2cbfc9 | 427 | .Nm pax |
f7d3c69d KM |
428 | will prompt for the pathname of the file or device of the next volume in the |
429 | archive. | |
9f2cbfc9 KM |
430 | .It Fl i |
431 | Interactively rename files or archive members. | |
432 | For each archive member matching a | |
433 | .Ar pattern | |
434 | operand or each file matching a | |
435 | .Ar file | |
436 | operand, | |
437 | .Nm pax | |
438 | will prompt to | |
439 | .Pa /dev/tty | |
440 | giving the name of the file, its file mode and its modification time. | |
441 | .Nm Pax | |
442 | will then read a line from | |
443 | .Pa /dev/tty . | |
444 | If this line is blank, the file or archive member is skipped. | |
445 | If this line consists of a single period, the | |
446 | file or archive member is processed with no modification to its name. | |
447 | Otherwise, its name is replaced with the contents of the line. | |
448 | .Nm Pax | |
f7d3c69d | 449 | will immediately exit with a non-zero exit status if |
9f2cbfc9 KM |
450 | .Dv <EOF> |
451 | is encountered when reading a response or if | |
452 | .Pa /dev/tty | |
453 | cannot be opened for reading and writing. | |
454 | .It Fl k | |
455 | Do not overwrite existing files. | |
456 | .It Fl l | |
457 | Link files. (The letter ell). | |
458 | In the | |
459 | .Em copy | |
460 | mode ( | |
461 | .Fl r | |
462 | .Fl w ) , | |
463 | hard links are made between the source and destination file hierarchies | |
464 | whenever possible. | |
465 | .It Fl n | |
466 | Select the first archive member that matches each | |
467 | .Ar pattern | |
468 | operand. | |
469 | No more than one archive member is matched for each | |
470 | .Ar pattern . | |
471 | When members of type directory are matched, the file hierarchy rooted at that | |
472 | directory is also matched (unless | |
473 | .Fl d | |
474 | is also specified). | |
475 | .It Fl o Ar options | |
476 | Information to modify the algorithm for extracting or writing archive files | |
477 | which is specific to the archive format specified by | |
478 | .Fl x . | |
479 | In general, | |
480 | .Ar options | |
481 | take the form: | |
482 | .Cm name=value | |
483 | .It Fl p Ar string | |
484 | Specify one or more file characteristic options (privileges). | |
485 | The | |
486 | .Ar string | |
487 | option-argument is a string specifying file characteristics to be retained or | |
488 | discarded on extraction. | |
489 | The string consists of the specification characters | |
490 | .Cm a , e , m , o , | |
491 | and | |
492 | .Cm p . | |
493 | Multiple characteristics can be concatenated within the same string | |
494 | and multiple | |
495 | .Fl p | |
496 | options can be specified. | |
497 | The meaning of the specification characters are as follows: | |
498 | .Bl -tag -width 2n | |
499 | .It Cm a | |
500 | Do not preserve file access times. | |
501 | By default, file access times are preserved whenever possible. | |
502 | .It Cm e | |
503 | .Sq Preserve everything , | |
504 | the user ID, group ID, file mode bits, | |
505 | file access time, and file modification time. | |
506 | This is intended to be used by | |
507 | .Em root , | |
508 | someone with all the appropriate privileges, in order to preserve all | |
509 | aspects of the files as they are recorded in the archive. | |
510 | The | |
511 | .Cm e | |
512 | flag is the sum of the | |
513 | .Cm o | |
514 | and | |
515 | .Cm p | |
516 | flags. | |
517 | .It Cm m | |
518 | Do not preserve file modification times. | |
519 | By default, file modification times are preserved whenever possible. | |
520 | .It Cm o | |
521 | Preserve the user ID and group ID. | |
522 | .It Cm p | |
523 | .Sq Preserve | |
524 | the file mode bits. | |
f7d3c69d KM |
525 | This intended to be used by a |
526 | .Em user | |
527 | with regular privileges who wants to preserve all aspects of the file other | |
528 | than the ownership. | |
9f2cbfc9 KM |
529 | The file times are preserved by default, but two other flags are offered to |
530 | disable this and use the time of extraction instead. | |
531 | .El | |
532 | .Pp | |
533 | In the preceding list, | |
534 | .Sq preserve | |
535 | indicates that an attribute stored in the archive is given to the | |
536 | extracted file, subject to the permissions of the invoking | |
537 | process. | |
538 | Otherwise the attribute of the extracted file is determined as | |
539 | part of the normal file creation action. | |
540 | If neither the | |
541 | .Cm e | |
542 | nor the | |
543 | .Cm o | |
544 | specification character is specified, or the user ID and group ID are not | |
545 | preserved for any reason, | |
546 | .Nm pax | |
547 | will not set the | |
548 | .Dv S_ISUID | |
549 | .Em ( setuid ) | |
550 | and | |
551 | .Dv S_ISGID | |
552 | .Em ( setgid ) | |
553 | bits of the file mode. | |
554 | If the preservation of any of these items fails for any reason, | |
555 | .Nm pax | |
556 | will write a diagnostic message to | |
557 | .Dv standard error . | |
558 | Failure to preserve these items will affect the final exit status, | |
559 | but will not cause the extracted file to be deleted. | |
f7d3c69d | 560 | If the file characteristic letters in any of the string option-arguments are |
9f2cbfc9 KM |
561 | duplicated or conflict with each other, the one(s) given last will take |
562 | precedence. | |
563 | For example, if | |
564 | .Dl Fl p Ar eme | |
565 | is specified, file modification times are still preserved. | |
566 | .It Fl s Ar replstr | |
f7d3c69d | 567 | Modify the file or archive member names specified by the |
9f2cbfc9 KM |
568 | .Ar pattern |
569 | or | |
570 | .Ar file | |
571 | operands according to the substitution expression | |
572 | .Ar replstr , | |
573 | using the syntax of the | |
574 | .Xr ed 1 | |
575 | utility regular expressions. | |
576 | The format of these regular expressions are: | |
f7d3c69d KM |
577 | .Dl /old/new/[gp] |
578 | As in | |
579 | .Xr ed 1 , | |
9f2cbfc9 KM |
580 | .Cm old |
581 | is a basic regular expression and | |
582 | .Cm new | |
583 | can contain an ampersand (&), \\n (where n is a digit) back-references, | |
584 | or subexpression matching. | |
585 | The | |
586 | .Cm old | |
587 | string may also contain | |
588 | .Dv <newline> | |
589 | characters. | |
590 | Any non-null character can be used as a delimiter (/ is shown here). | |
591 | Multiple | |
592 | .Fl s | |
593 | expressions can be specified. | |
594 | The expressions are applied in the order they are specified on the | |
595 | command line, terminating with the first successful substitution. | |
596 | The optional trailing | |
597 | .Cm g | |
f7d3c69d KM |
598 | continues to apply the substitution expression to the pathname substring |
599 | which starts with the first character following the end of the last successful | |
600 | substitution. The first unsuccessful substitution stops the operation of the | |
601 | .Cm g | |
602 | option. | |
9f2cbfc9 KM |
603 | The optional trailing |
604 | .Cm p | |
605 | will cause the final result of a successful substitution to be written to | |
606 | .Dv standard error | |
607 | in the following format: | |
608 | .Dl <original pathname> >> <new pathname> | |
609 | File or archive member names that substitute to the empty string | |
610 | are not selected and will be skipped. | |
611 | .It Fl t | |
612 | Reset the access times of any file or directory read or accessed by | |
613 | .Nm pax | |
614 | to be the same as they were before being read or accessed by | |
615 | .Nm pax . | |
616 | .It Fl u | |
617 | Ignore files that are older (having a less recent file modification time) | |
618 | than a pre-existing file or archive member with the same name. | |
619 | During | |
620 | .Em read , | |
621 | an archive member with the same name as a file in the file system will be | |
622 | extracted if the archive member is newer than the file. | |
623 | During | |
624 | .Em write , | |
625 | a file system member with the same name as an archive member will be | |
626 | written to the archive if it is newer than the archive member. | |
627 | During | |
628 | .Em copy , | |
629 | the file in the destination hierarchy is replaced by the file in the source | |
630 | hierarchy or by a link to the file in the source hierarchy if the file in | |
631 | the source hierarchy is newer. | |
632 | .It Fl v | |
633 | During a | |
634 | .Em list | |
635 | operation, produce a verbose table of contents using the format of the | |
636 | .Xr ls 1 | |
637 | utility with the | |
638 | .Fl l | |
639 | option. | |
640 | For pathnames representing a hard link to a previous member of the archive, | |
641 | the output has the format: | |
642 | .Dl <ls -l listing> == <link name> | |
643 | For pathnames representing a symbolic link, the output has the format: | |
644 | .Dl <ls -l listing> => <link name> | |
f7d3c69d KM |
645 | Where <ls -l listing> is the output format specified by the |
646 | .Xr ls 1 | |
647 | utility when used with the | |
9f2cbfc9 KM |
648 | .Fl l |
649 | option. | |
650 | Otherwise for all the other operational modes ( | |
651 | .Em read , write , | |
f7d3c69d | 652 | and |
9f2cbfc9 KM |
653 | .Em copy ) , |
654 | pathnames are written and flushed to | |
655 | .Dv standard error | |
656 | without a trailing | |
657 | .Dv <newline> | |
658 | as soon as processing begins on that file or | |
659 | archive member. | |
660 | The trailing | |
661 | .Dv <newline> , | |
f7d3c69d | 662 | is not buffered, and is written only after the file has been read or written. |
9f2cbfc9 KM |
663 | .It Fl x Ar format |
664 | Specify the output archive format, with the default format being | |
665 | .Ar ustar . | |
666 | .Nm Pax | |
f7d3c69d | 667 | currently supports the following formats: |
9f2cbfc9 KM |
668 | .Bl -tag -width "sv4cpio" |
669 | .It Ar cpio | |
670 | The extended cpio interchange format specified in the | |
671 | .St -p1003.2 | |
672 | standard. | |
673 | The default blocksize for this format is 5120 bytes. | |
674 | Inode and device information about a file (used for detecting file hard links | |
675 | by this format) which may be truncated by this format is detected by | |
676 | .Nm pax | |
677 | and is repaired. | |
678 | .It Ar bcpio | |
679 | The old binary cpio format. | |
680 | The default blocksize for this format is 5120 bytes. | |
f7d3c69d KM |
681 | This format is not very portable and should not be used when other formats |
682 | are available. | |
9f2cbfc9 KM |
683 | Inode and device information about a file (used for detecting file hard links |
684 | by this format) which may be truncated by this format is detected by | |
685 | .Nm pax | |
686 | and is repaired. | |
687 | .It Ar sv4cpio | |
688 | The System V release 4 cpio. | |
689 | The default blocksize for this format is 5120 bytes. | |
690 | Inode and device information about a file (used for detecting file hard links | |
691 | by this format) which may be truncated by this format is detected by | |
692 | .Nm pax | |
693 | and is repaired. | |
694 | .It Ar sv4crc | |
695 | The System V release 4 cpio with file crc checksums. | |
696 | The default blocksize for this format is 5120 bytes. | |
697 | Inode and device information about a file (used for detecting file hard links | |
698 | by this format) which may be truncated by this format is detected by | |
699 | .Nm pax | |
700 | and is repaired. | |
701 | .It Ar tar | |
702 | The old BSD tar format as found in BSD4.3. | |
703 | The default blocksize for this format is 10240 bytes. | |
f7d3c69d KM |
704 | Pathnames stored by this format must be 100 characters or less in length. |
705 | Only | |
706 | .Em regular | |
707 | files, | |
708 | .Em hard links , soft links , | |
709 | and | |
710 | .Em directories | |
711 | will be archived (other file system types are not supported). | |
9f2cbfc9 KM |
712 | For backwards compatability with even older tar formats, a |
713 | .Fl o | |
714 | option can be used when writing an archive to omit the storage of directories. | |
715 | This option takes the form: | |
716 | .Dl Fl o Cm write_opt=nodir | |
717 | .It Ar ustar | |
718 | The extended tar interchange format specified in the | |
719 | .St -p1003.2 | |
720 | standard. | |
721 | The default blocksize for this format is 10240 bytes. | |
f7d3c69d | 722 | Pathnames stored by this format must be 250 characters or less in length. |
9f2cbfc9 KM |
723 | .El |
724 | .Pp | |
725 | .Nm Pax | |
726 | will detect and report any file that it is unable to store or extract | |
727 | as the result of any specific archive format restrictions. | |
f7d3c69d KM |
728 | The individual archive formats may impose additional restrictions on use. |
729 | Typical archive format restrictions include (but are not limited to): | |
730 | file pathname length, file size, link pathname length and the type of the file. | |
9f2cbfc9 KM |
731 | .It Fl B Ar bytes |
732 | Limit the number of bytes written to a single archive volume to | |
733 | .Ar bytes . | |
734 | The | |
f7d3c69d | 735 | .Ar bytes |
9f2cbfc9 KM |
736 | limit can end with |
737 | .Li m , | |
738 | .Li k , | |
739 | or | |
740 | .Li b | |
741 | to specify multiplication by 1048576 (1M), 1024 (1K) or 512, respectively. | |
742 | A pair of | |
f7d3c69d | 743 | .Ar bytes |
9f2cbfc9 KM |
744 | limits can be separated by |
745 | .Li x | |
746 | to indicate a product. | |
f7d3c69d KM |
747 | .Pp |
748 | .Em Warning : | |
749 | Only use this option when writing a archive to a device which supports | |
750 | an end of file read condition based on last (or largest) write offset | |
751 | (such as a regular file or a tape drive). | |
752 | The use of this option with a floppy or hard disk is not recommended. | |
753 | .It Fl D | |
754 | This option is the same as the | |
755 | .Fl u | |
756 | option, except that the file inode change time is checked instead of the | |
757 | file modification time. | |
758 | The file inode change time can be used to select files whose inode information | |
759 | (e.g. uid, gid, etc.) is newer than a copy of the file in the destination | |
760 | .Ar directory . | |
9f2cbfc9 KM |
761 | .It Fl E Ar limit |
762 | Limit the number of consecutive read faults while trying to read a flawed | |
763 | archives to | |
764 | .Ar limit . | |
765 | With a positive | |
766 | .Ar limit , | |
767 | .Nm pax | |
f7d3c69d KM |
768 | will attempt to recover from an archive read error and will |
769 | continue processing starting with the next file stored in the archive. | |
9f2cbfc9 KM |
770 | A |
771 | .Ar limit | |
772 | of 0 will cause | |
773 | .Nm pax | |
774 | to stop operation after the first read error is detected on an archive volume. | |
775 | A | |
776 | .Ar limit | |
777 | of | |
778 | .Li NONE | |
779 | will cause | |
780 | .Nm pax | |
f7d3c69d KM |
781 | to attempt to recover from read errors forever. |
782 | The default | |
783 | .Ar limit | |
784 | is a small positive number of retries. | |
785 | .Pp | |
786 | .Em Warning: | |
787 | Using this option with | |
788 | .Li NONE | |
789 | should be used with extreme caution as | |
9f2cbfc9 KM |
790 | .Nm pax |
791 | may get stuck in an infinite loop on a very badly flawed archive. | |
9f2cbfc9 KM |
792 | .It Fl G Ar group |
793 | Select a file based on its | |
794 | .Ar group | |
795 | name, or when starting with a | |
f7d3c69d KM |
796 | .Cm # , |
797 | a numeric gid. | |
798 | A '\\' can be used to escape the | |
9f2cbfc9 KM |
799 | .Cm # . |
800 | Multiple | |
801 | .Fl G | |
802 | options may be supplied and checking stops with the first match. | |
803 | .It Fl H | |
804 | Follow only command line symbolic links while performing a physical file | |
805 | system traversal. | |
806 | .It Fl L | |
807 | Follow all symbolic links to perform a logical file system traversal. | |
f7d3c69d KM |
808 | .It Fl T Ar [from_date][,to_date][/[c][m]] |
809 | Allow files to be selected based on a file modification or inode change | |
810 | time falling within a specified time range of | |
9f2cbfc9 KM |
811 | .Ar from_date |
812 | to | |
813 | .Ar to_date | |
814 | (the dates are inclusive). | |
815 | If only a | |
816 | .Ar from_date | |
f7d3c69d KM |
817 | is supplied, all files with a modification or inode change time |
818 | equal to or younger are selected. | |
9f2cbfc9 KM |
819 | If only a |
820 | .Ar to_date | |
f7d3c69d KM |
821 | is supplied, all files with a modification or inode change time |
822 | equal to or older will be selected. | |
9f2cbfc9 KM |
823 | When the |
824 | .Ar from_date | |
825 | is equal to the | |
826 | .Ar to_date , | |
f7d3c69d KM |
827 | only files with a modification or inode change time of exactly that |
828 | time will be selected. | |
829 | .Pp | |
830 | When | |
831 | .Nm pax | |
832 | is in the | |
833 | .Em write | |
834 | or | |
835 | .Em copy | |
836 | mode, the optional trailing field | |
837 | .Ar [c][m] | |
838 | can be used to determine which file time (inode change, file modification or | |
839 | both) are used in the comparison. | |
840 | If neither is specified, the default is to use file modification time only. | |
841 | The | |
842 | .Ar m | |
843 | specifies the comparison of file modification time (the time when | |
844 | the file was last written). | |
845 | The | |
846 | .Ar c | |
847 | specifies the comparison of inode change time (the time when the file | |
848 | inode was last changed; e.g. a change of owner, group, mode, etc). | |
849 | When | |
850 | .Ar c | |
851 | and | |
852 | .Ar m | |
853 | are both specified, then the modification and inode change times are | |
854 | both compared. | |
855 | The inode change time comparison is useful in selecting files whose | |
856 | attributes were recently changed or selecting files which were recently | |
857 | created and had their modification time reset to an older time (as what | |
858 | happens when a file is extracted from an archive and the modification time | |
859 | is preserved). | |
860 | Time comparisons using both file times is useful when | |
861 | .Nm pax | |
862 | is used to create a time based incremental archive (only files that were | |
863 | changed during a specified time range will be archived). | |
864 | .Pp | |
865 | A time range is made up of six different fields and each field must contain two | |
866 | digits. | |
9f2cbfc9 KM |
867 | The format is: |
868 | .Dl [yy[mm[dd[hh]]]]mm[.ss] | |
869 | Where | |
870 | .Cm yy | |
871 | is the last two digits of the year, | |
872 | the first | |
873 | .Cm mm | |
874 | is the month (from 01 to 12), | |
875 | .Cm dd | |
876 | is the day of the month (from 01 to 31), | |
877 | .Cm hh | |
878 | is the hour of the day (from 00 to 23), | |
879 | the second | |
880 | .Cm mm | |
881 | is the minute (from 00 to 59), | |
882 | and | |
883 | .Cm ss | |
884 | is the seconds (from 00 to 59). | |
f7d3c69d KM |
885 | The minute field |
886 | .Cm mm | |
887 | is required, while the other fields are optional and must be added in the | |
888 | following order: | |
889 | .Dl Cm hh , dd , mm , yy . | |
890 | The | |
891 | .Cm ss | |
892 | field may be added independently of the other fields. | |
9f2cbfc9 | 893 | Time ranges are relative to the current time, so |
f7d3c69d KM |
894 | .Dl Fl T Ar 1234/cm |
895 | would select all files with a modification or inode change time | |
896 | of 12:34 PM today or later. | |
9f2cbfc9 KM |
897 | Multiple |
898 | .Fl T | |
899 | time range can be supplied and checking stops with the first match. | |
900 | .It Fl U Ar user | |
901 | Select a file based on its | |
902 | .Ar user | |
903 | name, or when starting with a | |
f7d3c69d KM |
904 | .Cm # , |
905 | a numeric uid. | |
906 | A '\\' can be used to escape the | |
9f2cbfc9 KM |
907 | .Cm # . |
908 | Multiple | |
909 | .Fl U | |
910 | options may be supplied and checking stops with the first match. | |
911 | .It Fl X | |
912 | When traversing the file hierarchy specified by a pathname, | |
913 | do not descend into directories that have a different device ID. | |
914 | See the | |
915 | .Li st_dev | |
916 | field as described in | |
917 | .Xr stat 2 | |
918 | for more information about device ID's. | |
f7d3c69d KM |
919 | .It Fl Y |
920 | This option is the same as the | |
921 | .Fl D | |
922 | option, except that the inode change time is checked using the | |
923 | pathname created after all the file name modifications have completed. | |
9f2cbfc9 KM |
924 | .It Fl Z |
925 | This option is the same as the | |
926 | .Fl u | |
927 | option, except that the modification time is checked using the | |
928 | pathname created after all the file name modifications have completed. | |
929 | .El | |
930 | .Pp | |
931 | The options that operate on the names of files or archive members ( | |
932 | .Fl c , | |
933 | .Fl i , | |
934 | .Fl n , | |
935 | .Fl s , | |
936 | .Fl u , | |
937 | .Fl v , | |
f7d3c69d | 938 | .Fl D , |
9f2cbfc9 KM |
939 | .Fl G , |
940 | .Fl T , | |
941 | .Fl U , | |
f7d3c69d | 942 | .Fl Y , |
9f2cbfc9 KM |
943 | and |
944 | .Fl Z ) | |
945 | interact as follows. | |
946 | .Pp | |
947 | When extracting files during a | |
948 | .Em read | |
949 | operation, archive members are | |
950 | .Sq selected , | |
f7d3c69d | 951 | based only on the user specified pattern operands as modified by the |
9f2cbfc9 KM |
952 | .Fl c , |
953 | .Fl n , | |
954 | .Fl u , | |
f7d3c69d | 955 | .Fl D , |
9f2cbfc9 KM |
956 | .Fl G , |
957 | .Fl T , | |
958 | .Fl U | |
959 | options. | |
960 | Then any | |
961 | .Fl s | |
962 | and | |
963 | .Fl i | |
964 | options will modify in that order, the names of these selected files. | |
965 | Then the | |
f7d3c69d KM |
966 | .Fl Y |
967 | and | |
9f2cbfc9 | 968 | .Fl Z |
f7d3c69d | 969 | options will be applied based on the final pathname. |
9f2cbfc9 KM |
970 | Finally the |
971 | .Fl v | |
972 | option will write the names resulting from these modifications. | |
973 | .Pp | |
974 | When archiving files during a | |
975 | .Em write | |
f7d3c69d | 976 | operation, or copying files during a |
9f2cbfc9 KM |
977 | .Em copy |
978 | operation, archive members are | |
979 | .Sq selected , | |
f7d3c69d | 980 | based only on the user specified pathnames as modified by the |
9f2cbfc9 KM |
981 | .Fl n , |
982 | .Fl u , | |
f7d3c69d | 983 | .Fl D , |
9f2cbfc9 KM |
984 | .Fl G , |
985 | .Fl T , | |
986 | and | |
987 | .Fl U | |
f7d3c69d KM |
988 | options (the |
989 | .Fl D | |
990 | option only applies during a copy operation). | |
9f2cbfc9 KM |
991 | Then any |
992 | .Fl s | |
993 | and | |
994 | .Fl i | |
995 | options will modify in that order, the names of these selected files. | |
f7d3c69d KM |
996 | Then during a |
997 | .Em copy | |
998 | operation the | |
999 | .Fl Y | |
1000 | and the | |
1001 | .Fl Z | |
1002 | options will be applied based on the final pathname. | |
9f2cbfc9 KM |
1003 | Finally the |
1004 | .Fl v | |
1005 | option will write the names resulting from these modifications. | |
1006 | .Pp | |
f7d3c69d | 1007 | When one or both of the |
9f2cbfc9 | 1008 | .Fl u |
f7d3c69d KM |
1009 | or |
1010 | .Fl D | |
1011 | options are specified along with the | |
9f2cbfc9 | 1012 | .Fl n |
f7d3c69d | 1013 | option, a file is not considered selected unless it is newer |
9f2cbfc9 KM |
1014 | than the file to which it is compared. |
1015 | .Sh EXAMPLES | |
1016 | The command: | |
f7d3c69d KM |
1017 | .Dl pax -w -f /dev/rst0 .\ |
1018 | copies the contents of the current directory to the device | |
1019 | .Pa /dev/rst0 . | |
9f2cbfc9 KM |
1020 | .Pp |
1021 | The command: | |
1022 | .Dl pax -r -v -f filename | |
1023 | gives the verbose table of contents for an archive stored in | |
1024 | .Pa filename . | |
1025 | .Pp | |
1026 | The following commands: | |
1027 | .Dl mkdir newdir | |
1028 | .Dl cd olddir | |
f7d3c69d | 1029 | .Dl pax -rw .\ newdir |
9f2cbfc9 KM |
1030 | will copy the entire |
1031 | .Pa olddir | |
1032 | directory hierarchy to | |
1033 | .Pa newdir . | |
1034 | .Pp | |
1035 | The command: | |
1036 | .Dl pax -r -s ',^//*usr//*,,' -f a.pax | |
1037 | reads the archive | |
1038 | .Pa a.pax , | |
f7d3c69d KM |
1039 | with all files rooted in ``/usr'' into the archive extracted relative to the |
1040 | current directory. | |
9f2cbfc9 KM |
1041 | .Pp |
1042 | The command: | |
f7d3c69d | 1043 | .Dl pax -rw -i .\ dest_dir |
9f2cbfc9 KM |
1044 | can be used to interactively select the files to copy from the current |
1045 | directory to | |
1046 | .Pa dest_dir . | |
1047 | .Pp | |
1048 | The command: | |
1049 | .Dl pax -r -pe -U root -G bin -f a.pax | |
1050 | will extract all files from the archive | |
1051 | .Pa a.pax | |
1052 | which are owned by | |
1053 | .Em root | |
1054 | with group | |
1055 | .Em bin | |
1056 | and will preserve all file permissions. | |
f7d3c69d KM |
1057 | .Pp |
1058 | The command: | |
1059 | .Dl pax -r -w -v -Y -Z home /backup | |
1060 | will update (and list) only those files in the destination directory | |
1061 | .Pa /backup | |
1062 | which are older (less recent inode change or file modification times) than | |
1063 | files with the same name found in the source file tree | |
1064 | .Pa home . | |
9f2cbfc9 KM |
1065 | .Sh STANDARDS |
1066 | The | |
1067 | .Nm pax | |
1068 | utility is a superset of the | |
1069 | .St -p1003.2 | |
1070 | standard. | |
1071 | The options | |
1072 | .Fl B , | |
f7d3c69d | 1073 | .Fl D , |
9f2cbfc9 KM |
1074 | .Fl E , |
1075 | .Fl G , | |
1076 | .Fl H , | |
1077 | .Fl T , | |
1078 | .Fl U , | |
f7d3c69d | 1079 | .Fl Y , |
9f2cbfc9 KM |
1080 | .Fl Z , |
1081 | the archive formats | |
1082 | .Ar bcpio , | |
f7d3c69d | 1083 | .Ar sv4cpio , |
9f2cbfc9 KM |
1084 | .Ar sv4crc , |
1085 | .Ar tar , | |
1086 | and the flawed archive handling during | |
1087 | .Ar list | |
1088 | and | |
1089 | .Ar read | |
1090 | operations are extensions to the | |
1091 | .Tn POSIX | |
1092 | standard. | |
1093 | .Sh AUTHOR | |
1094 | Keith Muller at the University of California, San Diego | |
1095 | .Sh ERRORS | |
1096 | .Nm pax | |
1097 | will exit with one of the following values: | |
1098 | .Bl -tag -width 2n | |
1099 | .It 0 | |
1100 | All files were processed successfully. | |
1101 | .It 1 | |
1102 | An error occurred. | |
1103 | .El | |
1104 | .Pp | |
1105 | Whenever | |
1106 | .Nm pax | |
1107 | cannot create a file or a link when reading an archive or cannot | |
1108 | find a file when writing an archive, or cannot preserve the user ID, | |
1109 | group ID, or file mode when the | |
1110 | .Fl p | |
f7d3c69d | 1111 | option is specified, a diagnostic message is written to |
9f2cbfc9 | 1112 | .Dv standard error |
f7d3c69d | 1113 | and a non-zero exit status will be returned, but processing will continue. |
9f2cbfc9 KM |
1114 | In the case where pax cannot create a link to a file, |
1115 | .Nm pax | |
1116 | will not create a second copy of the file. | |
1117 | .Pp | |
1118 | If the extraction of a file from an archive is prematurely terminated by | |
1119 | a signal or error, | |
1120 | .Nm pax | |
1121 | may have only partially extracted a file the user wanted. | |
1122 | Additionally, the file modes of extracted files and directories | |
1123 | may have incorrect file bits, and the modification and access times may be | |
1124 | wrong. | |
1125 | .Pp | |
f7d3c69d | 1126 | If the creation of an archive is prematurely terminated by a signal or error, |
9f2cbfc9 | 1127 | .Nm pax |
f7d3c69d | 1128 | may have only partially created the archive which may violate the specific |
9f2cbfc9 | 1129 | archive format specification. |
f7d3c69d | 1130 | .Pp |
9f2cbfc9 KM |
1131 | If while doing a |
1132 | .Em copy , | |
1133 | .Nm pax | |
1134 | detects a file is about to overwrite itself, the file is not copied, | |
1135 | a diagnostic message is written to | |
1136 | .Dv standard error | |
1137 | and when | |
1138 | .Nm pax | |
1139 | completes it will exit with a non-zero exit status. |