Next: remove files, Previous: Writing to Standard Output, Up: Writing [Contents][Index]

#### Writing to an External Program

You can instruct `tar` to send the contents of each extracted file to the standard input of an external program:

`--to-command=command`

  Extract files and pipe their contents to the standard input of command. When this option is used, instead of creating the files specified, `tar` invokes command and pipes the contents of the files to its standard output. The command may contain command line arguments (see Running External Commands, for more detail).

  Notice, that command is executed once for each regular file extracted. Non-regular files (directories, etc.) are ignored when this option is used.

The command can obtain the information about the file it processes from the following environment variables:

`TAR_FILETYPE`

  Type of the file. It is a single letter with the following meaning:

  f | Regular file
  d | Directory
  l | Symbolic link
  h | Hard link
  b | Block device
  c | Character device

  Currently only regular files are supported.

`TAR_MODE`

  File mode, an octal number.

`TAR_FILENAME`

  The name of the file.

`TAR_REALNAME`

  Name of the file as stored in the archive.

`TAR_UNAME`

  Name of the file owner.

`TAR_GNAME`

  Name of the file owner group.

`TAR_ATIME`

  Time of last access. It is a decimal number, representing seconds since the Epoch. If the archive provides times with nanosecond precision, the nanoseconds are appended to the timestamp after a decimal point.

`TAR_MTIME`

  Time of last modification.

`TAR_CTIME`

  Time of last status change.

`TAR_SIZE`

  Size of the file.

`TAR_UID`

  UID of the file owner.

`TAR_GID`

  GID of the file owner.

Additionally, the following variables contain information about tar mode and the archive being processed:

`TAR_VERSION`

  GNU `tar` version number.

`TAR_ARCHIVE`

  The name of the archive `tar` is processing.

`TAR_BLOCKING_FACTOR`

  Current blocking factor (see Blocking).

`TAR_VOLUME`

  Ordinal number of the volume `tar` is processing.

`TAR_FORMAT`

  Format of the archive being processed. See Formats, for a complete list of archive format names.

These variables are defined prior to executing the command, so you can pass them as arguments, if you prefer. For example, if the command proc takes the member name and size as its arguments, then you could do:

    $ tar -x -f archive.tar \
           --to-command='proc $TAR_FILENAME $TAR_SIZE'

Notice single quotes to prevent variable names from being expanded by the shell when invoking `tar`.

If command exits with a non-0 status, `tar` will print an error message similar to the following:

    tar: 2345: Child returned status 1

Here, ‘`2345`’ is the PID of the finished process.

If this behavior is not wanted, use `--ignore-command-error`:

`--ignore-command-error`

  Ignore exit codes of subprocesses. Notice that if the program exits on signal or otherwise terminates abnormally, the error message will be printed even if this option is used.

`--no-ignore-command-error`

  Cancel the effect of any previous `--ignore-command-error` option. This option is useful if you have set `--ignore-command-error` in `TAR_OPTIONS` (see TAR_OPTIONS) and wish to temporarily cancel it.

Next: remove files, Previous: Writing to Standard Output, Up: Writing [Contents][Index]