Class TarArchive

The TarArchive class implements the concept of a 'Tape Archive'. A tar archive is a series of entries, each of which represents a file system object. Each entry in the archive consists of a header block followed by 0 or more data blocks. Directory entries consist only of the header block, and are followed by entries for the directory's contents. File entries consist of a header followed by the number of blocks needed to contain the file's contents. All entries are written on block boundaries. Blocks are 512 bytes long.

TarArchives are instantiated in either read or write mode, based upon whether they are instantiated with an InputStream or an OutputStream. Once instantiated TarArchives read/write mode can not be changed.

There is currently no support for random access to tar archives. However, it seems that subclassing TarArchive, and using the TarBuffer.CurrentRecord and TarBuffer.CurrentBlock properties, this would be rather trivial.

Inheritance

System.Object

TarArchive

Implements

System.IDisposable

Inherited Members

System.Object.Equals(System.Object)

System.Object.Equals(System.Object, System.Object)

System.Object.GetHashCode()

System.Object.GetType()

System.Object.MemberwiseClone()

System.Object.ReferenceEquals(System.Object, System.Object)

System.Object.ToString()

Namespace: ICSharpCode.SharpZipLib.Tar

Assembly: ICSharpCode.SharpZipLib.dll

Syntax

public class TarArchive : IDisposable

Constructors

TarArchive()

Constructor for a default TarArchive.

Declaration

protected TarArchive()

TarArchive(TarInputStream)

Initialise a TarArchive for input.

Declaration

protected TarArchive(TarInputStream stream)

Parameters

Type	Name	Description
TarInputStream	stream	The TarInputStream to use for input.

TarArchive(TarOutputStream)

Initialise a TarArchive for output.

Declaration

protected TarArchive(TarOutputStream stream)

Parameters

Type	Name	Description
TarOutputStream	stream	The TarOutputStream to use for output.

Properties

ApplyUserInfoOverrides

Get or set a value indicating if overrides defined by SetUserInfo should be applied.

Declaration

public bool ApplyUserInfoOverrides { get; set; }

Property Value

Type	Description
System.Boolean

Remarks

If overrides are not applied then the values as set in each header will be used.

AsciiTranslate

Get/set the ascii file translation flag. If ascii file translation is true, then the file is checked to see if it a binary file or not. If the flag is true and the test indicates it is ascii text file, it will be translated. The translation converts the local operating system's concept of line ends into the UNIX line end, '\n', which is the defacto standard for a TAR archive. This makes text files compatible with UNIX.

Declaration

public bool AsciiTranslate { get; set; }

Property Value

Type	Description
System.Boolean

GroupId

Get the archive group id. See ApplyUserInfoOverrides for detail on how to allow setting values on a per entry basis.

Declaration

public int GroupId { get; }

Property Value

Type	Description
System.Int32	The current group id.

GroupName

Get the archive group name. See ApplyUserInfoOverrides for detail on how to allow setting values on a per entry basis.

Declaration

public string GroupName { get; }

Property Value

Type	Description
System.String	The current group name.

IsStreamOwner

Sets the IsStreamOwner property on the underlying stream. Set this to false to prevent the Close of the TarArchive from closing the stream.

Declaration

public bool IsStreamOwner { set; }

Property Value

Type	Description
System.Boolean

PathPrefix

PathPrefix is added to entry names as they are written if the value is not null. A slash character is appended after PathPrefix

Declaration

public string PathPrefix { get; set; }

Property Value

Type	Description
System.String

RecordSize

Get the archive's record size. Tar archives are composed of a series of RECORDS each containing a number of BLOCKS. This allowed tar archives to match the IO characteristics of the physical device being used. Archives are expected to be properly "blocked".

Declaration

public int RecordSize { get; }

Property Value

Type	Description
System.Int32	The record size this archive is using.

RootPath

RootPath is removed from entry names if it is found at the beginning of the name.

Declaration

public string RootPath { get; set; }

Property Value

Type	Description
System.String

UserId

Get the archive user id. See ApplyUserInfoOverrides for detail on how to allow setting values on a per entry basis.

Declaration

public int UserId { get; }

Property Value

