Class TarArchive

sourceStream is not seekable.

sourceStream is null.

TarArchive(string)

Initializes a new instance of the Aspose.Zip.Tar.TarArchive class and composes entries list can be extracted from the archive.

public TarArchive(string path)

Parameters

path string

The path to the archive file.

Examples

The following example shows how to extract all of the entries to a directory.

using (var archive = new TarArchive("archive.tar")) 
{ 
   archive.ExtractToDirectory("C:\extracted");
}

Remarks

This constructor does not unpack any entry. See Aspose.Zip.Tar.TarEntry.Open method for unpacking.

Exceptions

path is null.

The caller does not have the required permission to access.

UnauthorizedAccessException

The path is empty, contains only white spaces, or contains invalid characters.

Access to file path is denied.

The specified path, file name, or both exceed the system-defined maximum length. For example, on Windows-based platforms, paths must be less than 248 characters, and file names must be less than 260 characters.

DirectoryNotFoundException

File at path contains a colon (:) in the middle of the string.

FileNotFoundException

The file is not found.

The specified path is invalid, such as being on an unmapped drive.

ReadOnlyCollection<TarEntry>

The file is already open.

Properties

Entries

Gets entries of Aspose.Zip.Tar.TarEntry type constituting the archive.

public ReadOnlyCollection<tarentry> Entries { get; }

Property Value

Methods

CreateEntries(DirectoryInfo, bool)

Adds to the archive all the files and directories recursively in the directory given.

public TarArchive CreateEntries(DirectoryInfo directory, bool includeRootDirectory = true)

Parameters

directory DirectoryInfo

Directory to compress.

includeRootDirectory bool

Indicates whether to include the root directory itself or not.

Returns

The archive with entries composed.

Examples

using (FileStream tarFile = File.Open("archive.tar", FileMode.Create))
{
    using (var archive = new TarArchive())
    {
        archive.CreateEntries(new DirectoryInfo("C:\folder"), false);
        archive.Save(tarFile);
    }
}

CreateEntries(string, bool)

Adds to the archive all the files and directories recursively in the directory given.

public TarArchive CreateEntries(string sourceDirectory, bool includeRootDirectory = true)

Parameters

sourceDirectory string

Directory to compress.

includeRootDirectory bool

Indicates whether to include the root directory itself or not.

Returns

The archive with entries composed.

Examples

using (FileStream tarFile = File.Open("archive.tar", FileMode.Create))
{
    using (var archive = new TarArchive())
    {
        archive.CreateEntries("C:\folder", false);
        archive.Save(tarFile);
    }
}

Exceptions

sourceDirectory is null.

The caller does not have the required permission to access sourceDirectory.

sourceDirectory contains invalid characters such as “, <, >, or |.

The specified path, file name, or both exceed the system-defined maximum length. For example, on Windows-based platforms, paths must be less than 248 characters, and file names must be less than 260 characters. The specified path, file name, or both are too long.

CreateEntry(string, Stream, FileSystemInfo)

Create single entry within the archive.

public TarEntry CreateEntry(string name, Stream source, FileSystemInfo fileInfo = null)

Parameters

name string

The name of the entry.

source Stream

The input stream for the entry.

fileInfo FileSystemInfo

The metadata of file or folder to be compressed.

Returns

TarEntry

Tar entry instance.

Examples

using (var archive = new TarArchive())
{
   archive.CreateEntry("bytes", new MemoryStream(new byte[] {0x00, 0xFF}));
   archive.Save(tarFile);
}

Remarks

The entry name is solely set within name parameter. The file name provided in fileInfo parameter does not affect the entry name.

fileInfo can refer to System.IO.DirectoryInfo if the entry is directory.

Exceptions

name is too long for tar as of IEEE 1003.1-1998 standard.

File name, as a part of name, exceeds 100 symbols.

CreateEntry(string, FileInfo, bool)

Create a single entry within the archive.

public TarEntry CreateEntry(string name, FileInfo fileInfo, bool openImmediately = false)

