Windows PowerShell command on Get-command pax

Manual Pages for UNIX Operating System command usage for man pax

User Commands pax(1)

NAME

pax - portable archive interchange

SYNOPSIS

pax [-cdnv] [-H | -L] [-f archive] [-o options]...

[-s replstr]... [pattern]...

pax -r [-cdiknuv@/] [-H | -L] [-f archive] [-o options]...

[-p string]... [-s replstr]... [pattern]...

pax -w [-dituvX@/] [-H | -L] [-b blocksize] [-a]

[-f archive] [-o options]... [-s replstr]...

[-x format] [file]...

pax -r -w [-diklntuvX@/] [-H | -L] [-o options]...

[-p string]... [-s replstr]... [file]... directory

DESCRIPTION

pax reads, writes, and writes lists of the members of

archive files and copies directory hierarchies. A variety of

archive formats are supported. See the -x format option.

Modes of Operations

The action to be taken depends on the presence of the -r and

-w options. The four combinations of -r and -w are referred

to as the four modes of operation: list, read, write, and copy modes, corresponding respectively to the four forms

shown in the SYNOPSIS.

list In list mode, that is, when neither -r nor -w are

specified, pax writes the names of the members of

the archive file read from the standard input, with path names matching the specified patterns, to standard output. If a named file has extended attributes, the extended attributes are also listed. If a named file is of type directory, the file hierarchy rooted at that file is listed as well.

read In read mode, that is, when -r is specified, but -w

is not, pax extracts the members of the archive

file read from the standard input, with path names matching the specified patterns. If an extracted file is of type directory, the file hierarchy rooted at that file is extracted as well. The extracted files are created performing path name

resolution with the directory in which pax was

SunOS 5.11 Last change: 16 Jul 2008 1

User Commands pax(1)

invoked as the current working directory. If an attempt is made to extract a directory when

the directory already exists, this is not con-

sidered an error. If an attempt is made to extract a FIFO when the FIFO already exists, this is not considered an error. The ownership, access and modification times, and file mode of the restored files are discussed under

the -p option.

write In write mode, that is, when -w is specified, but

-r is not, pax writes the contents of the file

operands to the standard output in an archive for-

mat. If no file operands are specified, a list of files to copy, one per line, are read from the standard input. A file of type directory includes all of the files in the file hierarchy rooted at the file.

copy In copy mode, that is, when both -r and -w are

specified, pax copies the file operands to the des-

tination directory. If no file operands are specified, a list of files to copy, one per line, are read from the standard input. A file of type directory includes all of the files in the file hierarchy rooted at the file. The effect of the copy is as if the copied files

were written to an archive file and then subse-

quently extracted, except that there can be hard links between the original and the copied files. If the destination directory is a subdirectory of one

of the files to be copied, the results are unspeci-

fied. It is an error if directory does not exist, is not writable by the user, or is not a directory. In read or copy modes, if intermediate directories are

necessary to extract an archive member, pax performs actions

equivalent to the mkdir(2) function, called with the follow-

ing arguments:

o The intermediate directory used as the path argu-

ment. o The octal value of 777 or rwx (read, write, and

SunOS 5.11 Last change: 16 Jul 2008 2

User Commands pax(1)

execute permissions) as the mode argument (see chmod(1)). If any specified pattern or file operands are not matched by

at least one file or archive member, pax writes a diagnostic

message to standard error for each one that did not match

and exits with a non-zero exit status.

The supported archive formats are automatically detected on input. The default output archive format is tar(1).

A single archive can span multiple files. pax determines

what file to read or write as the next file. If the selected archive format supports the specification of linked files, it is an error if these files cannot be linked when the archive is extracted, except if the files to be linked are symbolic links and the system is not capable of making hard links to symbolic links. In that case, separate copies of the symbolic link are created instead. Any of the various names in the archive that represent a file can be used to select the file for extraction. For archive formats that do not store file contents with each name that causes a hard link, if the file that contains the data is not

extracted during this pax session, either the data is

restored from the original file, or a diagnostic message is displayed with the name of a file that can be used to

extract the data. In traversing directories, pax detects

infinite loops, that is, entering a previously visited directory that is an ancestor of the last file visited. When

it detects an infinite loop, pax writes a diagnostic message

to standard error and terminates. OPTIONS The following options are supported:

-a Appends files to the end of the archive.

This option does not work for some archive

devices, such as 1/4-inch streaming tapes

and 8mm tapes.

-b blocksize Blocks the output at a positive decimal

integer number of bytes per write to the archive file. Devices and archive formats

can impose restrictions on blocking. Block-

ing is automatically determined on input. Portable applications must not specify a

SunOS 5.11 Last change: 16 Jul 2008 3

User Commands pax(1)

blocksize value larger than 32256. Default blocking when creating archives depends on

the archive format. See the -x option below.

-c Matches all file or archive members except

those specified by the pattern or file operands.

-d Causes files of type directory being copied

or archived or archive members of type directory being extracted or listed to match only the file or archive member itself and not the file hierarchy rooted at the file.

-f archive Specifies the path name of the input or out-

put archive, overriding the default standard input (in list or read modes) or standard output (write mode).

-H If a symbolic link referencing a file of

type directory is specified on the command

line, pax archives the file hierarchy rooted

in the file referenced by the link, using the name of the link as the root of the file hierarchy. Otherwise, if a symbolic link referencing a file of any other file type

which pax can normally archive is specified

on the command line, then pax archives the

file referenced by the link, using the name of the link. The default behavior is to archive the symbolic link itself.

-i Interactively renames files or archive

members. For each archive member matching a pattern operand or file matching a file operand, a prompt is written to the file /dev/tty. The prompt contains the name of the file or archive member. A line is then read from /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. pax immediately exits with a non-zero

exit status if end-of-file is encountered

when reading a response or if /dev/tty

SunOS 5.11 Last change: 16 Jul 2008 4

User Commands pax(1)

cannot be opened for reading and writing. The results of extracting a hard link to a file that has been renamed during extraction are unspecified.

-k Prevents the overwriting of existing files.

-l Links files. In copy mode, hard links are

made between the source and destination file hierarchies whenever possible. If specified

in conjunction with -H or -L, when a sym-

bolic link is encountered, the hard link created in the destination file hierarchy is to the file referenced by the symbolic link.

If specified when neither -H nor -L is

specified, when a symbolic link is encoun-

tered, the implementation creates a hard link to the symbolic link in the source file hierarchy or copies the symbolic link to the destination.

-L If a symbolic link referencing a file of

type directory is specified on the command line or encountered during the traversal of

a file hierarchy, pax archives the file

hierarchy rooted in the file referenced by the link, using the name of the link as the root of the file hierarchy. Otherwise, if a symbolic link referencing a file of any

other file type which pax can normally

archive is specified on the command line or encountered during the traversal of a file

hierarchy, pax archives the file referenced

by the link, using the name of the link. The default behavior is to archive the symbolic link itself.

-n Selects the first archive member that

matches each pattern operand. No more than

one archive member is matched for each pat-

tern, although members of type directory still match the file hierarchy rooted at that file.

-o options Provides information to the implementation

to modify the algorithm for extracting or

SunOS 5.11 Last change: 16 Jul 2008 5

User Commands pax(1)

writing files. The value of options consists

of one or more comma-separated keywords of

the form: keyword[[:]=value][,keyword[[:]=value], ...] Some keywords apply only to certain file formats, as indicated with each description. Use of keywords that are inapplicable to the

file format being processed produces unde-

fined results. Keywords in the options argument must be a string that would be a valid portable filename. Keywords are not expected to be filenames,

merely to follow the same character composi-

tion rules as portable filenames. Keywords can be preceded with white space. The value field consists of zero or more characters. Within value, the application precedes any literal comma with a backslash, which is ignored, but preserves the comma as

