erl_tar

模块

erl_tar

模块摘要

用于读写tar档案的Unix'tar'工具。

描述

该模块将文件归档并从tar文件中提取文件。该模块支持读取最常见的tar格式，即v7，STAR，USTAR和PAX，以及一些GNU tar对USTAR格式的扩展（特别是稀疏文件）。它以USTAR格式生成tar归档文件，除非由于USTAR中的限制（例如unicode元数据，文件名长度等）而归档的文件需要PAX格式。因此，erl_tar支持大多数现代tar公用事业公司生产的焦油档案，并生产类似便携式的tar球。

按照惯例，一个tar文件的名字将以“ .tar” 结尾。遵守公约，.tar在名称中加上“ ”。

使用函数create/2或者一个操作可以创建Tar文件create/3。

可替代地，进行更多的控制，使用的功能open/2，add/3,4和close/1。

要从tar文件中提取所有文件，请使用函数extract/1。要仅提取一些文件或能够指定更多选项，请使用函数extract/2。

要返回tar文件中的文件列表，请使用function table/1或table/2。要将文件列表打印到Erlang shell，请使用函数t/1或tt/1。

要将上述函数之一返回的错误条件转换为可读的消息，请使用函数format_error/1。

Unicode支持

如果file:native_name_encoding/0返回utf8，则在创建tar文件时，路径名以UTF-8编码，并且在解压缩tar文件时假定路径名以UTF-8编码。

如果file:native_name_encoding/0返回latin1，则不会完成路径名称的转换。

保存存储在PAX头中的Unicode元数据。

其他存储介质

所述ftp模块（Inets）通常访问使用所述磁盘tar文件file模块。当出现其他需求时，您可以定义自己的低级Erlang函数来执行存储介质上的写入和读取; 使用功能init/3。

这方面的一个例子是ssh_sftp:open_tar/3此函数使用SFTP通道在远程计算机上打开tar文件。

局限性

• 如果您必须与USTAR tar格式保持兼容，则必须确保存储的文件路径总共少于255个字节，最大文件名组件长度为100个字节。除名称字段外，USTAR还使用标题字段（前缀），并将长度超过100个字节的文件路径拆分为两部分。这种拆分是在目录边界上完成的，并且这样做是为了充分利用这两个字段中的可用空间，但实际上这通常意味着您的路径的字节数少于255个字节。erl_tar将自动升级格式PAX处理长文件名，所以这只是一个问题，如果你需要使用旧落实提取存档erl_tar或tar不支持PAX。在这种情况下，PAX标题将作为常规文件提取，您需要手动应用它们。

• 如上所述，如果您必须保持USTAR兼容，则还必须确保符号/硬链接的路径不超过100个字节，否则将使用PAX标头。

输出

add(TarDescriptor, Filename, Options) -> RetValue

类型

将文件添加到已打开供写入的tar文件open/1。

NameInArchive是文件存储在tar文件中的名称。从tar文件中提取文件时，该文件将获取该名称。

备选方案：

dereference

默认情况下，符号链接作为符号链接存储在tar文件中。要覆盖默认值并将符号链接指向的文件存储到tar文件中，请使用选项dereference。

verbose

打印有关添加的文件的信息消息。

{chunks,ChunkSize}

从文件中读取部分数据。这适用于内存有限的机器，例如，通过SFTP在远程计算机上构建一个tar文件，请参阅ssh_sftp:open_tar/3。

add(TarDescriptor, FilenameOrBin, NameInArchive, Options) -> RetValue

类型

将文件添加到已打开供写入的tar文件open/2。这个函数接受与add/3相同的选项

close(TarDescriptor)

类型

关闭open/2打开的tar文件

create(Name, FileList) ->RetValue

类型

创建一个tar文件并将其名称被指定的文件存档FileList到其中。这些文件可以从磁盘读取，也可以指定为二进制文件。

create(Name, FileList, OptionList)

类型

创建一个tar文件并将其名称被指定的文件存档FileList到其中。这些文件可以从磁盘读取，也可以指定为二进制文件。

OptionList修改默认值的选项如下：

compressed

整个tar文件被压缩，就好像它已经在gzip程序中运行一样。要遵守压缩tar文件以“ .tar.gz”或“ .tgz” 结尾的约定，请添加适当的扩展名。

cooked

默认情况下，函数open/2以raw模式打开tar文件，但速度更快，但不允许使用远程（Erlang）文件服务器。添加cooked到模式列表将覆盖默认值，并打开tar文件而不带选项raw。

dereference

默认情况下，符号链接作为符号链接存储在tar文件中。要覆盖默认值并将符号链接指向的文件存储到tar文件中，请使用选项dereference。

verbose

打印有关每个添加的文件的信息消息。

extract(Name) -> RetValue

类型

从tar存档中提取所有文件。

如果将参数Name指定为{binary,Binary}，则二进制文件的内容被假定为tar归档文件。

如果将参数Name指定为{file,Fd}，Fd则假定为从函数返回的文件描述符file:open/2。

否则，Name就是一个文件名。

注

在写入文件之前，将删除tar成员名称中的斜杠。也就是说，绝对路径将变成相对路径。当以这种方式更改路径时，会向错误记录器写入一条信息消息。

