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,
12 USTAR, and PAX, as well as some of GNU tar's extensions to the USTAR
13 format (sparse files most notably). It produces tar archives in USTAR
14 format, unless the files being archived require PAX format due to
15 restrictions in USTAR (such as unicode metadata, filename length, and
16 more). As such, erl_tar supports tar archives produced by most all mod‐
17 ern tar utilities, and produces tarballs which should be similarly por‐
18 table.
19 By convention, the name of a tar file is to end in ".tar". To abide to
21 the convention, add ".tar" to the name.
22 Tar files can be created in one operation using function create/2 or
24 create/3.
25 Alternatively, for more control, use functions open/2, add/3,4, and
27 close/1.
28 To extract all files from a tar file, use function extract/1. To
30 extract only some files or to be able to specify some more options, use
31 function extract/2.
32 To return a list of the files in a tar file, use function table/1 or
34 table/2. To print a list of files to the Erlang shell, use function t/1
35 or tt/1.
36 To convert an error term returned from one of the functions above to a
38 readable message, use function format_error/1.
39
41 If file:native_name_encoding/0 returns utf8, path names are encoded in
42 UTF-8 when creating tar files, and path names are assumed to be encoded
43 in UTF-8 when extracting tar files.
44 If file:native_name_encoding/0 returns latin1, no translation of path
46 names is done.
47 Unicode metadata stored in PAX headers is preserved
49
51 The ftp module normally accesses the tar file on disk using the file
52 module. When other needs arise, you can define your own low-level
53 Erlang functions to perform the writing and reading on the storage
54 media; use function init/3.
55 An example of this is the SFTP support in ssh_sftp:open_tar/3. This
57 function opens a tar file on a remote machine using an SFTP channel.
58
60 * If you must remain compatible with the USTAR tar format, you must
61 ensure file paths being stored are less than 255 bytes in total,
62 with a maximum filename component length of 100 bytes. USTAR uses a
63 header field (prefix) in addition to the name field, and splits
64 file paths longer than 100 bytes into two parts. This split is done
65 on a directory boundary, and is done in such a way to make the best
66 use of the space available in those two fields, but in practice
67 this will often mean that you have less than 255 bytes for a path.
68 erl_tar will automatically upgrade the format to PAX to handle
69 longer filenames, so this is only an issue if you need to extract
70 the archive with an older implementation of erl_tar or tar which
71 does not support PAX. In this case, the PAX headers will be
72 extracted as regular files, and you will need to apply them manu‐
73 ally.
74 * Like the above, if you must remain USTAR compatible, you must also
76 ensure than paths for symbolic/hard links are no more than 100
77 bytes, otherwise PAX headers will be used.
78
80 name_in_archive() = string()
81 open_type() =
83 file:filename_all() |
84 {binary, binary()} |
85 {file, file:io_device()}
86 tar_descriptor()
88
90 add(TarDescriptor, AddType, Options) -> ok | {error, term()}
91 add(TarDescriptor, Filename, NameInArchive, Options) ->
93 ok | {error, term()}
94 Types:
96 TarDescriptor = tar_descriptor()
98 Filename = file:filename_all()
99 NameInArchive = name_in_archive()
100 Options = [add_opt()]
101 add_type() =
102 name_in_archive() | {name_in_archive(), file:filename_all()}
103 add_opt() =
104 dereference | verbose |
105 {chunks, integer() >= 1} |
106 {atime, integer() >= 0} |
107 {mtime, integer() >= 0} |
108 {ctime, integer() >= 0} |
109 {uid, integer() >= 0} |
110 {gid, integer() >= 0}
111 Adds a file to a tar file that has been opened for writing by
113 open/1.
114 NameInArchive is the name under which the file becomes stored in
116 the tar file. The file gets this name when it is extracted from
117 the tar file.
118 Options:
120 dereference:
122 By default, symbolic links are stored as symbolic links in
123 the tar file. To override the default and store the file
124 that the symbolic link points to into the tar file, use
125 option dereference.
126 verbose:
128 Prints an informational message about the added file.
129 {chunks,ChunkSize}:
131 Reads data in parts from the file. This is intended for mem‐
132 ory-limited machines that, for example, builds a tar file on
133 a remote machine over SFTP, see ssh_sftp:open_tar/3.
134 {atime,non_neg_integer()}:
136 Sets the last time, as POSIX time, when the file was read.
137 See also file:read_file_info/1.
138 {mtime,non_neg_integer()}:
140 Sets the last time, as POSIX time, when the file was writ‐
141 ten. See also file:read_file_info/1.
142 {ctime,non_neg_integer()}:
144 Sets the time, as POSIX time, when the file was created.
145 See also file:read_file_info/1.
146 {uid,non_neg_integer()}:
148 Sets the file owner. file:read_file_info/1.
149 {gid,non_neg_integer()}:
151 Sets the group that the file owner belongs to.
152 file:read_file_info/1.
153 close(TarDescriptor :: tar_descriptor()) -> ok | {error, term()}
155 Closes a tar file opened by open/2.
157 create(Name :: file:filename_all(), FileList :: filelist()) ->
159 ok | {error, {string(), term()}}
160 Types:
162 filelist() =
164 [file:filename() | {name_in_archive(), file:filename_all()}]
165 Creates a tar file and archives the files whose names are speci‐
167 fied in FileList into it. The files can either be read from disk
168 or be specified as binaries.
169 create(Name :: file:filename_all(),
171 FileList :: filelist(),
172 Options :: [create_opt()]) ->
173 ok | {error, term()} | {error, {string(), term()}}
174 Types:
176 filelist() =
178 [file:filename() | {name_in_archive(), file:filename_all()}]
179 create_opt() = compressed | cooked | dereference | verbose
180 Creates a tar file and archives the files whose names are speci‐
182 fied in FileList into it. The files can either be read from disk
183 or be specified as binaries.
184 The options in OptionList modify the defaults as follows:
186 compressed:
188 The entire tar file is compressed, as if it has been run
189 through the gzip program. To abide to the convention that a
190 compressed tar file is to end in ".tar.gz" or ".tgz", add
191 the appropriate extension.
192 cooked:
194 By default, function open/2 opens the tar file in raw mode,
195 which is faster but does not allow a remote (Erlang) file
196 server to be used. Adding cooked to the mode list overrides
197 the default and opens the tar file without option raw.
198 dereference:
200 By default, symbolic links are stored as symbolic links in
201 the tar file. To override the default and store the file
202 that the symbolic link points to into the tar file, use
203 option dereference.
204 verbose:
206 Prints an informational message about each added file.
207 extract(Open :: open_type()) -> ok | {error, term()}
209 Extracts all files from a tar archive.
211 If argument Name is specified as {binary,Binary}, the contents
213 of the binary is assumed to be a tar archive.
214 If argument Name is specified as {file,Fd}, Fd is assumed to be
216 a file descriptor returned from function file:open/2.
217 Otherwise, Name is to be a filename.
219 Note:
221 Leading slashes in tar member names will be removed before writ‐
222 ing the file. That is, absolute paths will be turned into rela‐
223 tive paths. There will be an info message written to the error
224 logger when paths are changed in this way.
225 Warning:
228 The compressed and cooked flags are invalid when passing a file
229 descriptor with {file,Fd}. The file is assumed to have been
230 opened with the appropriate flags.
231 extract(Open :: open_type(), Opts :: [extract_opt()]) ->
234 {ok, [{string(), binary()}]} | {error, term()} | ok
235 Types:
237 extract_opt() =
239 {cwd, string()} |
240 {files, [name_in_archive()]} |
241 compressed | cooked | memory | keep_old_files | verbose
242 Extracts files from a tar archive.
244 If argument Name is specified as {binary,Binary}, the contents
246 of the binary is assumed to be a tar archive.
247 If argument Name is specified as {file,Fd}, Fd is assumed to be
249 a file descriptor returned from function file:open/2.
250 Otherwise, Name is to be a filename.
252 The following options modify the defaults for the extraction as
254 follows:
255 {cwd,Cwd}:
257 Files with relative filenames are by default extracted to
258 the current working directory. With this option, files are
259 instead extracted into directory Cwd.
260 {files,FileList}:
262 By default, all files are extracted from the tar file. With
263 this option, only those files are extracted whose names are
264 included in FileList.
265 compressed:
267 With this option, the file is uncompressed while extracting.
268 If the tar file is not compressed, this option is ignored.
269 cooked:
271 By default, function open/2 function opens the tar file in
272 raw mode, which is faster but does not allow a remote
273 (Erlang) file server to be used. Adding cooked to the mode
274 list overrides the default and opens the tar file without
275 option raw.
276 memory:
278 Instead of extracting to a directory, this option gives the
279 result as a list of tuples {Filename, Binary}, where Binary
280 is a binary containing the extracted data of the file named
281 Filename in the tar file.
282 keep_old_files:
284 By default, all existing files with the same name as files
285 in the tar file are overwritten. With this option, existing
286 files are not overwriten.
287 verbose:
289 Prints an informational message for each extracted file.
290 Warning:
292 The compressed and cooked flags are invalid when passing a file
293 descriptor with {file,Fd}. The file is assumed to have been
294 opened with the appropriate flags.
295 format_error(Atom :: term()) -> string()
298 Converts an error reason term to a human-readable error message
300 string.
301 init(UserData :: user_data(),
303 AccessMode :: write | read,
304 Fun :: file_op()) ->
305 {ok, tar_descriptor()} | {error, badarg}
306 Types:
308 user_data() = term()
310 file_op() =
311 fun((write | close | read2 | position,
312 {user_data(), iodata()} |
313 user_data() |
314 {user_data(), integer() >= 0} |
315 {user_data(), integer() >= 0}) ->
316 ok | eof |
317 {ok, string() | binary()} |
318 {ok, integer() >= 0} |
319 {error, term()})
320 The Fun is the definition of what to do when the different stor‐
322 age operations functions are to be called from the higher tar
323 handling functions (such as add/3, add/4, and close/1).
324 The Fun is called when the tar function wants to do a low-level
326 operation, like writing a block to a file. The Fun is called as
327 Fun(Op, {UserData,Parameters...}), where Op is the operation
328 name, UserData is the term passed as the first argument to
329 init/1 and Parameters... are the data added by the tar function
330 to be passed down to the storage handling function.
331 Parameter UserData is typically the result of opening a low-
333 level structure like a file descriptor or an SFTP channel id.
334 The different Fun clauses operate on that very term.
335 The following are the fun clauses parameter lists:
337 (write, {UserData,DataToWrite}):
339 Writes term DataToWrite using UserData.
340 (close, UserData):
342 Closes the access.
343 (read2, {UserData,Size}):
345 Reads using UserData but only Size bytes. Notice that there
346 is only an arity-2 read function, not an arity-1 function.
347 (position,{UserData,Position}):
349 Sets the position of UserData as defined for files in
350 file:position/2
351 Example:
353 The following is a complete Fun parameter for reading and writ‐
355 ing on files using the file module:
356 ExampleFun =
358 fun(write, {Fd,Data}) -> file:write(Fd, Data);
359 (position, {Fd,Pos}) -> file:position(Fd, Pos);
360 (read2, {Fd,Size}) -> file:read(Fd, Size);
361 (close, Fd) -> file:close(Fd)
362 end
363 Here Fd was specified to function init/3 as:
365 {ok,Fd} = file:open(Name, ...).
367 {ok,TarDesc} = erl_tar:init(Fd, [write], ExampleFun),
368 TarDesc is then used:
370 erl_tar:add(TarDesc, SomeValueIwantToAdd, FileNameInTarFile),
372 erl_tar:close(TarDesc)
373 When the erl_tar core wants to, for example, write a piece of
375 Data, it would call ExampleFun(write, {UserData,Data}).
376 Note:
378 This example with the file module operations is not necessary to
379 use directly, as that is what function open/2 in principle does.
380 Warning:
383 The TarDescriptor term is not a file descriptor. You are advised
384 not to rely on the specific contents of this term, as it can
385 change in future Erlang/OTP releases when more features are
386 added to this module.
387 open(Open :: open_type(), Mode :: [write | compressed | cooked]) ->
390 {ok, tar_descriptor()} | {error, term()}
391 Creates a tar file for writing (any existing file with the same
393 name is truncated).
394 By convention, the name of a tar file is to end in ".tar". To
396 abide to the convention, add ".tar" to the name.
397 Except for the write atom, the following atoms can be added to
399 OpenModeList:
400 compressed:
402 The entire tar file is compressed, as if it has been run
403 through the gzip program. To abide to the convention that a
404 compressed tar file is to end in ".tar.gz" or ".tgz", add
405 the appropriate extension.
406 cooked:
408 By default, the tar file is opened in raw mode, which is
409 faster but does not allow a remote (Erlang) file server to
410 be used. Adding cooked to the mode list overrides the
411 default and opens the tar file without option raw.
412 To add one file at the time into an opened tar file, use func‐
414 tion add/3,4. When you are finished adding files, use function
415 close/1 to close the tar file.
416 Warning:
418 The compressed and cooked flags are invalid when passing a file
419 descriptor with {file,Fd}. The file must already be opened with
420 the appropriate flags.
421 Warning:
424 The TarDescriptor term is not a file descriptor. You are advised
425 not to rely on the specific contents of this term, as it can
426 change in future Erlang/OTP releases when more features are
427 added to this module.
428 table(Open :: open_type()) ->
431 {ok, [name_in_archive()]} | {error, term()}
432 table(Open :: open_type(),
434 Opts :: [compressed | verbose | cooked]) ->
435 {ok, [name_in_archive() | tar_entry()]} | {error, term()}
436 Types:
438 tar_entry() =
440 {Name :: name_in_archive(),
441 Type :: typeflag(),
442 Size :: integer() >= 0,
443 MTime :: tar_time(),
444 Mode :: mode(),
445 Uid :: uid(),
446 Gid :: gid()}
447 tar_time() = integer() >= 0
448 typeflag() =
449 regular | link | symlink | char | block | directory | fifo |
450 reserved | unknown
451 mode() = integer() >= 0
452 uid() = integer() >= 0
453 gid() = integer() >= 0
454 Retrieves the names of all files in the tar file Name.
456 t(Name :: file:filename()) -> ok | {error, term()}
458 Prints the names of all files in the tar file Name to the Erlang
460 shell (similar to "tar t").
461 tt(Name :: open_type()) -> ok | {error, term()}
463 Prints names and information about all files in the tar file
465 Name to the Erlang shell (similar to "tar tv").
466Ericsson AB stdlib 3.14.1 erl_tar(3)