tar 0.2.0-nullsafety

Memory-efficient, streaming implementation of the tar file format

tar

This package provides stream-based readers and writers for tar files.

When working with large tar files, this library consumes considerably less memory than package:archive, although it is slightly slower.

Reading

To read entries from a tar file, use

import 'dart:io';
import 'package:tar/tar.dart';

Future<void> main() async {
  final reader = TarReader(File('file.tar').openRead());

  while (await reader.moveNext()) {
    // Use reader.header to see the header of the current tar entry
    print(reader.header.name);
    // And reader.contents to read the content of the current entry as a stream
    print(await reader.contents.transform(utf8.decoder).first);
  }
}

To read .tar.gz files, transform the stream with gzip.decoder first.

To easily go through all entries in a tar file, use Reader.forEach:

Future<void> main() async {
  final inputStream = File('file.tar').openRead();

  await TarReader.forEach(inputStream, (header, contents) {
    print(header.name);
    print(await contents.transform(utf8.decoder).first);
  });
}

Warning: Since the reader is backed by a single stream, concurrent calls to read are not allowed! Similarly, if you're reading from an entry's contents, make sure to fully drain the stream before calling read() again.

Writing

You can write tar files into a StreamSink<List<int>>, such as an IOSink:

import 'dart:io';
import 'package:tar/tar.dart';

Future<void> main() async {
  final output = File('test.tar').openWrite();

  await Stream<tar.Entry>.value(
    tar.MemoryEntry(
      tar.Header(
        name: 'hello.txt',
        mode: int.parse('644', radix: 8),
      ),
      utf8.encode('Hello world'),
    ),
  ).pipe(tar.tarWritingSink(output));
}

Note that tar files are always written in the pax format defined by the POSIX.1-2001 specification (--format=posix in GNU tar). When all entries have file names shorter than 100 chars and a size smaller than 8 GB, this is equivalent to the ustar format. This library won't write PAX headers when there is no reason to do so.

To write .tar.gz files, you can again transform the stream twice:

import 'dart:io';
import 'package:tar/tar.dart';

Future<void> write(Stream<tar.Entry> entries) {
  return entries
      .transform(tarWriter)
      .transform(gzip.encoder)
      .pipe(File('output.tar.gz').openWrite())
}

Features

• Supports v7, ustar, pax, gnu and star archives
• Supports extended pax headers for long file or link names
• Supports long file and link names generated by GNU-tar
• Hardened against denial-of-service attacks with invalid tar files

---

Big thanks to Garett Tok Ern Liang for writing the initial tar implementation this library is based on.