Parameters

name string

The name of the entry.

fileInfo FileInfo

The metadata of file or folder to be compressed.

openImmediately bool

True, if open the file immediately, otherwise open the file on archive saving.

Returns

TarEntry

Tar entry instance.

Examples

FileInfo fi = new FileInfo("data.bin");
using (var archive = new TarArchive())
{
   archive.CreateEntry("data.bin", fi);
   archive.Save(tarFile);
}

Remarks

The entry name is solely set within name parameter. The file name provided in fileInfo parameter does not affect the entry name.

fileInfo can refer to System.IO.DirectoryInfo if the entry is directory.

If the file is opened immediately with openImmediately parameter it becomes blocked until archive is disposed.

Exceptions

name is too long for tar as of IEEE 1003.1-1998 standard.

File name, as a part of name, exceeds 100 symbols.

CreateEntry(string, string, bool)

Create a single entry within the archive.

public TarEntry CreateEntry(string name, string path, bool openImmediately = false)

Parameters

name string

The name of the entry.

path string

Path to file to be compressed.

openImmediately bool

True, if open the file immediately, otherwise open the file on archive saving.

Returns

TarEntry

Tar entry instance.

Examples

using (var archive = new TarArchive())
{
    archive.CreateEntry("first.bin", "data.bin");
    archive.Save(outputTarFile);
}

Remarks

The entry name is solely set within name parameter. The file name provided in path parameter does not affect the entry name.

If the file is opened immediately with openImmediately parameter it becomes blocked until archive is disposed.

Exceptions

path is null.

The caller does not have the required permission to access.

UnauthorizedAccessException

The path is empty, contains only white spaces, or contains invalid characters. - or - File name, as a part of name, exceeds 100 symbols.

Access to file path is denied.

File at path contains a colon (:) in the middle of the string.

DeleteEntry(TarEntry)

Removes the first occurrence of a specific entry from the entry list.

public TarArchive DeleteEntry(TarEntry entry)

Parameters

entry TarEntry

The entry to remove from the entries list.

Returns

The archive with the entry deleted.

Examples

Here is how you can remove all entries except the last one:

using (var archive = new TarArchive("archive.tar"))
{
    while (archive.Entries.Count &gt; 1)
        archive.DeleteEntry(archive.Entries[0]);
    archive.Save(outputTarFile);
}

DeleteEntry(int)

Removes the entry from the entry list by index.

public TarArchive DeleteEntry(int entryIndex)

Parameters

entryIndex int

The zero-based index of the entry to remove.

Returns

ArgumentOutOfRangeException

The archive with the entry deleted.

Examples

using (var archive = new TarArchive("two_files.tar"))
{
    archive.DeleteEntry(0);
    archive.Save("single_file.tar");
}

Exceptions

entryIndex is less than 0.-or- entryIndex is equal to or greater than Entries count.

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public void Dispose()

Dispose(bool)

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

protected virtual void Dispose(bool disposing)

Parameters

disposing bool

Whether managed resources should be disposed.

ExtractToDirectory(string)

Extracts all the files in the archive to the directory provided.

public void ExtractToDirectory(string destinationDirectory)

Parameters

destinationDirectory string

The path to the directory to place the extracted files in.

Examples

using (var archive = new TarArchive("archive.tar")) 
{ 
   archive.ExtractToDirectory("C:\extracted");
}

Remarks

If the directory does not exist, it will be created.

Exceptions

path is null

The specified path, file name, or both exceed the system-defined maximum length. For example, on Windows-based platforms, paths must be less than 248 characters and file names must be less than 260 characters.

The caller does not have the required permission to access existing directory.

