1erl_tar(3) Erlang Module Definition erl_tar(3)
2
6 erl_tar - Unix 'tar' utility for reading and writing tar archives.
7
10 This module archives and extract files to and from a tar file. This
11 module supports reading most common tar formats, namely v7, STAR, US‐
12 TAR, and PAX, as well as some of GNU tar's extensions to the USTAR for‐
13 mat (sparse files most notably). It produces tar archives in USTAR for‐
14 mat, unless the files being archived require PAX format due to restric‐
15 tions in USTAR (such as unicode metadata, filename length, and more).
16 As such, erl_tar supports tar archives produced by most all modern tar
17 utilities, and produces tarballs which should be similarly portable.
18 By convention, the name of a tar file is to end in ".tar". To abide to
20 the convention, add ".tar" to the name.
21 Tar files can be created in one operation using function create/2 or
23 create/3.
24 Alternatively, for more control, use functions open/2, add/3,4, and
26 close/1.
27 To extract all files from a tar file, use function extract/1. To ex‐
29 tract only some files or to be able to specify some more options, use
30 function extract/2.
31 To return a list of the files in a tar file, use function table/1 or
33 table/2. To print a list of files to the Erlang shell, use function t/1
34 or tt/1.
35 To convert an error term returned from one of the functions above to a
37 readable message, use function format_error/1.
38
40 If file:native_name_encoding/0 returns utf8, path names are encoded in
41 UTF-8 when creating tar files, and path names are assumed to be encoded
42 in UTF-8 when extracting tar files.
43 If file:native_name_encoding/0 returns latin1, no translation of path
45 names is done.
46 Unicode metadata stored in PAX headers is preserved
48
50 The ftp module normally accesses the tar file on disk using the file
51 module. When other needs arise, you can define your own low-level Er‐
52 lang functions to perform the writing and reading on the storage media;
53 use function init/3.
54 An example of this is the SFTP support in ssh_sftp:open_tar/3. This
56 function opens a tar file on a remote machine using an SFTP channel.
57
59 * If you must remain compatible with the USTAR tar format, you must
60 ensure file paths being stored are less than 255 bytes in total,
61 with a maximum filename component length of 100 bytes. USTAR uses a
62 header field (prefix) in addition to the name field, and splits
63 file paths longer than 100 bytes into two parts. This split is done
64 on a directory boundary, and is done in such a way to make the best
65 use of the space available in those two fields, but in practice
66 this will often mean that you have less than 255 bytes for a path.
67 erl_tar will automatically upgrade the format to PAX to handle
68 longer filenames, so this is only an issue if you need to extract
69 the archive with an older implementation of erl_tar or tar which
70 does not support PAX. In this case, the PAX headers will be ex‐
71 tracted as regular files, and you will need to apply them manually.
72 * Like the above, if you must remain USTAR compatible, you must also
74 ensure than paths for symbolic/hard links are no more than 100
75 bytes, otherwise PAX headers will be used.
76
78 name_in_archive() = string()
79 open_type() =
81 file:filename_all() |
82 {binary, binary()} |
83 {file, file:io_device()}
84 tar_descriptor()
86
88 add(TarDescriptor, AddType, Options) -> ok | {error, term()}
89 add(TarDescriptor, Filename, NameInArchive, Options) ->
91 ok | {error, term()}
92 Types:
94 TarDescriptor = tar_descriptor()
96 Filename = file:filename_all()
97 NameInArchive = name_in_archive()
98 Options = [add_opt()]
99 add_type() =
100 name_in_archive() | {name_in_archive(), file:filename_all()}
101 add_opt() =
102 dereference | verbose |
103 {chunks, integer() >= 1} |
104 {atime, integer() >= 0} |
105 {mtime, integer() >= 0} |
106 {ctime, integer() >= 0} |
107 {uid, integer() >= 0} |
108 {gid, integer() >= 0}
109 Adds a file to a tar file that has been opened for writing by
111 open/1.
112 NameInArchive is the name under which the file becomes stored in
114 the tar file. The file gets this name when it is extracted from
115 the tar file.
116 Options:
118 dereference:
120 By default, symbolic links are stored as symbolic links in
121 the tar file. To override the default and store the file
122 that the symbolic link points to into the tar file, use op‐
123 tion dereference.
124 verbose:
126 Prints an informational message about the added file.
127 {chunks,ChunkSize}:
129 Reads data in parts from the file. This is intended for mem‐
130 ory-limited machines that, for example, builds a tar file on
131 a remote machine over SFTP, see ssh_sftp:open_tar/3.
132 {atime,non_neg_integer()}:
134 Sets the last time, as POSIX time, when the file was read.
135 See also file:read_file_info/1.
136 {mtime,non_neg_integer()}:
138 Sets the last time, as POSIX time, when the file was writ‐
139 ten. See also file:read_file_info/1.
140 {ctime,non_neg_integer()}:
142 Sets the time, as POSIX time, when the file was created.
143 See also file:read_file_info/1.
144 {uid,non_neg_integer()}:
146 Sets the file owner. file:read_file_info/1.
147 {gid,non_neg_integer()}:
149 Sets the group that the file owner belongs to.
150 file:read_file_info/1.
151 close(TarDescriptor :: tar_descriptor()) -> ok | {error, term()}
153 Closes a tar file opened by open/2.
155 create(Name :: file:filename_all(), FileList :: filelist()) ->
157 ok | {error, {string(), term()}}
158 Types:
160 filelist() =
162 [file:filename() | {name_in_archive(), file:filename_all()}]
163 Creates a tar file and archives the files whose names are speci‐
165 fied in FileList into it. The files can either be read from disk
166 or be specified as binaries.
167 create(Name :: file:filename_all(),
169 FileList :: filelist(),
170 Options :: [create_opt()]) ->
171 ok | {error, term()} | {error, {string(), term()}}
172 Types:
174 filelist() =
176 [file:filename() | {name_in_archive(), file:filename_all()}]
177 create_opt() = compressed | cooked | dereference | verbose
178 Creates a tar file and archives the files whose names are speci‐
180 fied in FileList into it. The files can either be read from disk
181 or be specified as binaries.
182 The options in OptionList modify the defaults as follows:
184 compressed:
186 The entire tar file is compressed, as if it has been run
187 through the gzip program. To abide to the convention that a
188 compressed tar file is to end in ".tar.gz" or ".tgz", add
189 the appropriate extension.
190 cooked:
192 By default, function open/2 opens the tar file in raw mode,
193 which is faster but does not allow a remote (Erlang) file
194 server to be used. Adding cooked to the mode list overrides
195 the default and opens the tar file without option raw.
196 dereference:
198 By default, symbolic links are stored as symbolic links in
199 the tar file. To override the default and store the file
200 that the symbolic link points to into the tar file, use op‐
201 tion dereference.
202 verbose:
204 Prints an informational message about each added file.
205 extract(Open :: open_type()) -> ok | {error, term()}
207 Extracts all files from a tar archive.
209 If argument Name is specified as {binary,Binary}, the contents
211 of the binary is assumed to be a tar archive.
212 If argument Name is specified as {file,Fd}, Fd is assumed to be
214 a file descriptor returned from function file:open/2.
215 Otherwise, Name is to be a filename.
217 Note:
219 Leading slashes in tar member names will be removed before writ‐
220 ing the file. That is, absolute paths will be turned into rela‐
221 tive paths. There will be an info message written to the error
222 logger when paths are changed in this way.
223 Warning:
226 The compressed and cooked flags are invalid when passing a file
227 descriptor with {file,Fd}. The file is assumed to have been
228 opened with the appropriate flags.
229 extract(Open :: open_type(), Opts :: [extract_opt()]) ->
232 {ok, [{string(), binary()}]} | {error, term()} | ok
233 Types:
235 extract_opt() =
237 {cwd, string()} |
238 {files, [name_in_archive()]} |
239 compressed | cooked | memory | keep_old_files | verbose
240 Extracts files from a tar archive.
242 If argument Name is specified as {binary,Binary}, the contents
244 of the binary is assumed to be a tar archive.
245 If argument Name is specified as {file,Fd}, Fd is assumed to be
247 a file descriptor returned from function file:open/2.
248 Otherwise, Name is to be a filename.
250 The following options modify the defaults for the extraction as
252 follows:
253 {cwd,Cwd}:
255 Files with relative filenames are by default extracted to
256 the current working directory. With this option, files are
257 instead extracted into directory Cwd.
258 {files,FileList}:
260 By default, all files are extracted from the tar file. With
261 this option, only those files are extracted whose names are
262 included in FileList.
263 compressed:
265 With this option, the file is uncompressed while extracting.
266 If the tar file is not compressed, this option is ignored.
267 cooked:
269 By default, function open/2 function opens the tar file in
270 raw mode, which is faster but does not allow a remote (Er‐
271 lang) file server to be used. Adding cooked to the mode list
272 overrides the default and opens the tar file without option
273 raw.
274 memory:
276 Instead of extracting to a directory, this option gives the
277 result as a list of tuples {Filename, Binary}, where Binary
278 is a binary containing the extracted data of the file named
279 Filename in the tar file.
280 keep_old_files:
282 By default, all existing files with the same name as files
283 in the tar file are overwritten. With this option, existing
284 files are not overwriten.
285 verbose:
287 Prints an informational message for each extracted file.
288 Warning:
290 The compressed and cooked flags are invalid when passing a file
291 descriptor with {file,Fd}. The file is assumed to have been
292 opened with the appropriate flags.
293 format_error(Atom :: term()) -> string()
296 Converts an error reason term to a human-readable error message
298 string.
299 init(UserData :: user_data(),
301 AccessMode :: write | read,
302 Fun :: file_op()) ->
303 {ok, tar_descriptor()} | {error, badarg}
304 Types:
306 user_data() = term()
308 file_op() =
309 fun((write | close | read2 | position,
310 {user_data(), iodata()} |
311 user_data() |
312 {user_data(), integer() >= 0} |
313 {user_data(), integer() >= 0}) ->
314 ok | eof |
315 {ok, string() | binary()} |
316 {ok, integer() >= 0} |
317 {error, term()})
318 The Fun is the definition of what to do when the different stor‐
320 age operations functions are to be called from the higher tar
321 handling functions (such as add/3, add/4, and close/1).
322 The Fun is called when the tar function wants to do a low-level
324 operation, like writing a block to a file. The Fun is called as
325 Fun(Op, {UserData,Parameters...}), where Op is the operation
326 name, UserData is the term passed as the first argument to
327 init/1 and Parameters... are the data added by the tar function
328 to be passed down to the storage handling function.
329 Parameter UserData is typically the result of opening a low-
331 level structure like a file descriptor or an SFTP channel id.
332 The different Fun clauses operate on that very term.
333 The following are the fun clauses parameter lists:
335 (write, {UserData,DataToWrite}):
337 Writes term DataToWrite using UserData.
338 (close, UserData):
340 Closes the access.
341 (read2, {UserData,Size}):
343 Reads using UserData but only Size bytes. Notice that there
344 is only an arity-2 read function, not an arity-1 function.
345 (position,{UserData,Position}):
347 Sets the position of UserData as defined for files in
348 file:position/2
349 Example:
351 The following is a complete Fun parameter for reading and writ‐
353 ing on files using the file module:
354 ExampleFun =
356 fun(write, {Fd,Data}) -> file:write(Fd, Data);
357 (position, {Fd,Pos}) -> file:position(Fd, Pos);
358 (read2, {Fd,Size}) -> file:read(Fd, Size);
359 (close, Fd) -> file:close(Fd)
360 end
361 Here Fd was specified to function init/3 as:
363 {ok,Fd} = file:open(Name, ...).
365 {ok,TarDesc} = erl_tar:init(Fd, [write], ExampleFun),
366 TarDesc is then used:
368 erl_tar:add(TarDesc, SomeValueIwantToAdd, FileNameInTarFile),
370 erl_tar:close(TarDesc)
371 When the erl_tar core wants to, for example, write a piece of
373 Data, it would call ExampleFun(write, {UserData,Data}).
374 Note:
376 This example with the file module operations is not necessary to
377 use directly, as that is what function open/2 in principle does.
378 Warning:
381 The TarDescriptor term is not a file descriptor. You are advised
382 not to rely on the specific contents of this term, as it can
383 change in future Erlang/OTP releases when more features are
384 added to this module.
385 open(Open :: open_type(), Mode :: [write | compressed | cooked]) ->
388 {ok, tar_descriptor()} | {error, term()}
389 Creates a tar file for writing (any existing file with the same
391 name is truncated).
392 By convention, the name of a tar file is to end in ".tar". To
394 abide to the convention, add ".tar" to the name.
395 Except for the write atom, the following atoms can be added to
397 OpenModeList:
398 compressed:
400 The entire tar file is compressed, as if it has been run
401 through the gzip program. To abide to the convention that a
402 compressed tar file is to end in ".tar.gz" or ".tgz", add
403 the appropriate extension.
404 cooked:
406 By default, the tar file is opened in raw mode, which is
407 faster but does not allow a remote (Erlang) file server to
408 be used. Adding cooked to the mode list overrides the de‐
409 fault and opens the tar file without option raw.
410 To add one file at the time into an opened tar file, use func‐
412 tion add/3,4. When you are finished adding files, use function
413 close/1 to close the tar file.
414 Warning:
416 The compressed and cooked flags are invalid when passing a file
417 descriptor with {file,Fd}. The file must already be opened with
418 the appropriate flags.
419 Warning:
422 The TarDescriptor term is not a file descriptor. You are advised
423 not to rely on the specific contents of this term, as it can
424 change in future Erlang/OTP releases when more features are
425 added to this module.
426 table(Open :: open_type()) ->
429 {ok, [name_in_archive()]} | {error, term()}
430 table(Open :: open_type(),
432 Opts :: [compressed | verbose | cooked]) ->
433 {ok, [name_in_archive() | tar_entry()]} | {error, term()}
434 Types:
436 tar_entry() =
438 {Name :: name_in_archive(),
439 Type :: typeflag(),
440 Size :: integer() >= 0,
441 MTime :: tar_time(),
442 Mode :: mode(),
443 Uid :: uid(),
444 Gid :: gid()}
445 tar_time() = integer() >= 0
446 typeflag() =
447 regular | link | symlink | char | block | directory | fifo |
448 reserved | unknown
449 mode() = integer() >= 0
450 uid() = integer() >= 0
451 gid() = integer() >= 0
452 Retrieves the names of all files in the tar file Name.
454 t(Name :: file:filename()) -> ok | {error, term()}
456 Prints the names of all files in the tar file Name to the Erlang
458 shell (similar to "tar t").
459 tt(Name :: open_type()) -> ok | {error, term()}
461 Prints names and information about all files in the tar file
463 Name to the Erlang shell (similar to "tar tv").
464Ericsson AB stdlib 4.3.1.3 erl_tar(3)