add a cpio implementation to tools directory

cpio utility is a mess in point of portability.
For example NetBSD cpio implementation does not support
userid and groupid changes for the archive. This
feature is required for initramfs filesystem targets.
This cpio is from the Heirloom project.

Fix needed rebuild of tools, when changing targets.

1 files changed, 919 insertions, 0 deletions

diff --git a/tools/cpio/src/pax.1 b/tools/cpio/src/pax.1
new file mode 100644
index 000000000..4fb9206f9
--- /dev/null
+++ b/tools/cpio/src/pax.1
@@ -0,0 +1,919 @@
+'\" t
+.\" Copyright (c) 2004 Gunnar Ritter
+.\"
+.\" This software is provided 'as-is', without any express or implied
+.\" warranty. In no event will the authors be held liable for any damages
+.\" arising from the use of this software.
+.\"
+.\" Permission is granted to anyone to use this software for any purpose,
+.\" including commercial applications, and to alter it and redistribute
+.\" it freely, subject to the following restrictions:
+.\"
+.\" 1. The origin of this software must not be misrepresented; you must not
+.\"    claim that you wrote the original software. If you use this software
+.\"    in a product, an acknowledgment in the product documentation would be
+.\"    appreciated but is not required.
+.\"
+.\" 2. Altered source versions must be plainly marked as such, and must not be
+.\"    misrepresented as being the original software.
+.\"
+.\" 3. This notice may not be removed or altered from any source distribution.
+.\" Sccsid @(#)pax.1	1.38 (gritter) 8/13/09
+.TH PAX 1 "8/13/09" "Heirloom Toolchest" "User Commands"
+.SH NAME
+pax \- portable archive interchange
+.SH SYNOPSIS
+.PD 0
+.HP
+.nh
+.ad l
+\fBpax\fR [\fB\-cdnvK\fR] [\fB\-b\ \fIsize\fR]
+[\fB\-f\ \fIfile\fR] [\fB\-s\ \fIreplstr\fR]
+[\fB\-x\ \fIhdr\fR] [\fIpatterns\fR]
+.HP
+.ad l
+\fBpax\fR \fB\-r\fR[\fBcdiknuvK\fR] [\fB\-b\ \fIsize\fR]
+[\fB\-f\ \fIfile\fR]
+[\fB\-o\ \fIoptions\fR]
+[\fB\-p\ \fIpriv\fR] [\fB\-s\ \fIreplstr\fR]
+[\fB\-x\ \fIhdr\fR] [\fIpatterns\fR]
+.HP
+.ad l
+\fBpax\fR \fB\-w\fR[\fBadiHtuvLX\fR] [\fB\-b\ \fIsize\fR]
+[\fB\-f\ \fIfile\fR]
+[\fB\-o\ \fIoptions\fR]
+[\fB\-s\ \fIreplstr\fR]
+[\fB\-x\ \fIhdr\fR] [\fIfiles\fR]
+.HP
+.ad l
+\fBpax\fR \fB\-rw\fR[\fBdiHklntuvLX\fR]
+[\fB\-p\ \fIpriv\fR] [\fB\-s\ \fIreplstr\fR]
+[\fIfiles\fR] \fIdirectory\fR
+.br
+.ad b
+.hy 1
+.PD
+.SH DESCRIPTION
+.I Pax
+creates and extracts file archives and copies files.
+.PP
+If neither the
+.I \-r
+or
+.I \-w
+options are given,
+.I pax
+works in
+.I list
+mode
+and prints the contents of the archive.
+.PP
+With the
+.B \-r
+option,
+.I pax
+works in
+.RI ` read '
+mode and extracts files from a file archive.
+By default,
+the archive is read from standard input.
+Optional arguments are interpreted as
+.I patterns
+and restrict the set of extracted files
+to those matching any of the
+.IR patterns .
+The syntax is identical to that described in
+.IR glob (7),
+except that the slash character
+.RB ` / '
+is matched by
+meta-character constructs with
+.RB ` * ',
+.RB ` ? '
+and
+.RB ` [ '.
+Care must be taken to quote meta-characters appropriately from the shell.
+If a pattern matches the prefix name of a directory in the archive,
+all files below that directory are also extracted.
+File permissions are set to those in the archive;
+if the caller is the super-user,
+ownerships are restored as well.
+options are specified.
+Archives compressed with
+.IR bzip2 (1),
+.IR compress (1),
+.IR gzip (1),
+or
+.IR rpm (1)
+are transparently de\%compressed on input.
+.PP
+With
+.BR \-w ,
+.I pax
+works in
+.RI ` write '
+mode,
+creates archives
+and writes them to standard output per default.
+A list of filenames to be included in the archive is
+read from standard input;
+if the name of a directory appears,
+all its members and the directory itself are recursively
+included in the archive.
+The
+.IR find (1)
+utility is useful to generate a list of files
+(see also its
+.I \-cpio
+and
+.I \-ncpio
+operators).
+When producing a filename list for
+.IR pax ,
+find should always be invoked with
+.I \-depth
+since this makes it possible to extract write-protected directories
+for users other than the super-user.
+If
+.I files
+are given on the command line,
+they are included in the archive
+in the same manner as described above
+and standard input is not read.
+.PP
+The
+.B \-rw
+options selects
+.RI ` copy '
+mode;
+a list of
+.I files
+is read from standard input
+or taken from the command line
+as described for
+.IR \-w ;
+files are copied to the specified
+.IR directory ,
+preserving attributes as described for
+.IR \-r .
+Special files are re-created in the target hierarchy,
+and hard links between copied files are preserved.
+.PP
+When a premature end-of-file is detected with
+.I \-r
+and
+.I \-w
+and the archive is a block or character special file,
+the user is prompted for new media.
+.PP
+The following options alter the behavior of
+.IR pax :
+.TP
+.B \-a
+Append files to the archive.
+The archive must be seekable,
+such as a regular file or a block device,
+or a tape device capable of writing between filemarks.
+.TP
+\fB\-b\fI size\fR[\fBw\fR|\fBb\fR|\fBk\fR|\fBm\fR]
+Blocks input and output archives at
+.I size
+byte records.
+The optional suffix multiplies
+.I size
+by 2 for
+.BR w ,
+512 for
+.BR b ,
+1024 for
+.BR k ,
+and 1048576 for
+.BR m .
+.TP
+.B \-c
+Reverses the sense of patterns
+such that a file that does not match any of the patterns
+is selected.
+.TP
+.B \-d
+Causes
+.I pax
+to ignore files below directories.
+In read mode,
+patterns matching directories
+cause only the directory itself to extracted,
+files below will be ignored
+unless another pattern applies to them.
+In write mode,
+arguments or standard input lines referring to directories
+do not cause files below the respective directory
+to be archived.
+.TP
+\fB\-f\fI\ file\fR
+Selects a
+.I file
+that is read with the
+.I \-r
+option instead of standard input
+or written with the
+.I \-w
+option instead of standard output.
+.TP
+.B \-H
+Follow symbolic links given on the command line when reading files with
+.I \-w
+or
+.IR \-rw ,
+but do not follow symbolic links encountered during directory traversal.
+.TP
+.B \-i
+Rename files interactively.
+Before a file is extracted from the archive,
+its file name is printed on standard error
+and the user is prompted to specify a substitute file name.
+If the line read from the terminal is empty,
+the file is skipped;
+if the line consists of a single dot,
+the name is retained;
+otherwise,
+the line forms the new file name.
+.TP
+.B \-k
+Causes existing files not to be overwritten.
+.TP
+.B \-K
+Try to continue operation on read errors and invalid headers.
+If an archive contains another archive,
+files from either archive may be chosen.
+.TP
+.B \-l
+Link files instead of copying them with
+.I \-rw
+if possible.
+.TP
+.B \-L
+Follow symbolic links when reading files with
+.I \-w
+or
+.IR \-rw .
+.B /usr/posix2001/bin/pax
+terminates immediately when it
+detects a symbolic link loop with this option.
+.TP
+.B \-n
+If any
+.I pattern
+arguments are present,
+each pattern can match exactly one archive member;
+further members that could match the particular pattern are ignored.
+Without
+.I pattern
+arguments,
+only the first occurence of
+a file that occurs more than once in the archive
+is selected, the following are ignored.
+.TP
+\fB\-o\ \fIoption\fB,\fR[\fIoption\fB,\fR\|...]
+Specifies options as described for \fI\-x pax\fR.
+.TP
+\fB\-p\ \fIstring\fR
+Specifies which file modes are to be preserved or ignored.
+.I string
+may contain one or more of
+.RS
+.TP
+.B a
+Inhibits preservation of file access times.
+.TP
+.B e
+Causes preservation of every possible mode, ownership and time.
+.TP
+.B m
+Inhibits preservation of file modification times.
+.TP
+.B o
+Causes preservation of owner and group IDs.
+.TP
+.B p
+Causes preservation of file mode bits
+regardless of the umask
+(see
+.IR umask (2)).
+.RE
+.IP
+If file ownership is preserved,
+.I pax
+tries to set the group ownerships to those specified in the archive
+or the original hierarchy, respectively,
+regardless of the privilegues of the invoking user.
+.BR /usr/5bin/pax ,
+.BR /usr/5bin/s42/pax ,
+and
+.B /usr/5bin/posix/pax
+try to set the user ownerships only if invoked by the super-user;
+if invoked by regular users,
+.B /usr/5bin/posix2001/pax
+will produce an error for any file that is not owned by the invoking user.
+.TP
+\fB\-s\ /\fIregular expression\fB/\fIreplacement\fB/\fR[\fBgp\fR]
+Modifies file names in a manner similar to that described in
+.IR ed (1).
+The
+.I p
+flag causes each modified file name to printed.
+Any character can be used as delimiter instead of
+.RI ` / '.
+If a file name is empty after the replacement is done,
+the file is ignored.
+This option can be specified multiple times
+to execute multiple substitutions in the order specified.
+.TP
+.B \-t
+Resets the access times of files
+that were included in the archive with
+.IR \-r .
+.TP
+.B \-u
+In read mode,
+.I pax
+will not overwrite existing target files
+that were modified more recently than the file in the archive
+when this option is given.
+In write mode,
+.I pax
+will read the archive first.
+It will then only append those files to the archive
+that are not already included
+or were more recently modified.
+.TP
+.B \-v
+Prints the file names of archived or extracted files with
+.I \-r
+and
+.I \-w
+and a verbose output format
+if neither of them is given.
+.TP
+\fB\-x\fI header\fR
+Specifies the archive header format to be one of:
+.sp
+.in +6
+.TS
+lfB l.
+\fBnewc\fR	SVR4 ASCII cpio format;\ 
+\fBcrc\fR	SVR4 ASCII cpio format with checksum;\ 
+\fBsco\fR	T{
+SCO UnixWare 7.1 ASCII cpio format;
+T}
+\fBscocrc\fR	T{
+SCO UnixWare 7.1 ASCII cpio format with checksum;
+T}
+\fBodc\fR	T{
+traditional ASCII cpio format, as standardized in IEEE Std. 1003.1, 1996;
+T}
+\fBcpio\fR	T{
+same as \fIodc\fR;
+T}
+\fBbin\fR	binary cpio format;
+\fBbbs\fR	byte-swapped binary cpio format;
+\fBsgi\fR	T{
+SGI IRIX extended binary cpio format;
+T}
+\fBcray\fR	T{
+Cray UNICOS 9 cpio format;
+T}
+\fBcray5\fR	T{
+Cray UNICOS 5 cpio format;
+T}
+\fBdec\fR	T{
+Digital UNIX extended cpio format;
+T}
+\fBtar\fR	tar format;
+\fBotar\fR	old tar format;
+\fBustar\fR	T{
+IEEE Std. 1003.1, 1996 tar format;
+T}
+.T&
+l s.
+\fBpax\fR[\fB:\fIoption\fB,\fR[\fIoption\fB,\fR\|...]]
+.T&
+l l.
+\&	T{
+IEEE Std. 1003.1, 2001 pax format.
+Format-specific \fIoptions\fR are:
+.in +2n
+.ti 0
+.br
+\fBlinkdata\fR
+.br
+For a regular file which has multiple hard links,
+the file data is stored once for each link in the archive,
+instead of being stored for the first entry only.
+This option must be used with care
+since many implementations are unable
+to read the resulting archive.
+.ti 0
+.br                                                                            
+\fBtimes\fR
+.br
+Causes the times of last access and last modification
+of each archived file
+to be stored in an extended \fIpax\fR header.
+This in particular allows the time of last access
+to be restored when the archive is read.
+.br
+.in -2n
+T}
+\fBsun\fR	T{
+Sun Solaris 7 extended tar format;
+T}
+\fBbar\fR	T{
+SunOS 4 bar format;
+T}
+\fBgnu\fR	T{
+GNU tar format;
+T}
+\fBzip\fR[\fB:\fIcc\fR]	T{
+zip format with optional compression method.
+If \fIcc\fR is one of
+\fBen\fR (normal, default),
+\fBex\fR (extra),
+\fBef\fR (fast),
+or
+\fBes\fR (super fast),
+the standard \fIdeflate\fR compression is used.
+\fBe0\fR selects no compression,
+and
+\fBbz2\fR selects \fIbzip2\fR compression.
+T}
+.TE
+.in -6
+.sp
+This option is ignored with
+.I \-r
+unless the
+.I \-K
+option is also present.
+The default for
+.I \-w
+is traditional ASCII cpio
+.I (odc)
+format.
+.PP
+.ne 38
+Characteristics of archive formats are as follows:
+.sp
+.TS
+allbox;
+l r r r l
+l1fB r2 n2 r2 c.
+	T{
+.ad l
+maximum user/\%group id
+T}	T{
+.ad l
+maximum file size
+T}	T{
+.ad l
+maximum pathname length
+T}	T{
+.ad l
+bits in dev_t (major/minor)
+T}
+\-x\ bin	65535	2 GB\ 	256	\ 16
+\-x\ sgi	65535	9 EB\ 	256	\ 14/18
+T{
+\-x\ odc
+T}	262143	8 GB\ 	256	\ 18
+\-x\ dec	262143	8 GB\ 	256	\ 24/24
+T{
+\-x\ newc,
+\-x\ crc
+T}	4.3e9	4 GB\ 	1024	\ 32/32
+T{
+\-x\ sco, \-x\ scocrc
+T}	4.3e9	9 EB\ 	1024	\ 32/32
+T{
+\-x\ cray, \-x\ cray5
+T}	1.8e19	9 EB\ 	65535	\ 64
+\-x\ otar	2097151	8 GB\ 	99	\ n/a
+T{
+\-x\ tar,
+\-x\ ustar
+T}	2097151	8 GB\ 	256 (99)	\ 21/21
+\-x\ pax	1.8e19	9 EB\ 	65535	\ 21/21
+\-x\ sun	1.8e19	9 EB\ 	65535	\ 63/63
+\-x\ gnu	1.8e19	9 EB\ 	65535	\ 63/63
+\-x\ bar	2097151	8 GB\ 	427	\ 21
+\-x\ zip	4.3e9	9 EB\ 	60000	\ 32
+.TE
+.sp
+.PP
+The byte order of
+.B binary
+cpio archives
+depends on the machine
+on which the archive is created.
+Unlike some other implementations,
+.I pax
+fully supports
+archives of either byte order.
+.I \-x\ bbs
+can be used to create an archive
+with the byte order opposed to that of the current machine.
+.PP
+The
+.B sgi
+format extends the binary format
+to handle larger files and more device bits.
+If an archive does not contain any entries
+that actually need the extensions,
+it is identical to a binary archive.
+.I \-x\ sgi
+archives are always created in MSB order.
+.PP
+The
+.B odc
+format was introduced with System\ III
+and standardized with IEEE Std. 1003.1.
+All known
+.I cpio
+and
+.I pax
+implementations since around 1980 can read this format.
+.PP
+The
+.B dec
+format extends the
+.I odc
+format
+to support more device bits.
+Archives in this format are generally incompatible with
+.I odc
+archives
+and need special implementation support to be read.
+.PP
+The
+.B \-x\ newc
+format was introduced with System\ V Release\ 4.
+Except for the file size,
+it imposes no practical limitations
+on files archived.
+The original SVR4 implementation
+stores the contents of hard linked files
+only once and with the last archived link.
+This
+.I pax
+ensures compatibility with SVR4.
+With archives created by implementations that employ other methods
+for storing hard linked files,
+each file is extracted as a single link,
+and some of these files may be empty.
+Implementations that expect methods other than the original SVR4 one
+may extract no data for hard linked files at all.
+.PP
+The
+.B crc
+format is essentially the same as the
+.I \-x\ newc
+format
+but adds a simple checksum (not a CRC, despite its name)
+for the data of regular files.
+The checksum requires the implementation to read each file twice,
+which can considerably increase running time and system overhead.
+As not all implementations claiming to support this format
+handle the checksum correctly,
+it is of limited use.
+.PP
+The
+.B sco
+and
+.B scocrc
+formats are variants of the
+.I \-x\ newc
+and
+.I \-x\ crc
+formats, respectively,
+with extensions to support larger files.
+The extensions result in a different archive format
+only if files larger than slightly below 2\ GB occur.
+.PP
+The
+.B cray
+format extends all header fields to 64 bits.
+It thus imposes no practical limitations of any kind
+on archived files,
+but requires special implementation support
+to be read.
+Although it is originally a binary format,
+the byte order is always MSB as on Cray machines.
+The
+.B cray5
+format is an older variant
+that was used with UNICOS 5 and earlier.
+.PP
+The
+.B otar
+format was introduced with the Unix 7th Edition
+.I tar
+utility.
+Archives in this format
+can be read on all Unix systems since about 1980.
+It can only hold regular files
+(and, on more recent systems, symbolic links).
+For file names that contain characters with the most significant bit set
+(non-ASCII characters),
+implementations differ in the interpretation of the header checksum.
+.PP
+The
+.B ustar
+format was introduced with IEEE Std. 1003.1.
+It extends the old
+.I tar
+format
+with support for directories, device files,
+and longer file names.
+Pathnames of single-linked files can consist of up to 256 characters,
+dependent on the position of slashes.
+Files with multiple links can only be archived
+if the first link encountered is no longer than 100 characters.
+Due to implementation errors,
+file names longer than 99 characters
+can not considered to be generally portable.
+Another addition of the
+.I ustar
+format
+are fields for the symbolic user and group IDs.
+These fields are created by
+.IR pax ,
+but ignored when reading such archives.
+.PP
+With
+.BR "\-x tar" ,
+a variant of the
+.I ustar
+format is selected
+which stores file type bits in the mode field
+to work around common implementation problems.
+These bits are ignored by
+.I pax
+when reading archives.
+.PP
+The
+.B pax
+format is an extension to the
+.I ustar
+format.
+If attributes cannot be archived with
+.IR ustar ,
+an extended header is written.
+Unless the size of an entry is greater than 8\ GB,
+a
+.I pax
+archive should be readable by any implementation                               
+capable of reading
+.I ustar
+archives,
+although files may be extracted under wrong names
+and extended headers may be extracted as separate files.
+If a file name contains non-UTF-8 characters,
+it may not be archived or extracted correctly
+because of a problem of the
+.I pax
+format specification.
+.PP
+The
+.B sun
+format extends the
+.I ustar
+format similar as the
+.I pax
+format does.
+The extended headers in
+.I sun
+format archives are not understood
+by implementations that support only the
+.I pax
+format and vice-versa.
+The
+.I sun
+format has also problems with non-UTF-8 characters in file names.
+.PP
+The
+.B GNU
+.I tar
+format is mostly compatible with the other
+.I tar
+formats,
+unless an archive entry actually uses its extended features.
+There are no practical limitations on files archived with this format.
+The implementation of
+.I pax
+is limited to expanded numerical fields
+and long file names;
+in particular,
+there is no support for sparse files or incremental backups.
+If
+.I pax
+creates a multi-volume
+.I GNU
+archive,
+it just splits a single-volume archive in multiple parts,
+as with the other formats;
+.I GNU
+multi-volume archives are not supported.
+.PP
+The
+.B bar
+format is similar to the
+.I tar
+format, but can store longer file names.
+It requires special implementation support to be read.
+.PP
+The
+.B zip
+format can be read in many non-Unix environments.
+There are several restrictions on archives
+intended for data exchange:
+only regular files should be stored;
+file times, permissions and ownerships
+might be ignored by other implementations;
+there should be no more than 65536 files in the archive;
+the total archive size should not exceed 2 GB;
+only
+.I deflate
+compression should be used.
+Otherwise,
+.I pax
+stores all information available with other archive formats
+in extended
+.I zip
+file headers,
+so if archive portability is of no concern,
+the
+.I zip
+implementation in
+.I pax
+can archive complete Unix file hierarchies.
+.I Pax
+supports the
+.I zip64
+format extension for large files;
+it automatically writes
+.I zip64
+entries if necessary.
+.I Pax
+can extract all known
+.I zip
+format compression codes.
+It does not support
+.I zip
+encryption.
+Multi-volume
+.I zip
+archives are created as splitted single-volume archives,
+as with the other formats written by
+.IR pax ;
+generic multi-volume
+.I zip
+archives are not supported.
+.SH EXAMPLES
+Extract all files named
+.I Makefile
+or
+.I makefile
+from the archive stored on
+.IR /dev/rmt/c0s0 ,
+overwriting recent files:
+.RS 2
+.sp
+pax \-r \-f /dev/rmt/c0s0 \'[Mm]akefile\' \'*/[Mm]akefile\'
+.RE
+.PP
+List the files contained in a software distribution archive:
+.RS 2
+.sp
+pax \-v \-f distribution.tar.gz
+.RE
+.PP
+Write a
+.IR gzip (1)
+compressed
+.I ustar
+archive containing all files below the directory
+.I \%project
+to the file
+.IR \%project.tar.gz ,
+excluding all directories named
+.I CVS
+or
+.I SCCS
+and their contents:
+.RS 2
+.sp
+find project \-depth \-print | egrep \-v \'/(CVS|SCCS)(/|$)\' |
+.br
+      pax \-wd \-x ustar | gzip \-c > project.tar.gz
+.RE
+.PP
+Copy the directory
+.I work
+and its contents
+to the directory
+.IR \%savedfiles ,
+preserving all file attributes:
+.RS 2
+.sp
+pax \-rw \-pe work savedfiles
+.RE
+.PP
+Self-extracting zip archives are not automatically recognized,
+but can normally be read using the
+.I \-K
+option, as with
+.RS 2
+.sp
+pax \-rK \-x zip \-f archive.exe
+.sp
+.RE
+.SH "ENVIRONMENT VARIABLES"
+.TP
+.BR LANG ", " LC_ALL
+See
+.IR locale (7).
+.TP
+.B LC_CTYPE
+Selects the mapping of bytes to characters
+used for matching patterns
+and regular expressions.
+.TP
+.B LC_TIME
+Sets the month names printed in list mode.
+.SH "SEE ALSO"
+cpio(1),
+find(1),
+tar(1)
+.SH DIAGNOSTICS
+.I Pax
+exits with
+.sp
+.TS
+l8fB l.
+0	after successful operation;
+1	on usage errors;
+2	when operation was continued after minor errors;
+3	on fatal error conditions.
+.TE
+.SH NOTES
+Device and inode numbers
+are used for hard link recognition
+with the various cpio formats.
+Since the header space cannot hold
+large numbers present in current file systems,
+devices and inode numbers are set on a per-archive basis.
+This enables hard link recognition with all cpio formats,
+but the link connection to files appended with
+.I \-a
+is not preserved.
+.PP
+If a numeric user or group id does not fit
+within the size of the header field in the selected format,
+files are stored with the user id (or group id, respectively)
+set to 60001.
+.PP
+Use of the
+.I \-a
+option with a
+.I zip
+format archive may cause data loss
+if the archive was not previously created by
+.I cpio
+or
+.I pax
+itself.
+.PP
+If the file names passed to
+.I "pax -w"
+begin with a slash character,
+absolute path names are stored in the archive
+and will be extracted to these path names later
+regardless of the current working directory.
+This is normally not advisable,
+and relative path names should be passed to
+.I pax
+only.
+The
+.I \-s
+option can be used to substitute relative for absolute path names
+and vice-versa.
+.PP
+.I Pax
+does not currently accept the
+\fB\-o delete\fR,
+\fB\-o exthdr.name\fR,
+\fB\-o globexthdr.name\fR,
+\fB\-o invalid\fR,
+\fB\-o listopt\fR,
+and
+\fB\-o keyword\fR
+options from POSIX.1-2001.