tar 包为 Dart 提供了一种内存高效的流式实现,用于读取和写入 tar 文件格式。该包专为处理大型归档文件而设计,无需将整个文件加载到内存中,支持对归档条目进行增量处理。非常适合需要高效文件压缩和解压的应用程序,尤其是在资源有限的情况下。该包可在所有主要平台上兼容,包括移动设备、网页和桌面端。它可与需要强大归档处理功能的 Flutter 应用无缝集成。
适合场景
大型 tar 文件的流式提取
在资源受限环境中的高效归档创建
在跨平台应用中集成基于 tar 的数据存储
处理归档日志或备份
在Flutter应用程序中处理压缩资源
主要特点
用于低内存使用的流式 I/O
支持读取和写入 tar 归档文件
跨平台兼容性(Android、iOS、Web、macOS、Windows、Linux)
归档条目的增量处理
轻量且快速的性能
适合对象
开发文件管理工具的开发者
需要高效归档处理的应用程序
内存资源有限的项目
使用 Flutter 的跨平台应用程序
处理大型数据集的归档格式工具
使用建议
不支持加密或压缩的 tar 文件(例如 .tar.gz)
需要手动处理文件权限和元数据
仅限基本的 tar 格式,不包含高级功能
不适用于复杂的归档操作
最好与已知的、格式良好的 tar 输入一起使用
原始 README
以下为关联源码仓库的 README 原文快照,最新内容请访问源码仓库。
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 due to the async overhead.
Reading
To read entries from a tar file, use a TarReader with a Stream emitting bytes (as List<int>):
import'dart:convert';
import'dart:io';
import'package:tar/tar.dart';
Future<void> main() async {
final reader = TarReader(File('file.tar').openRead());
while (await reader.moveNext()) {
final entry = reader.current;
// Use reader.header to see the header of the current tar entryprint(entry.header.name);
// And reader.contents to read the content of the current entry as a streamprint(await entry.contents.transform(utf8.decoder).first);
}
// Note that the reader will automatically close if moveNext() returns false or// throws. If you want to close a tar stream before that happens, use// reader.cancel();
}
To read .tar.gz files, transform the stream with gzip.decoder before
passing it to the TarReader.
To easily go through all entries in a tar file, use TarReader.forEach:
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.
Not subscribing to contents before calling moveNext() is acceptable too.
In this case, the reader will implicitly drain the stream.
The reader detects concurrency misuses and will throw an error when they occur,
there's no risk of reading faulty data.
Writing
When writing archives, package:tar expects a Stream of tar entries to include in
the archive.
This stream can then be converted into a stream of byte-array chunks forming the
encoded tar archive.
To write a tar stream into a StreamSink<List<int>>, such as an IOSink returned by
File.openWrite, use tarWritingSink:
By default, tar files are 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.
If you prefer writing GNU-style long filenames instead, you can use the
format option:
To change the output format on the tarWriter transformer, use
tarWriterWith.
Synchronous writing
As the content of tar entries is defined as an asynchronous stream, the tar encoder is asynchronous too.
The more specific SynchronousTarEntry class stores tar content as a list of bytes, meaning that it can be
written synchronously.
To synchronously write tar files, use tarConverter (or tarConverterWith for options):
List<int> createTarArchive(Iterable<SynchronousTarEntry> entries) {
lateList<int> result;
final sink = ByteConversionSink.withCallback((data) => result = data);
final output = tarConverter.startChunkedConversion(sink);
entries.forEach(output.add);
output.close();
return result;
}
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
Supports being compiled to JavaScript, tested on Node.js
Security considerations
Internally, this package contains checks to guard against some invalid tar files.
In particular,
The reader doesn't allocate memory based on values in a tar file (so there's
a guard against DoS attacks with tar files containing huge headers).
When encountering malformed tar files, the reader will throw a TarException.
Any other exception thrown indicates a bug in package:tar or how it's used.
The reader should never crash.
Reading a tar file can be cancelled mid-stream without leaking resources.
However, the tar reader does not throw exceptions for well-formed archives
with suspicious contents, such as
File names beginning with ../, / or names pointing out of the archive by
other means.
Link references to files outside of the archive.
Paths not using forward slashes.
Gzip + tar bombs.
Invalid permission bits in entries.
...
When reading or extracting untrusted tar files, it is your responsibility to
detect and handle these cases.
For instance, this naive extraction function is susceptible to invalid tar
files containing paths outside of the target directory:
Future<void> extractTarGz(File tarGz, Directory target) async {
final input = tarGz.openRead().transform(gzip.decoder);
awaitTarReader.forEach(input, (entry) async {
final destination =
// DON'T DO THIS! If `entry.name` contained `../`, this may escape the// target directory.
path.joinAll([target.path, ...path.posix.split(entry.name)]);
final f = File(destination);
await f.create(recursive: true);
await entry.contents.pipe(f.openWrite());
});
}
For an idea on how to guard against this, see the extraction logic
used by the pub client.
Big thanks to Garett Tok Ern Liang for writing the initial
Dart tar reader that this library is based on.