part of value. A comma as the final charac-

ter, or a comma followed solely by white space as the final characters, in options is

ignored. Multiple -o options can be speci-

fied. If keywords given to these multiple -o

options conflict, the keywords and values appearing later in command line sequence take precedence and the earlier ones are silently ignored. The following keyword values of options are supported for the file formats as indicated: delete=pattern This keyword is applicable only to the

-x pax format. When used in write or

copy mode, pax omits from extended

header records that it produces any key-

words matching the string pattern. When

used in read or list mode, pax ignores

any keywords matching the string pattern in the extended header records. In both cases, matching is performed using the pattern matching notation. For example:

-o delete=security.*

SunOS 5.11 Last change: 16 Jul 2008 6

User Commands pax(1)

would suppress security-related informa-

tion.

When multiple -o delete=pattern options

are specified, the patterns are addi-

tive. All keywords matching the speci-

fied string patterns are omitted from

extended header records that pax pro-

duces. exthdr.name=string This keyword is applicable only to the

-x pax format. This keyword allows user

control over the name that is written into the ustar header blocks for the

extended header. The name is the con-

tents of string, after the following character substitutions have been made:

%d The directory name of the file,

equivalent to the result of the dirname utility on the translated path name.

%f The filename of the file,

equivalent to the result of the basename utility on the translated path name.

%p The process ID of the pax process.

%% A '%' character.

Any other '%' characters in string pro-

duce undefined results.

If no -o exthdr.name=string is speci-

fied, pax uses the following default

value:

%d/PaxHeaders.%p/%f

globexthdr.name=string

SunOS 5.11 Last change: 16 Jul 2008 7

User Commands pax(1)

This keyword is applicable only to the

-x pax format. When used in write or

copy mode with the appropriate options,

pax creates global extended header

records with ustar header blocks that are treated as regular files by previous

versions of pax. This keyword allows

user control over the name that is writ-

ten into the ustar header blocks for global extended header records. The name is the contents of string, after the following character substitutions have been made:

%n An integer that represents the

sequence number of the global extended header record in the archive, starting at 1.

%p The process ID of the pax process.

%% A '%' character.

Any other '%' characters in string pro-

duce undefined results.

If no -o globexthdr.name=string is

specified, pax uses the following

default value:

$TMPDIR/GlobalHead.%p.%n

where $TMPDIR represents the value of

the TMPDIR environment variable. If

TMPDIR is not set, pax uses /tmp.

invalid=action This keyword is applicable only to the

-x pax format. This keyword allows user

control over the action pax takes upon

encountering values in an extended header record that, in read or copy mode, are invalid in the destination hierarchy or, in list mode , cannot be written in the codeset and current

locale of the implementation. The fol-

lowing are invalid values that are

SunOS 5.11 Last change: 16 Jul 2008 8

User Commands pax(1)

recognized by pax:

o In read or copy mode, a

filename or link name that con-

tains character encodings invalid in the destination hierarchy. For example, the name can contain embedded NULs. o In read or copy mode, a filename or link name that is longer than the maximum allowed in the destination hierarchy,

for either a path name com-

ponent or the entire path name. o In list mode, any character string value (filename, link name, user name, and so on) that cannot be written in the codeset and current locale of the implementation.

The following mutually-exclusive values

of the action argument are supported:

bypass In read or copy mode, pax

bypasses the file, causing no change to the destination

hierarchy. In list mode, pax

writes all requested valid values for the file, but its method for writing invalid values is unspecified.

rename In read or copy mode, pax acts

as if the -i option were in

effect for each file with invalid filename or link name values, allowing the user to provide a replacement name interactively. In list mode,

pax behaves identically to the

bypass action.

UTF-8 pax uses the actual UTF-8

encoding for the name when it is used in read, copy, or list mode and a filename, link name, owner name, or any other field in an extended header

SunOS 5.11 Last change: 16 Jul 2008 9

User Commands pax(1)

record cannot be translated

from the pax UTF-8 codeset

format to the codeset and

current locale of the imple-

mentation.

write In read or copy mode, pax

writes the file, translating the name, regardless of whether this can overwrite an existing file with a valid

name. In list mode, pax

behaves identically to the bypass action.

If no -o invalid= option is specified,

pax acts as if -o invalid=bypass were

specified. Any overwriting of existing

files that can be allowed by the -o

invalid= actions are subject to permis-

sion (-p) and modification time (-u)

restrictions, and are suppressed if the

-k option is also specified.

linkdata This keyword is applicable only to the

-x pax format. In write mode, pax writes

the contents of a file to the archive even when that file is merely a hard link to a file whose contents have already been written to the archive. listopt=format This keyword specifies the output format of the table of contents produced when

the -v option is specified in list mode.

(See List Mode Format Specifications below.) To avoid ambiguity, the listopt=format is the only or final

keyword=value pair in an -o option-

argument. All characters in the

remainder of the option-argument are

considered to be part of the format

string. When multiple -o listopt=format

options are specified, the format strings are considered to be a single, concatenated string, evaluated in

SunOS 5.11 Last change: 16 Jul 2008 10

User Commands pax(1)

command line order. times This keyword is applicable only to the

-x pax and -x xustar formats. When used

in write or copy mode, pax includes

atime and mtime extended header records for each file.

In addition to these keywords, if the -x pax

format is specified, any of the keywords and values, including implementation extensions,

can be used in -o option-arguments, in

either of two modes: keyword=value When used in write or copy mode, these keyword/value pairs are included at the beginning of the archive as typeflag g global extended header records. When used in read or list mode, these keyword/value pairs act as if they had been at the beginning of the archive as typeflag g global extended header records. keyword:=value When used in write or copy mode, these keyword/value pairs are included as records at the beginning of a typeflag x extended header for each file. This is equivalent to the

equal-sign form except

that it creates no typeflag g global extended header records. When used in read or list mode, these keyword/value pairs act as if they were included as records at the end of each extended

header. Thus, they over-

ride any global or file-

specific extended header record keywords of the

SunOS 5.11 Last change: 16 Jul 2008 11

User Commands pax(1)

same names. For example, in the command:

pax -r -o "

gname:=mygroup, "

-p string Specifies one or more file characteristic

options (privileges). The string option-

argument must be a string specifying file characteristics to be retained or discarded on extraction. The string consists of the specification characters a, e, 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 is as follows: a Does not preserve file access times. e Preserves the user ID, group ID, file

mode bits, access time, and modifica-

tion time. m Does not preserve file modification times. o Preserves the user ID and group ID. p Preserves the file mode bits. 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. Other-

wise, the attribute is determined as part of the normal file creation action. The access and modification times of the file is preserved unless otherwise specified with

the -p option or not stored in the archive.

SunOS 5.11 Last change: 16 Jul 2008 12

User Commands pax(1)

All attributes that are not preserved are

determined as part of the normal file crea-

tion action. If neither the e nor the o specification character is specified, or the user ID and group ID are not preserved for any reason,

pax does not set the setuid and setgid bits

of the file mode. If the preservation of any of these items

fails for any reason, pax writes a diagnos-

tic message to standard error. Failure to preserve these items affects the final exit status, but does not cause the extracted file to be deleted.

If file-characteristic letters in any of the

string option-arguments are duplicated or

conflict with each other, the ones given

last take precedence. For example, if -p eme

is specified, file modification times are preserved.

-r Reads an archive file from standard input.

-s replstr Modifies file or archive member names named

by pattern or file operands according to the substitution expression replstr, which is based on the ed(1) s (substitution) utility, using the regular expression syntax of regex(5). The concepts of ``address'' and ``line'' are meaningless in the context of

the pax command, and must not be supplied.

The format is:

-s /old/new/ [gp]

where, as in ed, old is a basic regular expression and new can contain an ampersand (&), a \n backreference, where n is a digit, or subexpression matching. The old string is also permitted to contain newlines.

