The TarDescriptor term is not a file descriptor. You should not rely on the specific contents of the TarDescriptor term, as it may change in future versions as more features are added to the erl_tar module.
The erl_tar module archives and extract files to and from a tar file. The tar file format is the POSIX extended tar file format specified in IEEE Std 1003.1 and ISO/IEC 9945-1. That is the same format as used by tar program on Solaris, but is not the same as used by the GNU tar program.
By convention, the name of a tar file should end in ".tar". To abide to the convention, you'll need to add ".tar" yourself to the name.
Tar files can be created in one operation using the create/2 or create/3 function.
Alternatively, for more control, the open, add/3,4, and close/1 functions can be used.
To extract all files from a tar file, use the extract/1 function. To extract only some files or to be able to specify some more options, use the extract/2 function.
To return a list of the files in a tar file, use either the table/1 or table/2 function. To print a list of files to the Erlang shell, use either the t/1 or tt/1 function.
To convert an error term returned from one of the functions above to a readable message, use the format_error/1 function.
For maximum compatibility, it is safe to archive files with names up to 100 characters in length. Such tar files can generally be extracted by any tar program.
If filenames exceed 100 characters in length, the resulting tar file can only be correctly extracted by a POSIX-compatible tar program (such as Solaris tar), not by GNU tar.
File have longer names than 256 bytes cannot be stored at all.
The filename of the file a symbolic link points is always limited to 100 characters.
add(TarDescriptor, Filename, Options) -> RetValue
Types:
TarDescriptor = term()
Filename = filename()
Options = [Option]
Option = dereference|verbose
RetValue = ok|{error,{Filename,Reason}}
Reason = term()
The add/3 function adds a file to a tar file that has been opened for writing by open/1.
add(TarDescriptor, FilenameOrBin, NameInArchive, Options) -> RetValue
Types:
TarDescriptor = term()
FilenameOrBin = Filename()|binary()
Filename = filename()()
NameInArchive = filename()
Options = [Option]
Option = dereference|verbose
RetValue = ok|{error,{Filename,Reason}}
Reason = term()
The add/4 function adds a file to a tar file that has been opened for writing by open/1. It accepts the same options as add/3.
NameInArchive is the name under which the file will be stored in the tar file. That is the name that the file will get when it will be extracted from the tar file.
Types:
TarDescriptor = term()
The close/1 function closes a tar file opened by open/1.
create(Name, FileList) ->RetValue
Types:
Name = filename()
FileList = [Filename|{NameInArchive, binary()},{NameInArchive, Filename}]
Filename = filename()
NameInArchive = filename()
RetValue = ok|{error,{Name,Reason}} <V>Reason = term()
The create/2 function creates a tar file and archives the files whose names are given in FileList into it. The files may either be read from disk or given as binaries.
create(Name, FileList, OptionList)
Types:
Name = filename()
FileList = [Filename|{NameInArchive, binary()},{NameInArchive, Filename}]
Filename = filename()
NameInArchive = filename()
OptionList = [Option]
Option = compressed|cooked|dereference|verbose
RetValue = ok|{error,{Name,Reason}} <V>Reason = term()
The create/3 function creates a tar file and archives the files whose names are given in FileList into it. The files may either be read from disk or given as binaries.
The options in OptionList modify the defaults as follows.
Types:
Name = filename()
RetValue = ok|{error,{Name,Reason}}
Reason = term()
The extract/1 function extracts all files from a tar archive.
If the Name argument is given as "{binary,Binary}", the contents of the binary is assumed to be a tar archive.
If the Name argument is given as "{file,Fd}", Fd is assumed to be a file descriptor returned from the file:open/2 function.
Otherwise, Name should be a filename.
Types:
Name = filename() | {binary,Binary} | {file,Fd}
Binary = binary()
Fd = file_descriptor()
OptionList = [Option]
Option = {cwd,Cwd}|{files,FileList}|keep_old_files|verbose|memory
Cwd = [dirname()]
FileList = [filename()]
RetValue = ok|MemoryRetValue|{error,{Name,Reason}}
MemoryRetValue = {ok, [{NameInArchive,binary()}]}
NameInArchive = filename()
Reason = term()
The extract/2 function extracts files from a tar archive.
If the Name argument is given as "{binary,Binary}", the contents of the binary is assumed to be a tar archive.
If the Name argument is given as "{file,Fd}", Fd is assumed to be a file descriptor returned from the file:open/2 function.
Otherwise, Name should be a filename.
The following options modify the defaults for the extraction as follows.
format_error(Reason) -> string()
Types:
Reason = term()
open(Name, OpenModeList) -> RetValue
Types:
Name = filename()
OpenModeList = [OpenMode]
Mode = write|compressed|cooked
RetValue = {ok,TarDescriptor}|{error,{Name,Reason}}
TarDescriptor = term()
Reason = term()
The open/2 function creates a tar file for writing. (Any existing file with the same name will be truncated.)
By convention, the name of a tar file should end in ".tar". To abide to the convention, you'll need to add ".tar" yourself to the name.
Except for the write atom the following atoms may be added to OpenModeList:
Use the add/3,4 functions to add one file at the time into an opened tar file. When you are finished adding files, use the close function to close the tar file.
The TarDescriptor term is not a file descriptor. You should not rely on the specific contents of the TarDescriptor term, as it may change in future versions as more features are added to the erl_tar module.
Types:
Name = filename()
RetValue = {ok,[string()]}|{error,{Name,Reason}}
Reason = term()
Types:
Name = filename()
Types:
Name = filename()
The t/1 function prints the names of all files in the tar file Name to the Erlang shell. (Similar to "tar t".)
Types:
Name = filename()
The tt/1 function prints names and information about all files in the tar file Name to the Erlang shell. (Similar to "tar tv".)