FILE_UNTAR

The FILE_UNTAR procedure uncompresses a TAR file or TAR data stream. FILE_UNTAR also automatically performs GZIP uncompression if necessary.

This routine is written in the IDL language. Its source code can be found in the file file_untar.pro in the lib subdirectory of the IDL distribution.

Note: Because of IDL's file I/O limitations, the resulting files and directories will not have any of the original file owner information, permissions (file modes) or time stamps. Instead, the files and directories will have the current file owner and default permissions, and will have a time stamp equal to the current system time.

Examples

In the following example, we create a TAR archive of the resource/fonts subdirectory within the IDL installation, and then expand the archive into our current working directory:

dir = FILEPATH('', SUBDIR=['resource','fonts'])

FILE_TAR, dir, 'idlresources.tar'

FILE_UNTAR, 'idlresources.tar', /VERBOSE

IDL prints:

% fonts/

% fonts/hersh1.chr, 97718 bytes

% fonts/tt/ttfont.map, 957 bytes

...

% Total 61 files, 2066629 bytes

% Time elapsed: 0.36199999 seconds.

Here, we get the list of all files in a ZIP, and extract only the first five files into our current working directory:

dir = FILEPATH('', SUBDIR=['resource','fonts'])

FILE_TAR, dir, 'idlresources.tar'

FILE_UNTAR, 'idlresources.tar', /LIST, FILES=files

FILE_UNTAR, 'idlresources.tar', EXTRACT_FILES=files[0:4], /VERBOSE

IDL prints:

% fonts/

  Extracted file fonts\

% fonts/hersh1.chr, 97718 bytes

  Extracted file fonts\hersh1.chr

% fonts/ps/

  Extracted file fonts\ps\

% fonts/ps/Arimo-Bold.pfa, 123426 bytes

  Extracted file fonts\ps\Arimo-Bold.pfa

% fonts/ps/Arimo-BoldItalic.pfa, 122513 bytes

  Extracted file fonts\ps\Arimo-BoldItalic.pfa

% fonts/ps/Arimo-Italic.pfa, 108377 bytes

  Skipped file fonts\ps\Arimo-Italic.pfa

...

% fonts/tt/ttfont.map, 1233 bytes

  Skipped file fonts\tt\ttfont.map

% Total 5 files, 11405628 bytes

% Time elapsed: 0.035000086 seconds.

See FILE_TAR for a different example using the Data argument.

Syntax

FILE_UNTAR, File [, DirectoryOut] [, FILES=variable] [, /LIST] [, /VERBOSE] [, /EXTRACT_FILES]

FILE_UNTAR, Data [, DirectoryOut] [, FILES=variable] [, /LIST] [, /VERBOSE] [, /EXTRACT_FILES]

Arguments

File

Set this argument to a scalar string giving the file to untar. IDL will automatically detect if the file is also GZIP compressed and uncompress the file first.

Data

Instead of a file name, you can set the first argument to a byte array containing the contents of a TAR file. IDL will automatically detect if the data stream is also GZIP compressed and uncompress the data first.

DirectoryOut

Set this optional argument to a scalar string giving the output directory. This directory will be created if it does not currently exist. If DirectoryOut is not provided then FILE_UNTAR will untar the archive into File's current directory.

Note: If the first argument is a data stream instead of a file name, then you must specify the DirectoryOut argument.

Keywords

EXTRACT_FILES

Set this keyword to a string or array of strings with the names of the files to be extracted from the zip. Unknown filenames will be ignored.

FILES

Set this keyword to a named variable. On return, this variable will contain a string array of all of the directories and files that were untarred.

LIST

Set this keyword to perform all of the FILE_UNTAR actions without actually untarring the file. The list of files can be retrieved using the FILES keyword, while the VERBOSE keyword will output the list of directories and files within the TAR file.

VERBOSE

Set this keyword to output additional information while the routine is executing.

Version History

8.2.3	Introduced
8.7	Added EXTRACT_FILES keyword