Any non-null character can be used as a del-

imiter (/ shown here). Multiple -s expres-

sions can be specified. The expressions are applied in the order specified, terminating with the first successful substitution. The

SunOS 5.11 Last change: 16 Jul 2008 13

User Commands pax(1)

optional trailing g is as defined in the ed

command. The optional trailing p causes suc-

cessful substitutions to be written to stan-

dard error. File or archive member names that substitute to the empty string are ignored when reading and writing archives.

-t When reading files from the file system, and

if the user has the permissions required by utime() to do so, sets the access time of each file read to the access time that it

had before being read by pax.

-u Ignores files that are older (having a less

recent file modification time) than a pre-

existing file or archive member with the same name. read mode An archive member with the same name as a file in the file system is extracted if the archive member is newer than the file. write mode An archive file member with the same name as a file in the file system is superseded if the file is newer than the

archive member. If option -a

is also specified, this is accomplished by appending to the archive. Otherwise, it is unspecified whether this is accomplished by actual replacement in the archive or by appending to the archive. copy mode 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.

SunOS 5.11 Last change: 16 Jul 2008 14

User Commands pax(1)

-v In list mode, produces a verbose table of

contents (see Standard Output). Otherwise, writes archive member path names and extended attributes to standard error (see Standard Error).

-w Writes files to the standard output in the

specified archive format.

-x format Specifies the output archive format. The pax

utility recognizes the following formats: cpio The extended cpio(1) interchange

format. See IEEE Std 1003.1-2001.

The default blocksize for this format for character special

archive files is 5120. Implementa-

tions support all blocksize values less than or equal to 32256 that are multiples of 512. This archive format allows files with UIDs and GIDs up to 262143 to be stored in the archive. Files with UIDs and GIDs greater than this value are archived with the UID and GID of 60001.

pax The pax interchange format. See

IEEE Std 1003.1-2001. The default

blocksize for this format for character special archive files is 5120. Implementations support all blocksize values less than or equal to 32256 that are multiples of 512. Similar to ustar. Also allows archiving and extracting files whose size is greater than 8GB;

whose UID, GID, devmajor, or dev-

minor values are greater than 2097151; whose path (including filename) is greater than 255 characters; or whose linkname is greater than 100 characters.

SunOS 5.11 Last change: 16 Jul 2008 15

User Commands pax(1)

ustar The extended tar(1) interchange format. See the IEEE 1003.1(1990)

specifications. The default block-

size for this format for character special archive files is 10240.

Implementations support all block-

size values less than or equal to 32256 that are multiples of 512. This archive format allows files with UIDs and GIDs up to 2097151 to be stored in the archive. Files with UIDs and GIDs greater than this value are archived with the UID and GID of 60001. xustar Similar to ustar. Also allows archiving and extracting files whose size is greater than 8GB;

whose UID, GID, devmajor, or dev-

minor values are greater than 2097151; whose path (including filename) is greater than 255 characters; or whose linkname is greater than 100 characters. This option should not be used if the archive is to be extracted by an archiver that cannot handle the larger values. Any attempt to append to an archive file in a format different from the existing archive

format causes pax to exit immediately with a

non-zero exit status.

In copy mode, if no -x format is specified,

pax behaves as if -x pax were specified.

-X When traversing the file hierarchy specified

by a path name, pax does not descend into

directories that have a different device ID

(st_dev, see stat(2)).

-@ Includes extended attributes in the archive.

pax does not place extended attributes in

the archive by default. When traversing the file hierarchy specified

by a path name, pax descends into the

SunOS 5.11 Last change: 16 Jul 2008 16

User Commands pax(1)

attribute directory for any file with extended attributes. Extended attributes go into the archive as special files.

When this flag is used during file extrac-

tion, any extended attributes associated with a file being extracted are also extracted. Extended attribute files can only be extracted from an archive as part of a normal file extract. Attempts to explicitly extract attribute records are ignored.

-/ Includes extended system attributes in the

archive. pax does not place extended system

attributes in the archive by default. When traversing the file hierarchy specified

by a path name, pax descends into the attri-

bute directory for any file with extended attributes. Extended attributes go into the archive as special files. When this flag is used during file extraction, any extended attributes associated with a file being extracted are also extracted. Extended attribute files can only be extracted from an archive as part of a normal file extract. Attempts to explicitly extract attribute records are ignored.

Specifying more than one of the mutually-exclusive options

-H and -L is not considered an error. The last option speci-

fied determines the behavior of the utility. The options that operate on the names of files or archive

members (-c, -i, -n, -s, -u and -v) interact as follows.

In read mode, the archive members are selected based on the

user-specified pattern operands as modified by the -c, -n

and -u options. Then, any -s and -i options modify, in that

order, the names of the selected files. The -v option writes

names resulting from these modifications.

In write mode, the files are selected based on the user-

specified path names as modified by the -n and -u options.

Then, any -s and -i options modify, in that order, the names

of these selected files. The -v option writes names

SunOS 5.11 Last change: 16 Jul 2008 17

User Commands pax(1)

resulting from these modifications.

If both the -u and -n options are specified, pax does not

consider a file selected unless it is newer than the file to which it is compared. List Mode Format Specifications

In list mode with the -o listopt=format option, the format

argument is applied for each selected file. pax appends a

NEWLINE to the listopt output for each selected file. The

format argument is used as the format string with the fol-

lowing exceptions. (See printf(1) for the first five excep-

tions.)

1. A SPACE character in the format string, in any con-

text other than a flag of a conversion specifica-

tion, is treated as an ordinary character that is copied to the output. 2. A ' ' character in the format string is treated as a ' ' character, not as a SPACE. 3. In addition to the escape sequences described in the formats(5) manual page, (\\, \a, \b, \f, \n,

\r, \t, \v), \ddd, where ddd is a one-, two-, or

three-digit octal number, is written as a byte with

the numeric value specified by the octal number. 4. Output from the d or u conversion specifiers is not preceded or followed with BLANKs not specified by the format operand.

5. Output from the o conversion specifier is not pre-

ceded with zeros that are not specified by the for-

mat operand. 6. The sequence (keyword) can occur before a format conversion specifier. The conversion argument is

defined by the value of keyword. The following key-

words are supported (see IEEE Std 1003.1-2001):

o Any of the Field Name entries in ustar Header

Block and Octet-Oriented cpio Archive Entry.

The implementation supports the cpio keywords

without the leading c_ in addition to the form

required by Values for cpio c_ mode Field.

o Any keyword defined for the extended header in

pax Extended Header.

o Any keyword provided as an implementation-

SunOS 5.11 Last change: 16 Jul 2008 18

User Commands pax(1)

defined extension within the extended header

defined in pax Extended Header.

For example, the sequence "%(charset)s" is the string

value of the name of the character set in the extended header. The result of the keyword conversion argument is the value from the applicable header field or extended header, without any trailing NULs. All keyword values used as conversion arguments are

translated from the UTF -8 encoding to the character set

appropriate for the local file system, user database, and so on, as applicable. 7. An additional conversion specifier character, T, is used to specify time formats. The T conversion specifier character can be preceded by the sequence

(keyword=subformat), where subformat is a date for-

mat as defined by date operands. The default key-

word is mtime and the default subformat is:

%b %e %H:%M %Y

8. An additional conversion specifier character, M, is used to specify the file mode string as defined in ls Standard Output. If (keyword) is omitted, the

mode keyword is used. For example, %.1M writes the

single character corresponding to the entry type

field of the ls -l command.

9. An additional conversion specifier character, D, is used to specify the device for block or special

files, if applicable, in an implementation-defined

format. If not applicable, and (keyword) is speci-

fied, then this conversion is equivalent to

%(keyword)u. If not applicable, and (keyword) is

