Annotation of src/bin/pax/pax.1, Revision 1.71
1.71 ! gutterid 1: .\" $NetBSD: pax.1,v 1.70 2019/03/19 00:12:08 gutteridge Exp $
1.3 cgd 2: .\"
1.45 agc 3: .\" Copyright (c) 1992 Keith Muller.
1.1 jtc 4: .\" Copyright (c) 1992, 1993
5: .\" The Regents of the University of California. All rights reserved.
1.44 agc 6: .\"
7: .\" This code is derived from software contributed to Berkeley by
8: .\" Keith Muller of the University of California, San Diego.
9: .\"
10: .\" Redistribution and use in source and binary forms, with or without
11: .\" modification, are permitted provided that the following conditions
12: .\" are met:
13: .\" 1. Redistributions of source code must retain the above copyright
14: .\" notice, this list of conditions and the following disclaimer.
15: .\" 2. Redistributions in binary form must reproduce the above copyright
16: .\" notice, this list of conditions and the following disclaimer in the
17: .\" documentation and/or other materials provided with the distribution.
18: .\" 3. Neither the name of the University nor the names of its contributors
1.1 jtc 19: .\" may be used to endorse or promote products derived from this software
20: .\" without specific prior written permission.
21: .\"
22: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
23: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
26: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
28: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
29: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
31: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32: .\" SUCH DAMAGE.
33: .\"
1.3 cgd 34: .\" @(#)pax.1 8.4 (Berkeley) 4/18/94
1.1 jtc 35: .\"
1.70 gutterid 36: .Dd March 19, 2019
1.1 jtc 37: .Dt PAX 1
1.17 garbled 38: .Os
1.1 jtc 39: .Sh NAME
40: .Nm pax
41: .Nd read and write file archives and copy directory hierarchies
42: .Sh SYNOPSIS
1.39 wiz 43: .Nm
1.55 wiz 44: .Op Fl 0cdjnOVvz
1.10 mycroft 45: .Op Fl E Ar limit
1.1 jtc 46: .Op Fl f Ar archive
1.30 lukem 47: .Op Fl N Ar dbdir
1.1 jtc 48: .Op Fl s Ar replstr
1.10 mycroft 49: .Ar ...\&
1.1 jtc 50: .Op Fl U Ar user
1.10 mycroft 51: .Ar ...\&
1.1 jtc 52: .Op Fl G Ar group
1.10 mycroft 53: .Ar ...\&
1.1 jtc 54: .Oo
55: .Fl T
1.54 hira 56: .Sm off
1.1 jtc 57: .Op Ar from_date
1.14 mycroft 58: .Oo , Ar to_date Oc
59: .Sm on
1.1 jtc 60: .Oc
1.10 mycroft 61: .Ar ...\&
62: .Op Ar pattern ...\&
1.39 wiz 63: .Nm
1.1 jtc 64: .Fl r
1.55 wiz 65: .Op Fl AcDdijknOuVvYZz
1.10 mycroft 66: .Op Fl E Ar limit
1.1 jtc 67: .Op Fl f Ar archive
1.30 lukem 68: .Op Fl N Ar dbdir
1.1 jtc 69: .Op Fl o Ar options
1.10 mycroft 70: .Ar ...\&
1.1 jtc 71: .Op Fl p Ar string
1.10 mycroft 72: .Ar ...\&
1.1 jtc 73: .Op Fl s Ar replstr
1.10 mycroft 74: .Ar ...\&
1.1 jtc 75: .Op Fl U Ar user
1.10 mycroft 76: .Ar ...\&
1.1 jtc 77: .Op Fl G Ar group
1.10 mycroft 78: .Ar ...\&
1.1 jtc 79: .Oo
80: .Fl T
1.54 hira 81: .Sm off
1.1 jtc 82: .Op Ar from_date
1.14 mycroft 83: .Oo , Ar to_date Oc
84: .Sm on
1.1 jtc 85: .Oc
1.10 mycroft 86: .Ar ...\&
87: .Op Ar pattern ...\&
1.39 wiz 88: .Nm
1.1 jtc 89: .Fl w
1.55 wiz 90: .Op Fl AdHijLMOPtuVvXz
1.1 jtc 91: .Op Fl b Ar blocksize
92: .Oo
93: .Op Fl a
94: .Op Fl f Ar archive
95: .Oc
96: .Op Fl x Ar format
1.10 mycroft 97: .Op Fl B Ar bytes
1.30 lukem 98: .Op Fl N Ar dbdir
1.1 jtc 99: .Op Fl o Ar options
1.10 mycroft 100: .Ar ...\&
101: .Op Fl s Ar replstr
102: .Ar ...\&
1.1 jtc 103: .Op Fl U Ar user
1.10 mycroft 104: .Ar ...\&
1.1 jtc 105: .Op Fl G Ar group
1.10 mycroft 106: .Ar ...\&
1.1 jtc 107: .Oo
108: .Fl T
1.54 hira 109: .Sm off
1.1 jtc 110: .Op Ar from_date
1.14 mycroft 111: .Oo , Ar to_date Oc
112: .Oo /[ Cm c ] [ Cm m ] Oc
1.13 mycroft 113: .Sm on
1.1 jtc 114: .Oc
1.10 mycroft 115: .Ar ...\&
116: .Op Ar file ...\&
1.39 wiz 117: .Nm
1.1 jtc 118: .Fl r
119: .Fl w
1.55 wiz 120: .Op Fl ADdHijkLlMnOPtuVvXYZz
1.30 lukem 121: .Op Fl N Ar dbdir
1.1 jtc 122: .Op Fl p Ar string
1.10 mycroft 123: .Ar ...\&
1.1 jtc 124: .Op Fl s Ar replstr
1.10 mycroft 125: .Ar ...\&
1.1 jtc 126: .Op Fl U Ar user
1.10 mycroft 127: .Ar ...\&
1.1 jtc 128: .Op Fl G Ar group
1.10 mycroft 129: .Ar ...\&
1.1 jtc 130: .Oo
131: .Fl T
1.54 hira 132: .Sm off
1.1 jtc 133: .Op Ar from_date
1.14 mycroft 134: .Oo , Ar to_date Oc
135: .Oo /[ Cm c ] [ Cm m ] Oc
1.13 mycroft 136: .Sm on
1.1 jtc 137: .Oc
1.10 mycroft 138: .Ar ...\&
139: .Op Ar file ...\&
1.1 jtc 140: .Ar directory
141: .Sh DESCRIPTION
1.5 lukem 142: .Nm
1.1 jtc 143: will read, write, and list the members of an archive file,
144: and will copy directory hierarchies.
1.38 wiz 145: If the archive file is of the form:
1.35 christos 146: .Ar [[user@]host:]file
147: then the archive will be processed using
148: .Xr rmt 8 .
149: .Pp
1.5 lukem 150: .Nm
1.1 jtc 151: operation is independent of the specific archive format,
152: and supports a wide variety of different archive formats.
153: A list of supported archive formats can be found under the description of the
154: .Fl x
155: option.
156: .Pp
157: The presence of the
158: .Fl r
159: and the
160: .Fl w
161: options specifies which of the following functional modes
1.5 lukem 162: .Nm
1.1 jtc 163: will operate under:
164: .Em list , read , write ,
165: and
1.19 enami 166: .Em copy .
1.1 jtc 167: .Bl -tag -width 6n
1.15 mycroft 168: .It Aq none
1.1 jtc 169: .Em List .
1.5 lukem 170: .Nm
1.1 jtc 171: will write to
172: .Dv standard output
173: a table of contents of the members of the archive file read from
174: .Dv standard input ,
175: whose pathnames match the specified
1.19 enami 176: .Ar patterns .
1.1 jtc 177: The table of contents contains one filename per line
178: and is written using single line buffering.
179: .It Fl r
180: .Em Read .
1.5 lukem 181: .Nm
1.1 jtc 182: extracts the members of the archive file read from the
183: .Dv standard input ,
1.27 wiz 184: with pathnames matching the specified
1.19 enami 185: .Ar patterns .
1.1 jtc 186: The archive format and blocking is automatically determined on input.
187: When an extracted file is a directory, the entire file hierarchy
188: rooted at that directory is extracted.
189: All extracted files are created relative to the current file hierarchy.
190: The setting of ownership, access and modification times, and file mode of
191: the extracted files are discussed in more detail under the
192: .Fl p
193: option.
194: .It Fl w
195: .Em Write .
1.5 lukem 196: .Nm
1.27 wiz 197: writes an archive containing the
1.1 jtc 198: .Ar file
199: operands to
200: .Dv standard output
201: using the specified archive format.
1.27 wiz 202: When no
1.1 jtc 203: .Ar file
1.27 wiz 204: operands are specified, a list of files to copy with one per line is read from
1.1 jtc 205: .Dv standard input .
1.27 wiz 206: When a
1.1 jtc 207: .Ar file
208: operand is also a directory, the entire file hierarchy rooted
209: at that directory will be included.
210: .It Fl r Fl w
211: .Em Copy .
1.5 lukem 212: .Nm
1.1 jtc 213: copies the
214: .Ar file
215: operands to the destination
216: .Ar directory .
1.27 wiz 217: When no
1.1 jtc 218: .Ar file
219: operands are specified, a list of files to copy with one per line is read from
220: the
221: .Dv standard input .
222: When a
223: .Ar file
224: operand is also a directory the entire file
225: hierarchy rooted at that directory will be included.
226: The effect of the
227: .Em copy
228: is as if the copied files were written to an archive file and then
229: subsequently extracted, except that there may be hard links between
230: the original and the copied files (see the
231: .Fl l
232: option below).
233: .Pp
234: .Em Warning :
235: The destination
236: .Ar directory
237: must not be one of the
238: .Ar file
239: operands or a member of a file hierarchy rooted at one of the
240: .Ar file
241: operands.
242: The result of a
243: .Em copy
244: under these conditions is unpredictable.
245: .El
246: .Pp
247: While processing a damaged archive during a
248: .Em read
249: or
250: .Em list
251: operation,
1.5 lukem 252: .Nm
1.1 jtc 253: will attempt to recover from media defects and will search through the archive
254: to locate and process the largest number of archive members possible (see the
255: .Fl E
256: option for more details on error handling).
257: .Sh OPERANDS
258: The
259: .Ar directory
260: operand specifies a destination directory pathname.
261: If the
262: .Ar directory
263: operand does not exist, or it is not writable by the user,
264: or it is not of type directory,
1.5 lukem 265: .Nm
1.1 jtc 266: will exit with a non-zero exit status.
267: .Pp
268: The
269: .Ar pattern
270: operand is used to select one or more pathnames of archive members.
271: Archive members are selected using the pattern matching notation described
272: by
273: .Xr fnmatch 3 .
1.27 wiz 274: When the
1.1 jtc 275: .Ar pattern
276: operand is not supplied, all members of the archive will be selected.
1.27 wiz 277: When a
1.1 jtc 278: .Ar pattern
279: matches a directory, the entire file hierarchy rooted at that directory will
280: be selected.
281: When a
282: .Ar pattern
283: operand does not select at least one archive member,
1.5 lukem 284: .Nm
1.1 jtc 285: will write these
286: .Ar pattern
287: operands in a diagnostic message to
288: .Dv standard error
289: and then exit with a non-zero exit status.
290: .Pp
291: The
292: .Ar file
293: operand specifies the pathname of a file to be copied or archived.
294: When a
295: .Ar file
296: operand does not select at least one archive member,
1.5 lukem 297: .Nm
1.1 jtc 298: will write these
299: .Ar file
300: operand pathnames in a diagnostic message to
301: .Dv standard error
302: and then exit with a non-zero exit status.
303: .Sh OPTIONS
304: The following options are supported:
305: .Bl -tag -width 4n
306: .It Fl r
307: Read an archive file from
308: .Dv standard input
309: and extract the specified
310: .Ar files .
311: If any intermediate directories are needed in order to extract an archive
312: member, these directories will be created as if
313: .Xr mkdir 2
314: was called with the bitwise inclusive
1.27 wiz 315: .Dv OR
1.1 jtc 316: of
317: .Dv S_IRWXU , S_IRWXG ,
318: and
1.27 wiz 319: .Dv S_IRWXO
1.1 jtc 320: as the mode argument.
321: When the selected archive format supports the specification of linked
322: files and these files cannot be linked while the archive is being extracted,
1.5 lukem 323: .Nm
1.1 jtc 324: will write a diagnostic message to
325: .Dv standard error
326: and exit with a non-zero exit status at the completion of operation.
327: .It Fl w
328: Write files to the
329: .Dv standard output
330: in the specified archive format.
331: When no
332: .Ar file
333: operands are specified,
334: .Dv standard input
335: is read for a list of pathnames with one per line without any leading or
336: trailing
337: .Aq blanks .
338: .It Fl a
339: Append
340: .Ar files
341: to the end of an archive that was previously written.
342: If an archive format is not specified with a
343: .Fl x
344: option, the format currently being used in the archive will be selected.
345: Any attempt to append to an archive in a format different from the
1.27 wiz 346: format already used in the archive will cause
1.5 lukem 347: .Nm
1.1 jtc 348: to exit immediately
349: with a non-zero exit status.
350: The blocking size used in the archive volume where writing starts
351: will continue to be used for the remainder of that archive volume.
352: .Pp
353: .Em Warning :
354: Many storage devices are not able to support the operations necessary
355: to perform an append operation.
356: Any attempt to append to an archive stored on such a device may damage the
357: archive or have other unpredictable results.
358: Tape drives in particular are more likely to not support an append operation.
359: An archive stored in a regular file system file or on a disk device will
360: usually support an append operation.
361: .It Fl b Ar blocksize
362: When
363: .Em writing
364: an archive,
365: block the output at a positive decimal integer number of
366: bytes per write to the archive file.
367: The
368: .Ar blocksize
369: must be a multiple of 512 bytes with a maximum of 32256 bytes.
370: A
371: .Ar blocksize
372: can end with
373: .Li k
374: or
375: .Li b
376: to specify multiplication by 1024 (1K) or 512, respectively.
377: A pair of
378: .Ar blocksizes
379: can be separated by
380: .Li x
381: to indicate a product.
382: A specific archive device may impose additional restrictions on the size
383: of blocking it will support.
1.27 wiz 384: When blocking is not specified, the default
1.1 jtc 385: .Ar blocksize
386: is dependent on the specific archive format being used (see the
387: .Fl x
388: option).
389: .It Fl c
390: Match all file or archive members
391: .Em except
392: those specified by the
393: .Ar pattern
394: and
395: .Ar file
396: operands.
397: .It Fl d
398: Cause files of type directory being copied or archived, or archive members of
399: type directory being extracted, to match only the directory file or archive
400: member and not the file hierarchy rooted at the directory.
401: .It Fl f Ar archive
402: Specify
403: .Ar archive
404: as the pathname of the input or output archive, overriding the default
405: .Dv standard input
406: (for
407: .Em list
408: and
409: .Em read )
410: or
411: .Dv standard output
412: (for
413: .Em write ) .
414: A single archive may span multiple files and different archive devices.
415: When required,
1.5 lukem 416: .Nm
1.1 jtc 417: will prompt for the pathname of the file or device of the next volume in the
418: archive.
419: .It Fl i
420: Interactively rename files or archive members.
421: For each archive member matching a
422: .Ar pattern
423: operand or each file matching a
424: .Ar file
425: operand,
1.5 lukem 426: .Nm
1.1 jtc 427: will prompt to
428: .Pa /dev/tty
429: giving the name of the file, its file mode and its modification time.
1.5 lukem 430: .Nm
1.1 jtc 431: will then read a line from
432: .Pa /dev/tty .
433: If this line is blank, the file or archive member is skipped.
434: If this line consists of a single period, the
435: file or archive member is processed with no modification to its name.
436: Otherwise, its name is replaced with the contents of the line.
1.5 lukem 437: .Nm
1.27 wiz 438: will immediately exit with a non-zero exit status if
439: .Aq Dv EOF
1.1 jtc 440: is encountered when reading a response or if
441: .Pa /dev/tty
442: cannot be opened for reading and writing.
1.40 christos 443: .It Fl j
444: Use
445: .Xr bzip2 1
446: for compression when reading or writing archive files.
1.1 jtc 447: .It Fl k
448: Do not overwrite existing files.
449: .It Fl l
1.34 wiz 450: Link files.
451: (The letter ell).
1.1 jtc 452: In the
453: .Em copy
1.15 mycroft 454: mode
1.16 mycroft 455: .Fl ( r
456: .Fl w ) ,
1.1 jtc 457: hard links are made between the source and destination file hierarchies
458: whenever possible.
459: .It Fl n
460: Select the first archive member that matches each
461: .Ar pattern
462: operand.
463: No more than one archive member is matched for each
464: .Ar pattern .
465: When members of type directory are matched, the file hierarchy rooted at that
466: directory is also matched (unless
1.27 wiz 467: .Fl d
1.1 jtc 468: is also specified).
469: .It Fl o Ar options
470: Information to modify the algorithm for extracting or writing archive files
471: which is specific to the archive format specified by
472: .Fl x .
473: In general,
474: .Ar options
475: take the form:
476: .Cm name=value
477: .It Fl p Ar string
478: Specify one or more file characteristic options (privileges).
479: The
480: .Ar string
481: option-argument is a string specifying file characteristics to be retained or
482: discarded on extraction.
483: The string consists of the specification characters
1.51 christos 484: .Cm a , e ,
1.24 tv 485: .Cm m , o ,
1.1 jtc 486: and
487: .Cm p .
488: Multiple characteristics can be concatenated within the same string
489: and multiple
1.27 wiz 490: .Fl p
1.1 jtc 491: options can be specified.
492: The meaning of the specification characters are as follows:
493: .Bl -tag -width 2n
494: .It Cm a
495: Do not preserve file access times.
496: By default, file access times are preserved whenever possible.
497: .It Cm e
498: .Sq Preserve everything ,
499: the user ID, group ID, file mode bits,
500: file access time, and file modification time.
501: This is intended to be used by
502: .Em root ,
503: someone with all the appropriate privileges, in order to preserve all
504: aspects of the files as they are recorded in the archive.
1.27 wiz 505: The
1.1 jtc 506: .Cm e
507: flag is the sum of the
1.27 wiz 508: .Cm o
1.1 jtc 509: and
510: .Cm p
511: flags.
1.22 mycroft 512: .\" .It Cm f
513: .\" Do not preserve file flags.
514: .\" By default, file flags are preserved whenever possible.
1.1 jtc 515: .It Cm m
516: Do not preserve file modification times.
517: By default, file modification times are preserved whenever possible.
518: .It Cm o
519: Preserve the user ID and group ID.
520: .It Cm p
521: .Sq Preserve
522: the file mode bits.
1.42 wiz 523: This is intended to be used by a
1.27 wiz 524: .Em user
1.1 jtc 525: with regular privileges who wants to preserve all aspects of the file other
526: than the ownership.
527: The file times are preserved by default, but two other flags are offered to
528: disable this and use the time of extraction instead.
529: .El
530: .Pp
531: In the preceding list,
532: .Sq preserve
533: indicates that an attribute stored in the archive is given to the
534: extracted file, subject to the permissions of the invoking
535: process.
536: Otherwise the attribute of the extracted file is determined as
537: part of the normal file creation action.
1.27 wiz 538: If neither the
1.1 jtc 539: .Cm e
540: nor the
541: .Cm o
542: specification character is specified, or the user ID and group ID are not
543: preserved for any reason,
1.5 lukem 544: .Nm
1.1 jtc 545: will not set the
1.27 wiz 546: .Dv S_ISUID
1.1 jtc 547: .Em ( setuid )
548: and
549: .Dv S_ISGID
550: .Em ( setgid )
551: bits of the file mode.
552: If the preservation of any of these items fails for any reason,
1.5 lukem 553: .Nm
1.1 jtc 554: will write a diagnostic message to
555: .Dv standard error .
556: Failure to preserve these items will affect the final exit status,
557: but will not cause the extracted file to be deleted.
558: If the file characteristic letters in any of the string option-arguments are
559: duplicated or conflict with each other, the one(s) given last will take
560: precedence.
561: For example, if
562: .Dl Fl p Ar eme
563: is specified, file modification times are still preserved.
564: .It Fl s Ar replstr
565: Modify the file or archive member names specified by the
566: .Ar pattern
567: or
568: .Ar file
569: operands according to the substitution expression
570: .Ar replstr ,
571: using the syntax of the
572: .Xr ed 1
573: utility regular expressions.
574: The format of these regular expressions are:
1.70 gutterid 575: .Dl /old/new/[gps]
1.1 jtc 576: As in
577: .Xr ed 1 ,
578: .Cm old
579: is a basic regular expression and
580: .Cm new
1.69 wiz 581: can contain an ampersand (&), \en (where n is a digit) back-references,
1.1 jtc 582: or subexpression matching.
583: The
584: .Cm old
585: string may also contain
1.27 wiz 586: .Aq Dv newline
1.1 jtc 587: characters.
1.71 ! gutterid 588: Any non-null character except a backslash (\\) can be used as a delimiter
! 589: (/ is shown here).
1.1 jtc 590: Multiple
591: .Fl s
592: expressions can be specified.
593: The expressions are applied in the order they are specified on the
594: command line, terminating with the first successful substitution.
595: The optional trailing
596: .Cm g
597: continues to apply the substitution expression to the pathname substring
598: which starts with the first character following the end of the last successful
1.34 wiz 599: substitution.
600: The first unsuccessful substitution stops the operation of the
1.1 jtc 601: .Cm g
602: option.
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:
1.69 wiz 608: .Dl Ao "original pathname" Ac >> Ao "new pathname" Ac
1.1 jtc 609: File or archive member names that substitute to the empty string
610: are not selected and will be skipped.
1.70 gutterid 611: The substitutions are applied by default to the destination hard and symbolic
612: links.
613: The optional trailing
614: .Cm s
615: prevents the substitutions from being performed on symbolic link destinations.
1.1 jtc 616: .It Fl t
617: Reset the access times of any file or directory read or accessed by
1.5 lukem 618: .Nm
1.1 jtc 619: to be the same as they were before being read or accessed by
1.39 wiz 620: .Nm ,
1.25 kleink 621: if the user has the appropriate permissions required by
622: .Xr utime 3 .
1.1 jtc 623: .It Fl u
624: Ignore files that are older (having a less recent file modification time)
625: than a pre-existing file or archive member with the same name.
626: During
627: .Em read ,
628: an archive member with the same name as a file in the file system will be
629: extracted if the archive member is newer than the file.
630: During
631: .Em write ,
632: a file system member with the same name as an archive member will be
633: written to the archive if it is newer than the archive member.
634: During
635: .Em copy ,
636: the file in the destination hierarchy is replaced by the file in the source
637: hierarchy or by a link to the file in the source hierarchy if the file in
638: the source hierarchy is newer.
639: .It Fl v
640: During a
641: .Em list
642: operation, produce a verbose table of contents using the format of the
643: .Xr ls 1
644: utility with the
645: .Fl l
646: option.
647: For pathnames representing a hard link to a previous member of the archive,
648: the output has the format:
1.15 mycroft 649: .Dl Ao "ls -l listing" Ac == Ao "link name" Ac
650: Where
651: .Aq "ls -l listing"
1.27 wiz 652: is the output format specified by the
1.1 jtc 653: .Xr ls 1
654: utility when used with the
655: .Fl l
656: option.
1.52 christos 657: .Pp
1.15 mycroft 658: Otherwise for all the other operational modes
1.16 mycroft 659: .Em ( read , write ,
1.1 jtc 660: and
1.16 mycroft 661: .Em copy ) ,
1.1 jtc 662: pathnames are written and flushed to
663: .Dv standard error
664: without a trailing
1.27 wiz 665: .Aq Dv newline
1.1 jtc 666: as soon as processing begins on that file or
667: archive member.
668: The trailing
1.27 wiz 669: .Aq Dv newline ,
1.1 jtc 670: is not buffered, and is written only after the file has been read or written.
1.52 christos 671: .Pp
672: A final summary of archive operations is printed after they have been
673: completed.
1.1 jtc 674: .It Fl x Ar format
675: Specify the output archive format, with the default format being
676: .Ar ustar .
1.5 lukem 677: .Nm
1.1 jtc 678: currently supports the following formats:
679: .Bl -tag -width "sv4cpio"
680: .It Ar cpio
681: The extended cpio interchange format specified in the
682: .St -p1003.2
683: standard.
684: The default blocksize for this format is 5120 bytes.
685: Inode and device information about a file (used for detecting file hard links
686: by this format) which may be truncated by this format is detected by
1.5 lukem 687: .Nm
1.1 jtc 688: and is repaired.
689: .It Ar bcpio
690: The old binary cpio format.
691: The default blocksize for this format is 5120 bytes.
692: This format is not very portable and should not be used when other formats
693: are available.
694: Inode and device information about a file (used for detecting file hard links
695: by this format) which may be truncated by this format is detected by
1.5 lukem 696: .Nm
1.1 jtc 697: and is repaired.
698: .It Ar sv4cpio
1.8 perry 699: The
700: .At V.4
701: cpio.
1.1 jtc 702: The default blocksize for this format is 5120 bytes.
703: Inode and device information about a file (used for detecting file hard links
704: by this format) which may be truncated by this format is detected by
1.5 lukem 705: .Nm
1.1 jtc 706: and is repaired.
707: .It Ar sv4crc
1.8 perry 708: The
709: .At V.4
710: cpio with file crc checksums.
1.1 jtc 711: The default blocksize for this format is 5120 bytes.
712: Inode and device information about a file (used for detecting file hard links
713: by this format) which may be truncated by this format is detected by
1.5 lukem 714: .Nm
1.1 jtc 715: and is repaired.
716: .It Ar tar
1.8 perry 717: The old
718: .Bx
1.27 wiz 719: tar format as found in
1.8 perry 720: .Bx 4.3 .
1.1 jtc 721: The default blocksize for this format is 10240 bytes.
722: Pathnames stored by this format must be 100 characters or less in length.
723: Only
724: .Em regular
725: files,
726: .Em hard links , soft links ,
727: and
728: .Em directories
1.48 grant 729: will be archived (other file types are not supported).
730: For backward compatibility with even older tar formats, a
1.1 jtc 731: .Fl o
732: option can be used when writing an archive to omit the storage of directories.
733: This option takes the form:
734: .Dl Fl o Cm write_opt=nodir
735: .It Ar ustar
736: The extended tar interchange format specified in the
737: .St -p1003.2
738: standard.
739: The default blocksize for this format is 10240 bytes.
740: Pathnames stored by this format must be 250 characters or less in length.
741: .El
742: .Pp
1.5 lukem 743: .Nm
1.1 jtc 744: will detect and report any file that it is unable to store or extract
745: as the result of any specific archive format restrictions.
746: The individual archive formats may impose additional restrictions on use.
747: Typical archive format restrictions include (but are not limited to):
748: file pathname length, file size, link pathname length and the type of the file.
1.62 christos 749: .It Fl Fl gnu
1.63 wiz 750: Recognize GNU tar extensions.
1.66 christos 751: .It Fl Fl timestamp Ar timestamp
752: Store all modification times in the archive with the
753: .Ar timestamp
754: given instead of the actual modification time of the individual archive member
755: so that repeatable builds are possible.
1.67 wiz 756: The
1.66 christos 757: .Ar timestamp
758: can be a
759: .Pa pathname ,
760: where the timestamps are derived from that file, a parseable date for
761: .Xr parsedate 3
762: (this option is not yet available in the tools build), or an integer value
763: interpreted as the number of seconds from the Epoch.
1.61 wiz 764: .It Fl Fl xz
765: Use
766: .Xr xz 1
767: compression, when reading or writing archive files.
1.9 mrg 768: .It Fl z
769: Use
770: .Xr gzip 1
771: compression, when reading or writing archive files.
1.18 tron 772: .It Fl A
773: Do not strip leading `/'s from file names.
1.1 jtc 774: .It Fl B Ar bytes
775: Limit the number of bytes written to a single archive volume to
776: .Ar bytes .
777: The
778: .Ar bytes
779: limit can end with
780: .Li m ,
781: .Li k ,
782: or
783: .Li b
784: to specify multiplication by 1048576 (1M), 1024 (1K) or 512, respectively.
785: A pair of
786: .Ar bytes
787: limits can be separated by
788: .Li x
789: to indicate a product.
790: .Pp
791: .Em Warning :
792: Only use this option when writing an archive to a device which supports
793: an end of file read condition based on last (or largest) write offset
1.27 wiz 794: (such as a regular file or a tape drive).
1.1 jtc 795: The use of this option with a floppy or hard disk is not recommended.
796: .It Fl D
797: This option is the same as the
798: .Fl u
799: option, except that the file inode change time is checked instead of the
800: file modification time.
801: The file inode change time can be used to select files whose inode information
802: (e.g. uid, gid, etc.) is newer than a copy of the file in the destination
803: .Ar directory .
804: .It Fl E Ar limit
805: Limit the number of consecutive read faults while trying to read a flawed
806: archives to
807: .Ar limit .
808: With a positive
809: .Ar limit ,
1.5 lukem 810: .Nm
1.1 jtc 811: will attempt to recover from an archive read error and will
812: continue processing starting with the next file stored in the archive.
813: A
814: .Ar limit
815: of 0 will cause
1.5 lukem 816: .Nm
1.1 jtc 817: to stop operation after the first read error is detected on an archive volume.
818: A
819: .Ar limit
820: of
821: .Li NONE
822: will cause
1.5 lukem 823: .Nm
1.1 jtc 824: to attempt to recover from read errors forever.
1.27 wiz 825: The default
1.1 jtc 826: .Ar limit
827: is a small positive number of retries.
828: .Pp
1.27 wiz 829: .Em Warning :
1.1 jtc 830: Using this option with
831: .Li NONE
832: should be used with extreme caution as
1.5 lukem 833: .Nm
1.1 jtc 834: may get stuck in an infinite loop on a very badly flawed archive.
835: .It Fl G Ar group
836: Select a file based on its
837: .Ar group
838: name, or when starting with a
839: .Cm # ,
840: a numeric gid.
1.57 joerg 841: A '\e' can be used to escape the
1.1 jtc 842: .Cm # .
1.27 wiz 843: Multiple
1.1 jtc 844: .Fl G
845: options may be supplied and checking stops with the first match.
846: .It Fl H
847: Follow only command line symbolic links while performing a physical file
848: system traversal.
849: .It Fl L
850: Follow all symbolic links to perform a logical file system traversal.
1.26 lukem 851: .It Fl M
852: During a
853: .Em write
854: or
855: .Em copy
856: operation, treat the list of files on
857: .Dv standard input
858: as an
859: .Xr mtree 8
860: .Sq specfile
861: specification, and write or copy only those items in the specfile.
862: .Pp
863: If the file exists in the underlying file system, its permissions and
864: modification time will be used unless specifically overridden by the specfile.
865: An error will be raised if the type of entry in the specfile conflicts
866: with that of an existing file.
1.32 lukem 867: A directory entry that is marked
868: .Sq Sy optional
1.33 wiz 869: will not be copied (even though its contents will be).
1.32 lukem 870: .Pp
871: Otherwise, the entry will be
872: .Sq faked-up ,
873: and it is necessary to specify at least the following parameters
1.26 lukem 874: in the specfile:
875: .Sy type ,
876: .Sy mode ,
877: .Sy gname
878: or
879: .Sy gid ,
880: and
881: .Sy uname
882: or
883: .Sy uid ,
884: .Sy device
885: (in the case of block or character devices), and
886: .Sy link
887: (in the case of symbolic links).
888: If
889: .Sy time
890: isn't provided, the current time will be used.
1.32 lukem 891: A
892: .Sq faked-up
893: entry that is marked
894: .Sq Sy optional
895: will not be copied.
1.30 lukem 896: .It Fl N Ar dbdir
897: Except for lookups for the
898: .Fl G
899: and
900: .Fl U
901: options,
902: use the user database text file
903: .Pa master.passwd
904: and group database text file
905: .Pa group
906: from
907: .Ar dbdir ,
908: rather than using the results from the system's
909: .Xr getpwnam 3
910: and
911: .Xr getgrnam 3
912: (and related) library calls.
1.23 thorpej 913: .It Fl O
1.34 wiz 914: Force the archive to be one volume.
915: If a volume ends prematurely,
1.23 thorpej 916: .Nm
1.34 wiz 917: will not prompt for a new volume.
918: This option can be useful for
1.23 thorpej 919: automated tasks where error recovery cannot be performed by a human.
1.1 jtc 920: .It Fl P
921: Do not follow symbolic links, perform a physical file system traversal.
922: This is the default mode.
923: .It Fl T Ar [from_date][,to_date][/[c][m]]
924: Allow files to be selected based on a file modification or inode change
1.27 wiz 925: time falling within a specified time range of
1.1 jtc 926: .Ar from_date
927: to
928: .Ar to_date
929: (the dates are inclusive).
1.27 wiz 930: If only a
1.1 jtc 931: .Ar from_date
932: is supplied, all files with a modification or inode change time
933: equal to or younger are selected.
934: If only a
935: .Ar to_date
936: is supplied, all files with a modification or inode change time
937: equal to or older will be selected.
1.27 wiz 938: When the
1.1 jtc 939: .Ar from_date
940: is equal to the
941: .Ar to_date ,
942: only files with a modification or inode change time of exactly that
943: time will be selected.
944: .Pp
945: When
1.5 lukem 946: .Nm
1.27 wiz 947: is in the
1.1 jtc 948: .Em write
949: or
950: .Em copy
951: mode, the optional trailing field
952: .Ar [c][m]
953: can be used to determine which file time (inode change, file modification or
954: both) are used in the comparison.
955: If neither is specified, the default is to use file modification time only.
956: The
957: .Ar m
958: specifies the comparison of file modification time (the time when
959: the file was last written).
960: The
961: .Ar c
962: specifies the comparison of inode change time (the time when the file
963: inode was last changed; e.g. a change of owner, group, mode, etc).
1.27 wiz 964: When
1.1 jtc 965: .Ar c
966: and
967: .Ar m
968: are both specified, then the modification and inode change times are
969: both compared.
970: The inode change time comparison is useful in selecting files whose
971: attributes were recently changed or selecting files which were recently
972: created and had their modification time reset to an older time (as what
973: happens when a file is extracted from an archive and the modification time
974: is preserved).
975: Time comparisons using both file times is useful when
1.5 lukem 976: .Nm
1.1 jtc 977: is used to create a time based incremental archive (only files that were
978: changed during a specified time range will be archived).
979: .Pp
1.64 pgoyette 980: A time range is made up of seven different fields and each field must contain
981: two digits.
1.1 jtc 982: The format is:
1.7 mycroft 983: .Dl [[[[[cc]yy]mm]dd]hh]mm[\&.ss]
1.64 pgoyette 984: where
1.7 mycroft 985: .Cm cc
986: is the first two digits of the year (the century),
1.1 jtc 987: .Cm yy
988: is the last two digits of the year,
989: the first
990: .Cm mm
991: is the month (from 01 to 12),
992: .Cm dd
993: is the day of the month (from 01 to 31),
994: .Cm hh
995: is the hour of the day (from 00 to 23),
996: the second
997: .Cm mm
998: is the minute (from 00 to 59),
999: and
1000: .Cm ss
1.7 mycroft 1001: is the seconds (from 00 to 61).
1002: Only the minute field
1.1 jtc 1003: .Cm mm
1.7 mycroft 1004: is required; the others will default to the current system values.
1.27 wiz 1005: The
1.1 jtc 1006: .Cm ss
1007: field may be added independently of the other fields.
1.7 mycroft 1008: If the century is not specified, it defaults to 1900 for
1009: years between 69 and 99, or 2000 for years between 0 and 68.
1.1 jtc 1010: Time ranges are relative to the current time, so
1011: .Dl Fl T Ar 1234/cm
1012: would select all files with a modification or inode change time
1013: of 12:34 PM today or later.
1.27 wiz 1014: Multiple
1.1 jtc 1015: .Fl T
1016: time range can be supplied and checking stops with the first match.
1017: .It Fl U Ar user
1018: Select a file based on its
1019: .Ar user
1020: name, or when starting with a
1021: .Cm # ,
1022: a numeric uid.
1.57 joerg 1023: A '\e' can be used to escape the
1.1 jtc 1024: .Cm # .
1.27 wiz 1025: Multiple
1.1 jtc 1026: .Fl U
1027: options may be supplied and checking stops with the first match.
1.52 christos 1028: .It Fl V
1029: A final summary of archive operations is printed after they have been
1.55 wiz 1030: completed.
1031: Some potentially long-running tape operations are noted.
1.1 jtc 1032: .It Fl X
1033: When traversing the file hierarchy specified by a pathname,
1034: do not descend into directories that have a different device ID.
1035: See the
1.27 wiz 1036: .Li st_dev
1.1 jtc 1037: field as described in
1038: .Xr stat 2
1039: for more information about device ID's.
1040: .It Fl Y
1041: This option is the same as the
1042: .Fl D
1043: option, except that the inode change time is checked using the
1044: pathname created after all the file name modifications have completed.
1045: .It Fl Z
1046: This option is the same as the
1047: .Fl u
1048: option, except that the modification time is checked using the
1049: pathname created after all the file name modifications have completed.
1.49 christos 1050: .It Fl 0
1051: Use the nul character instead of \en as the file separator when reading
1052: files from standard input.
1.59 wiz 1053: .It Fl Fl force-local
1.36 christos 1054: Do not interpret filenames that contain a `:' as remote files.
1.59 wiz 1055: .It Fl Fl insecure
1.36 christos 1056: Normally
1057: .Nm
1.55 wiz 1058: ignores filenames that contain
1059: .Dq ..
1060: as a path component.
1061: With this option,
1062: files that contain
1063: .Dq ..
1064: can be processed.
1.59 wiz 1065: .It Fl Fl use-compress-program
1.58 christos 1066: Use the named program as the program to decompress the input or compress
1067: the output.
1.1 jtc 1068: .El
1069: .Pp
1.15 mycroft 1070: The options that operate on the names of files or archive members
1.16 mycroft 1071: .Fl ( c ,
1.1 jtc 1072: .Fl i ,
1073: .Fl n ,
1074: .Fl s ,
1075: .Fl u ,
1076: .Fl v ,
1077: .Fl D ,
1078: .Fl G ,
1079: .Fl T ,
1080: .Fl U ,
1081: .Fl Y ,
1082: and
1.16 mycroft 1083: .Fl Z )
1.1 jtc 1084: interact as follows.
1085: .Pp
1086: When extracting files during a
1087: .Em read
1088: operation, archive members are
1089: .Sq selected ,
1090: based only on the user specified pattern operands as modified by the
1091: .Fl c ,
1092: .Fl n ,
1093: .Fl u ,
1094: .Fl D ,
1095: .Fl G ,
1096: .Fl T ,
1097: .Fl U
1098: options.
1099: Then any
1100: .Fl s
1101: and
1102: .Fl i
1103: options will modify in that order, the names of these selected files.
1104: Then the
1105: .Fl Y
1106: and
1107: .Fl Z
1108: options will be applied based on the final pathname.
1.27 wiz 1109: Finally the
1.1 jtc 1110: .Fl v
1111: option will write the names resulting from these modifications.
1112: .Pp
1113: When archiving files during a
1114: .Em write
1115: operation, or copying files during a
1116: .Em copy
1117: operation, archive members are
1118: .Sq selected ,
1119: based only on the user specified pathnames as modified by the
1120: .Fl n ,
1121: .Fl u ,
1122: .Fl D ,
1123: .Fl G ,
1124: .Fl T ,
1.27 wiz 1125: and
1.1 jtc 1126: .Fl U
1127: options (the
1128: .Fl D
1129: option only applies during a copy operation).
1130: Then any
1.27 wiz 1131: .Fl s
1.1 jtc 1132: and
1133: .Fl i
1134: options will modify in that order, the names of these selected files.
1135: Then during a
1136: .Em copy
1137: operation the
1138: .Fl Y
1139: and the
1140: .Fl Z
1141: options will be applied based on the final pathname.
1142: Finally the
1143: .Fl v
1144: option will write the names resulting from these modifications.
1145: .Pp
1146: When one or both of the
1147: .Fl u
1148: or
1149: .Fl D
1150: options are specified along with the
1151: .Fl n
1152: option, a file is not considered selected unless it is newer
1153: than the file to which it is compared.
1.50 wiz 1154: .Sh EXIT STATUS
1155: .Nm
1156: will exit with one of the following values:
1157: .Bl -tag -width 2n
1158: .It 0
1159: All files were processed successfully.
1160: .It 1
1161: An error occurred.
1162: .El
1163: .Pp
1164: Whenever
1165: .Nm
1166: cannot create a file or a link when reading an archive or cannot
1167: find a file when writing an archive, or cannot preserve the user ID,
1168: group ID, or file mode when the
1169: .Fl p
1170: option is specified, a diagnostic message is written to
1171: .Dv standard error
1172: and a non-zero exit status will be returned, but processing will continue.
1173: In the case where pax cannot create a link to a file,
1174: .Nm
1175: will not create a second copy of the file.
1176: .Pp
1177: If the extraction of a file from an archive is prematurely terminated by
1178: a signal or error,
1179: .Nm
1180: may have only partially extracted a file the user wanted.
1181: Additionally, the file modes of extracted files and directories
1182: may have incorrect file bits, and the modification and access times may be
1183: wrong.
1184: .Pp
1185: If the creation of an archive is prematurely terminated by a signal or error,
1186: .Nm
1187: may have only partially created the archive which may violate the specific
1188: archive format specification.
1189: .Pp
1190: If while doing a
1191: .Em copy ,
1192: .Nm
1193: detects a file is about to overwrite itself, the file is not copied,
1194: a diagnostic message is written to
1195: .Dv standard error
1196: and when
1197: .Nm
1198: completes it will exit with a non-zero exit status.
1.1 jtc 1199: .Sh EXAMPLES
1200: The command:
1.27 wiz 1201: .Dl pax -w -f /dev/rst0 \&.
1.1 jtc 1202: copies the contents of the current directory to the device
1203: .Pa /dev/rst0 .
1204: .Pp
1205: The command:
1.4 pk 1206: .Dl pax -v -f filename
1.1 jtc 1207: gives the verbose table of contents for an archive stored in
1208: .Pa filename .
1209: .Pp
1210: The following commands:
1211: .Dl mkdir newdir
1212: .Dl cd olddir
1.28 hubertf 1213: .Dl pax -rw -pp .\ ../newdir
1.1 jtc 1214: will copy the entire
1215: .Pa olddir
1216: directory hierarchy to
1.28 hubertf 1217: .Pa newdir ,
1.29 hubertf 1218: preserving permissions and access times.
1219: .Pp
1220: When running as root, one may also wish to preserve file
1.34 wiz 1221: ownership when copying directory trees.
1222: This can be done with the following commands:
1.29 hubertf 1223: .Dl cd olddir
1.56 christos 1224: .Dl pax -rw -pe .\ ../newdir
1.29 hubertf 1225: which will copy the contents of
1226: .Pa olddir
1227: into
1.56 christos 1228: .Pa ../newdir ,
1.29 hubertf 1229: preserving ownership, permissions and access times.
1.1 jtc 1230: .Pp
1231: The command:
1232: .Dl pax -r -s ',^//*usr//*,,' -f a.pax
1.27 wiz 1233: reads the archive
1.1 jtc 1234: .Pa a.pax ,
1235: with all files rooted in ``/usr'' into the archive extracted relative to the
1236: current directory.
1237: .Pp
1238: The command:
1239: .Dl pax -rw -i .\ dest_dir
1240: can be used to interactively select the files to copy from the current
1241: directory to
1242: .Pa dest_dir .
1243: .Pp
1244: The command:
1245: .Dl pax -r -pe -U root -G bin -f a.pax
1246: will extract all files from the archive
1247: .Pa a.pax
1248: which are owned by
1249: .Em root
1250: with group
1251: .Em bin
1252: and will preserve all file permissions.
1253: .Pp
1254: The command:
1255: .Dl pax -r -w -v -Y -Z home /backup
1256: will update (and list) only those files in the destination directory
1257: .Pa /backup
1258: which are older (less recent inode change or file modification times) than
1259: files with the same name found in the source file tree
1260: .Pa home .
1.27 wiz 1261: .Sh SEE ALSO
1262: .Xr cpio 1 ,
1263: .Xr tar 1 ,
1264: .Xr symlink 7 ,
1265: .Xr mtree 8
1266: .Sh STANDARDS
1267: The
1268: .Nm
1269: utility is a superset of the
1270: .St -p1003.2
1271: standard.
1272: The options
1273: .Fl B ,
1274: .Fl D ,
1275: .Fl E ,
1276: .Fl G ,
1277: .Fl H ,
1278: .Fl L ,
1279: .Fl M ,
1280: .Fl O ,
1281: .Fl P ,
1282: .Fl T ,
1283: .Fl U ,
1284: .Fl Y ,
1285: .Fl Z ,
1.43 mrg 1286: .Fl z ,
1.27 wiz 1287: the archive formats
1288: .Ar bcpio ,
1289: .Ar sv4cpio ,
1290: .Ar sv4crc ,
1291: .Ar tar ,
1292: and the flawed archive handling during
1293: .Ar list
1294: and
1295: .Ar read
1296: operations are extensions to the
1297: .Tn POSIX
1298: standard.
1.68 sevan 1299: .Sh HISTORY
1300: A
1301: .Nm
1302: utility appeared in
1303: .Bx 4.4 .
1.27 wiz 1304: .Sh AUTHORS
1.65 wiz 1305: .An -nosplit
1306: .An Keith Muller
1307: at the University of California, San Diego.
1308: .An Luke Mewburn
1309: implemented
1.27 wiz 1310: .Fl M .
CVSweb <webmaster@jp.NetBSD.org>