Type	Description
System.Int32	The current user id.

UserName

Get the archive user name. See ApplyUserInfoOverrides for detail on how to allow setting values on a per entry basis.

Declaration

public string UserName { get; }

Property Value

Type	Description
System.String	The current user name.

Methods

Close()

Closes the archive and releases any associated resources.

Declaration

public virtual void Close()

CloseArchive()

Close the archive.

Declaration

[Obsolete("Use Close instead")]
public void CloseArchive()

CreateInputTarArchive(Stream)

The InputStream based constructors create a TarArchive for the purposes of extracting or listing a tar archive. Thus, use these constructors when you wish to extract files from or list the contents of an existing tar archive.

Declaration

[Obsolete("No Encoding for Name field is specified, any non-ASCII bytes will be discarded")]
public static TarArchive CreateInputTarArchive(Stream inputStream)

Parameters

Type	Name	Description
System.IO.Stream	inputStream	The stream to retrieve archive data from.

Returns

Type	Description
TarArchive	Returns a new TarArchive suitable for reading from.

CreateInputTarArchive(Stream, Int32)

Create TarArchive for reading setting block factor

Declaration

[Obsolete("No Encoding for Name field is specified, any non-ASCII bytes will be discarded")]
public static TarArchive CreateInputTarArchive(Stream inputStream, int blockFactor)

Parameters

Type	Name	Description
System.IO.Stream	inputStream	A stream containing the tar archive contents
System.Int32	blockFactor	The blocking factor to apply

Returns

Type	Description
TarArchive	Returns a TarArchive suitable for reading.

CreateInputTarArchive(Stream, Int32, Encoding)

Create TarArchive for reading setting block factor

Declaration

public static TarArchive CreateInputTarArchive(Stream inputStream, int blockFactor, Encoding nameEncoding)

Parameters

Type	Name	Description
System.IO.Stream	inputStream	A stream containing the tar archive contents
System.Int32	blockFactor	The blocking factor to apply
System.Text.Encoding	nameEncoding	The System.Text.Encoding used for the Name fields, or null for ASCII only

Returns

Type	Description
TarArchive	Returns a TarArchive suitable for reading.

CreateInputTarArchive(Stream, Encoding)

The InputStream based constructors create a TarArchive for the purposes of extracting or listing a tar archive. Thus, use these constructors when you wish to extract files from or list the contents of an existing tar archive.

Declaration

public static TarArchive CreateInputTarArchive(Stream inputStream, Encoding nameEncoding)

Parameters

Type	Name	Description
System.IO.Stream	inputStream	The stream to retrieve archive data from.
System.Text.Encoding	nameEncoding	The System.Text.Encoding used for the Name fields, or null for ASCII only

Returns

Type	Description
TarArchive	Returns a new TarArchive suitable for reading from.

CreateOutputTarArchive(Stream)

Create a TarArchive for writing to, using the default blocking factor

Declaration

public static TarArchive CreateOutputTarArchive(Stream outputStream)

Parameters

Type	Name	Description
System.IO.Stream	outputStream	The System.IO.Stream to write to

Returns

Type	Description
TarArchive	Returns a TarArchive suitable for writing.

CreateOutputTarArchive(Stream, Int32)

Create a tar archive for writing.

Declaration

public static TarArchive CreateOutputTarArchive(Stream outputStream, int blockFactor)

Parameters

Type	Name	Description
System.IO.Stream	outputStream	The stream to write to
System.Int32	blockFactor	The blocking factor to use for buffering.

Returns

Type	Description
TarArchive	Returns a TarArchive suitable for writing.

CreateOutputTarArchive(Stream, Int32, Encoding)

Create a tar archive for writing.

Declaration

public static TarArchive CreateOutputTarArchive(Stream outputStream, int blockFactor, Encoding nameEncoding)

Parameters

Type	Name	Description
System.IO.Stream	outputStream	The stream to write to
System.Int32	blockFactor	The blocking factor to use for buffering.
System.Text.Encoding	nameEncoding	The System.Text.Encoding used for the Name fields, or null for ASCII only

Returns

Type	Description
TarArchive	Returns a TarArchive suitable for writing.

