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 add(TarDescriptor, Filename, Options) -> RetValue
81 Types:
83 TarDescriptor = term()
85 FilenameOrBin = filename()|binary()
86 NameInArchive = filename()
87 Filename = filename()|{NameInArchive,FilenameOrBin}
88 Options = [Option]
89 Option = dereference|verbose|{chunks,ChunkSize}
90 |{atime,non_neg_integer()}|{mtime,non_neg_integer()}
91 |{ctime,non_neg_integer()}|{uid,non_neg_integer()}
92 |{gid,non_neg_integer()}
93 ChunkSize = positive_integer()
94 RetValue = ok|{error,{Filename,Reason}}
95 Reason = term()
96 Adds a file to a tar file that has been opened for writing by
98 open/1.
99 NameInArchive is the name under which the file becomes stored in
101 the tar file. The file gets this name when it is extracted from
102 the tar file.
103 Options:
105 dereference:
107 By default, symbolic links are stored as symbolic links in
108 the tar file. To override the default and store the file
109 that the symbolic link points to into the tar file, use
110 option dereference.
111 verbose:
113 Prints an informational message about the added file.
114 {chunks,ChunkSize}:
116 Reads data in parts from the file. This is intended for mem‐
117 ory-limited machines that, for example, builds a tar file on
118 a remote machine over SFTP, see ssh_sftp:open_tar/3.
119 {atime,non_neg_integer()}:
121 Sets the last time, as POSIX time, when the file was read.
122 See also file:read_file_info/1.
123 {mtime,non_neg_integer()}:
125 Sets the last time, as POSIX time, when the file was writ‐
126 ten. See also file:read_file_info/1.
127 {ctime,non_neg_integer()}:
129 Sets the time, as POSIX time, when the file was created.
130 See also file:read_file_info/1.
131 {uid,non_neg_integer()}:
133 Sets the file owner. file:read_file_info/1.
134 {gid,non_neg_integer()}:
136 Sets the group that the file owner belongs to.
137 file:read_file_info/1.
138 add(TarDescriptor, FilenameOrBin, NameInArchive, Options) -> RetValue
140 Types:
142 TarDescriptor = term()
144 FilenameOrBin = filename()|binary()
145 Filename = filename()
146 NameInArchive = filename()
147 Options = [Option]
148 Option = dereference|verbose
149 RetValue = ok|{error,{Filename,Reason}}
150 Reason = term()
151 Adds a file to a tar file that has been opened for writing by
153 open/2. This function accepts the same options as add/3.
154 close(TarDescriptor)
156 Types:
158 TarDescriptor = term()
160 Closes a tar file opened by open/2.
162 create(Name, FileList) ->RetValue
164 Types:
166 Name = filename()
168 FileList = [Filename|{NameInArchive, FilenameOrBin}]
169 FilenameOrBin = filename()|binary()
170 Filename = filename()
171 NameInArchive = filename()
172 RetValue = ok|{error,{Name,Reason}}
173 Reason = term()
174 Creates a tar file and archives the files whose names are speci‐
176 fied in FileList into it. The files can either be read from disk
177 or be specified as binaries.
178 create(Name, FileList, OptionList)
180 Types:
182 Name = filename()
184 FileList = [Filename|{NameInArchive, FilenameOrBin}]
185 FilenameOrBin = filename()|binary()
186 Filename = filename()
187 NameInArchive = filename()
188 OptionList = [Option]
189 Option = compressed|cooked|dereference|verbose
190 RetValue = ok|{error,{Name,Reason}}
191 Reason = term()
192 Creates a tar file and archives the files whose names are speci‐
194 fied in FileList into it. The files can either be read from disk
195 or be specified as binaries.
196 The options in OptionList modify the defaults as follows:
198 compressed:
200 The entire tar file is compressed, as if it has been run
201 through the gzip program. To abide to the convention that a
202 compressed tar file is to end in ".tar.gz" or ".tgz", add
203 the appropriate extension.
204 cooked:
206 By default, function open/2 opens the tar file in raw mode,
207 which is faster but does not allow a remote (Erlang) file
208 server to be used. Adding cooked to the mode list overrides
209 the default and opens the tar file without option raw.
210 dereference:
212 By default, symbolic links are stored as symbolic links in
213 the tar file. To override the default and store the file
214 that the symbolic link points to into the tar file, use
215 option dereference.
216 verbose:
218 Prints an informational message about each added file.
219 extract(Name) -> RetValue
221 Types:
223 Name = filename() | {binary,binary()} | {file,Fd}
225 Fd = file_descriptor()
226 RetValue = ok|{error,{Name,Reason}}
227 Reason = term()
228 Extracts all files from a tar archive.
230 If argument Name is specified as {binary,Binary}, the contents
232 of the binary is assumed to be a tar archive.
233 If argument Name is specified as {file,Fd}, Fd is assumed to be
235 a file descriptor returned from function file:open/2.
236 Otherwise, Name is to be a filename.
238 Note:
240 Leading slashes in tar member names will be removed before writ‐
241 ing the file. That is, absolute paths will be turned into rela‐
242 tive paths. There will be an info message written to the error
243 logger when paths are changed in this way.
244 extract(Name, OptionList)
247 Types:
249 Name = filename() | {binary,binary()} | {file,Fd}
251 Fd = file_descriptor()
252 OptionList = [Option]
253 Option = {cwd,Cwd}|{files,FileList}|keep_old_files|ver‐
254 bose|memory
255 Cwd = [dirname()]
256 FileList = [filename()]
257 RetValue = ok|MemoryRetValue|{error,{Name,Reason}}
258 MemoryRetValue = {ok, [{NameInArchive,binary()}]}
259 NameInArchive = filename()
260 Reason = term()
261 Extracts files from a tar archive.
263 If argument Name is specified as {binary,Binary}, the contents
265 of the binary is assumed to be a tar archive.
266 If argument Name is specified as {file,Fd}, Fd is assumed to be
268 a file descriptor returned from function file:open/2.
269 Otherwise, Name is to be a filename.
271 The following options modify the defaults for the extraction as
273 follows:
274 {cwd,Cwd}:
276 Files with relative filenames are by default extracted to
277 the current working directory. With this option, files are
278 instead extracted into directory Cwd.
279 {files,FileList}:
281 By default, all files are extracted from the tar file. With
282 this option, only those files are extracted whose names are
283 included in FileList.
284 compressed:
286 With this option, the file is uncompressed while extracting.
287 If the tar file is not compressed, this option is ignored.
288 cooked:
290 By default, function open/2 function opens the tar file in
291 raw mode, which is faster but does not allow a remote
292 (Erlang) file server to be used. Adding cooked to the mode
293 list overrides the default and opens the tar file without
294 option raw.
295 memory:
297 Instead of extracting to a directory, this option gives the
298 result as a list of tuples {Filename, Binary}, where Binary
299 is a binary containing the extracted data of the file named
300 Filename in the tar file.
301 keep_old_files:
303 By default, all existing files with the same name as files
304 in the tar file are overwritten. With this option, existing
305 files are not overwriten.
306 verbose:
308 Prints an informational message for each extracted file.
309 format_error(Reason) -> string()
311 Types:
313 Reason = term()
315 Converts an error reason term to a human-readable error message
317 string.
318 init(UserPrivate, AccessMode, Fun) -> {ok,TarDescriptor} | {error,Rea‐
320 son}
321 Types:
323 UserPrivate = term()
325 AccessMode = [write] | [read]
326 Fun when AccessMode is [write] = fun(write, {UserPri‐
327 vate,DataToWrite})->...; (position,{UserPrivate,Posi‐
328 tion})->...; (close, UserPrivate)->... end
329 Fun when AccessMode is [read] = fun(read2, {UserPri‐
330 vate,Size})->...; (position,{UserPrivate,Position})->...;
331 (close, UserPrivate)->... end
332 TarDescriptor = term()
333 Reason = term()
334 The Fun is the definition of what to do when the different stor‐
336 age operations functions are to be called from the higher tar
337 handling functions (such as add/3, add/4, and close/1).
338 The Fun is called when the tar function wants to do a low-level
340 operation, like writing a block to a file. The Fun is called as
341 Fun(Op, {UserPrivate,Parameters...}), where Op is the operation
342 name, UserPrivate is the term passed as the first argument to
343 init/1 and Parameters... are the data added by the tar function
344 to be passed down to the storage handling function.
345 Parameter UserPrivate is typically the result of opening a low-
347 level structure like a file descriptor or an SFTP channel id.
348 The different Fun clauses operate on that very term.
349 The following are the fun clauses parameter lists:
351 (write, {UserPrivate,DataToWrite}):
353 Writes term DataToWrite using UserPrivate.
354 (close, UserPrivate):
356 Closes the access.
357 (read2, {UserPrivate,Size}):
359 Reads using UserPrivate but only Size bytes. Notice that
360 there is only an arity-2 read function, not an arity-1 func‐
361 tion.
362 (position,{UserPrivate,Position}):
364 Sets the position of UserPrivate as defined for files in
365 file:position/2
366 Example:
368 The following is a complete Fun parameter for reading and writ‐
370 ing on files using the file module:
371 ExampleFun =
373 fun(write, {Fd,Data}) -> file:write(Fd, Data);
374 (position, {Fd,Pos}) -> file:position(Fd, Pos);
375 (read2, {Fd,Size}) -> file:read(Fd, Size);
376 (close, Fd) -> file:close(Fd)
377 end
378 Here Fd was specified to function init/3 as:
380 {ok,Fd} = file:open(Name, ...).
382 {ok,TarDesc} = erl_tar:init(Fd, [write], ExampleFun),
383 TarDesc is then used:
385 erl_tar:add(TarDesc, SomeValueIwantToAdd, FileNameInTarFile),
387 erl_tar:close(TarDesc)
388 When the erl_tar core wants to, for example, write a piece of
390 Data, it would call ExampleFun(write, {UserPrivate,Data}).
391 Note:
393 This example with the file module operations is not necessary to
394 use directly, as that is what function open/2 in principle does.
395 Warning:
398 The TarDescriptor term is not a file descriptor. You are advised
399 not to rely on the specific contents of this term, as it can
400 change in future Erlang/OTP releases when more features are
401 added to this module.
402 open(Name, OpenModeList) -> RetValue
405 Types:
407 Name = filename()
409 OpenModeList = [OpenMode]
410 Mode = write|compressed|cooked
411 RetValue = {ok,TarDescriptor}|{error,{Name,Reason}}
412 TarDescriptor = term()
413 Reason = term()
414 Creates a tar file for writing (any existing file with the same
416 name is truncated).
417 By convention, the name of a tar file is to end in ".tar". To
419 abide to the convention, add ".tar" to the name.
420 Except for the write atom, the following atoms can be added to
422 OpenModeList:
423 compressed:
425 The entire tar file is compressed, as if it has been run
426 through the gzip program. To abide to the convention that a
427 compressed tar file is to end in ".tar.gz" or ".tgz", add
428 the appropriate extension.
429 cooked:
431 By default, the tar file is opened in raw mode, which is
432 faster but does not allow a remote (Erlang) file server to
433 be used. Adding cooked to the mode list overrides the
434 default and opens the tar file without option raw.
435 To add one file at the time into an opened tar file, use func‐
437 tion add/3,4. When you are finished adding files, use function
438 close/1 to close the tar file.
439 Warning:
441 The TarDescriptor term is not a file descriptor. You are advised
442 not to rely on the specific contents of this term, as it can
443 change in future Erlang/OTP releases when more features are
444 added to this module..
445 table(Name) -> RetValue
448 Types:
450 Name = filename()|{binary,binary()}|{file,file_descriptor()}
452 RetValue = {ok,[string()]}|{error,{Name,Reason}}
453 Reason = term()
454 Retrieves the names of all files in the tar file Name.
456 table(Name, Options)
458 Types:
460 Name = filename()|{binary,binary()}|{file,file_descriptor()}
462 Retrieves the names of all files in the tar file Name.
464 t(Name)
466 Types:
468 Name = filename()|{binary,binary()}|{file,file_descriptor()}
470 Prints the names of all files in the tar file Name to the Erlang
472 shell (similar to "tar t").
473 tt(Name)
475 Types:
477 Name = filename()|{binary,binary()}|{file,file_descriptor()}
479 Prints names and information about all files in the tar file
481 Name to the Erlang shell (similar to "tar tv").
482Ericsson AB stdlib 3.10 erl_tar(3)