omitted, then this conversion is equivalent to SPACE. 10. An additional conversion specifier character, F, is

used to specify a path name. The F conversion char-

acter can be preceded by a sequence of comma-

separated keywords: (keyword[,keyword] ... )

The values for all the keywords that are non-null

are concatenated, each separated by a '/'. The

SunOS 5.11 Last change: 16 Jul 2008 19

User Commands pax(1)

default is (path) if the keyword path is defined. Otherwise, the default is (prefix,name). 11. An additional conversion specifier character, L, is used to specify a symbolic link expansion. If the

current file is a symbolic link, then %L expands

to:

"%s -> %s", value of keyword, contents of link

Otherwise, the %L conversion specification is the

equivalent of %F.

OPERANDS The following operands are supported: directory The destination directory path name for copy mode. file A path name of a file to be copied or archived. pattern A pattern matching one or more path names of archive members. A pattern must conform to the pattern matching notation found on the

fnmatch(5) manual page. The default, if no pat-

tern is specified, is to select all members in the archive.

OUTPUT

Output formats are discussed below: Standard Output

In write mode, if -f is not specified, the standard output

is the archive formatted according to one of the formats

described below. See -x format for a list of supported for-

mats.

In list mode, when the -o listopt=format option has been

specified, the selected archive members are written to stan-

dard output using the format described above under List Mode

Format Specifications. In list mode without the -o

listopt=format option, the table of contents of the selected archive members are written to standard output using the following format:

"%s\n", pathname

SunOS 5.11 Last change: 16 Jul 2008 20

User Commands pax(1)

If the -v option is specified in list mode, the table of

contents of the selected archive members are written to standard output using the following formats: o For path names representing hard links to previous members of the archive:

"%s == %s\n", o For all other path names:

"%s\n",

where is the format specified by

the ls command with the -l option. When writing

path names in this format, it is unspecified what is written for fields for which the underlying

archive format does not have the correct informa-

tion, although the correct number of blank-

character-separated fields is written.

In list mode, standard output is not buffered more than a line at a time. Standard Error

If -v is specified in read, write or copy modes, pax writes

the path names it processes to the standard error output using the following format:

"%s\n", pathname

These path names are written as soon as processing is begun on the file or archive member, and are flushed to standard

error. The trailing NEWLINE character, which is not buf-

fered, is written when the file has been read or written.

If the -s option is specified, and the replacement string

has a trailing p, substitutions are written to standard error in the following format:

"%s >> %s\n", ,

SunOS 5.11 Last change: 16 Jul 2008 21

User Commands pax(1)

In all operating modes of pax, optional messages of unspeci-

fied format concerning the input archive format and volume number, the number of files, blocks, volumes, and media parts as well as other diagnostic messages can be written to standard error. In all formats, for both standard output and standard error,

it is unspecified how non-printable characters in path names

or link names are written.

When pax is in read mode or list mode, using the -x pax

archive format, and a file name, link name, owner name, or any other field in an extended header record cannot be

translated from the pax UTF-8 codeset format to the codeset

and current locale of the implementation, pax writes a diag-

nostic message to standard error, processes the file as

described for the -o invalid=option, and then processes the

next file in the archive. Output Files In read mode, the extracted output files are of the archived file type. In copy mode, the copied output files are the type of the file being copied . In either mode, existing files in the destination hierarchy are overwritten only when

all permission (-p), modification time (-u), and invalid-

value (-o invalid=) tests allow it. In write mode, the out-

put file named by the -f option-argument is a file formatted

according to one of the specifications in IEEE Std 1003.1-

2001.

ERRORS

If pax 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

-p option is specified, a diagnostic message is written to

standard error and a non-zero exit status is returned, but

processing continues. In the case where pax cannot create a

link to a file, pax does not, by default, create a second

copy of the file. If the extraction of a file from an archive is prematurely

terminated by a signal or error, pax can have only partially

extracted the file or, if the -n option was not specified,

can have extracted a file of the same name as that specified by the user, but which is not the file the user wanted. Additionally, the file modes of extracted directories can have additional bits from the read, write, execute mask set as well as incorrect modification and access times.

SunOS 5.11 Last change: 16 Jul 2008 22

User Commands pax(1)

USAGE

The -p (privileges) option was invented to reconcile differ-

ences between historical tar(1) and cpio(1) implementations.

In particular, the two utilities use -m in diametrically

opposed ways. The -p option also provides a consistent means

of extending the ways in which future file attributes can be

addressed, such as for enhanced security systems or high-

performance files. Although it can seem complex, there are really two modes that are most commonly used:

-p e Preserve everything. This would be used by the his-

torical superuser, someone with all the appropriate privileges, to preserve all aspects of the files as they are recorded in the archive. The e flag is the

sum of o and p, and other implementation-dependent

attributes.

-p p Preserve the file mode bits. This would be used by

the user with regular privileges who wished to

preserve aspects of the file other than the owner-

ship. The file times are preserved by default, but two other flags are offered to disable these and use the time of extraction.

The one path name per line format of standard input pre-

cludes path names containing newlines. Although such path names violate the portable filename guidelines, they can

exist and their presence can inhibit usage of pax within

shell scripts. This problem is inherited from historical archive programs. The problem can be avoided by listing file name arguments on the command line instead of on standard input. It is almost certain that appropriate privileges are

required for pax to accomplish parts of this. Specifically,

creating files of type block special or character special, restoring file access times unless the files are owned by

the user (the -t option), or preserving file owner, group,

and mode (the -p option) all probably require appropriate

privileges. In read mode, implementations are permitted to overwrite files when the archive has multiple members with the same name. This can fail if permissions on the first version of the file do not permit it to be overwritten.

SunOS 5.11 Last change: 16 Jul 2008 23

User Commands pax(1)

When using the -x xustar and -x -pax archive formats, if the

underlying file system reports that the file being archived

contains holes, the Solaris pax utility records the presence

of holes in an extended header record when the file is archived. If this extended header record is associated with a file in the archive, those holes are recreated whenever

that file is extracted from the archive. See the SEEK_DATA

and SEEK_HOLE whence values in lseek(2). In all other cases,

any NUL (\0) characters found in the archive is written to the file when it is extracted.

See largefile(5) for the description of the behavior of pax

when encountering files greater than or equal to 2 Gbyte ( 2^31 bytes). Standard Input In write mode, the standard input is used only if no file operands are specified. It is a text file containing a list of path names, one per line, without leading or trailing

blanks. In list and read modes, if -f is not specified, the

standard input is an archive file. Otherwise, the standard input is not used. Input Files

The input file named by the archive option-argument, or

standard input when the archive is read from there, is a file formatted according to one of the formats described below. See Extended Description. The file /dev/tty is used to write prompts and read responses.

EXAMPLES

Example 1 Copying the Contents of the Current Directory The following command:

example% pax -w -f /dev/rmt/1m .

copies the contents of the current directory to tape drive 1, medium density. This assumes historical System V device naming procedures. The historical BSD device name would be /dev/rmt9. Example 2 Copying the Directory Hierarchy

SunOS 5.11 Last change: 16 Jul 2008 24

User Commands pax(1)

The following commands:

example% mkdir newdir

example% pax -rw olddir newdir

copy the olddir directory hierarchy to newdir. Example 3 Reading an Archive Extracted Relative to the Current Directory The following command:

example% pax -r -s ',^//usr//,,' -f a.pax

reads the archive a.pax, with all files rooted in /usr in

the archive extracted relative to the current directory. Example 4 Overriding the Default Output Description Using the option:

-o listopt="%M %(atime)T %(size)D %(name)s"

overrides the default output description in Standard Output and instead writes:

-rw-rw- - - Jan 12 15:53 2003 1492 /usr/foo/bar

Using the options:

-o listopt='%L\t%(size)D\n%.7' \