CreateOutputTarArchive(Stream, Encoding)

Create a TarArchive for writing to, using the default blocking factor

Declaration

public static TarArchive CreateOutputTarArchive(Stream outputStream, Encoding nameEncoding)

Parameters

Type	Name	Description
System.IO.Stream	outputStream	The System.IO.Stream to write to
System.Text.Encoding	nameEncoding	The System.Text.Encoding used for the Name fields, or null for ASCII only

Returns

Type	Description
TarArchive	Returns a TarArchive suitable for writing.

Dispose()

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

Declaration

public void Dispose()

Dispose(Boolean)

Releases the unmanaged resources used by the FileStream and optionally releases the managed resources.

Declaration

protected virtual void Dispose(bool disposing)

Parameters

Type	Name	Description
System.Boolean	disposing	true to release both managed and unmanaged resources; false to release only unmanaged resources.

ExtractContents(String)

Perform the "extract" command and extract the contents of the archive.

Declaration

public void ExtractContents(string destinationDirectory)

Parameters

Type	Name	Description
System.String	destinationDirectory	The destination directory into which to extract.

ExtractContents(String, Boolean)

Perform the "extract" command and extract the contents of the archive.

Declaration

public void ExtractContents(string destinationDirectory, bool allowParentTraversal)

Parameters

Type	Name	Description
System.String	destinationDirectory	The destination directory into which to extract.
System.Boolean	allowParentTraversal	Allow parent directory traversal in file paths (e.g. ../file)

Finalize()

Ensures that resources are freed and other cleanup operations are performed when the garbage collector reclaims the TarArchive.

Declaration

protected void Finalize()

ListContents()

Perform the "list" command for the archive contents.

NOTE That this method uses the progress event to actually list the contents. If the progress display event is not set, nothing will be listed!

Declaration

public void ListContents()

OnProgressMessageEvent(TarEntry, String)

Raises the ProgressMessage event

Declaration

protected virtual void OnProgressMessageEvent(TarEntry entry, string message)

Parameters

Type	Name	Description
TarEntry	entry	The TarEntry for this event
System.String	message	message for this event. Null is no message

SetAsciiTranslation(Boolean)

Set the ascii file translation flag.

Declaration

[Obsolete("Use the AsciiTranslate property")]
public void SetAsciiTranslation(bool translateAsciiFiles)

Parameters

Type	Name	Description
System.Boolean	translateAsciiFiles	If true, translate ascii text files.

SetKeepOldFiles(Boolean)

Set the flag that determines whether existing files are kept, or overwritten during extraction.

Declaration

public void SetKeepOldFiles(bool keepExistingFiles)

Parameters

Type	Name	Description
System.Boolean	keepExistingFiles	If true, do not overwrite existing files.

SetUserInfo(Int32, String, Int32, String)

Set user and group information that will be used to fill in the tar archive's entry headers. This information is based on that available for the linux operating system, which is not always available on other operating systems. TarArchive allows the programmer to specify values to be used in their place. ApplyUserInfoOverrides is set to true by this call.

Declaration

public void SetUserInfo(int userId, string userName, int groupId, string groupName)

Parameters

Type	Name	Description
System.Int32	userId	The user id to use in the headers.
System.String	userName	The user name to use in the headers.
System.Int32	groupId	The group id to use in the headers.
System.String	groupName	The group name to use in the headers.

WriteEntry(TarEntry, Boolean)

Write an entry to the archive. This method will call the putNextEntry and then write the contents of the entry, and finally call closeEntry() for entries that are files. For directories, it will call putNextEntry(), and then, if the recurse flag is true, process each entry that is a child of the directory.

Declaration

public void WriteEntry(TarEntry sourceEntry, bool recurse)

Parameters

Type	Name	Description
TarEntry	sourceEntry	The TarEntry representing the entry to write to the archive.
System.Boolean	recurse	If true, process the children of directory entries.

Events

ProgressMessageEvent

Client hook allowing detailed information to be reported during processing

Declaration

public event ProgressMessageHandler ProgressMessageEvent

Event Type

Type	Description
ProgressMessageHandler

Implements

System.IDisposable