aboutsummaryrefslogtreecommitdiffstats
path: root/lib/stdlib/doc/src/erl_tar.xml
blob: ccf0f3901f1c09693cf75d86afd96ef6a78c2da2 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">

<erlref>
  <header>
    <copyright>
      <year>2003</year><year>2013</year>
      <holder>Ericsson AB. All Rights Reserved.</holder>
    </copyright>
    <legalnotice>
      The contents of this file are subject to the Erlang Public License,
      Version 1.1, (the "License"); you may not use this file except in
      compliance with the License. You should have received a copy of the
      Erlang Public License along with this software. If not, it can be
      retrieved online at http://www.erlang.org/.
    
      Software distributed under the License is distributed on an "AS IS"
      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
      the License for the specific language governing rights and limitations
      under the License.
    
    </legalnotice>

    <title>erl_tar</title>
    <prepared>Bjorn Gustavsson</prepared>
    <responsible>Bjorn Gustavsson</responsible>
    <docno>1</docno>
    <approved>Kenneth Lundin</approved>
    <checked></checked>
    <date>03-01-21</date>
    <rev>A</rev>
    <file>erl_tar.sgml</file>
  </header>
  <module>erl_tar</module>
  <modulesummary>Unix 'tar' utility for reading and writing tar archives</modulesummary>
  <description>
    <p>The <c>erl_tar</c> module archives and extract files to and from
      a tar file. <c>erl_tar</c> supports the <c>ustar</c> format
      (IEEE Std 1003.1 and ISO/IEC&nbsp;9945-1). All modern <c>tar</c>
      programs (including GNU tar) can read this format. To ensure that
      that GNU tar produces a tar file that <c>erl_tar</c> can read,
      give the <c>--format=ustar</c> option to GNU tar.</p>
    <p>By convention, the name of a tar file should end in "<c>.tar</c>".
      To abide to the convention, you'll need to add "<c>.tar</c>" yourself
      to the name.</p>
    <p>Tar files can be created in one operation using the
      <seealso marker="#create_2">create/2</seealso> or
      <seealso marker="#create_3">create/3</seealso> function.</p>
    <p>Alternatively, for more control, the
      <seealso marker="#open">open</seealso>,
      <seealso marker="#add">add/3,4</seealso>, and 
      <seealso marker="#close">close/1</seealso> functions can be used.</p>
    <p>To extract all files from a tar file, use the 
      <seealso marker="#extract_1">extract/1</seealso> function.
      To extract only some files or to be able to specify some more options,
      use the <seealso marker="#extract_2">extract/2</seealso> function.</p>
    <p>To return a list of the files in a tar file,
      use either the <seealso marker="#table_1">table/1</seealso> or
      <seealso marker="#table_2">table/2</seealso> function.
      To print a list of files to the Erlang shell,
      use either the <seealso marker="#t_1">t/1</seealso> or
      <seealso marker="#tt_1">tt/1</seealso> function.</p>
    <p>To convert an error term returned from one of the functions
      above to a readable message, use the
      <seealso marker="#format_error_1">format_error/1</seealso> function.</p>
  </description>

  <section>
    <title>UNICODE SUPPORT</title>
    <p>If <seealso
    marker="kernel:file#native_name_encoding/0">file:native_name_encoding/0</seealso>
    returns <c>utf8</c>, path names will be encoded in UTF-8 when
    creating tar files and path names will be assumed to be encoded in
    UTF-8 when extracting tar files.</p>

    <p>If <seealso
    marker="kernel:file#native_name_encoding/0">file:native_name_encoding/0</seealso>
    returns <c>latin1</c>, no translation of path names will be
    done.</p>
  </section>

  <section>
    <title>LIMITATIONS</title>
    <p>For maximum compatibility, it is safe to archive files with names
      up to 100 characters in length. Such tar files can generally be
      extracted by any <c>tar</c> program.</p>
    <p>If filenames exceed 100 characters in length, the resulting tar
      file can only be correctly extracted by a POSIX-compatible <c>tar</c>
      program (such as Solaris <c>tar</c>), not by GNU tar.</p>
    <p>File have longer names than 256 bytes cannot be stored at all.</p>
    <p>The filename of the file a symbolic link points is always limited
      to 100 characters.</p>
  </section>
  <funcs>
    <func>
      <name>add(TarDescriptor, Filename, Options) -> RetValue</name>
      <fsummary>Add a file to an open tar file</fsummary>
      <type>
        <v>TarDescriptor = term()</v>
        <v>Filename = filename()</v>
        <v>Options = [Option]</v>
        <v>Option = dereference|verbose</v>
        <v>RetValue = ok|{error,{Filename,Reason}}</v>
        <v>Reason = term()</v>
      </type>
      <desc>
        <p>The <marker id="add"></marker><c>add/3</c> function adds
           a file to a tar file that has been opened for writing by
          <seealso marker="#open">open/1</seealso>.</p>
        <taglist>
          <tag><c>dereference</c></tag>
          <item>
            <p>By default, symbolic links will be stored as symbolic links
              in the tar file. Use the <c>dereference</c> option to override the
              default and store the file that the symbolic link points to into
              the tar file.</p>
          </item>
          <tag><c>verbose</c></tag>
          <item>
            <p>Print an informational message about the file being added.</p>
          </item>
        </taglist>
      </desc>
    </func>
    <func>
      <name>add(TarDescriptor, FilenameOrBin, NameInArchive, Options) -> RetValue </name>
      <fsummary>Add a file to an open tar file</fsummary>
      <type>
        <v>TarDescriptor = term()</v>
        <v>FilenameOrBin = Filename()|binary()</v>
        <v>Filename = filename()()</v>
        <v>NameInArchive = filename()</v>
        <v>Options = [Option]</v>
        <v>Option = dereference|verbose</v>
        <v>RetValue = ok|{error,{Filename,Reason}}</v>
        <v>Reason = term()</v>
      </type>
      <desc>
        <p>The <c>add/4</c> function adds a file to a tar file
          that has been opened for writing by
          <seealso marker="#open">open/1</seealso>. It accepts the same
          options as <seealso marker="#add">add/3</seealso>.</p>
        <p><c>NameInArchive</c> is the name under which the file will
          be stored in the tar file. That is the name that the file will
          get when it will be extracted from the tar file.</p>
      </desc>
    </func>
    <func>
      <name>close(TarDescriptor)</name>
      <fsummary>Close an open tar file</fsummary>
      <type>
        <v>TarDescriptor = term()</v>
      </type>
      <desc>
        <p>The <marker id="close"></marker><c>close/1</c> function
          closes a tar file
          opened by <seealso marker="#open">open/1</seealso>.</p>
      </desc>
    </func>
    <func>
      <name>create(Name, FileList) ->RetValue </name>
      <fsummary>Create a tar archive</fsummary>
      <type>
        <v>Name = filename()</v>
        <v>FileList = [Filename|{NameInArchive, binary()},{NameInArchive, Filename}]</v>
        <v>Filename = filename()</v>
        <v>NameInArchive = filename()</v>
        <v>RetValue = ok|{error,{Name,Reason}}</v>
        <v>Reason = term()</v>
      </type>
      <desc>
        <p>The <marker id="create_2"></marker><c>create/2</c> function
          creates a tar file and
          archives the files whose names are given in <c>FileList</c> into it.
          The files may either be read from disk or given as
          binaries.</p>
      </desc>
    </func>
    <func>
      <name>create(Name, FileList, OptionList)</name>
      <fsummary>Create a tar archive with options</fsummary>
      <type>
        <v>Name = filename()</v>
	<v>FileList = [Filename|{NameInArchive, binary()},{NameInArchive, Filename}]</v>
	<v>Filename = filename()</v>
        <v>NameInArchive = filename()</v>
        <v>OptionList = [Option]</v>
        <v>Option = compressed|cooked|dereference|verbose</v>
        <v>RetValue = ok|{error,{Name,Reason}}</v>
        <v>Reason = term()</v>
      </type>
      <desc>
        <p>The <marker id="create_3"></marker><c>create/3</c> function
          creates a tar file and archives the files whose names are given
          in <c>FileList</c> into it. The files may either be read from
          disk or given as binaries.</p>
        <p>The options in <c>OptionList</c> modify the defaults as follows.
          </p>
        <taglist>
          <tag><c>compressed</c></tag>
          <item>
            <p>The entire tar file will be compressed, as if it has
              been run through the <c>gzip</c> program. To abide to the
              convention that a compressed tar file should end in "<c>.tar.gz</c>" or
              "<c>.tgz</c>", you'll need to add the appropriate extension yourself.</p>
          </item>
          <tag><c>cooked</c></tag>
          <item>
            <p>By default, the <c>open/2</c> function will open the tar file
              in <c>raw</c> mode, which is faster but does not allow a remote (erlang)
              file server to be used. Adding <c>cooked</c> to the mode list will 
              override the default and open the tar file without the <c>raw</c>
              option.</p>
          </item>
          <tag><c>dereference</c></tag>
          <item>
            <p>By default, symbolic links will be stored as symbolic links
              in the tar file. Use the <c>dereference</c> option to override the
              default and store the file that the symbolic link points to into
              the tar file.</p>
          </item>
          <tag><c>verbose</c></tag>
          <item>
            <p>Print an informational message about each file being added.</p>
          </item>
        </taglist>
      </desc>
    </func>
    <func>
      <name>extract(Name) -> RetValue</name>
      <fsummary>Extract all files from a tar file</fsummary>
      <type>
        <v>Name = filename()</v>
        <v>RetValue = ok|{error,{Name,Reason}}</v>
        <v>Reason = term()</v>
      </type>
      <desc>
        <p>The <marker id="extract_1"></marker><c>extract/1</c> function
          extracts all files from a tar archive.</p>
        <p>If the <c>Name</c> argument is given as "<c>{binary,Binary}</c>",
          the contents of the binary is assumed to be a tar archive.
          </p>
        <p>If the <c>Name</c> argument is given as "<c>{file,Fd}</c>",
          <c>Fd</c> is assumed to be a file descriptor returned from
          the <c>file:open/2</c> function.
          </p>
        <p>Otherwise, <c>Name</c> should be a filename.</p>
      </desc>
    </func>
    <func>
      <name>extract(Name, OptionList)</name>
      <fsummary>Extract files from a tar file</fsummary>
      <type>
        <v>Name = filename() | {binary,Binary} | {file,Fd}  </v>
        <v>Binary = binary()</v>
        <v>Fd = file_descriptor()</v>
        <v>OptionList = [Option]</v>
        <v>Option = {cwd,Cwd}|{files,FileList}|keep_old_files|verbose|memory</v>
        <v>Cwd = [dirname()]</v>
        <v>FileList = [filename()]</v>
        <v>RetValue = ok|MemoryRetValue|{error,{Name,Reason}}</v>
        <v>MemoryRetValue = {ok, [{NameInArchive,binary()}]}</v>
        <v>NameInArchive = filename()</v>
        <v>Reason = term()</v>
      </type>
      <desc>
        <p>The <marker id="extract_2"></marker><c>extract/2</c> function
          extracts files from a tar archive.</p>
        <p>If the <c>Name</c> argument is given as "<c>{binary,Binary}</c>",
          the contents of the binary is assumed to be a tar archive.
          </p>
        <p>If the <c>Name</c> argument is given as "<c>{file,Fd}</c>",
          <c>Fd</c> is assumed to be a file descriptor returned from
          the <c>file:open/2</c> function.
          </p>
        <p>Otherwise, <c>Name</c> should be a filename.
          </p>
        <p>The following options modify the defaults for the extraction as
          follows.</p>
        <taglist>
          <tag><c>{cwd,Cwd}</c></tag>
          <item>
            <p>Files with relative filenames will by default be extracted
              to the current working directory.
              Given the <c>{cwd,Cwd}</c> option, the <c>extract/2</c> function
              will extract into the directory <c>Cwd</c> instead of to the current
              working directory.</p>
          </item>
          <tag><c>{files,FileList}</c></tag>
          <item>
            <p>By default, all files will be extracted from the tar file.
              Given the <c>{files,Files}</c> option, the <c>extract/2</c> function
              will only extract the files whose names are included in <c>FileList</c>.</p>
          </item>
          <tag><c>compressed</c></tag>
          <item>
            <p>Given the <c>compressed</c> option, the <c>extract/2</c>
              function will uncompress the file while extracting
              If the tar file is not actually compressed, the <c>compressed</c>
              will effectively be ignored.</p>
          </item>
          <tag><c>cooked</c></tag>
          <item>
            <p>By default, the <c>open/2</c> function will open the tar file
              in <c>raw</c> mode, which is faster but does not allow a remote (erlang)
              file server to be used. Adding <c>cooked</c> to the mode list will 
              override the default and open the tar file without the <c>raw</c>
              option.</p>
          </item>
          <tag><c>memory</c></tag>
          <item>
            <p>Instead of extracting to a directory, the memory option will
	      give the result  as  a  list  of  tuples  {Filename, Binary}, where
	      Binary is a binary containing the extracted data of the file named
	      Filename in the tar file.</p>
          </item>
          <tag><c>keep_old_files</c></tag>
          <item>
            <p>By default, all existing files with the same name as file in
              the tar file will be overwritten
              Given the <c>keep_old_files</c> option, the <c>extract/2</c> function
              will not overwrite any existing files.</p>
          </item>
          <tag><c>verbose</c></tag>
          <item>
            <p>Print an informational message as each file is being extracted.</p>
          </item>
        </taglist>
      </desc>
    </func>
    <func>
      <name>format_error(Reason) -> string()</name>
      <fsummary>Convert error term to a readable string</fsummary>
      <type>
        <v>Reason = term()</v>
      </type>
      <desc>
        <p>The <marker id="format_error_1"></marker><c>format_error/1</c>
          function converts
          an error reason term to a human-readable error message string.</p>
      </desc>
    </func>
    <func>
      <name>open(Name, OpenModeList) -> RetValue</name>
      <fsummary>Open a tar file for writing.</fsummary>
      <type>
        <v>Name = filename()</v>
        <v>OpenModeList = [OpenMode]</v>
        <v>Mode = write|compressed|cooked</v>
        <v>RetValue = {ok,TarDescriptor}|{error,{Name,Reason}}</v>
	<v>TarDescriptor = term()</v>
        <v>Reason = term()</v>
      </type>
      <desc>
        <p>The <marker id="open"></marker><c>open/2</c> function creates
         a tar file for writing.
        (Any existing file with the same name will be truncated.)</p>
        <p>By convention, the name of a tar file should end in "<c>.tar</c>".
          To abide to the convention, you'll need to add "<c>.tar</c>" yourself
          to the name.</p>
        <p>Except for the <c>write</c> atom the following atoms
	may be added to <c>OpenModeList</c>:</p>
        <taglist>
          <tag><c>compressed</c></tag>
          <item>
            <p>The entire tar file will be compressed, as if it has
              been run through the <c>gzip</c> program. To abide to the
              convention that a compressed tar file should end in "<c>.tar.gz</c>" or
              "<c>.tgz</c>", you'll need to add the appropriate extension yourself.</p>
          </item>
          <tag><c>cooked</c></tag>
          <item>
            <p>By default, the <c>open/2</c> function will open the tar file
              in <c>raw</c> mode, which is faster but does not allow a remote (erlang)
              file server to be used. Adding <c>cooked</c> to the mode list will 
              override the default and open the tar file without the <c>raw</c>
              option.</p>
          </item>
        </taglist>
        <p>Use the <seealso marker="#add">add/3,4</seealso> functions
          to add one file at the time into an opened tar file. When you are
          finished adding files, use the <seealso marker="#close">close</seealso>
          function to close the tar file.</p>
        <warning>
          <p>The <c>TarDescriptor</c> term is not a file descriptor.
            You should not rely on the specific contents of the <c>TarDescriptor</c>
            term, as it may change in future versions as more features are added
            to the <c>erl_tar</c> module.</p>
        </warning>
      </desc>
    </func>
    <func>
      <name>table(Name) -> RetValue</name>
      <fsummary>Retrieve the name of all files in a tar file</fsummary>
      <type>
        <v>Name = filename()</v>
        <v>RetValue = {ok,[string()]}|{error,{Name,Reason}}</v>
        <v>Reason = term()</v>
      </type>
      <desc>
        <p>The <marker id="table_1"></marker><c>table/1</c> function
          retrieves the names of all files in the tar file <c>Name</c>.</p>
      </desc>
    </func>
    <func>
      <name>table(Name, Options)</name>
      <fsummary>Retrieve name and information of all files in a tar file</fsummary>
      <type>
        <v>Name = filename()</v>
      </type>
      <desc>
        <p>The <marker id="table_2"></marker><c>table/2</c> function
          retrieves the names of all files in the tar file <c>Name</c>.</p>
      </desc>
    </func>
    <func>
      <name>t(Name)</name>
      <fsummary>Print the name of each file in a tar file</fsummary>
      <type>
        <v>Name = filename()</v>
      </type>
      <desc>
        <p>The <marker id="t_1"></marker><c>t/1</c> function prints the names
          of all files in the tar file <c>Name</c> to the Erlang shell.
          (Similar to "<c>tar&nbsp;t</c>".)</p>
      </desc>
    </func>
    <func>
      <name>tt(Name)</name>
      <fsummary>Print name and information for each file in a tar file</fsummary>
      <type>
        <v>Name = filename()</v>
      </type>
      <desc>
        <p>The <marker id="tt_1"></marker><c>tt/1</c> function prints
          names and
          information about all files in the tar file <c>Name</c> to
          the Erlang shell. (Similar to "<c>tar&nbsp;tv</c>".)</p>
      </desc>
    </func>
  </funcs>
</erlref>