If directory does not exist, path contains a colon character (:) that is not part of a drive label (“C:").

path is a zero-length string, contains only white space, or contains one or more invalid characters. You can query for invalid characters by using the System.IO.Path.GetInvalidPathChars method. -or- path is prefixed with, or contains, only a colon character (:).

The directory specified by path is a file. -or- The network name is not known.

FromGZip(Stream)

Extracts supplied gzip archive and composes Aspose.Zip.Tar.TarArchive from extracted data.

Important: gzip archive is fully extracted within this method, its content is kept internally. Beware of memory consumption.

public static TarArchive FromGZip(Stream source)

Parameters

source Stream

The source of the archive.

Returns

An instance of Aspose.Zip.Tar.TarArchive

Remarks

GZip extraction stream is not seekable by the nature of compression algorithm. Tar archive provides facility to extract arbitrary record, so it has to operate seekable stream under the hood.

Exceptions

Archive is corrupted.

FromGZip(string)

Extracts supplied gzip archive and composes Aspose.Zip.Tar.TarArchive from extracted data.

Important: gzip archive is fully extracted within this method, its content is kept internally. Beware of memory consumption.

public static TarArchive FromGZip(string path)

Parameters

path string

The path to the archive file.

Returns

An instance of Aspose.Zip.Tar.TarArchive

Remarks

GZip extraction stream is not seekable by the nature of compression algorithm. Tar archive provides facility to extract arbitrary record, so it has to operate seekable stream under the hood.

Exceptions

Archive is corrupted.

FromLZMA(Stream)

Extracts supplied LZMA archive and composes Aspose.Zip.Tar.TarArchive from extracted data.

Important: LZMA archive is fully extracted within this method, its content is kept internally. Beware of memory consumption.

public static TarArchive FromLZMA(Stream source)

Parameters

source Stream

The source of the archive.

Returns

An instance of Aspose.Zip.Tar.TarArchive

Remarks

LZMA extraction stream is not seekable by the nature of compression algorithm. Tar archive provides facility to extract arbitrary record, so it has to operate seekable stream under the hood.

FromLZMA(string)

Extracts supplied LZMA archive and composes Aspose.Zip.Tar.TarArchive from extracted data.

Important: LZMA archive is fully extracted within this method, its content is kept internally. Beware of memory consumption.

public static TarArchive FromLZMA(string path)

Parameters

path string

The path to the archive file.

Returns

An instance of Aspose.Zip.Tar.TarArchive

Remarks

LZMA extraction stream is not seekable by the nature of compression algorithm. Tar archive provides facility to extract arbitrary record, so it has to operate seekable stream under the hood.

FromLZip(Stream)

Extracts supplied lzip archive and composes Aspose.Zip.Tar.TarArchive from extracted data.

Important: lzip archive is fully extracted within this method, its content is kept internally. Beware of memory consumption.

public static TarArchive FromLZip(Stream source)

Parameters

source Stream

The source of the archive.

Returns

An instance of Aspose.Zip.Tar.TarArchive

Remarks

Lzip extraction stream is not seekable by the nature of compression algorithm. Tar archive provides facility to extract arbitrary record, so it has to operate seekable stream under the hood.

FromLZip(string)

Extracts supplied lzip archive and composes Aspose.Zip.Tar.TarArchive from extracted data.

Important: lzip archive is fully extracted within this method, its content is kept internally. Beware of memory consumption.

public static TarArchive FromLZip(string path)

Parameters

path string

The path to the archive file.

Returns

An instance of Aspose.Zip.Tar.TarArchive

Remarks

Lzip extraction stream is not seekable by the nature of compression algorithm. Tar archive provides facility to extract arbitrary record, so it has to operate seekable stream under the hood.

FromXz(Stream)

Extracts supplied xz format archive and composes Aspose.Zip.Tar.TarArchive from extracted data.

Important: xz archive is fully extracted within this method, its content is kept internally. Beware of memory consumption.

public static TarArchive FromXz(Stream source)

Parameters

source Stream

The source of the archive.

Returns

An instance of Aspose.Zip.Tar.TarArchive

Remarks

Tar archive provides facility to extract arbitrary record, so it has to operate seekable stream under the hood.

FromXz(string)

Extracts supplied xz format archive and composes Aspose.Zip.Tar.TarArchive from extracted data.

Important: xz archive is fully extracted within this method, its content is kept internally. Beware of memory consumption.

public static TarArchive FromXz(string path)

Parameters

path string

The path to the archive file.

Returns

An instance of Aspose.Zip.Tar.TarArchive

Remarks

Tar archive provides facility to extract arbitrary record, so it has to operate seekable stream under the hood.

FromZ(Stream)

Extracts supplied Z format archive and composes Aspose.Zip.Tar.TarArchive from extracted data.

Important: Z archive is fully extracted within this method, its content is kept internally. Beware of memory consumption.

public static TarArchive FromZ(Stream source)

Parameters

source Stream

The source of the archive.

Returns

An instance of Aspose.Zip.Tar.TarArchive

Remarks

Tar archive provides facility to extract arbitrary record, so it has to operate seekable stream under the hood.

FromZ(string)

Extracts supplied Z format archive and composes Aspose.Zip.Tar.TarArchive from extracted data.

Important: Z archive is fully extracted within this method, its content is kept internally. Beware of memory consumption.

public static TarArchive FromZ(string path)

Parameters

path string

The path to the archive file.

Returns

An instance of Aspose.Zip.Tar.TarArchive

Remarks

Tar archive provides facility to extract arbitrary record, so it has to operate seekable stream under the hood.

FromZstandard(Stream)

Extracts supplied Zstandard archive and composes Aspose.Zip.Tar.TarArchive from extracted data.

Important: Zstandard archive is fully extracted within this method, its content is kept internally. Beware of memory consumption.

public static TarArchive FromZstandard(Stream source)

Parameters

source Stream

The source of the archive.

Returns

An instance of Aspose.Zip.Tar.TarArchive

Exceptions

Zstandard stream is corrupted or not readable.

Data is corrupted.

FromZstandard(string)

Extracts supplied Zstandard archive and composes Aspose.Zip.Tar.TarArchive from extracted data.

Important: Zstandard archive is fully extracted within this method, its content is kept internally. Beware of memory consumption.

public static TarArchive FromZstandard(string path)

Parameters

path string

The path to the archive file.

Returns

An instance of Aspose.Zip.Tar.TarArchive

Exceptions

Zstandard stream is corrupted or not readable.

Data is corrupted.

Save(Stream, TarFormat?)

Saves archive to the stream provided.

public void Save(Stream output, TarFormat? format = null)

Parameters

output Stream

Destination stream.

format TarFormat?

Defines tar header format. Null value will be treated as USTar when possible.

Examples

using (FileStream tarFile = File.Open("archive.tar", FileMode.Create))
{
    using (var archive = new TarArchive())
    {
        archive.CreateEntry("entry1", "data.bin");
        archive.Save(tarFile);
    }
}

Remarks

output must be writable.

Exceptions

output is not writable. - or - output is the same stream we extract from. - OR - It is impossible to save archive in format due to format restrictions.

Save(string, TarFormat?)

Saves archive to destination file provided.

public void Save(string destinationFileName, TarFormat? format = null)

Parameters

destinationFileName string

The path of the archive to be created. If the specified file name points to an existing file, it will be overwritten.

format TarFormat?

Defines tar header format. Null value will be treated as USTar when possible.

Examples

using (var archive = new TarArchive())
{
    archive.CreateEntry("entry1", "data.bin");        
    archive.Save("myarchive.tar");
}

Remarks

It is possible to save an archive to the same path as it was loaded from. However, this is not recommended because this approach uses copying to temporary file.

Exceptions

destinationFileName is a zero-length string, contains only white space, or contains one or more invalid characters as defined by System.IO.Path.InvalidPathChars.

destinationFileName is null.

DirectoryNotFoundException

The specified destinationFileName, file name, or both exceed the system-defined maximum length. For example, on Windows-based platforms, paths must be less than 248 characters, and file names must be less than 260 characters.

The specified destinationFileName is invalid, (for example, it is on an unmapped drive).

UnauthorizedAccessException

An I/O error occurred while opening the file.

destinationFileName specified a file that is read-only and access is not Read.-or- path specified a directory.-or- The caller does not have the required permission.

destinationFileName is in an invalid format.

FileNotFoundException

The file is not found.

SaveGzipped(Stream, TarFormat?)

Saves archive to the stream with gzip compression.

public void SaveGzipped(Stream output, TarFormat? format = null)

Parameters

output Stream

Destination stream.

format TarFormat?

Defines the tar header format. Null value will be treated as USTar when possible.

Examples

using (FileStream result = File.OpenWrite("result.tar.gz"))
{
    using (FileStream source = File.Open("data.bin", FileMode.Open, FileAccess.Read))
    {
        using (var archive = new TarArchive())
        {
            archive.CreateEntry("entry.bin", source);
            archive.SaveGzipped(result);
        }
    }
}

Remarks

output must be writable.

Exceptions

output is null.

output is not writable.

SaveGzipped(string, TarFormat?)

Saves archive to the file by path with gzip compression.

public void SaveGzipped(string path, TarFormat? format = null)

Parameters

path string

The path of the archive to be created. If the specified file name points to an existing file, it will be overwritten.

format TarFormat?

Defines the tar header format. Null value will be treated as USTar when possible.

Examples

using (FileStream source = File.Open("data.bin", FileMode.Open, FileAccess.Read))
{
    using (var archive = new TarArchive())
    {
        archive.CreateEntry("entry.bin", source);
        archive.SaveGzipped("result.tar.gz");
    }
}

SaveLZMACompressed(Stream, TarFormat?)

Saves archive to the stream with LZMA compression.

public void SaveLZMACompressed(Stream output, TarFormat? format = null)

Parameters

output Stream

Destination stream.

format TarFormat?

Defines the tar header format. Null value will be treated as USTar when possible.

Examples

using (FileStream result = File.OpenWrite("result.tar.lzma"))
{
    using (FileStream source = File.Open("data.bin", FileMode.Open, FileAccess.Read))
    {
        using (var archive = new TarArchive())
        {
            archive.CreateEntry("entry.bin", source);
            archive.SaveLZMACompressed(result);
        }
    }
}

Remarks

output must be writable.

Important: tar archive is composed then compressed within this method, its content is kept internally. Beware of memory consumption.

Exceptions

output is null.

output is not writable.

SaveLZMACompressed(string, TarFormat?)

Saves archive to the file by path with lzma compression.

public void SaveLZMACompressed(string path, TarFormat? format = null)

Parameters

path string

The path of the archive to be created. If the specified file name points to an existing file, it will be overwritten.

format TarFormat?

Defines the tar header format. Null value will be treated as USTar when possible.

Examples

using (FileStream source = File.Open("data.bin", FileMode.Open, FileAccess.Read))
{
    using (var archive = new TarArchive())
    {
        archive.CreateEntry("entry.bin", source);
        archive.SaveLZMACompressed("result.tar.lzma");
    }
}

Remarks

Important: tar archive is composed then compressed within this method, its content is kept internally. Beware of memory consumption.

SaveLzipped(Stream, TarFormat?)

Saves archive to the stream with lzip compression.

public void SaveLzipped(Stream output, TarFormat? format = null)

Parameters

output Stream

Destination stream.

format TarFormat?

Defines tar header format. Null value will be treated as USTar when possible.

Examples

using (FileStream result = File.OpenWrite("result.tar.lz"))
{
    using (FileStream source = File.Open("data.bin", FileMode.Open, FileAccess.Read))
    {
        using (var archive = new TarArchive())
        {
            archive.CreateEntry("entry.bin", source);
            archive.SaveLzipped(result);
        }
    }
}

Remarks

output must be writable.

Exceptions

output is null.

output is not writable.

SaveLzipped(string, TarFormat?)

Saves archive to the file by path with lzip compression.

public void SaveLzipped(string path, TarFormat? format = null)

Parameters

path string

The path of the archive to be created. If the specified file name points to an existing file, it will be overwritten.

format TarFormat?

Defines the tar header format. Null value will be treated as USTar when possible.

Examples

using (FileStream source = File.Open("data.bin", FileMode.Open, FileAccess.Read))
{
    using (var archive = new TarArchive())
    {
        archive.CreateEntry("entry.bin", source);
        archive.SaveGzipped("result.tar.lz");
    }
}

SaveXzCompressed(Stream, TarFormat?, XzArchiveSettings)

Saves archive to the stream with xz compression.

public void SaveXzCompressed(Stream output, TarFormat? format = null, XzArchiveSettings settings = null)

Parameters

output Stream

Destination stream.

format TarFormat?

Defines the tar header format. Null value will be treated as USTar when possible.

settings XzArchiveSettings

Set of setting particular xz archive: dictionary size, block size, check type.

Examples

using (FileStream result = File.OpenWrite("result.tar.xz"))
{
    using (FileStream source = File.Open("data.bin", FileMode.Open, FileAccess.Read))
    {
        using (var archive = new TarArchive())
        {
            archive.CreateEntry("entry.bin", source);
            archive.SaveXzCompressed(result);
        }
    }
}

Remarks

outputThe stream must be writable.

Exceptions

output is null.

output is not writable.

SaveXzCompressed(string, TarFormat?, XzArchiveSettings)

Saves archive to the path by path with xz compression.

public void SaveXzCompressed(string path, TarFormat? format = null, XzArchiveSettings settings = null)

Parameters

path string

The path of the archive to be created. If the specified file name points to an existing file, it will be overwritten.

format TarFormat?

Defines tar header format. Null value will be treated as USTar when possible.

settings XzArchiveSettings

Set of setting particular xz archive: dictionary size, block size, check type.

Examples

using (FileStream source = File.Open("data.bin", FileMode.Open, FileAccess.Read))
{
    using (var archive = new TarArchive())
    {
        archive.CreateEntry("entry.bin", source);
        archive.SaveXzCompressed("result.tar.xz");
    }
}

SaveZCompressed(Stream, TarFormat?)

Saves archive to the stream with Z compression.

public void SaveZCompressed(Stream output, TarFormat? format = null)

Parameters

output Stream

Destination stream.

format TarFormat?

Defines the tar header format. Null value will be treated as USTar when possible.

Examples

using (FileStream result = File.OpenWrite("result.tar.Z"))
{
    using (FileStream source = File.Open("data.bin", FileMode.Open, FileAccess.Read))
    {
        using (var archive = new TarArchive())
        {
            archive.CreateEntry("entry.bin", source);
            archive.SaveZCompressed(result);
        }
    }
}

Remarks

output must be writable.

Exceptions

output is null.

output is not writable.

SaveZCompressed(string, TarFormat?)

Saves archive to the path by path with Z compression.

public void SaveZCompressed(string path, TarFormat? format = null)

Parameters

path string

The path of the archive to be created. If the specified file name points to an existing file, it will be overwritten.

format TarFormat?

Defines the tar header format. Null value will be treated as USTar when possible.

Examples

using (FileStream source = File.Open("data.bin", FileMode.Open, FileAccess.Read))
{
    using (var archive = new TarArchive())
    {
        archive.CreateEntry("entry.bin", source);
        archive.SaveZCompressed("result.tar.Z");
    }
}

SaveZstandard(Stream, TarFormat?)

Saves archive to the stream with Zstandard compression.

public void SaveZstandard(Stream output, TarFormat? format = null)

Parameters

output Stream

Destination stream.

format TarFormat?

Defines the tar header format. Null value will be treated as USTar when possible.

Examples

using (FileStream result = File.OpenWrite("result.tar.zst"))
{
    using (FileStream source = File.Open("data.bin", FileMode.Open, FileAccess.Read))
    {
        using (var archive = new TarArchive())
        {
            archive.CreateEntry("entry.bin", source);
            archive.SaveZstandard(result);
        }
    }
}

Remarks

output must be writable.

Exceptions

output is null.