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