1.\" $NetBSD: pax.1,v 1.68 2016/08/12 01:52:22 sevan 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 August 12, 2016 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 timestamp Ar timestamp 746Store all modification times in the archive with the 747.Ar timestamp 748given instead of the actual modification time of the individual archive member 749so that repeatable builds are possible. 750The 751.Ar timestamp 752can be a 753.Pa pathname , 754where the timestamps are derived from that file, a parseable date for 755.Xr parsedate 3 756(this option is not yet available in the tools build), or an integer value 757interpreted as the number of seconds from the Epoch. 758.It Fl Fl xz 759Use 760.Xr xz 1 761compression, when reading or writing archive files. 762.It Fl z 763Use 764.Xr gzip 1 765compression, when reading or writing archive files. 766.It Fl A 767Do not strip leading `/'s from file names. 768.It Fl B Ar bytes 769Limit the number of bytes written to a single archive volume to 770.Ar bytes . 771The 772.Ar bytes 773limit can end with 774.Li m , 775.Li k , 776or 777.Li b 778to specify multiplication by 1048576 (1M), 1024 (1K) or 512, respectively. 779A pair of 780.Ar bytes 781limits can be separated by 782.Li x 783to indicate a product. 784.Pp 785.Em Warning : 786Only use this option when writing an archive to a device which supports 787an end of file read condition based on last (or largest) write offset 788(such as a regular file or a tape drive). 789The use of this option with a floppy or hard disk is not recommended. 790.It Fl D 791This option is the same as the 792.Fl u 793option, except that the file inode change time is checked instead of the 794file modification time. 795The file inode change time can be used to select files whose inode information 796(e.g. uid, gid, etc.) is newer than a copy of the file in the destination 797.Ar directory . 798.It Fl E Ar limit 799Limit the number of consecutive read faults while trying to read a flawed 800archives to 801.Ar limit . 802With a positive 803.Ar limit , 804.Nm 805will attempt to recover from an archive read error and will 806continue processing starting with the next file stored in the archive. 807A 808.Ar limit 809of 0 will cause 810.Nm 811to stop operation after the first read error is detected on an archive volume. 812A 813.Ar limit 814of 815.Li NONE 816will cause 817.Nm 818to attempt to recover from read errors forever. 819The default 820.Ar limit 821is a small positive number of retries. 822.Pp 823.Em Warning : 824Using this option with 825.Li NONE 826should be used with extreme caution as 827.Nm 828may get stuck in an infinite loop on a very badly flawed archive. 829.It Fl G Ar group 830Select a file based on its 831.Ar group 832name, or when starting with a 833.Cm # , 834a numeric gid. 835A '\e' can be used to escape the 836.Cm # . 837Multiple 838.Fl G 839options may be supplied and checking stops with the first match. 840.It Fl H 841Follow only command line symbolic links while performing a physical file 842system traversal. 843.It Fl L 844Follow all symbolic links to perform a logical file system traversal. 845.It Fl M 846During a 847.Em write 848or 849.Em copy 850operation, treat the list of files on 851.Dv standard input 852as an 853.Xr mtree 8 854.Sq specfile 855specification, and write or copy only those items in the specfile. 856.Pp 857If the file exists in the underlying file system, its permissions and 858modification time will be used unless specifically overridden by the specfile. 859An error will be raised if the type of entry in the specfile conflicts 860with that of an existing file. 861A directory entry that is marked 862.Sq Sy optional 863will not be copied (even though its contents will be). 864.Pp 865Otherwise, the entry will be 866.Sq faked-up , 867and it is necessary to specify at least the following parameters 868in the specfile: 869.Sy type , 870.Sy mode , 871.Sy gname 872or 873.Sy gid , 874and 875.Sy uname 876or 877.Sy uid , 878.Sy device 879(in the case of block or character devices), and 880.Sy link 881(in the case of symbolic links). 882If 883.Sy time 884isn't provided, the current time will be used. 885A 886.Sq faked-up 887entry that is marked 888.Sq Sy optional 889will not be copied. 890.It Fl N Ar dbdir 891Except for lookups for the 892.Fl G 893and 894.Fl U 895options, 896use the user database text file 897.Pa master.passwd 898and group database text file 899.Pa group 900from 901.Ar dbdir , 902rather than using the results from the system's 903.Xr getpwnam 3 904and 905.Xr getgrnam 3 906(and related) library calls. 907.It Fl O 908Force the archive to be one volume. 909If a volume ends prematurely, 910.Nm 911will not prompt for a new volume. 912This option can be useful for 913automated tasks where error recovery cannot be performed by a human. 914.It Fl P 915Do not follow symbolic links, perform a physical file system traversal. 916This is the default mode. 917.It Fl T Ar [from_date][,to_date][/[c][m]] 918Allow files to be selected based on a file modification or inode change 919time falling within a specified time range of 920.Ar from_date 921to 922.Ar to_date 923(the dates are inclusive). 924If only a 925.Ar from_date 926is supplied, all files with a modification or inode change time 927equal to or younger are selected. 928If only a 929.Ar to_date 930is supplied, all files with a modification or inode change time 931equal to or older will be selected. 932When the 933.Ar from_date 934is equal to the 935.Ar to_date , 936only files with a modification or inode change time of exactly that 937time will be selected. 938.Pp 939When 940.Nm 941is in the 942.Em write 943or 944.Em copy 945mode, the optional trailing field 946.Ar [c][m] 947can be used to determine which file time (inode change, file modification or 948both) are used in the comparison. 949If neither is specified, the default is to use file modification time only. 950The 951.Ar m 952specifies the comparison of file modification time (the time when 953the file was last written). 954The 955.Ar c 956specifies the comparison of inode change time (the time when the file 957inode was last changed; e.g. a change of owner, group, mode, etc). 958When 959.Ar c 960and 961.Ar m 962are both specified, then the modification and inode change times are 963both compared. 964The inode change time comparison is useful in selecting files whose 965attributes were recently changed or selecting files which were recently 966created and had their modification time reset to an older time (as what 967happens when a file is extracted from an archive and the modification time 968is preserved). 969Time comparisons using both file times is useful when 970.Nm 971is used to create a time based incremental archive (only files that were 972changed during a specified time range will be archived). 973.Pp 974A time range is made up of seven different fields and each field must contain 975two digits. 976The format is: 977.Dl [[[[[cc]yy]mm]dd]hh]mm[\&.ss] 978where 979.Cm cc 980is the first two digits of the year (the century), 981.Cm yy 982is the last two digits of the year, 983the first 984.Cm mm 985is the month (from 01 to 12), 986.Cm dd 987is the day of the month (from 01 to 31), 988.Cm hh 989is the hour of the day (from 00 to 23), 990the second 991.Cm mm 992is the minute (from 00 to 59), 993and 994.Cm ss 995is the seconds (from 00 to 61). 996Only the minute field 997.Cm mm 998is required; the others will default to the current system values. 999The 1000.Cm ss 1001field may be added independently of the other fields. 1002If the century is not specified, it defaults to 1900 for 1003years between 69 and 99, or 2000 for years between 0 and 68. 1004Time ranges are relative to the current time, so 1005.Dl Fl T Ar 1234/cm 1006would select all files with a modification or inode change time 1007of 12:34 PM today or later. 1008Multiple 1009.Fl T 1010time range can be supplied and checking stops with the first match. 1011.It Fl U Ar user 1012Select a file based on its 1013.Ar user 1014name, or when starting with a 1015.Cm # , 1016a numeric uid. 1017A '\e' can be used to escape the 1018.Cm # . 1019Multiple 1020.Fl U 1021options may be supplied and checking stops with the first match. 1022.It Fl V 1023A final summary of archive operations is printed after they have been 1024completed. 1025Some potentially long-running tape operations are noted. 1026.It Fl X 1027When traversing the file hierarchy specified by a pathname, 1028do not descend into directories that have a different device ID. 1029See the 1030.Li st_dev 1031field as described in 1032.Xr stat 2 1033for more information about device ID's. 1034.It Fl Y 1035This option is the same as the 1036.Fl D 1037option, except that the inode change time is checked using the 1038pathname created after all the file name modifications have completed. 1039.It Fl Z 1040This option is the same as the 1041.Fl u 1042option, except that the modification time is checked using the 1043pathname created after all the file name modifications have completed. 1044.It Fl 0 1045Use the nul character instead of \en as the file separator when reading 1046files from standard input. 1047.It Fl Fl force-local 1048Do not interpret filenames that contain a `:' as remote files. 1049.It Fl Fl insecure 1050Normally 1051.Nm 1052ignores filenames that contain 1053.Dq .. 1054as a path component. 1055With this option, 1056files that contain 1057.Dq .. 1058can be processed. 1059.It Fl Fl use-compress-program 1060Use the named program as the program to decompress the input or compress 1061the output. 1062.El 1063.Pp 1064The options that operate on the names of files or archive members 1065.Fl ( c , 1066.Fl i , 1067.Fl n , 1068.Fl s , 1069.Fl u , 1070.Fl v , 1071.Fl D , 1072.Fl G , 1073.Fl T , 1074.Fl U , 1075.Fl Y , 1076and 1077.Fl Z ) 1078interact as follows. 1079.Pp 1080When extracting files during a 1081.Em read 1082operation, archive members are 1083.Sq selected , 1084based only on the user specified pattern operands as modified by the 1085.Fl c , 1086.Fl n , 1087.Fl u , 1088.Fl D , 1089.Fl G , 1090.Fl T , 1091.Fl U 1092options. 1093Then any 1094.Fl s 1095and 1096.Fl i 1097options will modify in that order, the names of these selected files. 1098Then the 1099.Fl Y 1100and 1101.Fl Z 1102options will be applied based on the final pathname. 1103Finally the 1104.Fl v 1105option will write the names resulting from these modifications. 1106.Pp 1107When archiving files during a 1108.Em write 1109operation, or copying files during a 1110.Em copy 1111operation, archive members are 1112.Sq selected , 1113based only on the user specified pathnames as modified by the 1114.Fl n , 1115.Fl u , 1116.Fl D , 1117.Fl G , 1118.Fl T , 1119and 1120.Fl U 1121options (the 1122.Fl D 1123option only applies during a copy operation). 1124Then any 1125.Fl s 1126and 1127.Fl i 1128options will modify in that order, the names of these selected files. 1129Then during a 1130.Em copy 1131operation the 1132.Fl Y 1133and the 1134.Fl Z 1135options will be applied based on the final pathname. 1136Finally the 1137.Fl v 1138option will write the names resulting from these modifications. 1139.Pp 1140When one or both of the 1141.Fl u 1142or 1143.Fl D 1144options are specified along with the 1145.Fl n 1146option, a file is not considered selected unless it is newer 1147than the file to which it is compared. 1148.Sh EXIT STATUS 1149.Nm 1150will exit with one of the following values: 1151.Bl -tag -width 2n 1152.It 0 1153All files were processed successfully. 1154.It 1 1155An error occurred. 1156.El 1157.Pp 1158Whenever 1159.Nm 1160cannot create a file or a link when reading an archive or cannot 1161find a file when writing an archive, or cannot preserve the user ID, 1162group ID, or file mode when the 1163.Fl p 1164option is specified, a diagnostic message is written to 1165.Dv standard error 1166and a non-zero exit status will be returned, but processing will continue. 1167In the case where pax cannot create a link to a file, 1168.Nm 1169will not create a second copy of the file. 1170.Pp 1171If the extraction of a file from an archive is prematurely terminated by 1172a signal or error, 1173.Nm 1174may have only partially extracted a file the user wanted. 1175Additionally, the file modes of extracted files and directories 1176may have incorrect file bits, and the modification and access times may be 1177wrong. 1178.Pp 1179If the creation of an archive is prematurely terminated by a signal or error, 1180.Nm 1181may have only partially created the archive which may violate the specific 1182archive format specification. 1183.Pp 1184If while doing a 1185.Em copy , 1186.Nm 1187detects a file is about to overwrite itself, the file is not copied, 1188a diagnostic message is written to 1189.Dv standard error 1190and when 1191.Nm 1192completes it will exit with a non-zero exit status. 1193.Sh EXAMPLES 1194The command: 1195.Dl pax -w -f /dev/rst0 \&. 1196copies the contents of the current directory to the device 1197.Pa /dev/rst0 . 1198.Pp 1199The command: 1200.Dl pax -v -f filename 1201gives the verbose table of contents for an archive stored in 1202.Pa filename . 1203.Pp 1204The following commands: 1205.Dl mkdir newdir 1206.Dl cd olddir 1207.Dl pax -rw -pp .\ ../newdir 1208will copy the entire 1209.Pa olddir 1210directory hierarchy to 1211.Pa newdir , 1212preserving permissions and access times. 1213.Pp 1214When running as root, one may also wish to preserve file 1215ownership when copying directory trees. 1216This can be done with the following commands: 1217.Dl cd olddir 1218.Dl pax -rw -pe .\ ../newdir 1219which will copy the contents of 1220.Pa olddir 1221into 1222.Pa ../newdir , 1223preserving ownership, permissions and access times. 1224.Pp 1225The command: 1226.Dl pax -r -s ',^//*usr//*,,' -f a.pax 1227reads the archive 1228.Pa a.pax , 1229with all files rooted in ``/usr'' into the archive extracted relative to the 1230current directory. 1231.Pp 1232The command: 1233.Dl pax -rw -i .\ dest_dir 1234can be used to interactively select the files to copy from the current 1235directory to 1236.Pa dest_dir . 1237.Pp 1238The command: 1239.Dl pax -r -pe -U root -G bin -f a.pax 1240will extract all files from the archive 1241.Pa a.pax 1242which are owned by 1243.Em root 1244with group 1245.Em bin 1246and will preserve all file permissions. 1247.Pp 1248The command: 1249.Dl pax -r -w -v -Y -Z home /backup 1250will update (and list) only those files in the destination directory 1251.Pa /backup 1252which are older (less recent inode change or file modification times) than 1253files with the same name found in the source file tree 1254.Pa home . 1255.Sh SEE ALSO 1256.Xr cpio 1 , 1257.Xr tar 1 , 1258.Xr symlink 7 , 1259.Xr mtree 8 1260.Sh STANDARDS 1261The 1262.Nm 1263utility is a superset of the 1264.St -p1003.2 1265standard. 1266The options 1267.Fl B , 1268.Fl D , 1269.Fl E , 1270.Fl G , 1271.Fl H , 1272.Fl L , 1273.Fl M , 1274.Fl O , 1275.Fl P , 1276.Fl T , 1277.Fl U , 1278.Fl Y , 1279.Fl Z , 1280.Fl z , 1281the archive formats 1282.Ar bcpio , 1283.Ar sv4cpio , 1284.Ar sv4crc , 1285.Ar tar , 1286and the flawed archive handling during 1287.Ar list 1288and 1289.Ar read 1290operations are extensions to the 1291.Tn POSIX 1292standard. 1293.Sh HISTORY 1294A 1295.Nm 1296utility appeared in 1297.Bx 4.4 . 1298.Sh AUTHORS 1299.An -nosplit 1300.An Keith Muller 1301at the University of California, San Diego. 1302.An Luke Mewburn 1303implemented 1304.Fl M . 1305