godi_pax − read and write file archives and copy directory hierarchies

godi_pax [−cdjvz] [−f archive] [−s replstr] ... [pattern ...]

godi_pax −r [−cdjkuvz] [−f archive] [−x format] [−o options] ... [−p string] ... [−s replstr] ... [pattern ...]

godi_pax −w [−djtuvz] [−f archive] [−x format] [−o options] ... [−s replstr] ... [file ...]

godi_pax −r −w [−djkltuvz] [−p string] ... [−s replstr] ... [file ...] directory

DESCRIPTION

godi_pax will read, write, and list the members of an archive file, and will copy directory hierarchies. godi_pax is a special implementation of the POSIX "pax" command for the purposes of GODI. A number of features are not implemented; in particular all features that would require super-user privileges. The "pax" command provides a unified interface to several archive formats. In this particular version, however, only (POSIX) "tar" is implemented. Note also that this version does not support magnetic tapes.

The presence of the −r and the −w options specifies which of the following functional modes godi_pax will operate under: list, read, write, and copy.

List. godi_pax 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 patterns. The table of contents contains one filename per line.

−r’ Read. godi_pax extracts the members of the archive file read from the standard input, with pathnames matching the specified patterns. The archive format is derived from the file name. When reading from stdin, the -x option must be passed to set the archive format (note that this is non-standard behavior). 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. If the archive contains absolute file names, or file names including ".." as part of the path name, extraction is refused, however. The setting of ownership, access and modification times, and file mode of the extracted files are discussed in more detail under the −p option.

−w’ Write. godi_pax writes an archive containing the file operands to standard output using the specified archive format. When no file operands are specified, a list of files to copy with one per line is read from standard input. When a file operand is also a directory, the entire file hierarchy rooted at that directory will be included.

−r −w
Copy. godi_pax copies the file operands to the destination directory. When no file operands are specified, a list of files to copy with one per line is read from the standard input. When a file operand is also a directory the entire file hierarchy rooted at that directory will be included. The effect of the copy is as if the copied files were written to an archive file and then subsequently extracted.

Warning: The destination directory must not be one of the file operands or a member of a file hierarchy rooted at one of the file operands. The result of a copy under these conditions is unpredictable.

This version of "pax" does not support reading from damaged archives.

OPERANDS

The directory operand specifies a destination directory pathname. If the directory operand does not exist, or it is not writable by the user, or it is not of type directory, godi_pax will exit with a non-zero exit status.

The pattern operand is used to select one or more pathnames of archive members. Archive members are selected using the pattern matching notation described by fnmatch(3). When the pattern operand is not supplied, all members of the archive will be selected. When a pattern matches a directory, the entire file hierarchy rooted at that directory will be selected. When a pattern operand does not select at least one archive member, godi_pax will write these pattern operands in a diagnostic message to standard error and then exit with a non-zero exit status.

The file operand specifies the pathname of a file to be copied or archived. When a file operand does not select at least one archive member, godi_pax will write these file operand pathnames in a diagnostic message to standard error and then exit with a non-zero exit status.

The following options are supported:

−w’ Write files to the standard output in the specified archive format. When no file operands are specified, standard input is read for a list of pathnames with one per line without any leading or trailing 〈blanks〉.

−a’ This standard POSIX option is not supported.

−b blocksize
This standard POSIX option is ignored.

−c’ Match all file or archive members except those specified by the pattern and file operands.

−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.

−f archive
Specify archive as the pathname of the input or output archive, overriding the default standard input (for list and read) or standard output (for write).

−i’ This standard POSIX option is not supported.

−j’ Use bzip2(1) for compression when reading or writing archive files. This option is automatically selected when the archive name has a ".bz" or ".bz2" suffix.

−k’ Do not overwrite existing files.

−l’ Link files. (The letter ell). This standard POSIX option is not supported.

−n’ This standard POSIX option is not supported.

−o options
Information to modify the algorithm for extracting or writing archive files which is specific to the archive format specified by −x. In general, options take the form: name=value

−p string
Specify one or more file characteristic options (privileges). The string option-argument is a string specifying file characteristics to be retained or discarded on extraction. The string consists of the specification characters a, e, f, m, o, and p. Multiple characteristics can be concatenated within the same string and multiple −p options can be specified. The meaning of the specification characters are as follows:

a
This option is ignored for POSIX compatibility.

e
This option is ignored for POSIX compatibility.

m
Do not preserve file modification times. By default, file modification times are preserved whenever possible.

o
This option is ignored for POSIX compatibility.

p
This option is ignored for POSIX compatibility.

In the preceding list, ’preserve’ indicates that an attribute stored in the archive is given to the extracted file, subject to the permissions of the invoking process. Otherwise, directories are created using the default permission attributes, and for regular files only the owner’s file attributes are taken into account.

−s replstr
Modify the file or archive member names specified by the pattern or file operands according to the substitution expression replstr, using the syntax of the ed(1) utility regular expressions. The format of these regular expressions are: /old/new/[gp] As in ed(1), old is a basic regular expression and new can contain an ampersand (&), \n (where n is a digit) back-references, or subexpression matching. The old string may also contain 〈newline〉 characters. Any non-null character can be used as a delimiter (/ is shown here). Multiple −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. The optional trailing 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 g option. The optional trailing p will cause the final result of a successful substitution to be written to standard error in the following format: 〈
original pathname〉 >> 〈
new pathname〉 File or archive member names that substitute to the empty string are not selected and will be skipped.

−t’ This standard POSIX option is not supported.

−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.

−v’ During a list operation, produce a verbose table of contents using the format of the ls(1) utility with the −l option. For pathnames representing a hard link to a previous member of the archive, the output has the format: 〈
ls -l listing〉 == 〈
link name〉 Where 〈ls -l listing〉 is the output format specified by the ls(1) utility when used with the −l option. Otherwise for all the other operational modes (read, write, and copy), the pathnames being processed are written to stdout.

−x format
Specify the output archive format, with the default format being ustar. godi_pax currently supports the following formats:

ustar’ The extended tar interchange format specified in the IEEE Std 1003.2 (‘‘POSIX.2’’) standard. Pathnames stored by this format must be 250 characters or less in length.

godi_pax 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.

−z’ Use gzip(1) compression, when reading or writing archive files. This option is automatically selected if the archive file name has ".gz" suffix.

−X’ This standard POSIX option is not supported.

The options that operate on the names of files or archive members (−c, −s, −u, −v) interact as follows.

When extracting files during a read operation, archive members are ’selected’, based only on the user specified pattern operands as modified by the −c, −u options. Then any −s options will modify in that order, the names of these selected files. Finally the −v option will write the names resulting from these modifications.

When archiving files during a write operation, or copying files during a copy operation, archive members are ’selected’, based only on the user specified pathnames as modified by the −u options. Then any −s options will modify in that order, the names of these selected files. Finally the −v option will write the names resulting from these modifications.

EXAMPLES

The command:

godi_pax -w -f /tmp/sample.tar .

copies the contents of the current directory to the file /tmp/sample.tar.

The command:

godi_pax -v -f filename

gives the verbose table of contents for an archive stored in filename.

The following commands:

mkdir newdir

cd olddir

godi_pax -rw -pp . ../newdir

will copy the entire olddir directory hierarchy to newdir, preserving permissions and access times (as far as implemented).

The command:

godi_pax -r -s ’,^//*usr//*,,’ -f a.tar

reads the archive a.tar, with all files rooted in ‘‘/usr’’ into the archive extracted relative to the current directory.

godi_pax will exit with one of the following values:

All files were processed successfully.

1
An error occurred.

This version of "pax" stops as soon as the first non-ignorable error occurs. In this case, a diagnostic message is written to standard error and a non-zero exit status will be returned

If the extraction of a file from an archive is prematurely terminated by a signal or error, godi_pax 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.

If the creation of an archive is prematurely terminated by a signal or error, godi_pax may have only partially created the archive which may violate the specific archive format specification.

If while doing a copy, godi_pax detects a file is about to overwrite itself, this is considered as an error.

STANDARDS

The godi_pax utility is a subset of the IEEE Std 1003.2 (‘‘POSIX.2’’) standard.

Gerd Stolpmann

GODI May 26, 2008 GODI