extract(Name, OptionList)

类型

从tar存档中提取文件。

如果将参数Name指定为{binary,Binary}，则二进制文件的内容被假定为tar归档文件。

如果将参数Name指定为{file,Fd}，Fd则假定为从函数返回的文件描述符file:open/2。

否则，Name就是成为一个文件名。

以下选项将提取的默认值修改如下：

{cwd,Cwd}

具有相关文件名的文件默认提取到当前工作目录。使用此选项，文件将被提取到目录Cwd中

{files,FileList}

默认情况下，所有文件都从tar文件中提取。使用此选项，仅提取名称包含在其中的文件FileList。

compressed

使用此选项，文件将在解压缩时解压缩。如果tar文件未被压缩，则忽略此选项。

cooked

默认情况下，函数open/2函数以raw模式打开tar文件，但速度更快但不允许使用远程（Erlang）文件服务器。添加cooked到模式列表将覆盖默认值，并打开tar文件而不带选项raw。

memory

该选项不是解压缩到目录，而是将结果作为元组列表提供{Filename, Binary}，其中Binary是一个二进制文件，其中包含Filenametar文件中命名的文件的提取数据。

keep_old_files

默认情况下，与tar文件中的文件同名的所有现有文件都会被覆盖。使用此选项，现有文件不会被覆盖。

verbose

为每个提取的文件打印一条信息消息。

format_error(Reason) -> string()

类型

将错误原因项转换为人类可读的错误消息字符串。

init(UserPrivate, AccessMode, Fun) -> {ok,TarDescriptor} | {error,Reason}

类型

Fun是定义在从较高焦油处理函数（如add / 3，add / 4和close / 1）调用不同的存储操作函数时要执行的操作。

Fun函数在tar函数想要执行低级操作时调用，例如将块写入文件。 Fun被称为Fun（Op，{UserPrivate，Parameters ...}），其中Op是操作名称，UserPrivate是作为init / 1的第一个参数传递的术语，而参数...是由 tar函数传递给存储处理函数。

参数UserPrivate通常是打开低级结构（如文件描述符或SFTP通道ID）的结果。不同的Fun条款在这个术语上运作。

以下是Fun的子句参数列表：

(write, {UserPrivate,DataToWrite})

写入项DataToWrite使用UserPrivate...

(close, UserPrivate)

关闭通道。

(read2, {UserPrivate,Size})

使用UserPrivate读取但只能读取Size字节。 请注意，只有arity-2读取功能，而不是arity-1功能。

(position,{UserPrivate,Position})

设置UserPrivate文件中定义的位置file:position/2

例子：

以下是一个完整的Fun参数，用于使用file模块：

ExampleFun = 
   fun(write, {Fd,Data}) ->  file:write(Fd, Data);
      (position, {Fd,Pos}) -> file:position(Fd, Pos);
      (read2, {Fd,Size}) -> file:read(Fd, Size);
      (close, Fd) -> file:close(Fd)
   end

这里Fd指定的功能init/3如下：

{ok,Fd} = file:open(Name, ...).
{ok,TarDesc} = erl_tar:init(Fd, [write], ExampleFun),

TarDesc 然后被使用：

erl_tar:add(TarDesc, SomeValueIwantToAdd, FileNameInTarFile),
...,
erl_tar:close(TarDesc)

例如，当erl_tar核心想要写一段数据时，它会调用ExampleFun（write，{UserPrivate，Data}）。

注

这个file模块操作的例子没有必要直接使用，因为这是open/2原则上的功能。

警告

该TarDescriptor术语不是文件描述符。建议您不要依赖此术语的具体内容，因为在未来的Erlang / OTP版本中，当将更多功能添加到此模块时，它可能会发生变化。

open(Name, OpenModeList) -> RetValue

类型

创建一个用于写入的tar文件（任何具有相同名称的现有文件被截断）。

按照惯例，一个tar文件的名字将以“ .tar” 结尾。遵守公约，.tar在名称中加上“ ”。

除了write原子，以下原子可以添加到OpenModeList*

compressed

整个tar文件被压缩，就好像它已经在gzip程序中运行一样。要遵守压缩tar文件以“ .tar.gz”或“ .tgz” 结尾的约定，请添加适当的扩展名。

cooked

默认情况下，tar文件以raw模式打开，但速度更快，但不允许使用远程（Erlang）文件服务器。添加cooked到模式列表将覆盖默认值，并打开tar文件而不带选项raw。

要将某个文件在当时添加到打开的tar文件中，请使用函数add/3,4。当您完成添加文件时，使用函数close/1关闭tar文件。

警告

该TarDescriptor术语不是文件描述符。建议您不要依赖此术语的具体内容，因为在未来的Erlang / OTP版本中，当将更多功能添加到此模块时，它可能会发生变化。

table(Name) -> RetValue

类型

检索tar文件中所有文件的名称Name。

table(Name, Options)

类型

检索tar文件中所有文件的名称Name。

t(Name)

类型

将tar文件中的所有文件的名称打印Name到Erlang shell（类似于“ tar t”）。

tt(Name)

类型

将tar文件Name中的所有文件的名称和信息打印到Erlang shell（类似于“ tar tv”）。