Annotation of src/bin/pax/pax.1, Revision 1.61
1.61 ! wiz 1: .\" $NetBSD: pax.1,v 1.60 2011/06/19 00:55:09 christos 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.60 christos 36: .Dd June 18, 2011
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:
575: .Dl /old/new/[gp]
576: As in
577: .Xr ed 1 ,
578: .Cm old
579: is a basic regular expression and
580: .Cm new
1.57 joerg 581: can contain an ampersand (\*[Am]), \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.
588: Any non-null character can be used as a delimiter (/ is shown here).
589: Multiple
590: .Fl s
591: expressions can be specified.
592: The expressions are applied in the order they are specified on the
593: command line, terminating with the first successful substitution.
594: The optional trailing
595: .Cm g
596: continues to apply the substitution expression to the pathname substring
597: which starts with the first character following the end of the last successful
1.34 wiz 598: substitution.
599: The first unsuccessful substitution stops the operation of the
1.1 jtc 600: .Cm g
601: option.
602: The optional trailing
603: .Cm p
604: will cause the final result of a successful substitution to be written to
605: .Dv standard error
606: in the following format:
1.31 ross 607: .Dl Ao "original pathname" Ac \*[Gt]\*[Gt] Ao "new pathname" Ac
1.1 jtc 608: File or archive member names that substitute to the empty string
609: are not selected and will be skipped.
610: .It Fl t
611: Reset the access times of any file or directory read or accessed by
1.5 lukem 612: .Nm
1.1 jtc 613: to be the same as they were before being read or accessed by
1.39 wiz 614: .Nm ,
1.25 kleink 615: if the user has the appropriate permissions required by
616: .Xr utime 3 .
1.1 jtc 617: .It Fl u
618: Ignore files that are older (having a less recent file modification time)
619: than a pre-existing file or archive member with the same name.
620: During
621: .Em read ,
622: an archive member with the same name as a file in the file system will be
623: extracted if the archive member is newer than the file.
624: During
625: .Em write ,
626: a file system member with the same name as an archive member will be
627: written to the archive if it is newer than the archive member.
628: During
629: .Em copy ,
630: the file in the destination hierarchy is replaced by the file in the source
631: hierarchy or by a link to the file in the source hierarchy if the file in
632: the source hierarchy is newer.
633: .It Fl v
634: During a
635: .Em list
636: operation, produce a verbose table of contents using the format of the
637: .Xr ls 1
638: utility with the
639: .Fl l
640: option.
641: For pathnames representing a hard link to a previous member of the archive,
642: the output has the format:
1.15 mycroft 643: .Dl Ao "ls -l listing" Ac == Ao "link name" Ac
644: Where
645: .Aq "ls -l listing"
1.27 wiz 646: is the output format specified by the
1.1 jtc 647: .Xr ls 1
648: utility when used with the
649: .Fl l
650: option.
1.52 christos 651: .Pp
1.15 mycroft 652: Otherwise for all the other operational modes
1.16 mycroft 653: .Em ( read , write ,
1.1 jtc 654: and
1.16 mycroft 655: .Em copy ) ,
1.1 jtc 656: pathnames are written and flushed to
657: .Dv standard error
658: without a trailing
1.27 wiz 659: .Aq Dv newline
1.1 jtc 660: as soon as processing begins on that file or
661: archive member.
662: The trailing
1.27 wiz 663: .Aq Dv newline ,
1.1 jtc 664: is not buffered, and is written only after the file has been read or written.
1.52 christos 665: .Pp
666: A final summary of archive operations is printed after they have been
667: completed.
1.1 jtc 668: .It Fl x Ar format
669: Specify the output archive format, with the default format being
670: .Ar ustar .
1.5 lukem 671: .Nm
1.1 jtc 672: currently supports the following formats:
673: .Bl -tag -width "sv4cpio"
674: .It Ar cpio
675: The extended cpio interchange format specified in the
676: .St -p1003.2
677: standard.
678: The default blocksize for this format is 5120 bytes.
679: Inode and device information about a file (used for detecting file hard links
680: by this format) which may be truncated by this format is detected by
1.5 lukem 681: .Nm
1.1 jtc 682: and is repaired.
683: .It Ar bcpio
684: The old binary cpio format.
685: The default blocksize for this format is 5120 bytes.
686: This format is not very portable and should not be used when other formats
687: are available.
688: Inode and device information about a file (used for detecting file hard links
689: by this format) which may be truncated by this format is detected by
1.5 lukem 690: .Nm
1.1 jtc 691: and is repaired.
692: .It Ar sv4cpio
1.8 perry 693: The
694: .At V.4
695: cpio.
1.1 jtc 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
1.5 lukem 699: .Nm
1.1 jtc 700: and is repaired.
701: .It Ar sv4crc
1.8 perry 702: The
703: .At V.4
704: cpio with file crc checksums.
1.1 jtc 705: The default blocksize for this format is 5120 bytes.
706: Inode and device information about a file (used for detecting file hard links
707: by this format) which may be truncated by this format is detected by
1.5 lukem 708: .Nm
1.1 jtc 709: and is repaired.
710: .It Ar tar
1.8 perry 711: The old
712: .Bx
1.27 wiz 713: tar format as found in
1.8 perry 714: .Bx 4.3 .
1.1 jtc 715: The default blocksize for this format is 10240 bytes.
716: Pathnames stored by this format must be 100 characters or less in length.
717: Only
718: .Em regular
719: files,
720: .Em hard links , soft links ,
721: and
722: .Em directories
1.48 grant 723: will be archived (other file types are not supported).
724: For backward compatibility with even older tar formats, a
1.1 jtc 725: .Fl o
726: option can be used when writing an archive to omit the storage of directories.
727: This option takes the form:
728: .Dl Fl o Cm write_opt=nodir
729: .It Ar ustar
730: The extended tar interchange format specified in the
731: .St -p1003.2
732: standard.
733: The default blocksize for this format is 10240 bytes.
734: Pathnames stored by this format must be 250 characters or less in length.
735: .El
736: .Pp
1.5 lukem 737: .Nm
1.1 jtc 738: will detect and report any file that it is unable to store or extract
739: as the result of any specific archive format restrictions.
740: The individual archive formats may impose additional restrictions on use.
741: Typical archive format restrictions include (but are not limited to):
742: file pathname length, file size, link pathname length and the type of the file.
1.61 ! wiz 743: .It Fl Fl xz
! 744: Use
! 745: .Xr xz 1
! 746: compression, when reading or writing archive files.
1.9 mrg 747: .It Fl z
748: Use
749: .Xr gzip 1
750: compression, when reading or writing archive files.
1.18 tron 751: .It Fl A
752: Do not strip leading `/'s from file names.
1.1 jtc 753: .It Fl B Ar bytes
754: Limit the number of bytes written to a single archive volume to
755: .Ar bytes .
756: The
757: .Ar bytes
758: limit can end with
759: .Li m ,
760: .Li k ,
761: or
762: .Li b
763: to specify multiplication by 1048576 (1M), 1024 (1K) or 512, respectively.
764: A pair of
765: .Ar bytes
766: limits can be separated by
767: .Li x
768: to indicate a product.
769: .Pp
770: .Em Warning :
771: Only use this option when writing an archive to a device which supports
772: an end of file read condition based on last (or largest) write offset
1.27 wiz 773: (such as a regular file or a tape drive).
1.1 jtc 774: The use of this option with a floppy or hard disk is not recommended.
775: .It Fl D
776: This option is the same as the
777: .Fl u
778: option, except that the file inode change time is checked instead of the
779: file modification time.
780: The file inode change time can be used to select files whose inode information
781: (e.g. uid, gid, etc.) is newer than a copy of the file in the destination
782: .Ar directory .
783: .It Fl E Ar limit
784: Limit the number of consecutive read faults while trying to read a flawed
785: archives to
786: .Ar limit .
787: With a positive
788: .Ar limit ,
1.5 lukem 789: .Nm
1.1 jtc 790: will attempt to recover from an archive read error and will
791: continue processing starting with the next file stored in the archive.
792: A
793: .Ar limit
794: of 0 will cause
1.5 lukem 795: .Nm
1.1 jtc 796: to stop operation after the first read error is detected on an archive volume.
797: A
798: .Ar limit
799: of
800: .Li NONE
801: will cause
1.5 lukem 802: .Nm
1.1 jtc 803: to attempt to recover from read errors forever.
1.27 wiz 804: The default
1.1 jtc 805: .Ar limit
806: is a small positive number of retries.
807: .Pp
1.27 wiz 808: .Em Warning :
1.1 jtc 809: Using this option with
810: .Li NONE
811: should be used with extreme caution as
1.5 lukem 812: .Nm
1.1 jtc 813: may get stuck in an infinite loop on a very badly flawed archive.
814: .It Fl G Ar group
815: Select a file based on its
816: .Ar group
817: name, or when starting with a
818: .Cm # ,
819: a numeric gid.
1.57 joerg 820: A '\e' can be used to escape the
1.1 jtc 821: .Cm # .
1.27 wiz 822: Multiple
1.1 jtc 823: .Fl G
824: options may be supplied and checking stops with the first match.
825: .It Fl H
826: Follow only command line symbolic links while performing a physical file
827: system traversal.
828: .It Fl L
829: Follow all symbolic links to perform a logical file system traversal.
1.26 lukem 830: .It Fl M
831: During a
832: .Em write
833: or
834: .Em copy
835: operation, treat the list of files on
836: .Dv standard input
837: as an
838: .Xr mtree 8
839: .Sq specfile
840: specification, and write or copy only those items in the specfile.
841: .Pp
842: If the file exists in the underlying file system, its permissions and
843: modification time will be used unless specifically overridden by the specfile.
844: An error will be raised if the type of entry in the specfile conflicts
845: with that of an existing file.
1.32 lukem 846: A directory entry that is marked
847: .Sq Sy optional
1.33 wiz 848: will not be copied (even though its contents will be).
1.32 lukem 849: .Pp
850: Otherwise, the entry will be
851: .Sq faked-up ,
852: and it is necessary to specify at least the following parameters
1.26 lukem 853: in the specfile:
854: .Sy type ,
855: .Sy mode ,
856: .Sy gname
857: or
858: .Sy gid ,
859: and
860: .Sy uname
861: or
862: .Sy uid ,
863: .Sy device
864: (in the case of block or character devices), and
865: .Sy link
866: (in the case of symbolic links).
867: If
868: .Sy time
869: isn't provided, the current time will be used.
1.32 lukem 870: A
871: .Sq faked-up
872: entry that is marked
873: .Sq Sy optional
874: will not be copied.
1.30 lukem 875: .It Fl N Ar dbdir
876: Except for lookups for the
877: .Fl G
878: and
879: .Fl U
880: options,
881: use the user database text file
882: .Pa master.passwd
883: and group database text file
884: .Pa group
885: from
886: .Ar dbdir ,
887: rather than using the results from the system's
888: .Xr getpwnam 3
889: and
890: .Xr getgrnam 3
891: (and related) library calls.
1.23 thorpej 892: .It Fl O
1.34 wiz 893: Force the archive to be one volume.
894: If a volume ends prematurely,
1.23 thorpej 895: .Nm
1.34 wiz 896: will not prompt for a new volume.
897: This option can be useful for
1.23 thorpej 898: automated tasks where error recovery cannot be performed by a human.
1.1 jtc 899: .It Fl P
900: Do not follow symbolic links, perform a physical file system traversal.
901: This is the default mode.
902: .It Fl T Ar [from_date][,to_date][/[c][m]]
903: Allow files to be selected based on a file modification or inode change
1.27 wiz 904: time falling within a specified time range of
1.1 jtc 905: .Ar from_date
906: to
907: .Ar to_date
908: (the dates are inclusive).
1.27 wiz 909: If only a
1.1 jtc 910: .Ar from_date
911: is supplied, all files with a modification or inode change time
912: equal to or younger are selected.
913: If only a
914: .Ar to_date
915: is supplied, all files with a modification or inode change time
916: equal to or older will be selected.
1.27 wiz 917: When the
1.1 jtc 918: .Ar from_date
919: is equal to the
920: .Ar to_date ,
921: only files with a modification or inode change time of exactly that
922: time will be selected.
923: .Pp
924: When
1.5 lukem 925: .Nm
1.27 wiz 926: is in the
1.1 jtc 927: .Em write
928: or
929: .Em copy
930: mode, the optional trailing field
931: .Ar [c][m]
932: can be used to determine which file time (inode change, file modification or
933: both) are used in the comparison.
934: If neither is specified, the default is to use file modification time only.
935: The
936: .Ar m
937: specifies the comparison of file modification time (the time when
938: the file was last written).
939: The
940: .Ar c
941: specifies the comparison of inode change time (the time when the file
942: inode was last changed; e.g. a change of owner, group, mode, etc).
1.27 wiz 943: When
1.1 jtc 944: .Ar c
945: and
946: .Ar m
947: are both specified, then the modification and inode change times are
948: both compared.
949: The inode change time comparison is useful in selecting files whose
950: attributes were recently changed or selecting files which were recently
951: created and had their modification time reset to an older time (as what
952: happens when a file is extracted from an archive and the modification time
953: is preserved).
954: Time comparisons using both file times is useful when
1.5 lukem 955: .Nm
1.1 jtc 956: is used to create a time based incremental archive (only files that were
957: changed during a specified time range will be archived).
958: .Pp
959: A time range is made up of six different fields and each field must contain two
960: digits.
961: The format is:
1.7 mycroft 962: .Dl [[[[[cc]yy]mm]dd]hh]mm[\&.ss]
1.1 jtc 963: Where
1.7 mycroft 964: .Cm cc
965: is the first two digits of the year (the century),
1.1 jtc 966: .Cm yy
967: is the last two digits of the year,
968: the first
969: .Cm mm
970: is the month (from 01 to 12),
971: .Cm dd
972: is the day of the month (from 01 to 31),
973: .Cm hh
974: is the hour of the day (from 00 to 23),
975: the second
976: .Cm mm
977: is the minute (from 00 to 59),
978: and
979: .Cm ss
1.7 mycroft 980: is the seconds (from 00 to 61).
981: Only the minute field
1.1 jtc 982: .Cm mm
1.7 mycroft 983: is required; the others will default to the current system values.
1.27 wiz 984: The
1.1 jtc 985: .Cm ss
986: field may be added independently of the other fields.
1.7 mycroft 987: If the century is not specified, it defaults to 1900 for
988: years between 69 and 99, or 2000 for years between 0 and 68.
1.1 jtc 989: Time ranges are relative to the current time, so
990: .Dl Fl T Ar 1234/cm
991: would select all files with a modification or inode change time
992: of 12:34 PM today or later.
1.27 wiz 993: Multiple
1.1 jtc 994: .Fl T
995: time range can be supplied and checking stops with the first match.
996: .It Fl U Ar user
997: Select a file based on its
998: .Ar user
999: name, or when starting with a
1000: .Cm # ,
1001: a numeric uid.
1.57 joerg 1002: A '\e' can be used to escape the
1.1 jtc 1003: .Cm # .
1.27 wiz 1004: Multiple
1.1 jtc 1005: .Fl U
1006: options may be supplied and checking stops with the first match.
1.52 christos 1007: .It Fl V
1008: A final summary of archive operations is printed after they have been
1.55 wiz 1009: completed.
1010: Some potentially long-running tape operations are noted.
1.1 jtc 1011: .It Fl X
1012: When traversing the file hierarchy specified by a pathname,
1013: do not descend into directories that have a different device ID.
1014: See the
1.27 wiz 1015: .Li st_dev
1.1 jtc 1016: field as described in
1017: .Xr stat 2
1018: for more information about device ID's.
1019: .It Fl Y
1020: This option is the same as the
1021: .Fl D
1022: option, except that the inode change time is checked using the
1023: pathname created after all the file name modifications have completed.
1024: .It Fl Z
1025: This option is the same as the
1026: .Fl u
1027: option, except that the modification time is checked using the
1028: pathname created after all the file name modifications have completed.
1.49 christos 1029: .It Fl 0
1030: Use the nul character instead of \en as the file separator when reading
1031: files from standard input.
1.59 wiz 1032: .It Fl Fl force-local
1.36 christos 1033: Do not interpret filenames that contain a `:' as remote files.
1.59 wiz 1034: .It Fl Fl insecure
1.36 christos 1035: Normally
1036: .Nm
1.55 wiz 1037: ignores filenames that contain
1038: .Dq ..
1039: as a path component.
1040: With this option,
1041: files that contain
1042: .Dq ..
1043: can be processed.
1.59 wiz 1044: .It Fl Fl use-compress-program
1.58 christos 1045: Use the named program as the program to decompress the input or compress
1046: the output.
1.1 jtc 1047: .El
1048: .Pp
1.15 mycroft 1049: The options that operate on the names of files or archive members
1.16 mycroft 1050: .Fl ( c ,
1.1 jtc 1051: .Fl i ,
1052: .Fl n ,
1053: .Fl s ,
1054: .Fl u ,
1055: .Fl v ,
1056: .Fl D ,
1057: .Fl G ,
1058: .Fl T ,
1059: .Fl U ,
1060: .Fl Y ,
1061: and
1.16 mycroft 1062: .Fl Z )
1.1 jtc 1063: interact as follows.
1064: .Pp
1065: When extracting files during a
1066: .Em read
1067: operation, archive members are
1068: .Sq selected ,
1069: based only on the user specified pattern operands as modified by the
1070: .Fl c ,
1071: .Fl n ,
1072: .Fl u ,
1073: .Fl D ,
1074: .Fl G ,
1075: .Fl T ,
1076: .Fl U
1077: options.
1078: Then any
1079: .Fl s
1080: and
1081: .Fl i
1082: options will modify in that order, the names of these selected files.
1083: Then the
1084: .Fl Y
1085: and
1086: .Fl Z
1087: options will be applied based on the final pathname.
1.27 wiz 1088: Finally the
1.1 jtc 1089: .Fl v
1090: option will write the names resulting from these modifications.
1091: .Pp
1092: When archiving files during a
1093: .Em write
1094: operation, or copying files during a
1095: .Em copy
1096: operation, archive members are
1097: .Sq selected ,
1098: based only on the user specified pathnames as modified by the
1099: .Fl n ,
1100: .Fl u ,
1101: .Fl D ,
1102: .Fl G ,
1103: .Fl T ,
1.27 wiz 1104: and
1.1 jtc 1105: .Fl U
1106: options (the
1107: .Fl D
1108: option only applies during a copy operation).
1109: Then any
1.27 wiz 1110: .Fl s
1.1 jtc 1111: and
1112: .Fl i
1113: options will modify in that order, the names of these selected files.
1114: Then during a
1115: .Em copy
1116: operation the
1117: .Fl Y
1118: and the
1119: .Fl Z
1120: options will be applied based on the final pathname.
1121: Finally the
1122: .Fl v
1123: option will write the names resulting from these modifications.
1124: .Pp
1125: When one or both of the
1126: .Fl u
1127: or
1128: .Fl D
1129: options are specified along with the
1130: .Fl n
1131: option, a file is not considered selected unless it is newer
1132: than the file to which it is compared.
1.50 wiz 1133: .Sh EXIT STATUS
1134: .Nm
1135: will exit with one of the following values:
1136: .Bl -tag -width 2n
1137: .It 0
1138: All files were processed successfully.
1139: .It 1
1140: An error occurred.
1141: .El
1142: .Pp
1143: Whenever
1144: .Nm
1145: cannot create a file or a link when reading an archive or cannot
1146: find a file when writing an archive, or cannot preserve the user ID,
1147: group ID, or file mode when the
1148: .Fl p
1149: option is specified, a diagnostic message is written to
1150: .Dv standard error
1151: and a non-zero exit status will be returned, but processing will continue.
1152: In the case where pax cannot create a link to a file,
1153: .Nm
1154: will not create a second copy of the file.
1155: .Pp
1156: If the extraction of a file from an archive is prematurely terminated by
1157: a signal or error,
1158: .Nm
1159: may have only partially extracted a file the user wanted.
1160: Additionally, the file modes of extracted files and directories
1161: may have incorrect file bits, and the modification and access times may be
1162: wrong.
1163: .Pp
1164: If the creation of an archive is prematurely terminated by a signal or error,
1165: .Nm
1166: may have only partially created the archive which may violate the specific
1167: archive format specification.
1168: .Pp
1169: If while doing a
1170: .Em copy ,
1171: .Nm
1172: detects a file is about to overwrite itself, the file is not copied,
1173: a diagnostic message is written to
1174: .Dv standard error
1175: and when
1176: .Nm
1177: completes it will exit with a non-zero exit status.
1.1 jtc 1178: .Sh EXAMPLES
1179: The command:
1.27 wiz 1180: .Dl pax -w -f /dev/rst0 \&.
1.1 jtc 1181: copies the contents of the current directory to the device
1182: .Pa /dev/rst0 .
1183: .Pp
1184: The command:
1.4 pk 1185: .Dl pax -v -f filename
1.1 jtc 1186: gives the verbose table of contents for an archive stored in
1187: .Pa filename .
1188: .Pp
1189: The following commands:
1190: .Dl mkdir newdir
1191: .Dl cd olddir
1.28 hubertf 1192: .Dl pax -rw -pp .\ ../newdir
1.1 jtc 1193: will copy the entire
1194: .Pa olddir
1195: directory hierarchy to
1.28 hubertf 1196: .Pa newdir ,
1.29 hubertf 1197: preserving permissions and access times.
1198: .Pp
1199: When running as root, one may also wish to preserve file
1.34 wiz 1200: ownership when copying directory trees.
1201: This can be done with the following commands:
1.29 hubertf 1202: .Dl cd olddir
1.56 christos 1203: .Dl pax -rw -pe .\ ../newdir
1.29 hubertf 1204: which will copy the contents of
1205: .Pa olddir
1206: into
1.56 christos 1207: .Pa ../newdir ,
1.29 hubertf 1208: preserving ownership, permissions and access times.
1.1 jtc 1209: .Pp
1210: The command:
1211: .Dl pax -r -s ',^//*usr//*,,' -f a.pax
1.27 wiz 1212: reads the archive
1.1 jtc 1213: .Pa a.pax ,
1214: with all files rooted in ``/usr'' into the archive extracted relative to the
1215: current directory.
1216: .Pp
1217: The command:
1218: .Dl pax -rw -i .\ dest_dir
1219: can be used to interactively select the files to copy from the current
1220: directory to
1221: .Pa dest_dir .
1222: .Pp
1223: The command:
1224: .Dl pax -r -pe -U root -G bin -f a.pax
1225: will extract all files from the archive
1226: .Pa a.pax
1227: which are owned by
1228: .Em root
1229: with group
1230: .Em bin
1231: and will preserve all file permissions.
1232: .Pp
1233: The command:
1234: .Dl pax -r -w -v -Y -Z home /backup
1235: will update (and list) only those files in the destination directory
1236: .Pa /backup
1237: which are older (less recent inode change or file modification times) than
1238: files with the same name found in the source file tree
1239: .Pa home .
1.27 wiz 1240: .Sh SEE ALSO
1241: .Xr cpio 1 ,
1242: .Xr tar 1 ,
1243: .Xr symlink 7 ,
1244: .Xr mtree 8
1245: .Sh STANDARDS
1246: The
1247: .Nm
1248: utility is a superset of the
1249: .St -p1003.2
1250: standard.
1251: The options
1252: .Fl B ,
1253: .Fl D ,
1254: .Fl E ,
1255: .Fl G ,
1256: .Fl H ,
1257: .Fl L ,
1258: .Fl M ,
1259: .Fl O ,
1260: .Fl P ,
1261: .Fl T ,
1262: .Fl U ,
1263: .Fl Y ,
1264: .Fl Z ,
1.43 mrg 1265: .Fl z ,
1.27 wiz 1266: the archive formats
1267: .Ar bcpio ,
1268: .Ar sv4cpio ,
1269: .Ar sv4crc ,
1270: .Ar tar ,
1271: and the flawed archive handling during
1272: .Ar list
1273: and
1274: .Ar read
1275: operations are extensions to the
1276: .Tn POSIX
1277: standard.
1278: .Sh AUTHORS
1279: Keith Muller at the University of California, San Diego.
1280: Luke Mewburn implemented
1281: .Fl M .
CVSweb <webmaster@jp.NetBSD.org>