1erl_tar(3)                 Erlang Module Definition                 erl_tar(3)
2
3
4

NAME

6       erl_tar - Unix 'tar' utility for reading and writing tar archives.
7
8

DESCRIPTION

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
20       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
23       Tar files can be created in one operation using  function  create/2  or
24       create/3.
25
26       Alternatively,  for  more  control,  use functions open/2, add/3,4, and
27       close/1.
28
29       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
33       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
37       To convert an error term returned from one of the functions above to  a
38       readable message, use function format_error/1.
39

UNICODE SUPPORT

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
45       If  file:native_name_encoding/0  returns latin1, no translation of path
46       names is done.
47
48       Unicode metadata stored in PAX headers is preserved
49

OTHER STORAGE MEDIA

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
56       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

LIMITATIONS

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
75         * 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

EXPORTS

80       add(TarDescriptor, Filename, Options) -> RetValue
81
82              Types:
83
84                 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
97              Adds  a  file  to a tar file that has been opened for writing by
98              open/1.
99
100              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
104              Options:
105
106                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
112                verbose:
113                  Prints an informational message about the added file.
114
115                {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
120                {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
124                {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
128                {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
132                {uid,non_neg_integer()}:
133                  Sets the file owner. file:read_file_info/1.
134
135                {gid,non_neg_integer()}:
136                  Sets  the  group   that   the   file   owner   belongs   to.
137                  file:read_file_info/1.
138
139       add(TarDescriptor, FilenameOrBin, NameInArchive, Options) -> RetValue
140
141              Types:
142
143                 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
152              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
155       close(TarDescriptor)
156
157              Types:
158
159                 TarDescriptor = term()
160
161              Closes a tar file opened by open/2.
162
163       create(Name, FileList) ->RetValue
164
165              Types:
166
167                 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
175              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
179       create(Name, FileList, OptionList)
180
181              Types:
182
183                 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
193              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
197              The options in OptionList modify the defaults as follows:
198
199                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
205                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
211                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
217                verbose:
218                  Prints an informational message about each added file.
219
220       extract(Name) -> RetValue
221
222              Types:
223
224                 Name = filename() | {binary,binary()} | {file,Fd}
225                 Fd = file_descriptor()
226                 RetValue = ok|{error,{Name,Reason}}
227                 Reason = term()
228
229              Extracts all files from a tar archive.
230
231              If  argument  Name is specified as {binary,Binary}, the contents
232              of the binary is assumed to be a tar archive.
233
234              If argument Name is specified as {file,Fd}, Fd is assumed to  be
235              a file descriptor returned from function file:open/2.
236
237              Otherwise, Name is to be a filename.
238
239          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
245
246       extract(Name, OptionList)
247
248              Types:
249
250                 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
262              Extracts files from a tar archive.
263
264              If  argument  Name is specified as {binary,Binary}, the contents
265              of the binary is assumed to be a tar archive.
266
267              If argument Name is specified as {file,Fd}, Fd is assumed to  be
268              a file descriptor returned from function file:open/2.
269
270              Otherwise, Name is to be a filename.
271
272              The  following options modify the defaults for the extraction as
273              follows:
274
275                {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
280                {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
285                compressed:
286                  With this option, the file is uncompressed while extracting.
287                  If the tar file is not compressed, this option is ignored.
288
289                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
296                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
302                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
307                verbose:
308                  Prints an informational message for each extracted file.
309
310       format_error(Reason) -> string()
311
312              Types:
313
314                 Reason = term()
315
316              Converts an error reason term to a human-readable error  message
317              string.
318
319       init(UserPrivate,  AccessMode, Fun) -> {ok,TarDescriptor} | {error,Rea‐
320       son}
321
322              Types:
323
324                 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
335              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
339              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
346              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
350              The following are the fun clauses parameter lists:
351
352                (write, {UserPrivate,DataToWrite}):
353                  Writes term DataToWrite using UserPrivate.
354
355                (close, UserPrivate):
356                  Closes the access.
357
358                (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
363                (position,{UserPrivate,Position}):
364                  Sets  the  position  of  UserPrivate as defined for files in
365                  file:position/2
366
367              Example:
368
369              The following is a complete Fun parameter for reading and  writ‐
370              ing on files using the file module:
371
372              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
379              Here Fd was specified to function init/3 as:
380
381              {ok,Fd} = file:open(Name, ...).
382              {ok,TarDesc} = erl_tar:init(Fd, [write], ExampleFun),
383
384              TarDesc is then used:
385
386              erl_tar:add(TarDesc, SomeValueIwantToAdd, FileNameInTarFile),
387              erl_tar:close(TarDesc)
388
389              When  the  erl_tar  core wants to, for example, write a piece of
390              Data, it would call ExampleFun(write, {UserPrivate,Data}).
391
392          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
396
397          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
403
404       open(Name, OpenModeList) -> RetValue
405
406              Types:
407
408                 Name = filename()
409                 OpenModeList = [OpenMode]
410                 Mode = write|compressed|cooked
411                 RetValue = {ok,TarDescriptor}|{error,{Name,Reason}}
412                 TarDescriptor = term()
413                 Reason = term()
414
415              Creates a tar file for writing (any existing file with the  same
416              name is truncated).
417
418              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
421              Except for the write atom, the following atoms can be  added  to
422              OpenModeList:
423
424                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
430                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
436              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
440          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
446
447       table(Name) -> RetValue
448
449              Types:
450
451                 Name = filename()|{binary,binary()}|{file,file_descriptor()}
452                 RetValue = {ok,[string()]}|{error,{Name,Reason}}
453                 Reason = term()
454
455              Retrieves the names of all files in the tar file Name.
456
457       table(Name, Options)
458
459              Types:
460
461                 Name = filename()|{binary,binary()}|{file,file_descriptor()}
462
463              Retrieves the names of all files in the tar file Name.
464
465       t(Name)
466
467              Types:
468
469                 Name = filename()|{binary,binary()}|{file,file_descriptor()}
470
471              Prints the names of all files in the tar file Name to the Erlang
472              shell (similar to "tar t").
473
474       tt(Name)
475
476              Types:
477
478                 Name = filename()|{binary,binary()}|{file,file_descriptor()}
479
480              Prints  names  and  information  about all files in the tar file
481              Name to the Erlang shell (similar to "tar tv").
482
483
484
485Ericsson AB                     stdlib 3.8.2.1                      erl_tar(3)
Impressum