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 extract(Open :: open_type(), Opts :: [extract_opt()]) ->
228 {ok, [{string(), binary()}]} | {error, term()} | ok
229 Types:
231 extract_opt() =
233 {cwd, string()} |
234 {files, [name_in_archive()]} |
235 compressed | cooked | memory | keep_old_files | verbose
236 Extracts files from a tar archive.
238 If argument Name is specified as {binary,Binary}, the contents
240 of the binary is assumed to be a tar archive.
241 If argument Name is specified as {file,Fd}, Fd is assumed to be
243 a file descriptor returned from function file:open/2.
244 Otherwise, Name is to be a filename.
246 The following options modify the defaults for the extraction as
248 follows:
249 {cwd,Cwd}:
251 Files with relative filenames are by default extracted to
252 the current working directory. With this option, files are
253 instead extracted into directory Cwd.
254 {files,FileList}:
256 By default, all files are extracted from the tar file. With
257 this option, only those files are extracted whose names are
258 included in FileList.
259 compressed:
261 With this option, the file is uncompressed while extracting.
262 If the tar file is not compressed, this option is ignored.
263 cooked:
265 By default, function open/2 function opens the tar file in
266 raw mode, which is faster but does not allow a remote
267 (Erlang) file server to be used. Adding cooked to the mode
268 list overrides the default and opens the tar file without
269 option raw.
270 memory:
272 Instead of extracting to a directory, this option gives the
273 result as a list of tuples {Filename, Binary}, where Binary
274 is a binary containing the extracted data of the file named
275 Filename in the tar file.
276 keep_old_files:
278 By default, all existing files with the same name as files
279 in the tar file are overwritten. With this option, existing
280 files are not overwriten.
281 verbose:
283 Prints an informational message for each extracted file.
284 format_error(Atom :: term()) -> string()
286 Converts an error reason term to a human-readable error message
288 string.
289 init(UserData :: user_data(),
291 AccessMode :: write | read,
292 Fun :: file_op()) ->
293 {ok, tar_descriptor()} | {error, badarg}
294 Types:
296 user_data() = term()
298 file_op() =
299 fun((write | close | read2 | position,
300 {user_data(), iodata()} |
301 user_data() |
302 {user_data(), integer() >= 0} |
303 {user_data(), integer() >= 0}) ->
304 ok | eof |
305 {ok, string() | binary()} |
306 {ok, integer() >= 0} |
307 {error, term()})
308 The Fun is the definition of what to do when the different stor‐
310 age operations functions are to be called from the higher tar
311 handling functions (such as add/3, add/4, and close/1).
312 The Fun is called when the tar function wants to do a low-level
314 operation, like writing a block to a file. The Fun is called as
315 Fun(Op, {UserData,Parameters...}), where Op is the operation
316 name, UserData is the term passed as the first argument to
317 init/1 and Parameters... are the data added by the tar function
318 to be passed down to the storage handling function.
319 Parameter UserData is typically the result of opening a low-
321 level structure like a file descriptor or an SFTP channel id.
322 The different Fun clauses operate on that very term.
323 The following are the fun clauses parameter lists:
325 (write, {UserData,DataToWrite}):
327 Writes term DataToWrite using UserData.
328 (close, UserData):
330 Closes the access.
331 (read2, {UserData,Size}):
333 Reads using UserData but only Size bytes. Notice that there
334 is only an arity-2 read function, not an arity-1 function.
335 (position,{UserData,Position}):
337 Sets the position of UserData as defined for files in
338 file:position/2
339 Example:
341 The following is a complete Fun parameter for reading and writ‐
343 ing on files using the file module:
344 ExampleFun =
346 fun(write, {Fd,Data}) -> file:write(Fd, Data);
347 (position, {Fd,Pos}) -> file:position(Fd, Pos);
348 (read2, {Fd,Size}) -> file:read(Fd, Size);
349 (close, Fd) -> file:close(Fd)
350 end
351 Here Fd was specified to function init/3 as:
353 {ok,Fd} = file:open(Name, ...).
355 {ok,TarDesc} = erl_tar:init(Fd, [write], ExampleFun),
356 TarDesc is then used:
358 erl_tar:add(TarDesc, SomeValueIwantToAdd, FileNameInTarFile),
360 erl_tar:close(TarDesc)
361 When the erl_tar core wants to, for example, write a piece of
363 Data, it would call ExampleFun(write, {UserData,Data}).
364 Note:
366 This example with the file module operations is not necessary to
367 use directly, as that is what function open/2 in principle does.
368 Warning:
371 The TarDescriptor term is not a file descriptor. You are advised
372 not to rely on the specific contents of this term, as it can
373 change in future Erlang/OTP releases when more features are
374 added to this module.
375 open(Open :: open_type(), Mode :: [write | compressed | cooked]) ->
378 {ok, tar_descriptor()} | {error, term()}
379 Creates a tar file for writing (any existing file with the same
381 name is truncated).
382 By convention, the name of a tar file is to end in ".tar". To
384 abide to the convention, add ".tar" to the name.
385 Except for the write atom, the following atoms can be added to
387 OpenModeList:
388 compressed:
390 The entire tar file is compressed, as if it has been run
391 through the gzip program. To abide to the convention that a
392 compressed tar file is to end in ".tar.gz" or ".tgz", add
393 the appropriate extension.
394 cooked:
396 By default, the tar file is opened in raw mode, which is
397 faster but does not allow a remote (Erlang) file server to
398 be used. Adding cooked to the mode list overrides the
399 default and opens the tar file without option raw.
400 To add one file at the time into an opened tar file, use func‐
402 tion add/3,4. When you are finished adding files, use function
403 close/1 to close the tar file.
404 Warning:
406 The TarDescriptor term is not a file descriptor. You are advised
407 not to rely on the specific contents of this term, as it can
408 change in future Erlang/OTP releases when more features are
409 added to this module..
410 table(Open :: open_type()) ->
413 {ok, [name_in_archive()]} | {error, term()}
414 table(Open :: open_type(),
416 Opts :: [compressed | verbose | cooked]) ->
417 {ok, [name_in_archive() | tar_entry()]} | {error, term()}
418 Types:
420 tar_entry() =
422 {Name :: name_in_archive(),
423 Type :: typeflag(),
424 Size :: integer() >= 0,
425 MTime :: tar_time(),
426 Mode :: mode(),
427 Uid :: uid(),
428 Gid :: gid()}
429 tar_time() = integer() >= 0
430 typeflag() =
431 regular | link | symlink | char | block | directory | fifo |
432 reserved | unknown
433 mode() = integer() >= 0
434 uid() = integer() >= 0
435 gid() = integer() >= 0
436 Retrieves the names of all files in the tar file Name.
438 t(Name :: file:filename()) -> ok | {error, term()}
440 Prints the names of all files in the tar file Name to the Erlang
442 shell (similar to "tar t").
443 tt(Name :: open_type()) -> ok | {error, term()}
445 Prints names and information about all files in the tar file
447 Name to the Erlang shell (similar to "tar tv").
448Ericsson AB stdlib 3.12.1 erl_tar(3)