PAX keywords (GNU tar 1.35)

#### 8.3.7.1 Controlling Extended Header Keywords

`--pax-option=keyword-list`

  Handle keywords in PAX extended headers. This option is equivalent to `-o` option of the `pax` utility.

Keyword-list is a comma-separated list of keyword options, each keyword option taking one of the following forms:

`delete=pattern`

  When used with one of archive-creation commands, this option instructs `tar` to omit from extended header records that it produces any keywords matching the string pattern. If the pattern contains shell metacharacters like ‘`*`’, it should be quoted to prevent the shell from expanding the pattern before `tar` sees it.

  When used in extract or list mode, this option instructs tar to ignore any keywords matching the given pattern in the extended header records. In both cases, matching is performed using the pattern matching notation described in POSIX 1003.2, 3.13 (see Wildcards Patterns and Matching). For example:

      --pax-option 'delete=security.*'

  would suppress security-related information.

`exthdr.name=string`

  This keyword allows user control over the name that is written into the ustar header blocks for the extended headers. The name is obtained from string after making the following substitutions:

  Meta-character | Replaced By
  --- | ---
  %d | The directory name of the file, equivalent to the result of the `dirname` utility on the translated file name.
  %f | The name of the file with the directory information stripped, equivalent to the result of the `basename` utility on the translated file name.
  %p | The process ID of the `tar` process.
  %% | A ‘`%`’ character.

  Any other ‘`%`’ characters in string produce undefined results.

  If no option ‘`exthdr.name=string`’ is specified, `tar` will use the following default value:

      %d/PaxHeaders/%f

  This default is selected to ensure the reproducibility of the archive. POSIX standard recommends to use ‘`%d/PaxHeaders.%p/%f`’ instead, which means the two archives created with the same set of options and containing the same set of files will be byte-to-byte different. This default will be used if the environment variable `POSIXLY_CORRECT` is set.

`exthdr.mtime=value`

  This keyword defines the value of the ‘`mtime`’ field that is written into the ustar header blocks for the extended headers. By default, the ‘`mtime`’ field is set to the modification time of the archive member described by that extended header (or to the value of the `--mtime` option, if supplied).

`globexthdr.name=string`

  This keyword allows user control over the name that is written into the ustar header blocks for global extended header records. The name is obtained from the contents of string, after making the following substitutions:

  Meta-character | Replaced By
  --- | ---
  %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 `tar` process.
  %% | A ‘`%`’ character.

  Any other ‘`%`’ characters in string produce undefined results.

  If no option ‘`globexthdr.name=string`’ is specified, `tar` will use the following default value:

      $TMPDIR/GlobalHead.%n

  If the environment variable `POSIXLY_CORRECT` is set, the following value is used instead:

      $TMPDIR/GlobalHead.%p.%n

  In both cases, ‘`$TMPDIR`’ stands for the value of the TMPDIR environment variable. If TMPDIR is not set, `tar` uses ‘`/tmp`’.

`globexthdr.mtime=value`

  This keyword defines the value of the ‘`mtime`’ field that is written into the ustar header blocks for the global extended headers. By default, the ‘`mtime`’ field is set to the time when `tar` was invoked.

`keyword=value`

  When used with one of archive-creation commands, these keyword/value pairs will be included at the beginning of the archive in a global extended header record. When used with one of archive-reading commands, `tar` will behave as if it has encountered these keyword/value pairs at the beginning of the archive in a global extended header record.

`keyword:=value`

  When used with one of archive-creation commands, these keyword/value pairs will be included as records at the beginning of an extended header for each file. This is effectively equivalent to keyword=value form except that it creates no global extended header records.

  When used with one of archive-reading commands, `tar` will behave as if these keyword/value pairs were included as records at the end of each extended header; thus, they will override any global or file-specific extended header record keywords of the same names. For example, in the command:

      tar --format=posix --create \
          --file archive --pax-option gname:=user .

  the group name will be forced to a new value for all files stored in the archive.

In any of the forms described above, the value may be a string enclosed in curly braces. In that case, the string between the braces is understood either as a textual time representation, as described in Date input formats, or a name of the existing file, starting with ‘`/`’ or ‘`.`’. In the latter case, the modification time of that file is used.

For example, to set all modification times to the current date, you use the following option:

    --pax-option 'mtime:={now}'

As another example, here is the option that ensures that any two archives created using it, will be binary equivalent if they have the same contents:

    --pax-option delete=atime

If you extract files from such an archive and recreate the archive from them, you will also need to eliminate changes due to ctime:

    --pax-option 'delete=atime,delete=ctime'

Normally `tar` saves an mtime value with subsecond resolution in an extended header for any file with a timestamp that is not on a one-second boundary. This is in addition to the traditional mtime timestamp in the header block. Although you can suppress subsecond timestamp resolution with `--pax-option delete=mtime`, this hack will not work for timestamps before 1970 or after 2242-03-16 12:56:31 UTC.

If the environment variable `POSIXLY_CORRECT` is set, two POSIX archives created using the same options on the same set of files might not be byte-to-byte equivalent even with the above options. This is because the POSIX default for extended header names includes the `tar` process ID, which typically differs at each run. To produce byte-to-byte equivalent archives in this case, either unset `POSIXLY_CORRECT`, or use the following option, which can be combined with the above options:

    --pax-option exthdr.name=%d/PaxHeaders/%f