TarWriter

public struct TarWriter

A type that allows to iteratively create TAR containers with the output being written into a FileHandle.

The TarWriter may be helpful in reducing the peak memory usage on certain platforms. However, to achieve this both the creation of TAR entries and the calls to TarWriter should be wrapped inside the autoreleasepool. Since the autoreleasepool is available only on Darwin platforms, the memory reducing effect may be not as significant on non-Darwin platforms (such as Linux or Windows).

The following code demonstrates an example usage of the TarWriter:

   let handle: FileHandle = ...
   let writer = TarWriter(fileHandle: handle)
   try autoreleasepool {
       let entry: TarEntry = ...
       try writer.append(entry)
   }
   try writer.finalize()
   try handle.close()

Note that TarWriter.finalize() must be called after finishing appending entries to the container. In addition, closing the FileHandle remains the responsibility of the caller.

Important

Due to the API availability limitations of Foundation’s FileHandle, on certain platforms errors in FileHandle operations may result in unrecoverable runtime failures due to unhandled Objective-C exceptions (which are impossible to correctly handle in Swift code). As such, it is not recommended to use TarWriter on those platforms. The following platforms are unaffected by this issue: macOS 10.15.4+, iOS 13.4+, watchOS 6.2+, tvOS 13.4+, and any other platforms without Objective-C runtime.
Show on GitHub

  • Creates a new instance for writing TAR entries using the specified format into the provided fileHandle.

    The TarWriter will be forced to use the provided format, meaning that certain properties of the entries may be missing from the output data if the chosen format does not support corresponding features. The default .pax format supports the largest set of features. Other (non-PAX) formats should only be used if you have a specific need for them and you understand limitations of those formats.

    Important

    TarWriter.finalize() must be called after all entries have been appended.

    Declaration

    Swift

    public init(fileHandle: FileHandle, force format: TarContainer.Format = .pax)

    Parameters

    fileHandle

    A handle into which the output will be written. Note that the TarWriter does not close the fileHandle and this remains the responsibility of the caller.
    force

    Force the usage of the specified format.
    Show on GitHub

  • Adds a new TAR entry at the end of the TAR container.

    On Darwin platforms it is recommended to wrap both the initialization of a TarEntry and the call to this function inside the autoreleasepool in order to reduce the peak memory usage.

    Throws

    Errors from the FileHandle operations.

    Declaration

    Swift

    public mutating func append(_ entry: TarEntry) throws
    Show on GitHub

  • Finalizes the TAR container by adding an EOF marker.

    Throws

    Errors from the FileHandle operations.

    Declaration

    Swift

    public func finalize() throws
    Show on GitHub