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,  US‐
12       TAR, and PAX, as well as some of GNU tar's extensions to the USTAR for‐
13       mat (sparse files most notably). It produces tar archives in USTAR for‐
14       mat, unless the files being archived require PAX format due to restric‐
15       tions in USTAR (such as unicode metadata, filename length,  and  more).
16       As  such, erl_tar supports tar archives produced by most all modern tar
17       utilities, and produces tarballs which should be similarly portable.
18
19       By convention, the name of a tar file is to end in ".tar". To abide  to
20       the convention, add ".tar" to the name.
21
22       Tar  files  can  be created in one operation using function create/2 or
23       create/3.
24
25       Alternatively, for more control, use  functions  open/2,  add/3,4,  and
26       close/1.
27
28       To  extract  all  files from a tar file, use function extract/1. To ex‐
29       tract only some files or to be able to specify some more  options,  use
30       function extract/2.
31
32       To  return  a  list of the files in a tar file, use function table/1 or
33       table/2. To print a list of files to the Erlang shell, use function t/1
34       or tt/1.
35
36       To  convert an error term returned from one of the functions above to a
37       readable message, use function format_error/1.
38

UNICODE SUPPORT

40       If file:native_name_encoding/0 returns utf8, path names are encoded  in
41       UTF-8 when creating tar files, and path names are assumed to be encoded
42       in UTF-8 when extracting tar files.
43
44       If file:native_name_encoding/0 returns latin1, no translation  of  path
45       names is done.
46
47       Unicode metadata stored in PAX headers is preserved
48

OTHER STORAGE MEDIA

50       The  ftp  module  normally accesses the tar file on disk using the file
51       module. When other needs arise, you can define your own  low-level  Er‐
52       lang functions to perform the writing and reading on the storage media;
53       use function init/3.
54
55       An example of this is the SFTP  support  in  ssh_sftp:open_tar/3.  This
56       function opens a tar file on a remote machine using an SFTP channel.
57

LIMITATIONS

59         * If  you  must remain compatible with the USTAR tar format, you must
60           ensure file paths being stored are less than 255  bytes  in  total,
61           with a maximum filename component length of 100 bytes. USTAR uses a
62           header field (prefix) in addition to the  name  field,  and  splits
63           file paths longer than 100 bytes into two parts. This split is done
64           on a directory boundary, and is done in such a way to make the best
65           use  of  the  space  available in those two fields, but in practice
66           this will often mean that you have less than 255 bytes for a  path.
67           erl_tar  will  automatically  upgrade  the  format to PAX to handle
68           longer filenames, so this is only an issue if you need  to  extract
69           the  archive  with  an older implementation of erl_tar or tar which
70           does not support PAX. In this case, the PAX  headers  will  be  ex‐
71           tracted as regular files, and you will need to apply them manually.
72
73         * Like  the above, if you must remain USTAR compatible, you must also
74           ensure than paths for symbolic/hard links  are  no  more  than  100
75           bytes, otherwise PAX headers will be used.
76

DATA TYPES

78       name_in_archive() = string()
79
80       open_type() =
81           file:filename_all() |
82           {binary, binary()} |
83           {file, file:io_device()}
84
85       tar_descriptor()
86

EXPORTS

