-.\" $OpenBSD: pax.1,v 1.65 2014/04/15 17:02:54 jmc Exp $
+.\" $OpenBSD: pax.1,v 1.66 2014/04/15 21:21:20 jmc Exp $
.\" $NetBSD: pax.1,v 1.3 1995/03/21 09:07:37 cgd Exp $
.\"
.\" Copyright (c) 1992 Keith Muller.
.Nm pax
.Nd read and write file archives and copy directory hierarchies
.Sh SYNOPSIS
-.Bk -words
.Nm pax
.Op Fl 0cdjnOvz
.Op Fl E Ar limit
.Op Fl U Ar user
.Op Ar
.Ar directory
-.Ek
.Sh DESCRIPTION
.Nm
will read, write, and list the members of an archive file
and
.Em copy .
.Bl -tag -width 6n
-.It \*(Ltnone\*(Gt
+.It Aq none
.Em List .
.Nm
will write to standard output
under these conditions is unpredictable.
.El
.Pp
-While processing a damaged archive during a
-.Em read
-or
-.Em list
-operation,
+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
.Sq Li x
to indicate a product.
.Pp
-.Em Warning :
+.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
-.Em writing
-an archive,
+When writing an archive,
block the output at a positive decimal integer number of
bytes per write to the archive file.
The
or
.Sq Li b
to specify multiplication by 1024 (1K) or 512, respectively.
-A pair of
-.Ar blocksizes
-can be separated by
+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
.Ar limit
is a small positive number of retries.
.Pp
-.Em Warning :
+.Sy Warning :
Using this option with
.Li NONE
should be used with extreme caution as
Specify
.Ar archive
as the pathname of the input or output archive, overriding the default
-standard input (for
-.Em list
-and
-.Em read )
+standard input (for list and read)
or standard output
-(for
-.Em write ) .
+(for write).
A single archive may span multiple files and different archive devices.
When required,
.Nm
(The lowercase letter
.Dq ell . )
Link files.
-In the
-.Em copy
-mode
+In copy mode
.Pq Fl r Fl w ,
hard links are made between the source and destination file hierarchies
whenever possible.
.Ar name Ns = Ns Ar value .
.Pp
The following options are available for the
-.Em ustar
+.Cm ustar
and old
.Bx
-.Em tar
+.Cm tar
formats:
.Pp
.Bl -tag -width Ds -compact
.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
-.Em root ,
+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
.It Cm p
.Dq Preserve
the file mode bits.
-This is intended to be used by a
-.Em user
-with regular privileges who wants to preserve all aspects of the file other
-than the ownership.
+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
.Nm
will not set the
.Dv S_ISUID
-.Em ( setuid )
-and
+(setuid) and
.Dv S_ISGID
-.Em ( setgid )
-bits of the file mode.
+(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.
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 \*(Gt\*(Gt Em new-pathname
+.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.
.Pp
When
.Nm
-is in the
-.Em write
-or
-.Em copy
-mode, the optional trailing field
+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.
.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
-.Em read ,
+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
-.Em write ,
+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
-.Em copy ,
+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
-.Em list
-operation, produce a verbose table of contents using the format of the
+During a list operation, produce a verbose table of contents using the format of the
.Xr ls 1
utility with the
.Fl l
For pathnames representing a hard link to a previous member of the archive,
the output has the format:
.Pp
-.Dl Em ls -l listing Li == Em link-name
+.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 Li -\*(Gt Em link-name
+.Dl Em ls -l listing No -> Em link-name
.Pp
Where
.Em ls -l listing
.Fl l
option.
Otherwise for all the other operational modes
-.Po Em read , write , No and Em copy
-.Pc ,
+(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
.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
-.Em regular
-files,
-.Em hard links , soft links ,
-and
-.Em directories
+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
.Pc
interact as follows.
.Pp
-When extracting files during a
-.Em read
-operation, archive members are
+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 v
option will write the names resulting from these modifications.
.Pp
-When archiving files during a
-.Em write
-operation, or copying files during a
-.Em copy
-operation, archive members are
+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 ,
and
.Fl i
options will modify in that order, the names of these selected files.
-Then during a
-.Em copy
-operation the
+Then during a copy operation the
.Fl Y
and the
.Fl Z
Path in which to store temporary files.
.El
.Sh EXIT STATUS
-The
-.Nm
-utility exits with one of the following values:
-.Pp
-.Bl -tag -width Ds -offset indent -compact
-.It 0
-All files were processed successfully.
-.It 1
-An error occurred.
-.El
+.Ex -std pax
.Sh EXAMPLES
Copy the contents of the current directory to the device
.Pa /dev/rst0 :
.Em bin
and preserve all file permissions:
.Pp
-.Dl "$ pax -r -pe -U root -G bin -f a.pax"
+.Dl $ pax -r -pe -U root -G bin -f a.pax
.Pp
Update (and list) only those files in the destination directory
.Pa /backup
files with the same name found in the source file tree
.Pa home :
.Pp
-.Dl "$ pax -r -w -v -Y -Z home /backup"
+.Dl $ pax -r -w -v -Y -Z home /backup
.Sh DIAGNOSTICS
Whenever
.Nm
may have only partially created the archive, which may violate the specific
archive format specification.
.Pp
-If while doing a
-.Em copy ,
+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
.St -p1003.1-2008
specification,
except that the
-.Em pax
-archive format is unsupported and the
+.Cm pax
+archive format and the
+.Cm listopt
+keyword are unsupported, and the
.Ev TZ
environment variable is unused.
.Pp
The flags
.Op Fl 0BDEGjOPTUYZz ,
the archive formats
-.Em bcpio ,
-.Em sv4cpio ,
-.Em sv4crc ,
+.Cm bcpio ,
+.Cm sv4cpio ,
+.Cm sv4crc ,
and
-.Em tar ,
+.Cm tar ,
the
.Cm b , k ,
and
additions to the
.Fl b
flag,
-and the flawed archive handling during
-.Em list
-and
-.Em read
-operations
+and the flawed archive handling during list and read operations
are extensions to that specification.
.Sh AUTHORS
Keith Muller at the University of California, San Diego.