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 (Inets) normally accesses the tar file on disk using the
52 file 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 ChunkSize = positive_integer()
91 RetValue = ok|{error,{Filename,Reason}}
92 Reason = term()
93 Adds a file to a tar file that has been opened for writing by
95 open/1.
96 NameInArchive is the name under which the file becomes stored in
98 the tar file. The file gets this name when it is extracted from
99 the tar file.
100 Options:
102 dereference:
104 By default, symbolic links are stored as symbolic links in
105 the tar file. To override the default and store the file
106 that the symbolic link points to into the tar file, use
107 option dereference.
108 verbose:
110 Prints an informational message about the added file.
111 {chunks,ChunkSize}:
113 Reads data in parts from the file. This is intended for mem‐
114 ory-limited machines that, for example, builds a tar file on
115 a remote machine over SFTP, see ssh_sftp:open_tar/3.
116 add(TarDescriptor, FilenameOrBin, NameInArchive, Options) -> RetValue
118 Types:
120 TarDescriptor = term()
122 FilenameOrBin = filename()|binary()
123 Filename = filename()
124 NameInArchive = filename()
125 Options = [Option]
126 Option = dereference|verbose
127 RetValue = ok|{error,{Filename,Reason}}
128 Reason = term()
129 Adds a file to a tar file that has been opened for writing by
131 open/2. This function accepts the same options as add/3.
132 close(TarDescriptor)
134 Types:
136 TarDescriptor = term()
138 Closes a tar file opened by open/2.
140 create(Name, FileList) ->RetValue
142 Types:
144 Name = filename()
146 FileList = [Filename|{NameInArchive, FilenameOrBin}]
147 FilenameOrBin = filename()|binary()
148 Filename = filename()
149 NameInArchive = filename()
150 RetValue = ok|{error,{Name,Reason}}
151 Reason = term()
152 Creates a tar file and archives the files whose names are speci‐
154 fied in FileList into it. The files can either be read from disk
155 or be specified as binaries.
156 create(Name, FileList, OptionList)
158 Types:
160 Name = filename()
162 FileList = [Filename|{NameInArchive, FilenameOrBin}]
163 FilenameOrBin = filename()|binary()
164 Filename = filename()
165 NameInArchive = filename()
166 OptionList = [Option]
167 Option = compressed|cooked|dereference|verbose
168 RetValue = ok|{error,{Name,Reason}}
169 Reason = term()
170 Creates a tar file and archives the files whose names are speci‐
172 fied in FileList into it. The files can either be read from disk
173 or be specified as binaries.
174 The options in OptionList modify the defaults as follows:
176 compressed:
178 The entire tar file is compressed, as if it has been run
179 through the gzip program. To abide to the convention that a
180 compressed tar file is to end in ".tar.gz" or ".tgz", add
181 the appropriate extension.
182 cooked:
184 By default, function open/2 opens the tar file in raw mode,
185 which is faster but does not allow a remote (Erlang) file
186 server to be used. Adding cooked to the mode list overrides
187 the default and opens the tar file without option raw.
188 dereference:
190 By default, symbolic links are stored as symbolic links in
191 the tar file. To override the default and store the file
192 that the symbolic link points to into the tar file, use
193 option dereference.
194 verbose:
196 Prints an informational message about each added file.
197 extract(Name) -> RetValue
199 Types:
201 Name = filename() | {binary,binary()} | {file,Fd}
203 Fd = file_descriptor()
204 RetValue = ok|{error,{Name,Reason}}
205 Reason = term()
206 Extracts all files from a tar archive.
208 If argument Name is specified as {binary,Binary}, the contents
210 of the binary is assumed to be a tar archive.
211 If argument Name is specified as {file,Fd}, Fd is assumed to be
213 a file descriptor returned from function file:open/2.
214 Otherwise, Name is to be a filename.
216 Note:
218 Leading slashes in tar member names will be removed before writ‐
219 ing the file. That is, absolute paths will be turned into rela‐
220 tive paths. There will be an info message written to the error
221 logger when paths are changed in this way.
222 extract(Name, OptionList)
225 Types:
227 Name = filename() | {binary,binary()} | {file,Fd}
229 Fd = file_descriptor()
230 OptionList = [Option]
231 Option = {cwd,Cwd}|{files,FileList}|keep_old_files|ver‐
232 bose|memory
233 Cwd = [dirname()]
234 FileList = [filename()]
235 RetValue = ok|MemoryRetValue|{error,{Name,Reason}}
236 MemoryRetValue = {ok, [{NameInArchive,binary()}]}
237 NameInArchive = filename()
238 Reason = term()
239 Extracts files from a tar archive.
241 If argument Name is specified as {binary,Binary}, the contents
243 of the binary is assumed to be a tar archive.
244 If argument Name is specified as {file,Fd}, Fd is assumed to be
246 a file descriptor returned from function file:open/2.
247 Otherwise, Name is to be a filename.
249 The following options modify the defaults for the extraction as
251 follows:
252 {cwd,Cwd}:
254 Files with relative filenames are by default extracted to
255 the current working directory. With this option, files are
256 instead extracted into directory Cwd.
257 {files,FileList}:
259 By default, all files are extracted from the tar file. With
260 this option, only those files are extracted whose names are
261 included in FileList.
262 compressed:
264 With this option, the file is uncompressed while extracting.
265 If the tar file is not compressed, this option is ignored.
266 cooked:
268 By default, function open/2 function opens the tar file in
269 raw mode, which is faster but does not allow a remote
270 (Erlang) file server to be used. Adding cooked to the mode
271 list overrides the default and opens the tar file without
272 option raw.
273 memory:
275 Instead of extracting to a directory, this option gives the
276 result as a list of tuples {Filename, Binary}, where Binary
277 is a binary containing the extracted data of the file named
278 Filename in the tar file.
279 keep_old_files:
281 By default, all existing files with the same name as files
282 in the tar file are overwritten. With this option, existing
283 files are not overwriten.
284 verbose:
286 Prints an informational message for each extracted file.
287 format_error(Reason) -> string()
289 Types:
291 Reason = term()
293 Cconverts an error reason term to a human-readable error message
295 string.
296 init(UserPrivate, AccessMode, Fun) -> {ok,TarDescriptor} | {error,Rea‐
298 son}
299 Types:
301 UserPrivate = term()
303 AccessMode = [write] | [read]
304 Fun when AccessMode is [write] = fun(write, {UserPri‐
305 vate,DataToWrite})->...; (position,{UserPrivate,Posi‐
306 tion})->...; (close, UserPrivate)->... end
307 Fun when AccessMode is [read] = fun(read2, {UserPri‐
308 vate,Size})->...; (position,{UserPrivate,Position})->...;
309 (close, UserPrivate)->... end
310 TarDescriptor = term()
311 Reason = term()
312 The Fun is the definition of what to do when the different stor‐
314 age operations functions are to be called from the higher tar
315 handling functions (such as add/3, add/4, and close/1).
316 The Fun is called when the tar function wants to do a low-level
318 operation, like writing a block to a file. The Fun is called as
319 Fun(Op, {UserPrivate,Parameters...}), where Op is the operation
320 name, UserPrivate is the term passed as the first argument to
321 init/1 and Parameters... are the data added by the tar function
322 to be passed down to the storage handling function.
323 Parameter UserPrivate is typically the result of opening a low-
325 level structure like a file descriptor or an SFTP channel id.
326 The different Fun clauses operate on that very term.
327 The following are the fun clauses parameter lists:
329 (write, {UserPrivate,DataToWrite}):
331 Writes term DataToWrite using UserPrivate.
332 (close, UserPrivate):
334 Closes the access.
335 (read2, {UserPrivate,Size}):
337 Reads using UserPrivate but only Size bytes. Notice that
338 there is only an arity-2 read function, not an arity-1 func‐
339 tion.
340 (position,{UserPrivate,Position}):
342 Sets the position of UserPrivate as defined for files in
343 file:position/2
344 Example:
346 The following is a complete Fun parameter for reading and writ‐
348 ing on files using the file module:
349 ExampleFun =
351 fun(write, {Fd,Data}) -> file:write(Fd, Data);
352 (position, {Fd,Pos}) -> file:position(Fd, Pos);
353 (read2, {Fd,Size}) -> file:read(Fd, Size);
354 (close, Fd) -> file:close(Fd)
355 end
356 Here Fd was specified to function init/3 as:
358 {ok,Fd} = file:open(Name, ...).
360 {ok,TarDesc} = erl_tar:init(Fd, [write], ExampleFun),
361 TarDesc is then used:
363 erl_tar:add(TarDesc, SomeValueIwantToAdd, FileNameInTarFile),
365 erl_tar:close(TarDesc)
366 When the erl_tar core wants to, for example, write a piece of
368 Data, it would call ExampleFun(write, {UserPrivate,Data}).
369 Note:
371 This example with the file module operations is not necessary to
372 use directly, as that is what function open/2 in principle does.
373 Warning:
376 The TarDescriptor term is not a file descriptor. You are advised
377 not to rely on the specific contents of this term, as it can
378 change in future Erlang/OTP releases when more features are
379 added to this module.
380 open(Name, OpenModeList) -> RetValue
383 Types:
385 Name = filename()
387 OpenModeList = [OpenMode]
388 Mode = write|compressed|cooked
389 RetValue = {ok,TarDescriptor}|{error,{Name,Reason}}
390 TarDescriptor = term()
391 Reason = term()
392 Creates a tar file for writing (any existing file with the same
394 name is truncated).
395 By convention, the name of a tar file is to end in ".tar". To
397 abide to the convention, add ".tar" to the name.
398 Except for the write atom, the following atoms can be added to
400 OpenModeList:
401 compressed:
403 The entire tar file is compressed, as if it has been run
404 through the gzip program. To abide to the convention that a
405 compressed tar file is to end in ".tar.gz" or ".tgz", add
406 the appropriate extension.
407 cooked:
409 By default, the tar file is opened in raw mode, which is
410 faster but does not allow a remote (Erlang) file server to
411 be used. Adding cooked to the mode list overrides the
412 default and opens the tar file without option raw.
413 To add one file at the time into an opened tar file, use func‐
415 tion add/3,4. When you are finished adding files, use function
416 close/1 to close the tar file.
417 Warning:
419 The TarDescriptor term is not a file descriptor. You are advised
420 not to rely on the specific contents of this term, as it can
421 change in future Erlang/OTP releases when more features are
422 added to this module..
423 table(Name) -> RetValue
426 Types:
428 Name = filename()|{binary,binary()}|{file,file_descriptor()}
430 RetValue = {ok,[string()]}|{error,{Name,Reason}}
431 Reason = term()
432 Retrieves the names of all files in the tar file Name.
434 table(Name, Options)
436 Types:
438 Name = filename()|{binary,binary()}|{file,file_descriptor()}
440 Retrieves the names of all files in the tar file Name.
442 t(Name)
444 Types:
446 Name = filename()|{binary,binary()}|{file,file_descriptor()}
448 Prints the names of all files in the tar file Name to the Erlang
450 shell (similar to "tar t").
451 tt(Name)
453 Types:
455 Name = filename()|{binary,binary()}|{file,file_descriptor()}
457 Prints names and information about all files in the tar file
459 Name to the Erlang shell (similar to "tar tv").
460Ericsson AB stdlib 3.4.5.1 erl_tar(3)