SunOS 5.11 Last change: 16 Jul 2008 25

User Commands pax(1)

-o listopt='(name)s\n%(atime)T\n%T'

overrides the default output description in standard output and instead writes:

usr/foo/bar -> /tmp 1492

/usr/foo Jan 12 15:53 1991 Jan 31 15:53 2003 ENVIRONMENT VARIABLES See environ(5) for descriptions of the following environment

variables that affect the execution of pax: LANG, LC_ALL,

LC_CTYPE, LC_MESSAGES, LC_TIME, and NLSPATH.

LC_COLLATE Determine the locale for the behaviour of

ranges, equivalence classes, and multi-

character collating elements used in the pat-

tern matching expressions for the pattern operand, the basic regular expression for the

-s option, and the extended regular expression

defined for the yesexpr locale keyword in the

LC_MESSAGES category.

TMPDIR Determine the path name that provides part of the default global extended header record

file, as described for the -o globexthdr= key-

word as described in the OPTIONS section. TZ Determine the timezone used to calculate date

and time strings when the -v option is speci-

fied. If TZ is unset or null, an unspecified default timezone is used. EXIT STATUS The following exit values are returned: 0 All files were processed successfully. >0 An error occurred.

SunOS 5.11 Last change: 16 Jul 2008 26

User Commands pax(1)

EXTENDED DESCRIPTION

pax Interchange Format

A pax archive tape or file produced in the -xpax format con-

tains a series of blocks. The physical layout of the archive

is identical to the ustar format described in ustar Inter-

change Format. Each file archived is represented by the fol-

lowing sequence: o An optional header block with extended header records. This header block is of the form 27403 with a typeflag value of x or g. The extended header records is included as the data for this header block. o A header block that describes the file. Any fields in the preceding optional extended header overrides the associated fields in this header block for this file. o Zero or more blocks that contain the contents of the file.

At the end of the archive file there are two 512-byte blocks

filled with binary zeroes, interpreted as an end-of-archive

indicator.

The following is a schematic of an example archive with glo-

bal extended header records and two actual files in pax for-

mat archive. In the example, the second file in the archive has no extended header preceding it, presumably because it has no need for extended attributes. Description Block Global Extended Header ustar Header [typeflag=g] Global Extended Header Data File 1: Extended Header is included ustar Header [typeflag=x] Extended Header Data [typeflag=0] ustar Header Data for File 1 File 2: No Extended Header is included ustar Header [typeflag=0] Data for File2 End of Archive Indicator Block of binary zeros Block of binary zeros

pax Header Block

The pax header block is identical to the ustar header block

described in ustar Interchange Format except that two

SunOS 5.11 Last change: 16 Jul 2008 27

User Commands pax(1)

additional typeflag values are defined:

g Represents global extended header records for the fol-

lowing files in the archive. The format of these

extended header records are as described in pax

Extended Header. Each value affects all subsequent files that do not override that value in their own extended header record and until another global extended header record is reached that provides another value for the same field. The typeflag g global headers should not be used with interchange media that could suffer partial data loss in transporting the archive. x Represents extended header records for the following file in the archive (which has its own ustar header block). The format of these extended header records is

as described in pax Extended Header.

For both of these types, the size field is the size of the extended header records in octets. The other fields in the

header block are not meaningful to this version of pax. How-

ever, if this archive is read by pax conforming to a previ-

ous version of ISO POSIX-2:1993 Standard, the header block

fields are used to create a regular file that contains the extended header records as data. Therefore, header block field values should be selected to provide reasonable file access to this regular file. A further difference from the ustar header block is that data blocks for files of typeflag 1 (the digit one) (hard link) might be included, which means that the size field can

be greater than zero. Archives created by pax -o linkdata

includes these data blocks with the hard links.

pax Extended Header

A pax extended header contains values that are inappropriate

for the ustar header block because of limitations in that format: fields requiring a character encoding other than

that described in the ISO/IEC 646: 1991 standard, fields representing file attributes not described in the ustar header, and fields whose format or length do not fit the requirements of the ustar header. The values in an extended header add attributes to the specified file or files or override values in the specified header blocks, as indicated in the following list of keywords. See the description of the typeflag g header block.

SunOS 5.11 Last change: 16 Jul 2008 28

User Commands pax(1)

An extended header consists of one or more records, each constructed as follows:

"%d %s=%s\n", length, keyword, value

The extended header records are encoded according to the

ISO/IEC 10646-1: 2000 standard (UTF-8). length, BLANK,

equals sign (=), and NEWLINE are limited to the portable

character set, as encoded in UTF-8. keyword and value can be

any UTF-8 characters. length is the decimal length of the

extended header record in octets, including the trailing NEWLINE. keyword is one of the entries from the following list or a keyword provided as an implementation extension. Keywords consisting entirely of lowercase letters, digits, and periods are reserved for future standardization. A keyword does not include an equals sign. In the following list, the notation of file(s) or block(s) are used to acknowledge that a keyword affects the specified single file after a typeflag x extended header, but possibly multiple files after typeflag g. Any requirements in the

list for pax to include a record when in write or copy mode

applies only when such a record has not already been pro-

vided through the use of the -o option. When used in copy

mode, pax behaves as if an archive had been created with

applicable extended header records and then extracted. atime The file access time for the specified files, equivalent to the value of the

st_atime member of the stat structure for a

file, as described by the stat(2) function. The access time (atime) is restored if the process has the appropriate privilege required to do so. The format of the value

is as described in pax Extended Header File

Times. charset The name of the character set used to encode the data in the specified files. The entries in the following table are defined to refer to known standards; additional names can be

agreed on between the originator and reci-

pient.

SunOS 5.11 Last change: 16 Jul 2008 29

User Commands pax(1)

value Formal Standard

ISO-IR 646 1990 ISO/IEC646:1990

ISO-IR 8859 1 1998 ISO/IEC8859-1:1998

ISO-IR 8859 2 1999 ISO/IEC 8859-2:1999

ISO-IR 8859 3 1999 ISO/IEC 8859-3:1999

ISO-IR 8859 4 1999 ISO/IEC8859-4:1998

ISO-IR 8859 5 1999 ISO/IEC8859-5-1999

ISO-IR 8859 6 1999 ISO/IEC8859-6-1999

ISO-IR 8859 7 1987 ISO/IEC8859-7:1987

ISO-IR 8859 8 1999 ISO/IEC8859-8:1999

ISO-IR 8859 9 1999 ISO/IEC8859-9:1999

ISO-IR 8859 10 1998 ISO/IEC8859-10:1999

ISO-IR 8859 13 1998 ISO/IEC8859-13:1998

ISO-IR 8859 14 1998 ISO/IEC8859-14:1998

ISO-IR 8859 15 1999 ISO/IEC8859-15:1999

ISO-IR 10646 2000 ISO/IEC 10646:2000

ISO-IR 10646 2000 UTF-8 ISO/IEC 10646,UTF-8 encoding

BINARY None The encoding is included in an extended

header for information only; when pax is

used as described in IEEE Std 1003.1-200x,

it does not translate the file data into any other encoding. The BINARY entry indicates unencoded binary data. When used in write or

copy mode, it is implementation-defined

whether pax includes a charset extended

header record for a file. comment A series of characters used as a comment. All characters in the value field are

ignored by pax.

gid The group ID of the group that owns the file, expressed as a decimal number using

digits from the ISO/IEC 646: 1991 standard. This record overrides the gid field in the specified header blocks. When used in write

or copy mode, pax includes a gid extended

header record for each file whose group ID is greater than 2097151 (octal 7777777). gname The group of the files, formatted as a group name in the group database. This record overrides the gid and gname fields in the specified header blocks, and any gid extended header record. When used in read,

copy, or list mode, pax translates the name

from the UTF-8 encoding in the header record

