         self.localPaxHeaderCounter = 0
     }
 
+    /**
+     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.
+     */
     public mutating func append(_ entry: TarEntry) throws {
         var out = Data()
         if format == .gnu {

    private var longLinkNameCounter: UInt
    private var localPaxHeaderCounter: UInt

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


import Foundation

/**
 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`:
 ```swift
    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. However, 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. 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+.
 */
public struct TarWriter {

    private let format: TarContainer.Format
