1pax(1) User Commands pax(1)
2
6 pax - portable archive interchange
7
9 pax [-cdnv] [-H | -L] [-f archive] [-o options]...
10 [-s replstr]... [pattern]...
11 pax -r [-cdiknuv@/] [-H | -L] [-f archive] [-o options]...
14 [-p string]... [-s replstr]... [pattern]...
15 pax -w [-dituvX@/] [-H | -L] [-b blocksize] [-a]
18 [-f archive] [-o options]... [-s replstr]...
19 [-x format] [file]...
20 pax -r -w [-diklntuvX@/] [-H | -L] [-o options]...
23 [-p string]... [-s replstr]... [file]... directory
24
27 pax reads, writes, and writes lists of the members of archive files and
28 copies directory hierarchies. A variety of archive formats are sup‐
29 ported. See the -x format option.
30 Modes of Operations
32 The action to be taken depends on the presence of the -r and -w
33 options. The four combinations of -r and -w are referred to as the four
34 modes of operation: list, read, write, and copy modes, corresponding
35 respectively to the four forms shown in the SYNOPSIS.
36 list In list mode, that is, when neither -r nor -w are specified,
38 pax writes the names of the members of the archive file read
39 from the standard input, with path names matching the speci‐
40 fied patterns, to standard output. If a named file has
41 extended attributes, the extended attributes are also listed.
42 If a named file is of type directory, the file hierarchy
43 rooted at that file is listed as well.
44 read In read mode, that is, when -r is specified, but -w is not,
47 pax extracts the members of the archive file read from the
48 standard input, with path names matching the specified pat‐
49 terns. If an extracted file is of type directory, the file
50 hierarchy rooted at that file is extracted as well. The
51 extracted files are created performing path name resolution
52 with the directory in which pax was invoked as the current
53 working directory.
54 If an attempt is made to extract a directory when the direc‐
56 tory already exists, this is not considered an error. If an
57 attempt is made to extract a FIFO when the FIFO already
58 exists, this is not considered an error.
59 The ownership, access and modification times, and file mode of
61 the restored files are discussed under the -p option.
62 write In write mode, that is, when -w is specified, but -r is not,
65 pax writes the contents of the file operands to the standard
66 output in an archive format. If no file operands are speci‐
67 fied, a list of files to copy, one per line, are read from the
68 standard input. A file of type directory includes all of the
69 files in the file hierarchy rooted at the file.
70 copy In copy mode, that is, when both -r and -w are specified, pax
73 copies the file operands to the destination directory.
74 If no file operands are specified, a list of files to copy,
76 one per line, are read from the standard input. A file of type
77 directory includes all of the files in the file hierarchy
78 rooted at the file.
79 The effect of the copy is as if the copied files were written
81 to an archive file and then subsequently extracted, except
82 that there can be hard links between the original and the
83 copied files. If the destination directory is a subdirectory
84 of one of the files to be copied, the results are unspecified.
85 It is an error if directory does not exist, is not writable by
86 the user, or is not a directory.
87 In read or copy modes, if intermediate directories are necessary to
91 extract an archive member, pax performs actions equivalent to the
92 mkdir(2) function, called with the following arguments:
93 o The intermediate directory used as the path argument.
95 o The octal value of 777 or rwx (read, write, and execute per‐
97 missions) as the mode argument (see chmod(1)).
98 If any specified pattern or file operands are not matched by at least
101 one file or archive member, pax writes a diagnostic message to standard
102 error for each one that did not match and exits with a non-zero exit
103 status.
104 The supported archive formats are automatically detected on input. The
107 default output archive format is tar(1).
108 A single archive can span multiple files. pax determines what file to
111 read or write as the next file.
112 If the selected archive format supports the specification of linked
115 files, it is an error if these files cannot be linked when the archive
116 is extracted, except if the files to be linked are symbolic links and
117 the system is not capable of making hard links to symbolic links. In
118 that case, separate copies of the symbolic link are created instead.
119 Any of the various names in the archive that represent a file can be
120 used to select the file for extraction. For archive formats that do not
121 store file contents with each name that causes a hard link, if the file
122 that contains the data is not extracted during this pax session, either
123 the data is restored from the original file, or a diagnostic message is
124 displayed with the name of a file that can be used to extract the data.
125 In traversing directories, pax detects infinite loops, that is, enter‐
126 ing a previously visited directory that is an ancestor of the last file
127 visited. When it detects an infinite loop, pax writes a diagnostic mes‐
128 sage to standard error and terminates.
129
131 The following options are supported:
132 -a Appends files to the end of the archive. This option
134 does not work for some archive devices, such as
135 1/4-inch streaming tapes and 8mm tapes.
136 -b blocksize Blocks the output at a positive decimal integer number
139 of bytes per write to the archive file. Devices and ar‐
140 chive formats can impose restrictions on blocking.
141 Blocking is automatically determined on input. Portable
142 applications must not specify a blocksize value larger
143 than 32256. Default blocking when creating archives
144 depends on the archive format. See the -x option below.
145 -c Matches all file or archive members except those speci‐
148 fied by the pattern or file operands.
149 -d Causes files of type directory being copied or archived
152 or archive members of type directory being extracted or
153 listed to match only the file or archive member itself
154 and not the file hierarchy rooted at the file.
155 -f archive Specifies the path name of the input or output archive,
158 overriding the default standard input (in list or read
159 modes) or standard output (write mode).
160 -H If a symbolic link referencing a file of type directory
163 is specified on the command line, pax archives the file
164 hierarchy rooted in the file referenced by the link,
165 using the name of the link as the root of the file
166 hierarchy. Otherwise, if a symbolic link referencing a
167 file of any other file type which pax can normally ar‐
168 chive is specified on the command line, then pax ar‐
169 chives the file referenced by the link, using the name
170 of the link. The default behavior is to archive the
171 symbolic link itself.
172 -i Interactively renames files or archive members. For
175 each archive member matching a pattern operand or file
176 matching a file operand, a prompt is written to the
177 file /dev/tty. The prompt contains the name of the file
178 or archive member. A line is then read from /dev/tty.
179 If this line is blank, the file or archive member is
180 skipped. If this line consists of a single period, the
181 file or archive member is processed with no modifica‐
182 tion to its name. Otherwise, its name is replaced with
183 the contents of the line. pax immediately exits with a
184 non-zero exit status if end-of-file is encountered when
185 reading a response or if /dev/tty cannot be opened for
186 reading and writing.
187 The results of extracting a hard link to a file that
189 has been renamed during extraction are unspecified.
190 -k Prevents the overwriting of existing files.
193 -l Links files. In copy mode, hard links are made between
196 the source and destination file hierarchies whenever
197 possible. If specified in conjunction with -H or -L,
198 when a symbolic link is encountered, the hard link cre‐
199 ated in the destination file hierarchy is to the file
200 referenced by the symbolic link. If specified when nei‐
201 ther -H nor -L is specified, when a symbolic link is
202 encountered, the implementation creates a hard link to
203 the symbolic link in the source file hierarchy or
204 copies the symbolic link to the destination.
205 -L If a symbolic link referencing a file of type directory
208 is specified on the command line or encountered during
209 the traversal of a file hierarchy, pax archives the
210 file hierarchy rooted in the file referenced by the
211 link, using the name of the link as the root of the
212 file hierarchy. Otherwise, if a symbolic link referenc‐
213 ing a file of any other file type which pax can nor‐
214 mally archive is specified on the command line or
215 encountered during the traversal of a file hierarchy,
216 pax archives the file referenced by the link, using the
217 name of the link. The default behavior is to archive
218 the symbolic link itself.
219 -n Selects the first archive member that matches each pat‐
222 tern operand. No more than one archive member is
223 matched for each pattern, although members of type
224 directory still match the file hierarchy rooted at that
225 file.
226 -o options Provides information to the implementation to modify
229 the algorithm for extracting or writing files. The
230 value of options consists of one or more comma-sepa‐
231 rated keywords of the form:
232 keyword[[:]=value][,keyword[[:]=value], ...]
234 Some keywords apply only to certain file formats, as
237 indicated with each description. Use of keywords that
238 are inapplicable to the file format being processed
239 produces undefined results.
240 Keywords in the options argument must be a string that
242 would be a valid portable filename.
243 Keywords are not expected to be filenames, merely to
245 follow the same character composition rules as portable
246 filenames.
247 Keywords can be preceded with white space. The value
249 field consists of zero or more characters. Within
250 value, the application precedes any literal comma with
251 a backslash, which is ignored, but preserves the comma
252 as part of value. A comma as the final character, or a
253 comma followed solely by white space as the final char‐
254 acters, in options is ignored. Multiple -o options can
255 be specified. If keywords given to these multiple -o
256 options conflict, the keywords and values appearing
257 later in command line sequence take precedence and the
258 earlier ones are silently ignored. The following key‐
259 word values of options are supported for the file for‐
260 mats as indicated:
261 delete=pattern
263 This keyword is applicable only to the -x pax for‐
265 mat. When used in write or copy mode, pax omits
266 from extended header records that it produces any
267 keywords matching the string pattern. When used in
268 read or list mode, pax ignores any keywords match‐
269 ing the string pattern in the extended header
270 records. In both cases, matching is performed using
271 the pattern matching notation. For example:
272 -o delete=security.*
274 would suppress security-related information.
277 When multiple -o delete=pattern options are speci‐
279 fied, the patterns are additive. All keywords
280 matching the specified string patterns are omitted
281 from extended header records that pax produces.
282 exthdr.name=string
285 This keyword is applicable only to the -x pax for‐
287 mat. This keyword allows user control over the name
288 that is written into the ustar header blocks for
289 the extended header. The name is the contents of
290 string, after the following character substitutions
291 have been made:
292 %d The directory name of the file, equivalent to
294 the result of the dirname utility on the
295 translated path name.
296 %f The filename of the file, equivalent to the
299 result of the basename utility on the trans‐
300 lated path name.
301 %p The process ID of the pax process.
304 %% A '%' character.
307 Any other '%' characters in string produce unde‐
309 fined results.
310 If no -o exthdr.name=string is specified, pax uses
312 the following default value:
313 %d/PaxHeaders.%p/%f
315 globexthdr.name=string
320 This keyword is applicable only to the -x pax for‐
322 mat. When used in write or copy mode with the
323 appropriate options, pax creates global extended
324 header records with ustar header blocks that are
325 treated as regular files by previous versions of
326 pax. This keyword allows user control over the name
327 that is written into the ustar header blocks for
328 global extended header records. The name is the
329 contents of string, after the following character
330 substitutions have been made:
331 %n An integer that represents the sequence num‐
333 ber of the global extended header record in
334 the archive, starting at 1.
335 %p The process ID of the pax process.
338 %% A '%' character.
341 Any other '%' characters in string produce unde‐
343 fined results.
344 If no -o globexthdr.name=string is specified, pax
346 uses the following default value:
347 $TMPDIR/GlobalHead.%p.%n
349 where $TMPDIR represents the value of the TMPDIR
352 environment variable. If TMPDIR is not set, pax
353 uses /tmp.
354 invalid=action
357 This keyword is applicable only to the -x pax for‐
359 mat. This keyword allows user control over the
360 action pax takes upon encountering values in an
361 extended header record that, in read or copy mode,
362 are invalid in the destination hierarchy or, in
363 list mode , cannot be written in the codeset and
364 current locale of the implementation. The following
365 are invalid values that are recognized by pax:
366 o In read or copy mode, a filename or link
368 name that contains character encodings
369 invalid in the destination hierarchy.
370 For example, the name can contain embed‐
371 ded NULs.
372 o In read or copy mode, a filename or link
374 name that is longer than the maximum
375 allowed in the destination hierarchy,
376 for either a path name component or the
377 entire path name.
378 o In list mode, any character string value
380 (filename, link name, user name, and so
381 on) that cannot be written in the code‐
382 set and current locale of the implemen‐
383 tation.
384 The following mutually-exclusive values of the
385 action argument are supported:
386 bypass In read or copy mode, pax bypasses the
388 file, causing no change to the destina‐
389 tion hierarchy. In list mode, pax writes
390 all requested valid values for the file,
391 but its method for writing invalid values
392 is unspecified.
393 rename In read or copy mode, pax acts as if the
396 -i option were in effect for each file
397 with invalid filename or link name val‐
398 ues, allowing the user to provide a
399 replacement name interactively. In list
400 mode, pax behaves identically to the
401 bypass action.
402 UTF-8 pax uses the actual UTF-8 encoding for
405 the name when it is used in read, copy,
406 or list mode and a filename, link name,
407 owner name, or any other field in an
408 extended header record cannot be trans‐
409 lated from the pax UTF-8 codeset format
410 to the codeset and current locale of the
411 implementation.
412 write In read or copy mode, pax writes the
415 file, translating the name, regardless of
416 whether this can overwrite an existing
417 file with a valid name. In list mode, pax
418 behaves identically to the bypass action.
419 If no -o invalid= option is specified, pax acts as
421 if -o invalid=bypass were specified. Any overwrit‐
422 ing of existing files that can be allowed by the -o
423 invalid= actions are subject to permission (-p) and
424 modification time (-u) restrictions, and are sup‐
425 pressed if the -k option is also specified.
426 linkdata
429 This keyword is applicable only to the -x pax for‐
431 mat. In write mode, pax writes the contents of a
432 file to the archive even when that file is merely a
433 hard link to a file whose contents have already
434 been written to the archive.
435 listopt=format
438 This keyword specifies the output format of the ta‐
440 ble of contents produced when the -v option is
441 specified in list mode. (See List Mode Format Spec‐
442 ifications below.) To avoid ambiguity, the
443 listopt=format is the only or final keyword=value
444 pair in an -o option-argument. All characters in
445 the remainder of the option-argument are considered
446 to be part of the format string. When multiple -o
447 listopt=format options are specified, the format
448 strings are considered to be a single, concatenated
449 string, evaluated in command line order.
450 times
453 This keyword is applicable only to the -x pax and
455 -x xustar formats. When used in write or copy mode,
456 pax includes atime and mtime extended header
457 records for each file.
458 In addition to these keywords, if the -x pax format is
460 specified, any of the keywords and values, including
461 implementation extensions, can be used in -o option-
462 arguments, in either of two modes:
463 keyword=value When used in write or copy mode,
465 these keyword/value pairs are
466 included at the beginning of the ar‐
467 chive as typeflag g global extended
468 header records. When used in read or
469 list mode, these keyword/value pairs
470 act as if they had been at the begin‐
471 ning of the archive as typeflag g
472 global extended header records.
473 keyword:=value When used in write or copy mode,
476 these keyword/value pairs are
477 included as records at the beginning
478 of a typeflag x extended header for
479 each file. This is equivalent to the
480 equal-sign form except that it cre‐
481 ates no typeflag g global extended
482 header records. When used in read or
483 list mode, these keyword/value pairs
484 act as if they were included as
485 records at the end of each extended
486 header. Thus, they override any
487 global or file-specific extended
488 header record keywords of the same
489 names. For example, in the command:
490 pax -r -o "
492 gname:=mygroup,
493 " <archive
494 the group name is forced to a new
497 value for all files read from the ar‐
498 chive.
499 -p string Specifies one or more file characteristic options
503 (privileges). The string option-argument must be a
504 string specifying file characteristics to be retained
505 or discarded on extraction. The string consists of the
506 specification characters a, e, m, o, and p. Multiple
507 characteristics can be concatenated within the same
508 string and multiple -p options can be specified. The
509 meaning of the specification characters is as follows:
510 a Does not preserve file access times.
512 e Preserves the user ID, group ID, file mode bits,
515 access time, and modification time.
516 m Does not preserve file modification times.
519 o Preserves the user ID and group ID.
522 p Preserves the file mode bits.
525 In the preceding list, preserve indicates that an
527 attribute stored in the archive is given to the
528 extracted file, subject to the permissions of the
529 invoking process. Otherwise, the attribute is deter‐
530 mined as part of the normal file creation action. The
531 access and modification times of the file is preserved
532 unless otherwise specified with the -p option or not
533 stored in the archive. All attributes that are not pre‐
534 served are determined as part of the normal file cre‐
535 ation action.
536 If neither the e nor the o specification character is
538 specified, or the user ID and group ID are not pre‐
539 served for any reason, pax does not set the setuid and
540 setgid bits of the file mode.
541 If the preservation of any of these items fails for any
543 reason, pax writes a diagnostic message to standard
544 error. Failure to preserve these items affects the
545 final exit status, but does not cause the extracted
546 file to be deleted.
547 If file-characteristic letters in any of the string
549 option-arguments are duplicated or conflict with each
550 other, the ones given last take precedence. For exam‐
551 ple, if -p eme is specified, file modification times
552 are preserved.
553 -r Reads an archive file from standard input.
556 -s replstr Modifies file or archive member names named by pattern
559 or file operands according to the substitution expres‐
560 sion replstr, which is based on the ed(1) s (substitu‐
561 tion) utility, using the regular expression syntax of
562 regex(5). The concepts of ``address'' and ``line'' are
563 meaningless in the context of the pax command, and must
564 not be supplied. The format is:
565 -s /old/new/ [gp]
567 where, as in ed, old is a basic regular expression and
570 new can contain an ampersand (&), a \n backreference,
571 where n is a digit, or subexpression matching. The old
572 string is also permitted to contain newlines.
573 Any non-null character can be used as a delimiter (/
575 shown here). Multiple -s expressions can be specified.
576 The expressions are applied in the order specified,
577 terminating with the first successful substitution. The
578 optional trailing g is as defined in the ed command.
579 The optional trailing p causes successful substitutions
580 to be written to standard error. File or archive member
581 names that substitute to the empty string are ignored
582 when reading and writing archives.
583 -t When reading files from the file system, and if the
586 user has the permissions required by utime() to do so,
587 sets the access time of each file read to the access
588 time that it had before being read by pax.
589 -u Ignores files that are older (having a less recent file
592 modification time) than a pre-existing file or archive
593 member with the same name.
594 read mode An archive member with the same name as a
596 file in the file system is extracted if
597 the archive member is newer than the
598 file.
599 write mode An archive file member with the same name
602 as a file in the file system is super‐
603 seded if the file is newer than the ar‐
604 chive member. If option -a is also speci‐
605 fied, this is accomplished by appending
606 to the archive. Otherwise, it is unspeci‐
607 fied whether this is accomplished by
608 actual replacement in the archive or by
609 appending to the archive.
610 copy mode The file in the destination hierarchy is
613 replaced by the file in the source hier‐
614 archy or by a link to the file in the
615 source hierarchy if the file in the
616 source hierarchy is newer.
617 -v In list mode, produces a verbose table of contents (see
621 Standard Output). Otherwise, writes archive member path
622 names and extended attributes to standard error (see
623 Standard Error).
624 -w Writes files to the standard output in the specified
627 archive format.
628 -x format Specifies the output archive format. The pax utility
631 recognizes the following formats:
632 cpio The extended cpio(1) interchange format. See
634 IEEE Std 1003.1-2001. The default blocksize
635 for this format for character special archive
636 files is 5120. Implementations support all
637 blocksize values less than or equal to 32256
638 that are multiples of 512.
639 This archive format allows files with UIDs
641 and GIDs up to 262143 to be stored in the ar‐
642 chive. Files with UIDs and GIDs greater than
643 this value are archived with the UID and GID
644 of 60001.
645 pax The pax interchange format. See IEEE Std
648 1003.1-2001. The default blocksize for this
649 format for character special archive files is
650 5120. Implementations support all blocksize
651 values less than or equal to 32256 that are
652 multiples of 512.
653 Similar to ustar. Also allows archiving and
655 extracting files whose size is greater than
656 8GB; whose UID, GID, devmajor, or devminor
657 values are greater than 2097151; whose path
658 (including filename) is greater than 255
659 characters; or whose linkname is greater than
660 100 characters.
661 ustar The extended tar(1) interchange format. See
664 the IEEE 1003.1(1990) specifications. The
665 default blocksize for this format for charac‐
666 ter special archive files is 10240. Implemen‐
667 tations support all blocksize values less
668 than or equal to 32256 that are multiples of
669 512.
670 This archive format allows files with UIDs
672 and GIDs up to 2097151 to be stored in the
673 archive. Files with UIDs and GIDs greater
674 than this value are archived with the UID and
675 GID of 60001.
676 xustar Similar to ustar. Also allows archiving and
679 extracting files whose size is greater than
680 8GB; whose UID, GID, devmajor, or devminor
681 values are greater than 2097151; whose path
682 (including filename) is greater than 255
683 characters; or whose linkname is greater than
684 100 characters. This option should not be
685 used if the archive is to be extracted by an
686 archiver that cannot handle the larger val‐
687 ues.
688 Any attempt to append to an archive file in a format
690 different from the existing archive format causes pax
691 to exit immediately with a non-zero exit status.
692 In copy mode, if no -x format is specified, pax behaves
694 as if -x pax were specified.
695 -X When traversing the file hierarchy specified by a path
698 name, pax does not descend into directories that have a
699 different device ID (st_dev, see stat(2)).
700 -@ Includes extended attributes in the archive. pax does
703 not place extended attributes in the archive by
704 default.
705 When traversing the file hierarchy specified by a path
707 name, pax descends into the attribute directory for any
708 file with extended attributes. Extended attributes go
709 into the archive as special files.
710 When this flag is used during file extraction, any
712 extended attributes associated with a file being
713 extracted are also extracted. Extended attribute files
714 can only be extracted from an archive as part of a nor‐
715 mal file extract. Attempts to explicitly extract
716 attribute records are ignored.
717 -/ Includes extended system attributes in the archive. pax
720 does not place extended system attributes in the ar‐
721 chive by default.
722 When traversing the file hierarchy specified by a path
724 name, pax descends into the attribute directory for any
725 file with extended attributes. Extended attributes go
726 into the archive as special files. When this flag is
727 used during file extraction, any extended attributes
728 associated with a file being extracted are also
729 extracted. Extended attribute files can only be
730 extracted from an archive as part of a normal file
731 extract. Attempts to explicitly extract attribute
732 records are ignored.
733 Specifying more than one of the mutually-exclusive options -H and -L is
737 not considered an error. The last option specified determines the
738 behavior of the utility.
739 The options that operate on the names of files or archive members (-c,
742 -i, -n, -s, -u and -v) interact as follows.
743 In read mode, the archive members are selected based on the user-speci‐
746 fied pattern operands as modified by the -c, -n and -u options. Then,
747 any -s and -i options modify, in that order, the names of the selected
748 files. The -v option writes names resulting from these modifications.
749 In write mode, the files are selected based on the user-specified path
752 names as modified by the -n and -u options. Then, any -s and -i options
753 modify, in that order, the names of these selected files. The -v option
754 writes names resulting from these modifications.
755 If both the -u and -n options are specified, pax does not consider a
758 file selected unless it is newer than the file to which it is compared.
759 List Mode Format Specifications
761 In list mode with the -o listopt=format option, the format argument is
762 applied for each selected file. pax appends a NEWLINE to the listopt
763 output for each selected file. The format argument is used as the for‐
764 mat string with the following exceptions. (See printf(1) for the first
765 five exceptions.)
766 1. A SPACE character in the format string, in any context other
768 than a flag of a conversion specification, is treated as an
769 ordinary character that is copied to the output.
770 2. A ' ' character in the format string is treated as a ' '
772 character, not as a SPACE.
773 3. In addition to the escape sequences described in the for‐
775 mats(5) manual page, (\\, \a, \b, \f, \n, \r, \t, \v), \ddd,
776 where ddd is a one-, two-, or three-digit octal number, is
777 written as a byte with the numeric value specified by the
778 octal number.
779 4. Output from the d or u conversion specifiers is not preceded
781 or followed with BLANKs not specified by the format operand.
782 5. Output from the o conversion specifier is not preceded with
784 zeros that are not specified by the format operand.
785 6. The sequence (keyword) can occur before a format conversion
787 specifier. The conversion argument is defined by the value
788 of keyword. The following keywords are supported (see IEEE
789 Std 1003.1-2001):
790 o Any of the Field Name entries in ustar Header Block and
792 Octet-Oriented cpio Archive Entry. The implementation
793 supports the cpio keywords without the leading c_ in
794 addition to the form required by Values for cpio c_ mode
795 Field.
796 o Any keyword defined for the extended header in pax
798 Extended Header.
799 o Any keyword provided as an implementation-defined exten‐
801 sion within the extended header defined in pax Extended
802 Header.
803 For example, the sequence "%(charset)s" is the string value of the
804 name of the character set in the extended header.
805 The result of the keyword conversion argument is the value from the
807 applicable header field or extended header, without any trailing
808 NULs.
809 All keyword values used as conversion arguments are translated from
811 the UTF -8 encoding to the character set appropriate for the local
812 file system, user database, and so on, as applicable.
813 7. An additional conversion specifier character, T, is used to
815 specify time formats. The T conversion specifier character
816 can be preceded by the sequence (keyword=subformat), where
817 subformat is a date format as defined by date operands. The
818 default keyword is mtime and the default subformat is:
819 %b %e %H:%M %Y
821 8. An additional conversion specifier character, M, is used to
825 specify the file mode string as defined in ls Standard Out‐
826 put. If (keyword) is omitted, the mode keyword is used. For
827 example, %.1M writes the single character corresponding to
828 the entry type field of the ls -l command.
829 9. An additional conversion specifier character, D, is used to
831 specify the device for block or special files, if applica‐
832 ble, in an implementation-defined format. If not applicable,
833 and (keyword) is specified, then this conversion is equiva‐
834 lent to %(keyword)u. If not applicable, and (keyword) is
835 omitted, then this conversion is equivalent to SPACE.
836 10. An additional conversion specifier character, F, is used to
838 specify a path name. The F conversion character can be pre‐
839 ceded by a sequence of comma-separated keywords:
840 (keyword[,keyword] ... )
842 The values for all the keywords that are non-null are con‐
845 catenated, each separated by a '/'. The default is (path) if
846 the keyword path is defined. Otherwise, the default is (pre‐
847 fix,name).
848 11. An additional conversion specifier character, L, is used to
850 specify a symbolic link expansion. If the current file is a
851 symbolic link, then %L expands to:
852 "%s -> %s", value of keyword, contents of link
854 Otherwise, the %L conversion specification is the equivalent
857 of %F.
858
860 The following operands are supported:
861 directory The destination directory path name for copy mode.
863 file A path name of a file to be copied or archived.
866 pattern A pattern matching one or more path names of archive mem‐
869 bers. A pattern must conform to the pattern matching nota‐
870 tion found on the fnmatch(5) manual page. The default, if
871 no pattern is specified, is to select all members in the
872 archive.
873
876 Output formats are discussed below:
877 Standard Output
879 In write mode, if -f is not specified, the standard output is the ar‐
880 chive formatted according to one of the formats described below. See -x
881 format for a list of supported formats.
882 In list mode, when the -o listopt=format option has been specified, the
885 selected archive members are written to standard output using the for‐
886 mat described above under List Mode Format Specifications. In list mode
887 without the -o listopt=format option, the table of contents of the
888 selected archive members are written to standard output using the fol‐
889 lowing format:
890 "%s\n", pathname
892 If the -v option is specified in list mode, the table of contents of
897 the selected archive members are written to standard output using the
898 following formats:
899 o For path names representing hard links to previous members
901 of the archive:
902 "%s == %s\n", <ls -l listing, linkname
904 o For all other path names:
908 "%s\n", <ls -l listing>
910 where <ls -l listing> is the format specified by the ls com‐
913 mand with the -l option. When writing path names in this
914 format, it is unspecified what is written for fields for
915 which the underlying archive format does not have the cor‐
916 rect information, although the correct number of blank-char‐
917 acter-separated fields is written.
918 In list mode, standard output is not buffered more than a line at a
921 time.
922 Standard Error
924 If -v is specified in read, write or copy modes, pax writes the path
925 names it processes to the standard error output using the following
926 format:
927 "%s\n", pathname
929 These path names are written as soon as processing is begun on the file
934 or archive member, and are flushed to standard error. The trailing NEW‐
935 LINE character, which is not buffered, is written when the file has
936 been read or written.
937 If the -s option is specified, and the replacement string has a trail‐
940 ing p, substitutions are written to standard error in the following
941 format:
942 "%s >> %s\n", <original pathname>, <new pathname>
944 In all operating modes of pax, optional messages of unspecified format
949 concerning the input archive format and volume number, the number of
950 files, blocks, volumes, and media parts as well as other diagnostic
951 messages can be written to standard error.
952 In all formats, for both standard output and standard error, it is
955 unspecified how non-printable characters in path names or link names
956 are written.
957 When pax is in read mode or list mode, using the -x pax archive format,
960 and a file name, link name, owner name, or any other field in an
961 extended header record cannot be translated from the pax UTF-8 codeset
962 format to the codeset and current locale of the implementation, pax
963 writes a diagnostic message to standard error, processes the file as
964 described for the -o invalid=option, and then processes the next file
965 in the archive.
966 Output Files
968 In read mode, the extracted output files are of the archived file type.
969 In copy mode, the copied output files are the type of the file being
970 copied . In either mode, existing files in the destination hierarchy
971 are overwritten only when all permission (-p), modification time (-u),
972 and invalid-value (-o invalid=) tests allow it. In write mode, the out‐
973 put file named by the -f option-argument is a file formatted according
974 to one of the specifications in IEEE Std 1003.1-2001.
975
977 If pax cannot create a file or a link when reading an archive, or can‐
978 not find a file when writing an archive, or cannot preserve the user
979 ID, group ID, or file mode when the -p option is specified, a diagnos‐
980 tic message is written to standard error and a non-zero exit status is
981 returned, but processing continues. In the case where pax cannot create
982 a link to a file, pax does not, by default, create a second copy of the
983 file.
984 If the extraction of a file from an archive is prematurely terminated
987 by a signal or error, pax can have only partially extracted the file
988 or, if the -n option was not specified, can have extracted a file of
989 the same name as that specified by the user, but which is not the file
990 the user wanted. Additionally, the file modes of extracted directories
991 can have additional bits from the read, write, execute mask set as well
992 as incorrect modification and access times.
993
995 The -p (privileges) option was invented to reconcile differences
996 between historical tar(1) and cpio(1) implementations. In particular,
997 the two utilities use -m in diametrically opposed ways. The -p option
998 also provides a consistent means of extending the ways in which future
999 file attributes can be addressed, such as for enhanced security systems
1000 or high-performance files. Although it can seem complex, there are
1001 really two modes that are most commonly used:
1002 -p e Preserve everything. This would be used by the historical supe‐
1004 ruser, someone with all the appropriate privileges, to preserve
1005 all aspects of the files as they are recorded in the archive.
1006 The e flag is the sum of o and p, and other implementation-
1007 dependent attributes.
1008 -p p Preserve the file mode bits. This would be used by the user
1011 with regular privileges who wished to preserve aspects of the
1012 file other than the ownership. The file times are preserved by
1013 default, but two other flags are offered to disable these and
1014 use the time of extraction.
1015 The one path name per line format of standard input precludes path
1019 names containing newlines. Although such path names violate the porta‐
1020 ble filename guidelines, they can exist and their presence can inhibit
1021 usage of pax within shell scripts. This problem is inherited from his‐
1022 torical archive programs. The problem can be avoided by listing file
1023 name arguments on the command line instead of on standard input.
1024 It is almost certain that appropriate privileges are required for pax
1027 to accomplish parts of this. Specifically, creating files of type block
1028 special or character special, restoring file access times unless the
1029 files are owned by the user (the -t option), or preserving file owner,
1030 group, and mode (the -p option) all probably require appropriate privi‐
1031 leges.
1032 In read mode, implementations are permitted to overwrite files when the
1035 archive has multiple members with the same name. This can fail if per‐
1036 missions on the first version of the file do not permit it to be over‐
1037 written.
1038 When using the -x xustar and -x -pax archive formats, if the underlying
1041 file system reports that the file being archived contains holes, the
1042 Solaris pax utility records the presence of holes in an extended header
1043 record when the file is archived. If this extended header record is
1044 associated with a file in the archive, those holes are recreated when‐
1045 ever that file is extracted from the archive. See the SEEK_DATA and
1046 SEEK_HOLE whence values in lseek(2). In all other cases, any NUL (\0)
1047 characters found in the archive is written to the file when it is
1048 extracted.
1049 See largefile(5) for the description of the behavior of pax when
1052 encountering files greater than or equal to 2 Gbyte ( 2^31 bytes).
1053 Standard Input
1055 In write mode, the standard input is used only if no file operands are
1056 specified. It is a text file containing a list of path names, one per
1057 line, without leading or trailing blanks. In list and read modes, if -f
1058 is not specified, the standard input is an archive file. Otherwise, the
1059 standard input is not used.
1060 Input Files
1062 The input file named by the archive option-argument, or standard input
1063 when the archive is read from there, is a file formatted according to
1064 one of the formats described below. See Extended Description. The file
1065 /dev/tty is used to write prompts and read responses.
1066
1068 Example 1 Copying the Contents of the Current Directory
1069 The following command:
1072 example% pax -w -f /dev/rmt/1m .
1075 copies the contents of the current directory to tape drive 1, medium
1080 density. This assumes historical System V device naming procedures. The
1081 historical BSD device name would be /dev/rmt9.
1082 Example 2 Copying the Directory Hierarchy
1085 The following commands:
1088 example% mkdir newdir
1091 example% pax -rw olddir newdir
1092 copy the olddir directory hierarchy to newdir.
1097 Example 3 Reading an Archive Extracted Relative to the Current Direc‐
1100 tory
1101 The following command:
1104 example% pax -r -s ',^//*usr//*,,' -f a.pax
1107 reads the archive a.pax, with all files rooted in /usr in the archive
1112 extracted relative to the current directory.
1113 Example 4 Overriding the Default Output Description
1116 Using the option:
1119 -o listopt="%M %(atime)T %(size)D %(name)s"
1122 overrides the default output description in Standard Output and instead
1127 writes:
1128 -rw-rw- - - Jan 12 15:53 2003 1492 /usr/foo/bar
1131 Using the options:
1136 -o listopt='%L\t%(size)D\n%.7' \
1139 -o listopt='(name)s\n%(atime)T\n%T'
1140 overrides the default output description in standard output and instead
1145 writes:
1146 usr/foo/bar -> /tmp 1492
1149 /usr/foo
1150 Jan 12 15:53 1991
1151 Jan 31 15:53 2003
1152
1156 See environ(5) for descriptions of the following environment variables
1157 that affect the execution of pax: LANG, LC_ALL, LC_CTYPE, LC_MESSAGES,
1158 LC_TIME, and NLSPATH.
1159 LC_COLLATE Determine the locale for the behaviour of ranges, equiva‐
1161 lence classes, and multi-character collating elements
1162 used in the pattern matching expressions for the pattern
1163 operand, the basic regular expression for the -s option,
1164 and the extended regular expression defined for the
1165 yesexpr locale keyword in the LC_MESSAGES category.
1166 TMPDIR Determine the path name that provides part of the default
1169 global extended header record file, as described for the
1170 -o globexthdr= keyword as described in the OPTIONS sec‐
1171 tion.
1172 TZ Determine the timezone used to calculate date and time
1175 strings when the -v option is specified. If TZ is unset
1176 or null, an unspecified default timezone is used.
1177
1180 The following exit values are returned:
1181 0 All files were processed successfully.
1183 >0 An error occurred.
1186
1189 pax Interchange Format
1190 A pax archive tape or file produced in the -xpax format contains a
1191 series of blocks. The physical layout of the archive is identical to
1192 the ustar format described in ustar Interchange Format. Each file
1193 archived is represented by the following sequence:
1194 o An optional header block with extended header records. This
1196 header block is of the form 27403 with a typeflag value of x
1197 or g. The extended header records is included as the data
1198 for this header block.
1199 o A header block that describes the file. Any fields in the
1201 preceding optional extended header overrides the associated
1202 fields in this header block for this file.
1203 o Zero or more blocks that contain the contents of the file.
1205 At the end of the archive file there are two 512-byte blocks filled
1208 with binary zeroes, interpreted as an end-of-archive indicator.
1209 The following is a schematic of an example archive with global extended
1212 header records and two actual files in pax format archive. In the exam‐
1213 ple, the second file in the archive has no extended header preceding
1214 it, presumably because it has no need for extended attributes.
1215 Description Block
1220 Global Extended Header ustar Header [typeflag=g]
1221 Global Extended Header Data
1222 File 1: Extended Header is included ustar Header [typeflag=x]
1223 Extended Header Data
1224 [typeflag=0]
1225 ustar Header Data for File 1
1226 File 2: No Extended Header is included ustar Header [typeflag=0]
1227 Data for File2
1229 End of Archive Indicator Block of binary zeros
1230 Block of binary zeros
1231 pax Header Block
1234 The pax header block is identical to the ustar header block described
1235 in ustar Interchange Format except that two additional typeflag values
1236 are defined:
1237 g Represents global extended header records for the following files
1239 in the archive. The format of these extended header records are as
1240 described in pax Extended Header. Each value affects all subse‐
1241 quent files that do not override that value in their own extended
1242 header record and until another global extended header record is
1243 reached that provides another value for the same field. The type‐
1244 flag g global headers should not be used with interchange media
1245 that could suffer partial data loss in transporting the archive.
1246 x Represents extended header records for the following file in the
1249 archive (which has its own ustar header block). The format of
1250 these extended header records is as described in pax Extended
1251 Header.
1252 For both of these types, the size field is the size of the extended
1256 header records in octets. The other fields in the header block are not
1257 meaningful to this version of pax. However, if this archive is read by
1258 pax conforming to a previous version of ISO POSIX-2:1993 Standard, the
1259 header block fields are used to create a regular file that contains the
1260 extended header records as data. Therefore, header block field values
1261 should be selected to provide reasonable file access to this regular
1262 file.
1263 A further difference from the ustar header block is that data blocks
1266 for files of typeflag 1 (the digit one) (hard link) might be included,
1267 which means that the size field can be greater than zero. Archives cre‐
1268 ated by pax -o linkdata includes these data blocks with the hard links.
1269 pax Extended Header
1271 A pax extended header contains values that are inappropriate for the
1272 ustar header block because of limitations in that format: fields
1273 requiring a character encoding other than that described in the ISO/IEC
1274 646: 1991 standard, fields representing file attributes not described
1275 in the ustar header, and fields whose format or length do not fit the
1276 requirements of the ustar header. The values in an extended header add
1277 attributes to the specified file or files or override values in the
1278 specified header blocks, as indicated in the following list of key‐
1279 words. See the description of the typeflag g header block.
1280 An extended header consists of one or more records, each constructed as
1283 follows:
1284 "%d %s=%s\n", length, keyword, value
1286 The extended header records are encoded according to the ISO/IEC
1291 10646-1: 2000 standard (UTF-8). length, BLANK, equals sign (=), and
1292 NEWLINE are limited to the portable character set, as encoded in UTF-8.
1293 keyword and value can be any UTF-8 characters. length is the decimal
1294 length of the extended header record in octets, including the trailing
1295 NEWLINE.
1296 keyword is one of the entries from the following list or a keyword pro‐
1299 vided as an implementation extension. Keywords consisting entirely of
1300 lowercase letters, digits, and periods are reserved for future stan‐
1301 dardization. A keyword does not include an equals sign.
1302 In the following list, the notation of file(s) or block(s) are used to
1305 acknowledge that a keyword affects the specified single file after a
1306 typeflag x extended header, but possibly multiple files after typeflag
1307 g. Any requirements in the list for pax to include a record when in
1308 write or copy mode applies only when such a record has not already been
1309 provided through the use of the -o option. When used in copy mode, pax
1310 behaves as if an archive had been created with applicable extended
1311 header records and then extracted.
1312 atime The file access time for the specified files, equiva‐
1314 lent to the value of the st_atime member of the stat
1315 structure for a file, as described by the stat(2) func‐
1316 tion. The access time (atime) is restored if the
1317 process has the appropriate privilege required to do
1318 so. The format of the value is as described in pax
1319 Extended Header File Times.
1320 charset The name of the character set used to encode the data
1323 in the specified files. The entries in the following
1324 table are defined to refer to known standards; addi‐
1325 tional names can be agreed on between the originator
1326 and recipient.
1327 value Formal Standard
1332 ISO-IR 646 1990 ISO/IEC646:1990
1333 ISO-IR 8859 1 1998 ISO/IEC8859-1:1998
1334 ISO-IR 8859 2 1999 ISO/IEC 8859-2:1999
1335 ISO-IR 8859 3 1999 ISO/IEC 8859-3:1999
1336 ISO-IR 8859 4 1999 ISO/IEC8859-4:1998
1337 ISO-IR 8859 5 1999 ISO/IEC8859-5-1999
1338 ISO-IR 8859 6 1999 ISO/IEC8859-6-1999
1339 ISO-IR 8859 7 1987 ISO/IEC8859-7:1987
1340 ISO-IR 8859 8 1999 ISO/IEC8859-8:1999
1341 ISO-IR 8859 9 1999 ISO/IEC8859-9:1999
1342 ISO-IR 8859 10 1998 ISO/IEC8859-10:1999
1343 ISO-IR 8859 13 1998 ISO/IEC8859-13:1998
1344 ISO-IR 8859 14 1998 ISO/IEC8859-14:1998
1345 ISO-IR 8859 15 1999 ISO/IEC8859-15:1999
1346 ISO-IR 10646 2000 ISO/IEC 10646:2000
1347 ISO-IR 10646 2000 UTF-8 ISO/IEC 10646,UTF-8 encoding
1348 BINARY None
1349 The encoding is included in an extended header for
1351 information only; when pax is used as described in IEEE
1352 Std 1003.1-200x, it does not translate the file data
1353 into any other encoding. The BINARY entry indicates
1354 unencoded binary data. When used in write or copy mode,
1355 it is implementation-defined whether pax includes a
1356 charset extended header record for a file.
1357 comment A series of characters used as a comment. All charac‐
1360 ters in the value field are ignored by pax.
1361 gid The group ID of the group that owns the file, expressed
1364 as a decimal number using digits from the ISO/IEC 646:
1365 1991 standard. This record overrides the gid field in
1366 the specified header blocks. When used in write or copy
1367 mode, pax includes a gid extended header record for
1368 each file whose group ID is greater than 2097151 (octal
1369 7777777).
1370 gname The group of the files, formatted as a group name in
1373 the group database. This record overrides the gid and
1374 gname fields in the specified header blocks, and any
1375 gid extended header record. When used in read, copy, or
1376 list mode, pax translates the name from the UTF-8
1377 encoding in the header record to the character set
1378 appropriate for the group database on the receiving
1379 system. If any of the UTF-8 characters cannot be trans‐
1380 lated, and if the -o invalid=UTF-8 option is not speci‐
1381 fied, the results are implementation-defined. When used
1382 in write or copy mode, pax includes a gname extended
1383 header record for each file whose group name cannot be
1384 represented entirely with the letters and digits of the
1385 portable character set.
1386 linkpath The pathname of a link being created to another file,
1389 of any type, previously archived. This record overrides
1390 the linkname field in the specified ustar header
1391 blocks. The specified ustar header block determines the
1392 type of link created. If typeflag of the specified
1393 header block is 1, it is a hard link. If typeflag is 2,
1394 it is a symbolic link and the linkpath value is the
1395 contents of the symbolic link. pax translates the name
1396 of the link (contents of the symbolic link) from the
1397 UTF-8 encoding to the character set appropriate for the
1398 local file system. When used in write or copy mode, pax
1399 includes a linkpath extended header record for each
1400 link whose pathname cannot be represented entirely with
1401 the members of the portable character set other than
1402 NULL.
1403 mtime The pathname of a link being created to another file,
1406 of any type, previously archived. This record overrides
1407 the linkname field in the specified ustar header
1408 blocks. The specified ustar header block determines the
1409 type of link created. If typeflag of the specified
1410 header block is 1, it is a hard link. If typeflag is 2,
1411 it is a symbolic link and the linkpath value is the
1412 contents of the symbolic link. pax translates the name
1413 of the link (contents of the symbolic link) from the
1414 UTF-8 encoding to the character set appropriate for the
1415 local file system. When used in write or copy mode, pax
1416 includes a linkpath extended header record for each
1417 link whose pathname cannot be represented entirely with
1418 the members of the portable character set other than
1419 NULL.
1420 path The pathname of the specified files. This record over‐
1423 rides the name and prefix fields in the specified
1424 header blocks. pax translates the pathname of the file
1425 from the UTF-8 encoding to the character set appropri‐
1426 ate for the local file system. When used in write or
1427 copy mode, pax includes a path extended header record
1428 for each file whose pathname cannot be represented
1429 entirely with the members of the portable character set
1430 other than NULL.
1431 realtime.any The keywords prefixed by realtime are reserved for
1434 future standardization.
1435 security.any The keywords prefixed by security are reserved for
1438 future standardization.
1439 size The size of the file in octets, expressed as a decimal
1442 number using digits from the ISO/IEC 646: 1991 stan‐
1443 dard. This record overrides the size field in the spec‐
1444 ified header blocks. When used in write or copy mode,
1445 pax includes a size extended header record for each
1446 file with a size value greater than 8589934591 (octal
1447 77777777777).
1448 uid The user ID of the file owner, expressed as a decimal
1451 number using digits from the ISO/IEC 646:1991 standard.
1452 This record overrides the uid field in the following
1453 header block(s). When used in write or copy mode, pax
1454 includes a uid extended header record for each file
1455 whose owner ID is greater than 2097151 (octal 7777777).
1456 uname The owner of the specified files, formatted as a user
1459 name in the user database. This record overrides the
1460 uid and uname fields in the specified header blocks,
1461 and any uid extended header record. When used in read,
1462 copy, or list mode, pax translates the name from the
1463 UTF-8 encoding in the header record to the character
1464 set appropriate for the user database on the receiving
1465 system. If any of the UTF-8 characters cannot be trans‐
1466 lated, and if the -o invalid= UTF-8 option is not spec‐
1467 ified, the results are implementation-defined. When
1468 used in write or copy mode, pax includes a uname
1469 extended header record for each file whose user name
1470 cannot be represented entirely with the letters and
1471 digits of the portable character set.
1472 If the value field is zero length, it deletes any header block field,
1476 previously entered extended header value, or global extended header
1477 value of the same name.
1478 If a keyword in an extended header record (or in an -o option-argument)
1481 overrides or deletes a corresponding field in the ustar header block,
1482 pax ignores the contents of that header block field.
1483 Unlike the ustar header block fields, NULLs does not delimit values;
1486 all characters within the value field are considered data for the
1487 field.
1488 pax Extended Header Keyword Precedence
1490 This section describes the precedence in which the various header
1491 records and fields and command line options are selected to apply to a
1492 file in the archive. When pax is used in read or list modes, it deter‐
1493 mines a file attribute in the following sequence:
1494 1. If -o delete=keyword-prefix is used, the affected attributes
1496 is determined from step 7, if applicable, or ignored other‐
1497 wise.
1498 2. If -o keyword:= is used, the affected attributes is ignored.
1500 3. If -o keyword:=value is used, the affected attribute is
1502 assigned the value.
1503 4. If there is a typeflag x extended header record, the
1505 affected attribute is assigned the value. When extended
1506 header records conflict, the last one given in the header
1507 takes precedence.
1508 5. If -o keyword=value is used, the affected attribute is
1510 assigned the value.
1511 6. If there is a typeflag g global extended header record, the
1513 affected attribute is assigned the value. When global
1514 extended header records conflict, the last one given in the
1515 global header takes precedence.
1516 7. Otherwise, the attribute is determined from the ustar header
1518 block.
1519 pax Extended Header File Times
1521 pax writes an mtime record for each file in write or copy modes if the
1522 file's modification time cannot be represented exactly in the ustar
1523 header logical record described in ustar Interchange Format. This can
1524 occur if the time is out of ustar range, or if the file system of the
1525 underlying implementation supports non-integer time granularities and
1526 the time is not an integer. All of these time records are formatted as
1527 a decimal representation of the time in seconds since the Epoch. If a
1528 period (.) decimal point character is present, the digits to the right
1529 of the point represents the units of a sub-second timing granularity,
1530 where the first digit is tenths of a second and each subsequent digit
1531 is a tenth of the previous digit. In read or copy mode, pax truncates
1532 the time of a file to the greatest value that is not greater than the
1533 input header file time. In write or copy mode, pax outputs a time
1534 exactly if it can be represented exactly as a decimal number, and oth‐
1535 erwise generates only enough digits so that the same time is recovered
1536 if the file is extracted on a system whose underlying implementation
1537 supports the same time granularity.
1538 ustar Interchange Format
1540 A ustar archive tape or file contains a series of logical records. Each
1541 logical record is a fixed-size logical record of 512 octets. Although
1542 this format can be thought of as being stored on 9-track industry-stan‐
1543 dard 12.7mm (0.5 in) magnetic tape, other types of transportable media
1544 are not excluded. Each file archived is represented by a header logical
1545 record that describes the file, followed by zero or more logical
1546 records that give the contents of the file. At the end of the archive
1547 file there are two 512-octet logical records filled with binary zeros,
1548 interpreted as an end-of-archive indicator.
1549 The logical records can be grouped for physical I/O operations, as
1552 described under the -bblocksize and -x ustar options. Each group of
1553 logical records can be written with a single operation equivalent to
1554 the write(2) function. On magnetic tape, the result of this write is a
1555 single tape physical block. The last physical block always is the full
1556 size, so logical records after the two zero logical records can contain
1557 undefined data.
1558 The header logical record is structured as shown in the following ta‐
1561 ble. All lengths and offsets are in decimal.
1562 Table 1 ustar Header Block
1564 Field Name Octet Offset Length (in Octets)
1567 name 0 100
1568 mode 100 8
1569 uid 108 8
1570 gid 116 8
1571 size 124 12
1572 mtime 136 12
1573 chksum 148 8
1574 typeflag 156 1
1575 linkname 157 100
1576 magic 257 6
1577 version 263 2
1578 uname 265 32
1579 gname 297 32
1580 devmajor 329 8
1581 devminor 337 8
1582 prefix 345 155
1583 All characters in the header logical record is represented in the coded
1587 character set of the ISO/IEC 646: 1991 standard. For maximum portabil‐
1588 ity between implementations, names should be selected from characters
1589 represented by the portable filename character set as octets with the
1590 most significant bit zero. If an implementation supports the use of
1591 characters outside of slash and the portable filename character set in
1592 names for files, users, and groups, one or more implementation-defined
1593 encodings of these characters are provided for interchange purposes.
1594 pax never creates filenames on the local system that cannot be accessed
1597 using the procedures described in IEEE Std 1003.1-200x. If a filename
1598 is found on the medium that would create an invalid filename, it is
1599 implementation-defined whether the data from the file is stored on the
1600 file hierarchy and under what name it is stored. pax can choose to
1601 ignore these files as long as it produces an error indicating that the
1602 file is being ignored. Each field within the header logical record is
1603 contiguous; that is, there is no padding used.
1604 Each field within the header logical record is contiguous. There is no
1607 padding used. Each character on the archive medium is stored contigu‐
1608 ously.
1609 The fields magic, uname and gname are character strings, each of which
1612 is terminated by a NULL character. The fields name, linkname, and pre‐
1613 fix are NULL-terminated character strings except when all characters in
1614 the array contain non-NULL characters including the last character. The
1615 version field is two octets containing the characters 00 (zero-zero)
1616 The typeflag contains a single character. All other fields are leading
1617 zero-filled octal numbers using digits from the ISO/IEC 646:1991 stan‐
1618 dard IRV. Each numeric field is terminated by one or more SPACE of NULL
1619 characters.
1620 Each character on the archive medium is stored contiguously. The fields
1623 magic, uname, and gname are character strings each terminated by a NULL
1624 character.
1625 name, linkname, and prefix are NULL-terminated character strings except
1628 when all characters in the array contain non-NULL characters including
1629 the last character. The version field is two octets containing the
1630 characters 00 (zero-zero). The typeflag contains a single character.
1631 All other fields are leading zero-filled octal numbers using digits
1632 from the ISO/IEC 646: 1991 standard IRV. Each numeric field is termi‐
1633 nated by one or more spaces or NULL characters.
1634 The name and the prefix fields produce the pathname of the file. A new
1637 pathname is formed, if prefix is not an empty string (its first charac‐
1638 ter is not NULL), by concatenating prefix (up to the first NULL charac‐
1639 ter), a slash character, and name; otherwise, name is used alone. In
1640 either case, name is terminated at the first NULL character. If prefix
1641 begins with a NULL character, it is ignored. In this manner, pathnames
1642 of at most 256 characters can be supported. If a pathname does not fit
1643 in the space provided, pax notifies the user of the error, and does not
1644 store any part of the file-header or data-on the medium.
1645 The linkname field does not use the prefix to produce a pathname. As
1648 such, a linkname is limited to 100 characters. If the name does not fit
1649 in the space provided, pax notifies the user of the error, and does not
1650 attempt to store the link on the medium. The mode field provides 12
1651 bits encoded in the ISO/IEC 646: 1991 standard octal digit representa‐
1652 tion. The encoded bits represent the following values in the ustar mode
1653 field:
1654 Bit Value IEE Std 1003.1-2001 Bit Description
1659 04000 S_ISUID Set UID on execution
1660 02000 S_ISGID Set GID on exectution
1661 01000 reserved Reserved for future standardization
1662 00400 S_IRUSR Read permission for file owner class
1663 00200 S_IWUSR Write permission for file owner class
1664 00100 S_IXUSR Execute/search permission for file
1665 owner class
1666 00040 S_IRGRP Read permission for file group class
1667 00020 S_IWGRP Write permission for file group class
1668 00010 S_IXGRP Execute/search permission for file
1669 group class
1670 00004 S_IROTH Read permission for file other class
1671 00002 S_IWOTH Write permission for file other class
1672 00001 S_IXOTH Execute/search permission for file
1673 other class
1674 When appropriate privilege is required to set one of these mode bits,
1678 and the user restoring the files from the archive does not have the
1679 appropriate privilege, the mode bits for which the user does not have
1680 appropriate privilege are ignored. Some of the mode bits in the archive
1681 format are not mentioned elsewhere in volume IEEE Std 1003.1-200x. If
1682 the implementation does not support those bits, they can be ignored.
1683 The uid and gid fields are the user and group ID of the owner and group
1686 of the file, respectively.
1687 The size field is the size of the file in octets. If the typeflag field
1690 is set to specify a file to be of type 1 (a link) or 2 (a symbolic
1691 link), the size field is specified as zero. If the typeflag field is
1692 set to specify a file of type 5 (directory), the size field is inter‐
1693 preted as described under the definition of that record type. No data
1694 logical records are stored for types 1, 2, or 5. If the typeflag field
1695 is set to 3 (character special file), 4 (block special file), or 6
1696 (FIFO), the meaning of the size field is unspecified by volume IEEE Std
1697 1003.1-200x, and no data logical records is stored on the medium. Addi‐
1698 tionally, for type 6, the size field is ignored when reading. If the
1699 typeflag field is set to any other value, the number of logical records
1700 written following the header is (size+511)/512, ignoring any fraction
1701 in the result of the division.
1702 The mtime field is the modification time of the file at the time it was
1705 archived. It is the ISO/IEC 646: 1991 standard representation of the
1706 octal value of the modification time obtained from the stat() function.
1707 The chksum field is the ISO/IEC 646: 1991 standard IRV representation
1710 of the octal value of the simple sum of all octets in the header logi‐
1711 cal record. Each octet in the header is treated as an unsigned value.
1712 These values are added to an unsigned integer, initialized to zero, the
1713 precision of which is not less than 17 bits. When calculating the
1714 checksum, the chksum field is treated as if it were all spaces.
1715 The typeflag field specifies the type of file archived. If a particular
1718 implementation does not recognize the type, or the user does not have
1719 appropriate privilege to create that type, the file is extracted as if
1720 it were a regular file if the file type is defined to have a meaning
1721 for the size field that could cause data logical records to be written
1722 on the medium. If conversion to a regular file occurs, pax produces an
1723 error indicating that the conversion took place. All of the typeflag
1724 fields are coded in the ISO/IEC 646: 1991 standard IRV:
1725 0 Represents a regular file. For backward compatibility,
1727 a typeflag value of binary zero ('\0') should be rec‐
1728 ognized as meaning a regular file when extracting
1729 files from the archive. Archives written with this
1730 version of the archive file format create regular
1731 files with a typeflag value of the ISO/IEC 646: 1991
1732 standard IRV '0'.
1733 1 Represents a file linked to another file, of any type,
1736 previously archived. Such files are identified by each
1737 file having the same device and file serial number.
1738 The linked-to name is specified in the linkname field
1739 with a NULL-character terminator if it is less than
1740 100 octets in length.
1741 2 Represents a symbolic link. The contents of the sym‐
1744 bolic link are stored in the linkname field.
1745 3,4 Represents character special files and block special
1748 files respectively. In this case the devmajor and
1749 devminor fields contain information defining the
1750 device, the format of which is unspecified by volume
1751 IEEE Std 1003.1-200x. Implementations can map the
1752 device specifications to their own local specification
1753 or can ignore the entry.
1754 5 Specifies a directory or subdirectory. On systems
1757 where disk allocation is performed on a directory
1758 basis, the size field contain the maximum number of
1759 octets (which can be rounded to the nearest disk block
1760 allocation unit) that the directory can hold. A size
1761 field of zero indicates no such limiting. Systems that
1762 do not support limiting in this manner should ignore
1763 the size field.
1764 6 Specifies a FIFO special file. The archiving of a FIFO
1767 file archives the existence of this file and not its
1768 contents.
1769 7 Reserved to represent a file to which an implementa‐
1772 tion has associated some high- performance attribute.
1773 Implementations without such extensions should treat
1774 this file as a regular file (type 0).
1775 A-Z The letters A through Z inclusive are reserved for
1778 custom implementations. All other values are reserved
1779 for future versions of IEEE Std 1003.1-200x.
1780 SUN.devmajor A Solaris extension to pax extended header keywords.
1783 Specifies the major device number of the file.
1784 When used in write or copy mode and the xustar or pax
1786 format (see -x format) was specified, pax includes a
1787 SUN.devmajor extended header record for each file
1788 whose major device number is too large to fit in 8
1789 octets.
1790 SUN.devminor A Solaris extension to pax extended header keywords.
1793 Specifies the minor device number of the file.
1794 When used in write or copy mode and the xustar or pax
1796 format (see -x format) is specified, pax includes a
1797 SUN.devminor extended header record for each file
1798 whose minor device number is too large to fit in 8
1799 octets.
1800 SUN.holesdata A Solaris extension to pax extended header keywords.
1803 Specifies the data and hole pairs for a sparse file.
1804 In write or copy modes and when the xustar or pax for‐
1806 mat (see -x format) is specified, pax includes a
1807 SUN.holesdate extended header record if the underlying
1808 file system supports the detection of files with holes
1809 (see fpathconf(2)) and reports that there is at least
1810 one hole in the file being archived. value consists of
1811 two or more consecutive entries of the following form:
1812 SPACEdata_offsetSPACEhole_offset
1814 where the data and hole offsets are the long values
1817 returned by passing SEEK_DATA and SEEK_HOLE to
1818 lseek(2), respectively. For example, the following
1819 entry is an example of the SUN.holesdata entry in the
1820 extended header for a file with data offsets at bytes
1821 0, 24576, and 49152, and hole offsets at bytes 8192,
1822 32768, and 49159: 49 SUN.holesdata= 0 8192 24576 32768
1823 49152 49159:
1824 49 SUN.holesdata= 0 8192 24576 32768 49152 49159
1826 When extracting a file from an archive in read or copy
1829 modes, if a SUN.holesdata = pair is found in the
1830 extended header for the file, then the file is
1831 restored with the holes identified using this data.
1832 For example, for the SUN.holesdata provided in the
1833 example above, bytes from 0 to 8192 are restored as
1834 data, a hole is created up to the next data position
1835 (24576), bytes 24576 to 32768 is restored as data, and
1836 so forth.
1837 X A Solaris custom typeflag implementation which speci‐
1840 fies an xustar format (see -x format) extended header.
1841 The typeflag 'x' extended header is treated as a ustar
1842 typeflag 'x' extended header.
1843 E A Solaris custom typeflag implementation which speci‐
1846 fies an extended attributes header. See fsattr(5).
1847 Attempts to archive a socket using ustar interchange format produce a
1851 diagnostic message. Handling of other file types is implementation-
1852 defined.
1853 The magic field is the specification that this archive was output in
1856 this archive format. If this field contains ustar (the five characters
1857 from the ISO/IEC 646: 1991 standard IRV shown followed by NULL), the
1858 uname and gname fields contain the ISO/IEC 646: 1991 standard IRV rep‐
1859 resentation of the owner and group of the file, respectively (truncated
1860 to fit, if necessary). When the file is restored by a privileged, pro‐
1861 tection-preserving version of the utility, the user and group databases
1862 are scanned for these names. If found, the user and group IDs contained
1863 within these files are used rather than the values contained within the
1864 uid and gid fields.
1865 cpio Interchange Format
1867 The octet-oriented cpio archive format are a series of entries, each
1868 comprising a header that describes the file, name of the file, and con‐
1869 tents of the file.
1870 An archive can be recorded as a series of fixed-size blocks of octets.
1873 This blocking is be used only to make physical I/O more efficient. The
1874 last group of blocks are always at the full size.
1875 For the octet-oriented cpio archive format, the individual entry infor‐
1878 mation are in the order indicated and described by the following table:
1879 Octet-Oriented cpio Archive Entry. See the cpio.h header for additional
1880 details.
1881 Header Field Name Length (in Octets) Interpreted as
1886 c_magic 6 Octal number
1887 c_dev 6 Octal number
1888 c_ino 6 Octal number
1889 c_mode 6 Octal number
1890 c_uid 6 Octal number
1891 c_gid 6 Octal number
1892 c_nlink 6 Octal number
1893 c_rdev 6 Octal number
1894 c_mtime 11 Octal number
1895 c_namesize 6 Octal number
1896 c_filesize 11 Octal number
1897 Filename Field Name Length Interpreted as
1903 c_name c_namesize Pathname string
1904 Filename Field Name Length Interpreted as
1910 c_filedata c_filesize Data
1911 cpio Header
1914 For each file in the archive, a header as defined previously written.
1915 The information in the header fields is written as streams of the
1916 ISO/IEC 646: 1991 standard characters interpreted as octal numbers. The
1917 octal numbers are extended to the necessary length by appending the
1918 ISO/IEC 646: 1991 standard IRV zeros at the most-significant-digit end
1919 of the number. The result is written to the most-significant digit of
1920 the stream of octets first. The fields are interpreted as follows:
1921 c_magic Identifies the archive as being a transportable archive
1923 by containing the identifying value "070707".
1924 c_dev,c_ino Contains values that uniquely identify the file within
1927 the archive (that is, no files contain the same pair of
1928 c_dev and c_ino values unless they are links to the same
1929 file). The values are determined in an unspecified man‐
1930 ner.
1931 c_mode Contains the file type and access permissions as defined
1934 in the following table.
1935 Directories, FIFOs, symbolic links, and regular files
1937 are supported on a system conforming to volume IEEE Std
1938 1003.1-200x; additional values defined previously are
1939 reserved for compatibility with existing systems. Addi‐
1940 tional file types can be supported. Such files should
1941 not be written to archives intended to be transported to
1942 other systems.
1943 File Permissions Name Value Indicates
1949 C_IRUSR 000400 by owner
1950 C_IWUSR 000200 by owner
1951 C_IXUSR 000100 by owner
1952 C_IRGRP 000040 by group
1953 CW_IWFGP 000020 by group
1954 CW_IXGRP 000010 by group
1955 CW_IROTH 000004 by others
1956 CW_IWOTH 000002 by others
1957 CW_IXOTH 000001 by others
1958 CW_ISUID 004000 Set uid
1959 W_ISGID 002000 Set gid
1960 W_ISVTX 001000 Reserved
1961 File Type Name Value Indicates
1967 C_ISDIR 040000 Directory
1968 C_ISFIFO 010000 FIFO
1969 C_ISREG 0100000 Regular file
1970 C_ISLNK 0120000 Symbolic link
1971 C_ISBLK 060000 Block special file
1972 C_ISCHR 020000 Character special file
1973 C_ISSOCK 0140000 Socket
1974 C_ISCTG 0110000 Reserved
1975 c_uid Contains the user ID of the owner.
1979 c_gid Contains the group ID of the group
1982 c_nlink Contains a number greater than or equal to the number of
1985 links in the archive referencing the file. If the -a
1986 option is used to append to a cpio archive, pax does
1987 need not to account for the files in the existing part
1988 of the archive when calculating the c_nlink values for
1989 the appended part of the archive. It does also need not
1990 alter the c_nlink values in the existing part of the ar‐
1991 chive if additional files with the same c_dev and c-ino
1992 values are appended to the archive.
1993 c_rdev Contains implementation-defined information for charac‐
1996 ter or block special files.
1997 c_mtime Contains the latest time of modification of the file at
2000 the time the archive was created.
2001 c_namesize Contains the length of the pathname, including the ter‐
2004 minating NULL character.
2005 c_filesize Contains the length of the file in octets. This is the
2008 length of the data section following the header struc‐
2009 ture.
2010 cpio Filename
2013 The c_name field contains the pathname of the file. The length of this
2014 field in octets is the value of c_namesize. If a filename is found on
2015 the medium that would create an invalid pathname, it is implementation-
2016 defined whether the data from the file is stored on the file hierarchy
2017 and under what name it is stored. All characters are represented in the
2018 ISO/IEC 646: 1991 standard IRV. For maximum portability between imple‐
2019 mentations, names should be selected from characters represented by the
2020 portable filename character set as octets with the most significant bit
2021 zero. If an implementation supports the use of characters outside the
2022 portable filename character set in names for files, users, and groups,
2023 one or more implementation-defined encodings of these characters are
2024 provided for interchange purposes.pax does not create filenames on the
2025 local system that cannot be accessed by way of the procedures described
2026 in volume IEEE Std 1003.1-200x. If a filename is found on the medium
2027 that would create an invalid filename, it is implementation-defined
2028 whether the data from the file is stored on the local file system and
2029 under what name it is stored. pax can choose to ignore these files as
2030 long as it produces an error indicating that the file is being ignored.
2031 cpio File Data
2033 Following c_name, there is c_filesize octets of data. Interpretation of
2034 such data occurs in a manner dependent on the file. If c_filesize is
2035 zero, no data is contained in c_filedata . When restoring from an ar‐
2036 chive:
2037 o If the user does not have the appropriate privilege to cre‐
2039 ate a file of the specified type, pax ignores the entry and
2040 writes an error message to standard error.
2041 o Only regular files have data to be restored. Presuming a
2043 regular file meets any selection criteria that might be
2044 imposed on the format-reading utility by the user, such data
2045 is restored.
2046 o If a user does not have appropriate privilege to set a par‐
2048 ticular mode flag, the flag is ignored. Some of the mode
2049 flags in the archive format are not mentioned in volume IEEE
2050 Std 1003.1-200x. If the implementation does not support
2051 those flags, they can be ignored.
2052 cpio Special Entries
2054 FIFO special files, directories, and the trailer are recorded with
2055 c_filesize equal to zero. For other special files, c_filesize is
2056 unspecified in volume IEEE Std 1003.1-200x. The header for the next
2057 file entry in the archive are written directly after the last octet of
2058 the file entry preceding it. A header denoting the filename trailer
2059 indicates the end of the archive; the contents of octets in the last
2060 block of the archive following such a header are undefined.
2061
2063 See attributes(5) for descriptions of the following attributes:
2064 ┌─────────────────────────────┬─────────────────────────────┐
2069 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
2070 ├─────────────────────────────┼─────────────────────────────┤
2071 │Availability │SUNWcsu │
2072 ├─────────────────────────────┼─────────────────────────────┤
2073 │Interface Stability │Committed │
2074 ├─────────────────────────────┼─────────────────────────────┤
2075 │Standard │See standards(5). │
2076 └─────────────────────────────┴─────────────────────────────┘
2077
2079 chmod(1), cpio(1), ed(1), printf(1), tar(1), mkdir(2), lseek(2),
2080 stat(2), write(2), archives.h(3HEAD), attributes(5), environ(5),
2081 fnmatch(5), formats(5)fsattr(5), largefile(5), regex(5), standards(5)
2082 IEEE Std 1003.1-200x, ISO/IEC 646: 1991, ISO POSIX-2:1993 Standard
2085SunOS 5.11 16 Jul 2008 pax(1)