SunOS 5.11 Last change: 16 Jul 2008 30

User Commands pax(1)

to the character set appropriate for the group database on the receiving system. If

any of the UTF-8 characters cannot be

translated, and if the -o invalid=UTF-8

option is not specified, the results are

implementation-defined. When used in write

or copy mode, pax includes a gname extended

header record for each file whose group name cannot be represented entirely with the letters and digits of the portable character set. linkpath The pathname of a link being created to another file, of any type, previously archived. This record overrides the linkname field in the specified ustar header blocks. The specified ustar header block determines the type of link created. If typeflag of the specified header block is 1, it is a hard link. If typeflag is 2, it is a symbolic link and the linkpath value is the contents

of the symbolic link. pax translates the

name of the link (contents of the symbolic

link) from the UTF-8 encoding to the charac-

ter set appropriate for the local file sys-

tem. When used in write or copy mode, pax

includes a linkpath extended header record for each link whose pathname cannot be represented entirely with the members of the portable character set other than NULL. mtime The pathname of a link being created to another file, of any type, previously archived. This record overrides the linkname field in the specified ustar header blocks. The specified ustar header block determines the type of link created. If typeflag of the specified header block is 1, it is a hard link. If typeflag is 2, it is a symbolic link and the linkpath value is the contents

of the symbolic link. pax translates the

name of the link (contents of the symbolic

link) from the UTF-8 encoding to the charac-

ter set appropriate for the local file sys-

tem. When used in write or copy mode, pax

includes a linkpath extended header record for each link whose pathname cannot be represented entirely with the members of the portable character set other than NULL.

SunOS 5.11 Last change: 16 Jul 2008 31

User Commands pax(1)

path The pathname of the specified files. This record overrides the name and prefix fields

in the specified header blocks. pax

translates the pathname of the file from the

UTF-8 encoding to the character set

appropriate for the local file system. When

used in write or copy mode, pax includes a

path extended header record for each file whose pathname cannot be represented entirely with the members of the portable character set other than NULL. realtime.any The keywords prefixed by realtime are reserved for future standardization. security.any The keywords prefixed by security are reserved for future standardization. size The size of the file in octets, expressed as a decimal number using digits from the

ISO/IEC 646: 1991 standard. This record overrides the size field in the specified header blocks. When used in write or copy

mode, pax includes a size extended header

record for each file with a size value greater than 8589934591 (octal 77777777777). uid The user ID of the file owner, expressed as a decimal number using digits from the

ISO/IEC 646:1991 standard. This record over-

rides the uid field in the following header block(s). When used in write or copy mode,

pax includes a uid extended header record

for each file whose owner ID is greater than 2097151 (octal 7777777). uname The owner of the specified files, formatted as a user name in the user database. This record overrides the uid and uname fields in the specified header blocks, and any uid extended header record. When used in read,

copy, or list mode, pax translates the name

from the UTF-8 encoding in the header record

to the character set appropriate for the user database on the receiving system. If

any of the UTF-8 characters cannot be

translated, and if the -o invalid= UTF-8

SunOS 5.11 Last change: 16 Jul 2008 32

User Commands pax(1)

option is not specified, the results are

implementation-defined. When used in write

or copy mode, pax includes a uname extended

header record for each file whose user name cannot be represented entirely with the letters and digits of the portable character set. If the value field is zero length, it deletes any header block field, previously entered extended header value, or global extended header value of the same name.

If a keyword in an extended header record (or in an -o

option-argument) overrides or deletes a corresponding field

in the ustar header block, pax ignores the contents of that

header block field. Unlike the ustar header block fields, NULLs does not delimit values; all characters within the value field are considered data for the field.

pax Extended Header Keyword Precedence

This section describes the precedence in which the various header records and fields and command line options are

selected to apply to a file in the archive. When pax is used

in read or list modes, it determines a file attribute in the following sequence:

1. If -o delete=keyword-prefix is used, the affected

attributes is determined from step 7, if applica-

ble, or ignored otherwise.

2. If -o keyword:= is used, the affected attributes is

ignored.

3. If -o keyword:=value is used, the affected attri-

bute is assigned the value. 4. If there is a typeflag x extended header record, the affected attribute is assigned the value. When extended header records conflict, the last one given in the header takes precedence.

5. If -o keyword=value is used, the affected attribute

is assigned the value. 6. If there is a typeflag g global extended header record, the affected attribute is assigned the

SunOS 5.11 Last change: 16 Jul 2008 33

User Commands pax(1)

value. When global extended header records con-

flict, the last one given in the global header takes precedence. 7. Otherwise, the attribute is determined from the ustar header block.

pax Extended Header File Times

pax writes an mtime record for each file in write or copy

modes if the file's modification time cannot be represented exactly in the ustar header logical record described in ustar Interchange Format. This can occur if the time is out of ustar range, or if the file system of the underlying

implementation supports non-integer time granularities and

the time is not an integer. All of these time records are formatted as a decimal representation of the time in seconds since the Epoch. If a period (.) decimal point character is present, the digits to the right of the point represents the

units of a sub-second timing granularity, where the first

digit is tenths of a second and each subsequent digit is a

tenth of the previous digit. In read or copy mode, pax trun-

cates the time of a file to the greatest value that is not greater than the input header file time. In write or copy

mode, pax outputs a time exactly if it can be represented

exactly as a decimal number, and otherwise generates only enough digits so that the same time is recovered if the file is extracted on a system whose underlying implementation supports the same time granularity. ustar Interchange Format A ustar archive tape or file contains a series of logical

records. Each logical record is a fixed-size logical record

of 512 octets. Although this format can be thought of as

being stored on 9-track industry-standard 12.7mm (0.5 in)

magnetic tape, other types of transportable media are not

excluded. Each file archived is represented by a header log-

ical record that describes the file, followed by zero or more logical records that give the contents of the file. At

the end of the archive file there are two 512-octet logical

records filled with binary zeros, interpreted as an end-of-

archive indicator.

The logical records can be grouped for physical I/O opera-

tions, as described under the -bblocksize and -x ustar

options. Each group of logical records can be written with a single operation equivalent to the write(2) function. On magnetic tape, the result of this write is a single tape physical block. The last physical block always is the full size, so logical records after the two zero logical records can contain undefined data.

SunOS 5.11 Last change: 16 Jul 2008 34

User Commands pax(1)

The header logical record is structured as shown in the fol-

lowing table. All lengths and offsets are in decimal. Table 1 ustar Header Block Field Name Octet Offset Length (in Octets) name 0 100 mode 100 8 uid 108 8 gid 116 8 size 124 12 mtime 136 12 chksum 148 8 typeflag 156 1 linkname 157 100 magic 257 6 version 263 2 uname 265 32 gname 297 32 devmajor 329 8 devminor 337 8 prefix 345 155 All characters in the header logical record is represented

in the coded character set of the ISO/IEC 646: 1991 stan-

dard. For maximum portability between implementations, names

should be selected from characters represented by the port-

able filename character set as octets with the most signifi-

cant bit zero. If an implementation supports the use of

characters outside of slash and the portable filename char-

acter set in names for files, users, and groups, one or more

implementation-defined encodings of these characters are

provided for interchange purposes.

pax never creates filenames on the local system that cannot

be accessed using the procedures described in IEEE Std

1003.1-200x. If a filename is found on the medium that would

create an invalid filename, it is implementation-defined

whether the data from the file is stored on the file hierar-

chy and under what name it is stored. pax can choose to

ignore these files as long as it produces an error indicat-

ing that the file is being ignored. Each field within the header logical record is contiguous; that is, there is no padding used. Each field within the header logical record is contiguous. There is no padding used. Each character on the archive medium is stored contiguously.

SunOS 5.11 Last change: 16 Jul 2008 35

User Commands pax(1)

