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