diff options
Diffstat (limited to 'bin/pax/pax.1')
| -rw-r--r-- | bin/pax/pax.1 | 1112 |
1 files changed, 1112 insertions, 0 deletions
diff --git a/bin/pax/pax.1 b/bin/pax/pax.1 new file mode 100644 index 0000000..d146a96 --- /dev/null +++ b/bin/pax/pax.1 @@ -0,0 +1,1112 @@ +.\" $OpenBSD: pax.1,v 1.75 2020/01/16 16:46:46 schwarze Exp $ +.\" $NetBSD: pax.1,v 1.3 1995/03/21 09:07:37 cgd Exp $ +.\" +.\" Copyright (c) 1992 Keith Muller. +.\" Copyright (c) 1992, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Keith Muller of the University of California, San Diego. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)pax.1 8.4 (Berkeley) 4/18/94 +.\" +.Dd $Mdocdate: January 16 2020 $ +.Dt PAX 1 +.Os +.Sh NAME +.Nm pax +.Nd read and write file archives and copy directory hierarchies +.Sh SYNOPSIS +.Nm pax +.Op Fl 0cdjnOvz +.Op Fl E Ar limit +.Op Fl f Ar archive +.Op Fl G Ar group +.Op Fl s Ar replstr +.Op Fl T Ar range +.Op Fl U Ar user +.Op Ar pattern ... +.Nm pax +.Fl r +.Op Fl 0cDdijknOuvYZz +.Op Fl E Ar limit +.Op Fl f Ar archive +.Op Fl G Ar group +.Op Fl o Ar options +.Op Fl p Ar string +.Op Fl s Ar replstr +.Op Fl T Ar range +.Op Fl U Ar user +.Op Ar pattern ... +.Nm pax +.Fl w +.Op Fl 0adHijLOPtuvXz +.Op Fl B Ar bytes +.Op Fl b Ar blocksize +.Op Fl f Ar archive +.Op Fl G Ar group +.Op Fl o Ar options +.Op Fl s Ar replstr +.Op Fl T Ar range +.Op Fl U Ar user +.Op Fl x Ar format +.Op Ar +.Nm pax +.Fl rw +.Op Fl 0DdHijkLlnOPtuvXYZ +.Op Fl G Ar group +.Op Fl p Ar string +.Op Fl s Ar replstr +.Op Fl T Ar range +.Op Fl U Ar user +.Op Ar +.Ar directory +.Sh DESCRIPTION +.Nm +will read, write, and list the members of an archive file +and will copy directory hierarchies. +.Nm +operation is independent of the specific archive format +and supports a wide variety of different archive formats. +A list of supported archive formats can be found under the description of the +.Fl x +option. +.Pp +The presence of the +.Fl r +and the +.Fl w +options specifies which of the following functional modes +.Nm +will operate under: +.Em list , read , write , +and +.Em copy . +.Bl -tag -width 6n +.It Aq none +.Em List . +.Nm +will write to standard output +a table of contents of the members of the archive file read from +standard input, whose pathnames match the specified +.Ar pattern +arguments. +The table of contents contains one filename per line +and is written using single line buffering. +.It Fl r +.Em Read . +.Nm +extracts the members of the archive file read from the standard input, +with pathnames matching the specified +.Ar pattern +arguments. +The archive format and blocking is automatically determined on input. +When an extracted file is a directory, the entire file hierarchy +rooted at that directory is extracted. +All extracted files are created relative to the current file hierarchy. +The setting of ownership, access and modification times, and file mode of +the extracted files are discussed in more detail under the +.Fl p +option. +.It Fl w +.Em Write . +.Nm +writes an archive containing the +.Ar file +operands to standard output +using the specified archive format. +When no +.Ar file +operands are specified, a list of files to copy with one per line is read from +standard input. +When a +.Ar file +operand is also a directory, the entire file hierarchy rooted +at that directory will be included. +.It Fl rw +.Em Copy . +.Nm +copies the +.Ar file +operands to the destination +.Ar directory . +When no +.Ar file +operands are specified, a list of files to copy with one per line is read from +the standard input. +When a +.Ar file +operand is also a directory the entire file +hierarchy rooted at that directory will be included. +The effect of the +.Em copy +is as if the copied files were written to an archive file and then +subsequently extracted, except that there may be hard links between +the original and the copied files (see the +.Fl l +option below). +.Pp +.Sy Warning : +The destination +.Ar directory +must not be one of the +.Ar file +operands or a member of a file hierarchy rooted at one of the +.Ar file +operands. +The result of a +.Em copy +under these conditions is unpredictable. +.El +.Pp +While processing a damaged archive during a read or list operation, +.Nm +will attempt to recover from media defects and will search through the archive +to locate and process the largest number of archive members possible (see the +.Fl E +option for more details on error handling). +.Pp +The +.Ar directory +operand specifies a destination directory pathname. +If the +.Ar directory +operand does not exist, or it is not writable by the user, +or it is not of type directory, +.Nm +will exit with a non-zero exit status. +.Pp +The +.Ar pattern +operand is used to select one or more pathnames of archive members. +Archive members are selected using the pattern matching notation described +by +.Xr glob 7 . +When the +.Ar pattern +operand is not supplied, all members of the archive will be selected. +When a +.Ar pattern +matches a directory, the entire file hierarchy rooted at that directory will +be selected. +When a +.Ar pattern +operand does not select at least one archive member, +.Nm +will write these +.Ar pattern +operands in a diagnostic message to standard error +and then exit with a non-zero exit status. +.Pp +The +.Ar file +operand specifies the pathname of a file to be copied or archived. +When a +.Ar file +operand does not select at least one archive member, +.Nm +will write these +.Ar file +operand pathnames in a diagnostic message to standard error +and then exit with a non-zero exit status. +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl 0 +Use the NUL +.Pq Ql \e0 +character as a pathname terminator, instead of newline +.Pq Ql \en . +This applies only to the pathnames read from standard input in +the write and copy modes, +and to the pathnames written to standard output in list mode. +This option is expected to be used in concert with the +.Fl print0 +function in +.Xr find 1 +or the +.Fl 0 +flag in +.Xr xargs 1 . +.It Fl a +Append the given +.Ar file +operands +to the end of an archive that was previously written. +If an archive format is not specified with a +.Fl x +option, the format currently being used in the archive will be selected. +Any attempt to append to an archive in a format different from the +format already used in the archive will cause +.Nm +to exit immediately +with a non-zero exit status. +The blocking size used in the archive volume where writing starts +will continue to be used for the remainder of that archive volume. +.Pp +.Sy Warning : +Many storage devices are not able to support the operations necessary +to perform an append operation. +Any attempt to append to an archive stored on such a device may damage the +archive or have other unpredictable results. +Tape drives in particular are more likely to not support an append operation. +An archive stored in a regular file system file or on a disk device will +usually support an append operation. +.It Fl B Ar bytes +Limit the number of bytes written to a single archive volume to +.Ar bytes . +The +.Ar bytes +limit can end with +.Sq Li m , +.Sq Li k , +or +.Sq Li b +to specify multiplication by 1048576 (1M), 1024 (1K) or 512, respectively. +A pair of +.Ar bytes +limits can be separated by +.Sq Li x +to indicate a product. +.Pp +.Sy Warning : +Only use this option when writing an archive to a device which supports +an end of file read condition based on last (or largest) write offset +(such as a regular file or a tape drive). +The use of this option with a floppy or hard disk is not recommended. +.It Fl b Ar blocksize +When writing an archive, +block the output at a positive decimal integer number of +bytes per write to the archive file. +The +.Ar blocksize +must be a multiple of 512 bytes with a maximum of 64512 bytes. +Archive block sizes larger than 32256 bytes violate the POSIX +standard and will not be portable to all systems. +A +.Ar blocksize +can end with +.Sq Li k +or +.Sq Li b +to specify multiplication by 1024 (1K) or 512, respectively. +A pair of blocksizes can be separated by +.Sq Li x +to indicate a product. +A specific archive device may impose additional restrictions on the size +of blocking it will support. +When blocking is not specified, the default +.Ar blocksize +is dependent on the specific archive format being used (see the +.Fl x +option). +.It Fl c +Match all file or archive members +.Em except +those specified by the +.Ar pattern +and +.Ar file +operands. +.It Fl D +This option is the same as the +.Fl u +option, except that the file inode change time is checked instead of the +file modification time. +The file inode change time can be used to select files whose inode information +(e.g., UID, GID, etc.) is newer than a copy of the file in the destination +.Ar directory . +.It Fl d +Cause files of type directory being copied or archived, or archive members of +type directory being extracted, to match only the directory file or archive +member and not the file hierarchy rooted at the directory. +.It Fl E Ar limit +Limit the number of consecutive read faults while trying to read a flawed +archive to +.Ar limit . +With a positive +.Ar limit , +.Nm +will attempt to recover from an archive read error and will +continue processing starting with the next file stored in the archive. +A +.Ar limit +of 0 will cause +.Nm +to stop operation after the first read error is detected on an archive volume. +The default +.Ar limit +is a small positive number of retries. +.It Fl f Ar archive +Specify +.Ar archive +as the pathname of the input or output archive, overriding the default +standard input (for list and read) +or standard output +(for write). +A single archive may span multiple files and different archive devices. +When required, +.Nm +will prompt for the pathname of the file or device of the next volume in the +archive. +.It Fl G Ar group +Select a file based on its +.Ar group +name, or when starting with a +.Cm # , +a numeric GID. +A +.Ql \e +can be used to escape the +.Cm # . +Multiple +.Fl G +options may be supplied and checking stops with the first match. +.It Fl H +Follow only command-line symbolic links while performing a physical file +system traversal. +.It Fl i +Interactively rename files or archive members. +For each archive member matching a +.Ar pattern +operand or each file matching a +.Ar file +operand, +.Nm +will prompt to +.Pa /dev/tty +giving the name of the file, its file mode, and its modification time. +.Nm +will then read a line from +.Pa /dev/tty . +If this line is blank, the file or archive member is skipped. +If this line consists of a single period, the +file or archive member is processed with no modification to its name. +Otherwise, its name is replaced with the contents of the line. +.Nm +will immediately exit with a non-zero exit status if +.Dv EOF +is encountered when reading a response or if +.Pa /dev/tty +cannot be opened for reading and writing. +.It Fl j +Use bzip2 to compress (decompress) the archive while writing (reading). +The bzip2 utility must be installed separately. +Incompatible with +.Fl a . +.It Fl k +Do not overwrite existing files. +.It Fl L +Follow all symbolic links to perform a logical file system traversal. +.It Fl l +(The lowercase letter +.Dq ell . ) +Link files. +In copy mode +.Pq Fl r Fl w , +hard links are made between the source and destination file hierarchies +whenever possible. +.It Fl n +Select the first archive member that matches each +.Ar pattern +operand. +No more than one archive member is matched for each +.Ar pattern . +When members of type directory are matched, the file hierarchy rooted at that +directory is also matched (unless +.Fl d +is also specified). +.It Fl O +Force the archive to be one volume. +If a volume ends prematurely, +.Nm +will not prompt for a new volume. +This option can be useful for +automated tasks where error recovery cannot be performed by a human. +.It Fl o Ar options +Information to modify the algorithm for extracting or writing archive files +which is specific to the archive format specified by +.Fl x . +In general, +.Ar options +take the form: +.Ar name Ns = Ns Ar value . +.Pp +The following options are available for the +.Cm ustar +and old +.Bx +.Cm tar +formats: +.Pp +.Bl -tag -width Ds -compact +.It Cm write_opt=nodir +When writing archives, omit the storage of directories. +.El +.It Fl P +Do not follow symbolic links, perform a physical file system traversal. +This is the default mode. +.It Fl p Ar string +Specify one or more file characteristic options (privileges). +The +.Ar string +option-argument is a string specifying file characteristics to be retained or +discarded on extraction. +The string consists of the specification characters +.Cm a , e , m , o , +and +.Cm p . +Multiple characteristics can be concatenated within the same string +and multiple +.Fl p +options can be specified. +The meanings of the specification characters are as follows: +.Bl -tag -width 2n +.It Cm a +Do not preserve file access times. +By default, file access times are preserved whenever possible. +.It Cm e +.Dq Preserve everything , +the user ID, group ID, file mode bits, +file access time, and file modification time. +This is intended to be used by root, +someone with all the appropriate privileges, in order to preserve all +aspects of the files as they are recorded in the archive. +The +.Cm e +flag is the sum of the +.Cm o +and +.Cm p +flags. +.It Cm m +Do not preserve file modification times. +By default, file modification times are preserved whenever possible. +.It Cm o +Preserve the user ID and group ID. +.It Cm p +.Dq Preserve +the file mode bits. +This is intended to be used by a user with regular privileges +who wants to preserve all aspects of the file other than the ownership. +The file times are preserved by default, but two other flags are offered to +disable this and use the time of extraction instead. +.El +.Pp +In the preceding list, +.Sq preserve +indicates that an attribute stored in the archive is given to the +extracted file, subject to the permissions of the invoking +process. +Otherwise the attribute of the extracted file is determined as +part of the normal file creation action. +If neither the +.Cm e +nor the +.Cm o +specification character is specified, or the user ID and group ID are not +preserved for any reason, +.Nm +will not set the +.Dv S_ISUID +(setuid) and +.Dv S_ISGID +(setgid) bits of the file mode. +If the preservation of any of these items fails for any reason, +.Nm +will write a diagnostic message to standard error. +Failure to preserve these items will affect the final exit status, +but will not cause the extracted file to be deleted. +If the file characteristic letters in any of the string option-arguments are +duplicated or conflict with each other, the one(s) given last will take +precedence. +For example, if +.Fl p Ar eme +is specified, file modification times are still preserved. +.It Fl r +Read an archive file from standard input +and extract the specified +.Ar file +operands. +If any intermediate directories are needed in order to extract an archive +member, these directories will be created as if +.Xr mkdir 2 +was called with the bitwise OR of +.Dv S_IRWXU , S_IRWXG , +and +.Dv S_IRWXO +as the mode argument. +When the selected archive format supports the specification of linked +files and these files cannot be linked while the archive is being extracted, +.Nm +will write a diagnostic message to standard error +and exit with a non-zero exit status at the completion of operation. +.It Fl s Ar replstr +Modify the archive member names according to the substitution expression +.Ar replstr , +using the syntax of the +.Xr ed 1 +utility regular expressions. +.Ar file +or +.Ar pattern +arguments may be given to restrict the list of archive members to those +specified. +.Pp +The format of these regular expressions is: +.Pp +.Dl /old/new/[gp] +.Pp +As in +.Xr ed 1 , +.Ar old +is a basic regular expression (see +.Xr re_format 7 ) +and +.Ar new +can contain an ampersand +.Pq Ql & , +.Ql \e Ns Em n +(where +.Em n +is a digit) back-references, +or subexpression matching. +The +.Ar old +string may also contain newline characters. +Any non-null character can be used as a delimiter +.Po +.Ql / +is shown here +.Pc . +Multiple +.Fl s +expressions can be specified. +The expressions are applied in the order they are specified on the +command line, terminating with the first successful substitution. +.Pp +The optional trailing +.Cm g +continues to apply the substitution expression to the pathname substring, +which starts with the first character following the end of the last successful +substitution. +The first unsuccessful substitution stops the operation of the +.Cm g +option. +The optional trailing +.Cm p +will cause the final result of a successful substitution to be written to +standard error in the following format: +.Pp +.D1 Em original-pathname No >> Em new-pathname +.Pp +File or archive member names that substitute to the empty string +are not selected and will be skipped. +.It Fl T Ar range +Allow files to be selected based on a file modification or inode change +time falling within the specified time range. +The range has the format: +.Sm off +.Bd -filled -offset indent +.Op Ar from_date +.Op \&, Ar to_date +.Op / Oo Cm c Oc Op Cm m +.Ed +.Sm on +.Pp +The dates specified by +.Ar from_date +to +.Ar to_date +are inclusive. +If only a +.Ar from_date +is supplied, all files with a modification or inode change time +equal to or younger are selected. +If only a +.Ar to_date +is supplied, all files with a modification or inode change time +equal to or older will be selected. +When the +.Ar from_date +is equal to the +.Ar to_date , +only files with a modification or inode change time of exactly that +time will be selected. +.Pp +When +.Nm +is in write or copy mode, the optional trailing field +.Oo Cm c Oc Ns Op Cm m +can be used to determine which file time (inode change, file modification or +both) are used in the comparison. +If neither is specified, the default is to use file modification time only. +The +.Cm m +specifies the comparison of file modification time (the time when +the file was last written). +The +.Cm c +specifies the comparison of inode change time (the time when the file +inode was last changed; e.g., a change of owner, group, mode, etc). +When +.Cm c +and +.Cm m +are both specified, then the modification and inode change times are +both compared. +.Pp +The inode change time comparison is useful in selecting files whose +attributes were recently changed or selecting files which were recently +created and had their modification time reset to an older time (as what +happens when a file is extracted from an archive and the modification time +is preserved). +Time comparisons using both file times is useful when +.Nm +is used to create a time based incremental archive (only files that were +changed during a specified time range will be archived). +.Pp +A time range is made up of six different fields and each field must contain two +digits. +The format is: +.Pp +.Dl [[[[[cc]yy]mm]dd]HH]MM[.SS] +.Pp +Where +.Ar cc +is the first two digits of the year (the century), +.Ar yy +is the last two digits of the year, +the first +.Ar mm +is the month (from 01 to 12), +.Ar dd +is the day of the month (from 01 to 31), +.Ar HH +is the hour of the day (from 00 to 23), +.Ar MM +is the minute (from 00 to 59), +and +.Ar SS +is the seconds (from 00 to 59). +The minute field +.Ar MM +is required, while the other fields are optional and must be added in the +following order: +.Ar HH , dd , mm , +.Ar yy , cc . +.Pp +The +.Ar SS +field may be added independently of the other fields. +Time ranges are relative to the current time, so +.Ic -T 1234/cm +would select all files with a modification or inode change time +of 12:34 PM today or later. +Multiple +.Fl T +time range can be supplied and checking stops with the first match. +.It Fl t +Reset the access times of any file or directory read or accessed by +.Nm +to be the same as they were before being read or accessed by +.Nm pax . +.It Fl U Ar user +Select a file based on its +.Ar user +name, or when starting with a +.Cm # , +a numeric UID. +A +.Ql \e +can be used to escape the +.Cm # . +Multiple +.Fl U +options may be supplied and checking stops with the first match. +.It Fl u +Ignore files that are older (having a less recent file modification time) +than a pre-existing file or archive member with the same name. +During read, +an archive member with the same name as a file in the file system will be +extracted if the archive member is newer than the file. +During write, +a file system member with the same name as an archive member will be +written to the archive if it is newer than the archive member. +During copy, +the file in the destination hierarchy is replaced by the file in the source +hierarchy or by a link to the file in the source hierarchy if the file in +the source hierarchy is newer. +.It Fl v +During a list operation, produce a verbose table of contents using the format of the +.Xr ls 1 +utility with the +.Fl l +option. +For pathnames representing a hard link to a previous member of the archive, +the output has the format: +.Pp +.Dl Em ls -l listing No == Em link-name +.Pp +For pathnames representing a symbolic link, the output has the format: +.Pp +.Dl Em ls -l listing No -> Em link-name +.Pp +Where +.Em ls -l listing +is the output format specified by the +.Xr ls 1 +utility when used with the +.Fl l +option. +Otherwise for all the other operational modes +(read, write, and copy), +pathnames are written and flushed to standard error +without a trailing newline +as soon as processing begins on that file or +archive member. +The trailing newline +is not buffered and is written only after the file has been read or written. +.It Fl w +Write files to the standard output +in the specified archive format. +When no +.Ar file +operands are specified, standard input +is read for a list of pathnames with one per line without any leading or +trailing +.Aq blanks . +.It Fl X +When traversing the file hierarchy specified by a pathname, +do not descend into directories that have a different device ID. +See the +.Li st_dev +field as described in +.Xr stat 2 +for more information about device IDs. +.It Fl x Ar format +Specify the output archive format, with the default format being +.Cm ustar . +.Nm +currently supports the following formats: +.Bl -tag -width "sv4cpio" +.It Cm bcpio +The old binary cpio format. +The default blocksize for this format is 5120 bytes. +This format is not very portable and should not be used when other formats +are available. +Inode and device information about a file (used for detecting file hard links +by this format), which may be truncated by this format, is detected by +.Nm +and is repaired. +.It Cm cpio +The extended cpio interchange format specified in the +.St -p1003.2 +standard. +The default blocksize for this format is 5120 bytes. +Inode and device information about a file (used for detecting file hard links +by this format), which may be truncated by this format, is detected by +.Nm +and is repaired. +.It Cm sv4cpio +The System V release 4 cpio. +The default blocksize for this format is 5120 bytes. +Inode and device information about a file (used for detecting file hard links +by this format), which may be truncated by this format, is detected by +.Nm +and is repaired. +.It Cm sv4crc +The System V release 4 cpio with file CRC checksums. +The default blocksize for this format is 5120 bytes. +Inode and device information about a file (used for detecting file hard links +by this format), which may be truncated by this format, is detected by +.Nm +and is repaired. +.It Cm tar +The old +.Bx +tar format as found in +.Bx 4.3 . +The default blocksize for this format is 10240 bytes. +Pathnames stored by this format must be 100 characters or less in length. +Only regular files, hard links, soft links, and directories +will be archived (other file system types are not supported). +For backwards compatibility with even older tar formats, a +.Fl o +option can be used when writing an archive to omit the storage of directories. +This option takes the form: +.Pp +.Dl Fl o Cm write_opt=nodir +.It Cm ustar +The extended tar interchange format specified in the +.St -p1003.2 +standard. +The default blocksize for this format is 10240 bytes. +Filenames stored by this format must be 100 characters or less in length; +the total pathname must be 256 characters or less. +.El +.Pp +.Nm +will detect and report any file that it is unable to store or extract +as the result of any specific archive format restrictions. +The individual archive formats may impose additional restrictions on use. +Typical archive format restrictions include (but are not limited to): +file pathname length, file size, link pathname length, and the type of the +file. +.It Fl Y +This option is the same as the +.Fl D +option, except that the inode change time is checked using the +pathname created after all the file name modifications have completed. +.It Fl Z +This option is the same as the +.Fl u +option, except that the modification time is checked using the +pathname created after all the file name modifications have completed. +.It Fl z +Use +.Xr gzip 1 +to compress (decompress) the archive while writing (reading). +Incompatible with +.Fl a . +.El +.Pp +The options that operate on the names of files or archive members +.Po Fl c , +.Fl i , +.Fl j , +.Fl n , +.Fl s , +.Fl u , +.Fl v , +.Fl D , +.Fl G , +.Fl T , +.Fl U , +.Fl Y , +and +.Fl Z +.Pc +interact as follows. +.Pp +When extracting files during a read operation, archive members are +.Sq selected , +based only on the user specified pattern operands as modified by the +.Fl c , +.Fl n , +.Fl u , +.Fl D , +.Fl G , +.Fl T , +.Fl U +options. +Then any +.Fl s +and +.Fl i +options will modify in that order, the names of these selected files. +Then the +.Fl Y +and +.Fl Z +options will be applied based on the final pathname. +Finally, the +.Fl v +option will write the names resulting from these modifications. +.Pp +When archiving files during a write operation, +or copying files during a copy operation, +archive members are +.Sq selected , +based only on the user specified pathnames as modified by the +.Fl n , +.Fl u , +.Fl D , +.Fl G , +.Fl T , +and +.Fl U +options (the +.Fl D +option only applies during a copy operation). +Then any +.Fl s +and +.Fl i +options will modify in that order, the names of these selected files. +Then during a copy operation the +.Fl Y +and the +.Fl Z +options will be applied based on the final pathname. +Finally, the +.Fl v +option will write the names resulting from these modifications. +.Pp +When one or both of the +.Fl u +or +.Fl D +options are specified along with the +.Fl n +option, a file is not considered selected unless it is newer +than the file to which it is compared. +.Sh ENVIRONMENT +.Bl -tag -width Ds +.It Ev TMPDIR +Path in which to store temporary files. +.El +.Sh EXIT STATUS +.Ex -std pax +.Sh EXAMPLES +Copy the contents of the current directory to the device +.Pa /dev/rst0 : +.Pp +.Dl $ pax -w -f /dev/rst0 \&. +.Pp +Give the verbose table of contents for an archive stored in +.Pa filename : +.Pp +.Dl $ pax -v -f filename +.Pp +This sequence of commands will copy the entire +.Pa olddir +directory hierarchy to +.Pa newdir : +.Bd -literal -offset indent +$ mkdir newdir +$ cd olddir +$ pax -rw . ../newdir +.Ed +.Pp +Extract files from the archive +.Pa a.pax . +Files rooted in +.Pa /usr +are extracted relative to the current working directory; +all other files are extracted to their unmodified path. +.Pp +.Dl $ pax -r -s ',^/usr/,,' -f a.pax +.Pp +This can be used to interactively select the files to copy from the +current directory to +.Pa dest_dir : +.Pp +.Dl $ pax -rw -i \&. dest_dir +.Pp +Extract all files from the archive +.Pa a.pax +which are owned by +.Em root +with group +.Em bin +and preserve all file permissions: +.Pp +.Dl $ pax -r -pe -U root -G bin -f a.pax +.Pp +Update (and list) only those files in the destination directory +.Pa /backup +which are older (less recent inode change or file modification times) than +files with the same name found in the source file tree +.Pa home : +.Pp +.Dl $ pax -r -w -v -Y -Z home /backup +.Sh DIAGNOSTICS +Whenever +.Nm +cannot create a file or a link when reading an archive or cannot +find a file when writing an archive, or cannot preserve the user ID, +group ID, or file mode when the +.Fl p +option is specified, a diagnostic message is written to standard error +and a non-zero exit status will be returned, but processing will continue. +In the case where +.Nm +cannot create a link to a file, +.Nm +will not create a second copy of the file. +.Pp +If the extraction of a file from an archive is prematurely terminated by +a signal or error, +.Nm +may have only partially extracted a file the user wanted. +Additionally, the file modes of extracted files and directories +may have incorrect file bits, and the modification and access times may be +wrong. +.Pp +If the creation of an archive is prematurely terminated by a signal or error, +.Nm +may have only partially created the archive, which may violate the specific +archive format specification. +.Pp +If while doing a copy, +.Nm +detects a file is about to overwrite itself, the file is not copied, +a diagnostic message is written to standard error +and when +.Nm +completes it will exit with a non-zero exit status. +.Sh SEE ALSO +.Xr cpio 1 , +.Xr tar 1 +.Sh STANDARDS +The +.Nm +utility is compliant with the +.St -p1003.1-2008 +specification, +except that the +.Cm pax +archive format and the +.Cm listopt +keyword are unsupported. +.Pp +The flags +.Op Fl 0BDEGjOPTUYZz , +the archive formats +.Cm bcpio , +.Cm sv4cpio , +.Cm sv4crc , +and +.Cm tar , +the +.Cm b , k , +and +.Cm x +additions to the +.Fl b +flag, +and the flawed archive handling during list and read operations +are extensions to that specification. +.Sh HISTORY +A +.Nm +utility appeared in +.Bx 4.4 . +.Sh AUTHORS +.An Keith Muller +at the University of California, San Diego. |