The fields magic, uname and gname are character strings, each of which is terminated by a NULL character. The fields

name, linkname, and prefix are NULL-terminated character

strings except when all characters in the array contain

non-NULL characters including the last character. The ver-

sion field is two octets containing the characters 00

(zero-zero) The typeflag contains a single character. All

other fields are leading zero-filled octal numbers using

digits from the ISO/IEC 646:1991 standard IRV. Each numeric field is terminated by one or more SPACE of NULL characters. Each character on the archive medium is stored contiguously. The fields magic, uname, and gname are character strings each terminated by a NULL character.

name, linkname, and prefix are NULL-terminated character

strings except when all characters in the array contain

non-NULL characters including the last character. The ver-

sion field is two octets containing the characters 00

(zero-zero). The typeflag contains a single character. All

other fields are leading zero-filled octal numbers using

digits from the ISO/IEC 646: 1991 standard IRV. Each numeric

field is terminated by one or more spaces or NULL charac-

ters. The name and the prefix fields produce the pathname of the file. A new pathname is formed, if prefix is not an empty string (its first character is not NULL), by concatenating prefix (up to the first NULL character), a slash character, and name; otherwise, name is used alone. In either case, name is terminated at the first NULL character. If prefix begins with a NULL character, it is ignored. In this manner, pathnames of at most 256 characters can be supported. If a

pathname does not fit in the space provided, pax notifies

the user of the error, and does not store any part of the

file-header or data-on the medium.

The linkname field does not use the prefix to produce a pathname. As such, a linkname is limited to 100 characters.

If the name does not fit in the space provided, pax notifies

the user of the error, and does not attempt to store the link on the medium. The mode field provides 12 bits encoded

in the ISO/IEC 646: 1991 standard octal digit representa-

tion. The encoded bits represent the following values in the ustar mode field:

SunOS 5.11 Last change: 16 Jul 2008 36

User Commands pax(1)

Bit Value IEE Std 1003.1-2001 Bit Description

04000 S_ISUID Set UID on execution

02000 S_ISGID Set GID on exectution

01000 reserved Reserved for future standardization

00400 S_IRUSR Read permission for file owner class

00200 S_IWUSR Write permission for file owner class

00100 S_IXUSR Execute/search permission for file

owner class

00040 S_IRGRP Read permission for file group class

00020 S_IWGRP Write permission for file group class

00010 S_IXGRP Execute/search permission for file

group class

00004 S_IROTH Read permission for file other class

00002 S_IWOTH Write permission for file other class

00001 S_IXOTH Execute/search permission for file

other class When appropriate privilege is required to set one of these mode bits, and the user restoring the files from the archive does not have the appropriate privilege, the mode bits for which the user does not have appropriate privilege are ignored. Some of the mode bits in the archive format are not

mentioned elsewhere in volume IEEE Std 1003.1-200x. If the

implementation does not support those bits, they can be ignored. The uid and gid fields are the user and group ID of the owner and group of the file, respectively. The size field is the size of the file in octets. If the typeflag field is set to specify a file to be of type 1 (a link) or 2 (a symbolic link), the size field is specified as zero. If the typeflag field is set to specify a file of type 5 (directory), the size field is interpreted as described under the definition of that record type. No data logical records are stored for types 1, 2, or 5. If the typeflag field is set to 3 (character special file), 4 (block special file), or 6 (FIFO), the meaning of the size field is

unspecified by volume IEEE Std 1003.1-200x, and no data log-

ical records is stored on the medium. Additionally, for type 6, the size field is ignored when reading. If the typeflag field is set to any other value, the number of logical records written following the header is (size+511)/512, ignoring any fraction in the result of the division. The mtime field is the modification time of the file at the

time it was archived. It is the ISO/IEC 646: 1991 standard

SunOS 5.11 Last change: 16 Jul 2008 37

User Commands pax(1)

representation of the octal value of the modification time obtained from the stat() function.

The chksum field is the ISO/IEC 646: 1991 standard IRV representation of the octal value of the simple sum of all octets in the header logical record. Each octet in the header is treated as an unsigned value. These values are

added to an unsigned integer, initialized to zero, the pre-

cision of which is not less than 17 bits. When calculating the checksum, the chksum field is treated as if it were all spaces. The typeflag field specifies the type of file archived. If a particular implementation does not recognize the type, or the user does not have appropriate privilege to create that type, the file is extracted as if it were a regular file if the file type is defined to have a meaning for the size field that could cause data logical records to be written on

the medium. If conversion to a regular file occurs, pax pro-

duces an error indicating that the conversion took place.

All of the typeflag fields are coded in the ISO/IEC 646: 1991 standard IRV: 0 Represents a regular file. For backward compatibility, a typeflag value of binary zero ('\0') should be recognized as meaning a regular file when extracting files from the archive. Archives written with this version of the archive file format create regular files with a typeflag value of the

ISO/IEC 646: 1991 standard IRV '0'. 1 Represents a file linked to another file, of any type, previously archived. Such files are identified by each file having the same device and file serial number. The

linked-to name is specified in the linkname

field with a NULL-character terminator if

it is less than 100 octets in length. 2 Represents a symbolic link. The contents of

the symbolic link are stored in the link-

name field. 3,4 Represents character special files and block special files respectively. In this case the devmajor and devminor fields

SunOS 5.11 Last change: 16 Jul 2008 38

User Commands pax(1)

contain information defining the device, the format of which is unspecified by

volume IEEE Std 1003.1-200x. Implementa-

tions can map the device specifications to their own local specification or can ignore the entry. 5 Specifies a directory or subdirectory. On systems where disk allocation is performed

on a directory basis, the size field con-

tain the maximum number of octets (which can be rounded to the nearest disk block allocation unit) that the directory can hold. A size field of zero indicates no such limiting. Systems that do not support limiting in this manner should ignore the size field.

6 Specifies a FIFO special file. The archiv-

ing of a FIFO file archives the existence of this file and not its contents. 7 Reserved to represent a file to which an

implementation has associated some high-

performance attribute. Implementations without such extensions should treat this file as a regular file (type 0).

A-Z The letters A through Z inclusive are

reserved for custom implementations. All

other values are reserved for future ver-

sions of IEEE Std 1003.1-200x.

SUN.devmajor A Solaris extension to pax extended header

keywords. Specifies the major device number of the file. When used in write or copy mode and the

xustar or pax format (see -x format) was

specified, pax includes a SUN.devmajor

extended header record for each file whose major device number is too large to fit in 8 octets.

SUN.devminor A Solaris extension to pax extended header

keywords. Specifies the minor device number

SunOS 5.11 Last change: 16 Jul 2008 39

User Commands pax(1)

of the file. When used in write or copy mode and the

xustar or pax format (see -x format) is

specified, pax includes a SUN.devminor

extended header record for each file whose minor device number is too large to fit in 8 octets.

SUN.holesdata A Solaris extension to pax extended header

keywords. Specifies the data and hole pairs for a sparse file. In write or copy modes and when the xustar

or pax format (see -x format) is specified,

pax includes a SUN.holesdate extended

header record if the underlying file system supports the detection of files with holes (see fpathconf(2)) and reports that there is at least one hole in the file being archived. value consists of two or more consecutive entries of the following form:

SPACEdata_offsetSPACEhole_offset

where the data and hole offsets are the

long values returned by passing SEEK_DATA

and SEEK_HOLE to lseek(2), respectively.

For example, the following entry is an example of the SUN.holesdata entry in the extended header for a file with data offsets at bytes 0, 24576, and 49152, and hole offsets at bytes 8192, 32768, and 49159: 49 SUN.holesdata= 0 8192 24576 32768 49152 49159: 49 SUN.holesdata= 0 8192 24576 32768 49152 49159 When extracting a file from an archive in read or copy modes, if a SUN.holesdata = pair is found in the extended header for the file, then the file is restored with the holes identified using this data. For example, for the SUN.holesdata provided in the example above, bytes from 0 to 8192 are restored as data, a hole is created up to the next data position (24576), bytes 24576 to 32768 is restored as data, and so forth.