88       add(TarDescriptor, AddType, Options) -> ok | {error, term()}
89
90       add(TarDescriptor, Filename, NameInArchive, Options) ->
91              ok | {error, term()}
92
93              Types:
94
95                 TarDescriptor = tar_descriptor()
96                 Filename = file:filename_all()
97                 NameInArchive = name_in_archive()
98                 Options = [add_opt()]
99                 add_type() =
100                     name_in_archive() | {name_in_archive(), file:filename_all()}
101                 add_opt() =
102                     dereference | verbose |
103                     {chunks, integer() >= 1} |
104                     {atime, integer() >= 0} |
105                     {mtime, integer() >= 0} |
106                     {ctime, integer() >= 0} |
107                     {uid, integer() >= 0} |
108                     {gid, integer() >= 0}
109
110              Adds  a  file  to a tar file that has been opened for writing by
111              open/1.
112
113              NameInArchive is the name under which the file becomes stored in
114              the  tar file. The file gets this name when it is extracted from
115              the tar file.
116
117              Options:
118
119                dereference:
120                  By default, symbolic links are stored as symbolic  links  in
121                  the  tar  file.  To  override the default and store the file
122                  that the symbolic link points to into the tar file, use  op‐
123                  tion dereference.
124
125                verbose:
126                  Prints an informational message about the added file.
127
128                {chunks,ChunkSize}:
129                  Reads data in parts from the file. This is intended for mem‐
130                  ory-limited machines that, for example, builds a tar file on
131                  a remote machine over SFTP, see ssh_sftp:open_tar/3.
132
133                {atime,non_neg_integer()}:
134                  Sets  the last time, as  POSIX time, when the file was read.
135                  See also file:read_file_info/1.
136
137                {mtime,non_neg_integer()}:
138                  Sets the last time, as  POSIX time, when the file was  writ‐
139                  ten. See also file:read_file_info/1.
140
141                {ctime,non_neg_integer()}:
142                  Sets  the  time,  as  POSIX time, when the file was created.
143                  See also file:read_file_info/1.
144
145                {uid,non_neg_integer()}:
146                  Sets the file owner. file:read_file_info/1.
147
148                {gid,non_neg_integer()}:
149                  Sets  the  group   that   the   file   owner   belongs   to.
150                  file:read_file_info/1.
151
152       close(TarDescriptor :: tar_descriptor()) -> ok | {error, term()}
153
154              Closes a tar file opened by open/2.
155
156       create(Name :: file:filename_all(), FileList :: filelist()) ->
157                 ok | {error, {string(), term()}}
158
159              Types:
160
161                 filelist() =
162                     [file:filename() | {name_in_archive(), file:filename_all()}]
163
164              Creates a tar file and archives the files whose names are speci‐
165              fied in FileList into it. The files can either be read from disk
166              or be specified as binaries.
167
168       create(Name :: file:filename_all(),
169              FileList :: filelist(),
170              Options :: [create_opt()]) ->
171                 ok | {error, term()} | {error, {string(), term()}}
172
173              Types:
174
175                 filelist() =
176                     [file:filename() | {name_in_archive(), file:filename_all()}]
177                 create_opt() = compressed | cooked | dereference | verbose
178
179              Creates a tar file and archives the files whose names are speci‐
180              fied in FileList into it. The files can either be read from disk
181              or be specified as binaries.
182
183              The options in OptionList modify the defaults as follows:
184
185                compressed:
186                  The  entire  tar  file  is compressed, as if it has been run
187                  through the gzip program. To abide to the convention that  a
188                  compressed  tar  file  is to end in ".tar.gz" or ".tgz", add
189                  the appropriate extension.
190
191                cooked:
192                  By default, function open/2 opens the tar file in raw  mode,
193                  which  is  faster  but does not allow a remote (Erlang) file
194                  server to be used. Adding cooked to the mode list  overrides
195                  the default and opens the tar file without option raw.
196
197                dereference:
198                  By  default,  symbolic links are stored as symbolic links in
199                  the tar file. To override the default  and  store  the  file
200                  that  the symbolic link points to into the tar file, use op‐
201                  tion dereference.
202
203                verbose:
204                  Prints an informational message about each added file.
205
206       extract(Open :: open_type()) -> ok | {error, term()}
207
208              Extracts all files from a tar archive.
209
210              If argument Name is specified as {binary,Binary},  the  contents
211              of the binary is assumed to be a tar archive.
212
213              If  argument Name is specified as {file,Fd}, Fd is assumed to be
214              a file descriptor returned from function file:open/2.
215
216              Otherwise, Name is to be a filename.
217
218          Note:
219              Leading slashes in tar member names will be removed before writ‐
220              ing  the file. That is, absolute paths will be turned into rela‐
221              tive paths. There will be an info message written to  the  error
222              logger when paths are changed in this way.
223
224
225          Warning:
226              The  compressed and cooked flags are invalid when passing a file
227              descriptor with {file,Fd}. The file  is  assumed  to  have  been
228              opened with the appropriate flags.
229
230
231       extract(Open :: open_type(), Opts :: [extract_opt()]) ->
232                  {ok, [{string(), binary()}]} | {error, term()} | ok
233
234              Types:
235
236                 extract_opt() =
237                     {cwd, string()} |
238                     {files, [name_in_archive()]} |
239                     compressed | cooked | memory | keep_old_files | verbose
240
241              Extracts files from a tar archive.
242
243              If  argument  Name is specified as {binary,Binary}, the contents
244              of the binary is assumed to be a tar archive.
245
246              If argument Name is specified as {file,Fd}, Fd is assumed to  be
247              a file descriptor returned from function file:open/2.
248
249              Otherwise, Name is to be a filename.
250
251              The  following options modify the defaults for the extraction as
252              follows:
253
254                {cwd,Cwd}:
255                  Files with relative filenames are by  default  extracted  to
256                  the  current  working directory. With this option, files are
257                  instead extracted into directory Cwd.
258
259                {files,FileList}:
260                  By default, all files are extracted from the tar file.  With
261                  this  option, only those files are extracted whose names are
262                  included in FileList.
263
264                compressed:
265                  With this option, the file is uncompressed while extracting.
266                  If the tar file is not compressed, this option is ignored.
267
268                cooked:
269                  By  default,  function open/2 function opens the tar file in
270                  raw mode, which is faster but does not allow a  remote  (Er‐
271                  lang) file server to be used. Adding cooked to the mode list
272                  overrides the default and opens the tar file without  option
273                  raw.
274
275                memory:
276                  Instead  of extracting to a directory, this option gives the
277                  result as a list of tuples {Filename, Binary}, where  Binary
278                  is  a binary containing the extracted data of the file named
279                  Filename in the tar file.
280
281                keep_old_files:
282                  By default, all existing files with the same name  as  files
283                  in  the tar file are overwritten. With this option, existing
284                  files are not overwriten.
285
286                verbose:
287                  Prints an informational message for each extracted file.
288
289          Warning:
290              The compressed and cooked flags are invalid when passing a  file
291              descriptor  with  {file,Fd}.  The  file  is assumed to have been
292              opened with the appropriate flags.
293
294
295       format_error(Atom :: term()) -> string()
296
297              Converts an error reason term to a human-readable error  message
298              string.
299
300       init(UserData :: user_data(),
301            AccessMode :: write | read,
302            Fun :: file_op()) ->
303               {ok, tar_descriptor()} | {error, badarg}
304
305              Types:
306
307                 user_data() = term()
308                 file_op() =
309                     fun((write | close | read2 | position,
310                          {user_data(), iodata()} |
311                          user_data() |
312                          {user_data(), integer() >= 0} |
313                          {user_data(), integer() >= 0}) ->
314                             ok | eof |
315                             {ok, string() | binary()} |
316                             {ok, integer() >= 0} |
317                             {error, term()})
318
319              The Fun is the definition of what to do when the different stor‐
320              age operations functions are to be called from  the  higher  tar
321              handling functions (such as add/3, add/4, and close/1).
322
323              The  Fun is called when the tar function wants to do a low-level
324              operation, like writing a block to a file. The Fun is called  as
325              Fun(Op,  {UserData,Parameters...}),  where  Op  is the operation
326              name, UserData is the term  passed  as  the  first  argument  to
327              init/1  and Parameters... are the data added by the tar function
328              to be passed down to the storage handling function.
329
330              Parameter UserData is typically the result  of  opening  a  low-
331              level  structure  like  a file descriptor or an SFTP channel id.
332              The different Fun clauses operate on that very term.
333
334              The following are the fun clauses parameter lists:
335
336                (write, {UserData,DataToWrite}):
337                  Writes term DataToWrite using UserData.
338
339                (close, UserData):
340                  Closes the access.
341
342                (read2, {UserData,Size}):
343                  Reads using UserData but only Size bytes. Notice that  there
344                  is only an arity-2 read function, not an arity-1 function.
345
346                (position,{UserData,Position}):
347                  Sets  the  position  of  UserData  as  defined  for files in
348                  file:position/2
349
350              Example:
351
352              The following is a complete Fun parameter for reading and  writ‐
353              ing on files using the file module:
354
355              ExampleFun =
356                 fun(write, {Fd,Data}) ->  file:write(Fd, Data);
357                    (position, {Fd,Pos}) -> file:position(Fd, Pos);
358                    (read2, {Fd,Size}) -> file:read(Fd, Size);
359                    (close, Fd) -> file:close(Fd)
360                 end
361
362              Here Fd was specified to function init/3 as:
363
364              {ok,Fd} = file:open(Name, ...).
365              {ok,TarDesc} = erl_tar:init(Fd, [write], ExampleFun),
366
367              TarDesc is then used:
368
369              erl_tar:add(TarDesc, SomeValueIwantToAdd, FileNameInTarFile),
370              erl_tar:close(TarDesc)
371
372              When  the  erl_tar  core wants to, for example, write a piece of
373              Data, it would call ExampleFun(write, {UserData,Data}).
374
375          Note:
376              This example with the file module operations is not necessary to
377              use directly, as that is what function open/2 in principle does.
378
379
380          Warning:
381              The TarDescriptor term is not a file descriptor. You are advised
382              not to rely on the specific contents of this  term,  as  it  can
383              change  in  future  Erlang/OTP  releases  when more features are
384              added to this module.
385
386
387       open(Open :: open_type(), Mode :: [write | compressed | cooked]) ->
388               {ok, tar_descriptor()} | {error, term()}
389
390              Creates a tar file for writing (any existing file with the  same
391              name is truncated).
392
393              By  convention,  the  name of a tar file is to end in ".tar". To
394              abide to the convention, add ".tar" to the name.
395
396              Except for the write atom, the following atoms can be  added  to
397              OpenModeList:
398
399                compressed:
400                  The  entire  tar  file  is compressed, as if it has been run
401                  through the gzip program. To abide to the convention that  a
402                  compressed  tar  file  is to end in ".tar.gz" or ".tgz", add
403                  the appropriate extension.
404
405                cooked:
406                  By default, the tar file is opened in  raw  mode,  which  is
407                  faster  but  does not allow a remote (Erlang) file server to
408                  be used. Adding cooked to the mode list  overrides  the  de‐
409                  fault and opens the tar file without option raw.
410
411              To  add  one file at the time into an opened tar file, use func‐
412              tion add/3,4. When you are finished adding files,  use  function
413              close/1 to close the tar file.
414
415          Warning:
416              The  compressed and cooked flags are invalid when passing a file
417              descriptor with {file,Fd}. The file must already be opened  with
418              the appropriate flags.
419
420
421          Warning:
422              The TarDescriptor term is not a file descriptor. You are advised
423              not to rely on the specific contents of this  term,  as  it  can
424              change  in  future  Erlang/OTP  releases  when more features are
425              added to this module.
426
427
428       table(Open :: open_type()) ->
429                {ok, [name_in_archive()]} | {error, term()}
430
431       table(Open :: open_type(),
432             Opts :: [compressed | verbose | cooked]) ->
433                {ok, [name_in_archive() | tar_entry()]} | {error, term()}
434
435              Types:
436
437                 tar_entry() =
438                     {Name :: name_in_archive(),
439                      Type :: typeflag(),
440                      Size :: integer() >= 0,
441                      MTime :: tar_time(),
442                      Mode :: mode(),
443                      Uid :: uid(),
444                      Gid :: gid()}
445                 tar_time() = integer() >= 0
446                 typeflag() =
447                     regular | link | symlink | char | block | directory | fifo |
448                     reserved | unknown
449                 mode() = integer() >= 0
450                 uid() = integer() >= 0
451                 gid() = integer() >= 0
452
453              Retrieves the names of all files in the tar file Name.
454
455       t(Name :: file:filename()) -> ok | {error, term()}
456
457              Prints the names of all files in the tar file Name to the Erlang
458              shell (similar to "tar t").
459
460       tt(Name :: open_type()) -> ok | {error, term()}
461
462              Prints  names  and  information  about all files in the tar file
463              Name to the Erlang shell (similar to "tar tv").
464
465
466
467Ericsson AB                     stdlib 4.3.1.3                      erl_tar(3)
Impressum