SunOS 5.11 Last change: 16 Jul 2008 40

User Commands pax(1)

X A Solaris custom typeflag implementation

which specifies an xustar format (see -x

format) extended header. The typeflag 'x' extended header is treated as a ustar typeflag 'x' extended header. E A Solaris custom typeflag implementation which specifies an extended attributes header. See fsattr(5). Attempts to archive a socket using ustar interchange format produce a diagnostic message. Handling of other file types

is implementation-defined.

The magic field is the specification that this archive was output in this archive format. If this field contains ustar

(the five characters from the ISO/IEC 646: 1991 standard IRV shown followed by NULL), the uname and gname fields contain

the ISO/IEC 646: 1991 standard IRV representation of the owner and group of the file, respectively (truncated to fit, if necessary). When the file is restored by a privileged,

protection-preserving version of the utility, the user and

group databases are scanned for these names. If found, the user and group IDs contained within these files are used rather than the values contained within the uid and gid fields. cpio Interchange Format

The octet-oriented cpio archive format are a series of

entries, each comprising a header that describes the file, name of the file, and contents of the file.

An archive can be recorded as a series of fixed-size blocks

of octets. This blocking is be used only to make physical

I/O more efficient. The last group of blocks are always at the full size.

For the octet-oriented cpio archive format, the individual

entry information are in the order indicated and described

by the following table: Octet-Oriented cpio Archive Entry.

See the cpio.h header for additional details. Header Field Name Length (in Octets) Interpreted as

c_magic 6 Octal number

SunOS 5.11 Last change: 16 Jul 2008 41

User Commands pax(1)

c_dev 6 Octal number

c_ino 6 Octal number

c_mode 6 Octal number

c_uid 6 Octal number

c_gid 6 Octal number

c_nlink 6 Octal number

c_rdev 6 Octal number

c_mtime 11 Octal number

c_namesize 6 Octal number

c_filesize 11 Octal number

Filename Field Name Length Interpreted as

c_name c_namesize Pathname string

Filename Field Name Length Interpreted as

c_filedata c_filesize Data

cpio Header For each file in the archive, a header as defined previously written. The information in the header fields is written as

streams of the ISO/IEC 646: 1991 standard characters inter-

preted as octal numbers. The octal numbers are extended to

the necessary length by appending the ISO/IEC 646: 1991

standard IRV zeros at the most-significant-digit end of the

number. The result is written to the most-significant digit

of the stream of octets first. The fields are interpreted as follows:

c_magic Identifies the archive as being a transport-

able archive by containing the identifying value "070707".

c_dev,c_ino Contains values that uniquely identify the

file within the archive (that is, no files

contain the same pair of c_dev and c_ino

values unless they are links to the same file). The values are determined in an unspecified manner.

c_mode Contains the file type and access permissions

as defined in the following table. Directories, FIFOs, symbolic links, and

SunOS 5.11 Last change: 16 Jul 2008 42

User Commands pax(1)

regular files are supported on a system con-

forming to volume IEEE Std 1003.1-200x; addi-

tional values defined previously are reserved for compatibility with existing systems. Additional file types can be supported. Such files should not be written to archives intended to be transported to other systems. File Permissions Name Value Indicates

C_IRUSR 000400 by owner

C_IWUSR 000200 by owner

C_IXUSR 000100 by owner

C_IRGRP 000040 by group

CW_IWFGP 000020 by group

CW_IXGRP 000010 by group

CW_IROTH 000004 by others

CW_IWOTH 000002 by others

CW_IXOTH 000001 by others

CW_ISUID 004000 Set uid

W_ISGID 002000 Set gid

W_ISVTX 001000 Reserved

File Type Name Value Indicates

C_ISDIR 040000 Directory

C_ISFIFO 010000 FIFO

C_ISREG 0100000 Regular file

C_ISLNK 0120000 Symbolic link

C_ISBLK 060000 Block special file

C_ISCHR 020000 Character special file

C_ISSOCK 0140000 Socket

C_ISCTG 0110000 Reserved

c_uid Contains the user ID of the owner.

c_gid Contains the group ID of the group

c_nlink Contains a number greater than or equal to

the number of links in the archive referenc-

ing the file. If the -a option is used to

append to a cpio archive, pax does need not

to account for the files in the existing part

of the archive when calculating the c_nlink

values for the appended part of the archive.

SunOS 5.11 Last change: 16 Jul 2008 43

User Commands pax(1)

It does also need not alter the c_nlink

values in the existing part of the archive if

additional files with the same c_dev and c-

ino values are appended to the archive.

c_rdev Contains implementation-defined information

for character or block special files.

c_mtime Contains the latest time of modification of

the file at the time the archive was created.

c_namesize Contains the length of the pathname, includ-

ing the terminating NULL character.

c_filesize Contains the length of the file in octets.

This is the length of the data section fol-

lowing the header structure. cpio Filename

The c_name field contains the pathname of the file. The

length of this field in octets is the value of c_namesize.

If a filename is found on the medium that would create an

invalid pathname, it is implementation-defined whether the

data from the file is stored on the file hierarchy and under what name it is stored. All characters are represented in

the ISO/IEC 646: 1991 standard IRV. For maximum portability

between implementations, names should be selected from char-

acters represented by the portable filename character set as

octets with the most significant bit zero. If an implementa-

tion supports the use of characters outside the portable filename character set in names for files, users, and

groups, one or more implementation-defined encodings of

these characters are provided for interchange purposes.pax

does not create filenames on the local system that cannot be accessed by way of the procedures described in volume IEEE

Std 1003.1-200x. If a filename is found on the medium that

would create an invalid filename, it is implementation-

defined whether the data from the file is stored on the

local file system and under what name it is stored. pax can

choose to ignore these files as long as it produces an error indicating that the file is being ignored. cpio File Data

Following c_name, there is c_filesize octets of data.

Interpretation of such data occurs in a manner dependent on

the file. If c_filesize is zero, no data is contained in

c_filedata . When restoring from an archive:

SunOS 5.11 Last change: 16 Jul 2008 44

User Commands pax(1)

o If the user does not have the appropriate privilege

to create a file of the specified type, pax ignores

the entry and writes an error message to standard error. o Only regular files have data to be restored.

Presuming a regular file meets any selection cri-

teria that might be imposed on the format-reading

utility by the user, such data is restored. o If a user does not have appropriate privilege to set a particular mode flag, the flag is ignored. Some of the mode flags in the archive format are

not mentioned in volume IEEE Std 1003.1-200x. If

the implementation does not support those flags, they can be ignored. cpio Special Entries FIFO special files, directories, and the trailer are

recorded with c_filesize equal to zero. For other special

files, c_filesize is unspecified in volume IEEE Std 1003.1-

200x. The header for the next file entry in the archive are written directly after the last octet of the file entry

preceding it. A header denoting the filename trailer indi-

cates the end of the archive; the contents of octets in the

last block of the archive following such a header are unde-

fined.

ATTRIBUTES

See attributes(5) for descriptions of the following attri-

butes:

____________________________________________________________

| ATTRIBUTE TYPE | ATTRIBUTE VALUE |

|_____________________________|_____________________________|

| Availability | SUNWcs |

|_____________________________|_____________________________|

| Interface Stability | Committed |

|_____________________________|_____________________________|

| Standard | See standards(5). |

|_____________________________|_____________________________|

User Commands pax(1)

IEEE Std 1003.1-200x, ISO/IEC 646: 1991, ISO POSIX-2:1993

Standard

SunOS 5.11 Last change: 16 Jul 2008 46