projects / OpenSPARC-T2-DV / blame
? search:
summary | tags | clone url | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
Initial commit of OpenSPARC T2 design and verification files.
[OpenSPARC-T2-DV] / tools / src / nas,5.n2.os.2 / lib / python / html / python / lib / module-tarfile.html
CommitLineData
86530b38
AT		 1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2<html>
3<head>
4<link rel="STYLESHEET" href="lib.css" type='text/css' />
5<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
6<link rel='start' href='../index.html' title='Python Documentation Index' />
7<link rel="first" href="lib.html" title='Python Library Reference' />
8<link rel='contents' href='contents.html' title="Contents" />
9<link rel='index' href='genindex.html' title='Index' />
10<link rel='last' href='about.html' title='About this document...' />
11<link rel='help' href='about.html' title='About this document...' />
12<link rel="next" href="module-readline.html" />
13<link rel="prev" href="module-zipfile.html" />
14<link rel="parent" href="someos.html" />
15<link rel="next" href="tarfile-objects.html" />
16<meta name='aesop' content='information' />
17<title>7.19 tarfile -- Read and write tar archive files</title>
18</head>
19<body>
20<DIV CLASS="navigation">
21<div id='top-navigation-panel' xml:id='top-navigation-panel'>
22<table align="center" width="100%" cellpadding="0" cellspacing="2">
23<tr>
24<td class='online-navigation'><a rel="prev" title="7.18.3 ZipInfo Objects"
25 href="zipinfo-objects.html"><img src='../icons/previous.png'
26 border='0' height='32' alt='Previous Page' width='32' /></A></td>
27<td class='online-navigation'><a rel="parent" title="7. Optional Operating System"
28 href="someos.html"><img src='../icons/up.png'
29 border='0' height='32' alt='Up One Level' width='32' /></A></td>
30<td class='online-navigation'><a rel="next" title="7.19.1 TarFile Objects"
31 href="tarfile-objects.html"><img src='../icons/next.png'
32 border='0' height='32' alt='Next Page' width='32' /></A></td>
33<td align="center" width="100%">Python Library Reference</td>
34<td class='online-navigation'><a rel="contents" title="Table of Contents"
35 href="contents.html"><img src='../icons/contents.png'
36 border='0' height='32' alt='Contents' width='32' /></A></td>
37<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
38 border='0' height='32' alt='Module Index' width='32' /></a></td>
39<td class='online-navigation'><a rel="index" title="Index"
40 href="genindex.html"><img src='../icons/index.png'
41 border='0' height='32' alt='Index' width='32' /></A></td>
42</tr></table>
43<div class='online-navigation'>
44<b class="navlabel">Previous:</b>
45<a class="sectref" rel="prev" href="zipinfo-objects.html">7.18.3 ZipInfo Objects</A>
46<b class="navlabel">Up:</b>
47<a class="sectref" rel="parent" href="someos.html">7. Optional Operating System</A>
48<b class="navlabel">Next:</b>
49<a class="sectref" rel="next" href="tarfile-objects.html">7.19.1 TarFile Objects</A>
50</div>
51<hr /></div>
52</DIV>
53<!--End of Navigation Panel-->
54
55<H1><A NAME="SECTION0091900000000000000000">
567.19 <tt class="module">tarfile</tt> -- Read and write tar archive files</A>
57</H1>
58
59<P>
60<A NAME="module-tarfile"></A>
61
62<span class="versionnote">New in version 2.3.</span>
63
64<P>
65
66<P>
67The <tt class="module">tarfile</tt> module makes it possible to read and create tar archives.
68Some facts and figures:
69
70<P>
71
72<UL>
73<LI>reads and writes <tt class="module">gzip</tt> and <tt class="module">bzip2</tt> compressed archives.
74</LI>
75<LI>creates POSIX 1003.1-1990 compliant or GNU tar compatible archives.
76</LI>
77<LI>reads GNU tar extensions <em>longname</em>, <em>longlink</em> and
78 <em>sparse</em>.
79</LI>
80<LI>stores pathnames of unlimited length using GNU tar extensions.
81</LI>
82<LI>handles directories, regular files, hardlinks, symbolic links, fifos,
83 character devices and block devices and is able to acquire and
84 restore file information like timestamp, access permissions and owner.
85</LI>
86<LI>can handle tape devices.
87</LI>
88</UL>
89
90<P>
91<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
92 <td><nobr><b><tt id='l2h-2889' xml:id='l2h-2889' class="function">open</tt></b>(</nobr></td>
93 <td><var></var><big>[</big><var>name</var><big>[</big><var>, mode
94 </var><big>[</big><var>, fileobj</var><big>[</big><var>, bufsize</var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
95<dd>
96 Return a <tt class="class">TarFile</tt> object for the pathname <var>name</var>.
97 For detailed information on <tt class="class">TarFile</tt> objects,
98 see <em class="citetitle"
99 >TarFile Objects</em> (section <A href="tarfile-objects.html#tarfile-objects">7.19.1</A>).
100
101<P>
102<var>mode</var> has to be a string of the form <code>'filemode[:compression]'</code>,
103 it defaults to <code>'r'</code>. Here is a full list of mode combinations:
104
105<P>
106<div class="center"><table class="realtable">
107 <thead>
108 <tr>
109 <th class="center">mode</th>
110 <th class="left" >action</th>
111 </tr>
112 </thead>
113 <tbody>
114 <tr><td class="center" valign="baseline"><code>'r'</code></td>
115 <td class="left" >Open for reading with transparent compression (recommended).</td></tr>
116 <tr><td class="center" valign="baseline"><code>'r:'</code></td>
117 <td class="left" >Open for reading exclusively without compression.</td></tr>
118 <tr><td class="center" valign="baseline"><code>'r:gz'</code></td>
119 <td class="left" >Open for reading with gzip compression.</td></tr>
120 <tr><td class="center" valign="baseline"><code>'r:bz2'</code></td>
121 <td class="left" >Open for reading with bzip2 compression.</td></tr>
122 <tr><td class="center" valign="baseline"><code>'a' or 'a:'</code></td>
123 <td class="left" >Open for appending with no compression.</td></tr>
124 <tr><td class="center" valign="baseline"><code>'w' or 'w:'</code></td>
125 <td class="left" >Open for uncompressed writing.</td></tr>
126 <tr><td class="center" valign="baseline"><code>'w:gz'</code></td>
127 <td class="left" >Open for gzip compressed writing.</td></tr>
128 <tr><td class="center" valign="baseline"><code>'w:bz2'</code></td>
129 <td class="left" >Open for bzip2 compressed writing.</td></tr></tbody>
130</table></div>
131
132<P>
133Note that <code>'a:gz'</code> or <code>'a:bz2'</code> is not possible.
134 If <var>mode</var> is not suitable to open a certain (compressed) file for
135 reading, <tt class="exception">ReadError</tt> is raised. Use <var>mode</var> <code>'r'</code> to
136 avoid this. If a compression method is not supported,
137 <tt class="exception">CompressionError</tt> is raised.
138
139<P>
140If <var>fileobj</var> is specified, it is used as an alternative to
141 a file object opened for <var>name</var>.
142
143<P>
144For special purposes, there is a second format for <var>mode</var>:
145 <code>'filemode|[compression]'</code>. <tt class="function">open()</tt> will return a
146 <tt class="class">TarFile</tt> object that processes its data as a stream of
147 blocks. No random seeking will be done on the file. If given,
148 <var>fileobj</var> may be any object that has a <tt class="method">read()</tt> or
149 <tt class="method">write()</tt> method (depending on the <var>mode</var>).
150 <var>bufsize</var> specifies the blocksize and defaults to <code>20 *
151 512</code> bytes. Use this variant in combination with
152 e.g. <code>sys.stdin</code>, a socket file object or a tape device.
153 However, such a <tt class="class">TarFile</tt> object is limited in that it does
154 not allow to be accessed randomly, see ``Examples''
155 (section&nbsp;<A href="tar-examples.html#tar-examples">7.19.3</A>). The currently possible modes:
156
157<P>
158<div class="center"><table class="realtable">
159 <thead>
160 <tr>
161 <th class="center">Mode</th>
162 <th class="left" >Action</th>
163 </tr>
164 </thead>
165 <tbody>
166 <tr><td class="center" valign="baseline"><code>'r|'</code></td>
167 <td class="left" >Open a <em>stream</em> of uncompressed tar blocks for reading.</td></tr>
168 <tr><td class="center" valign="baseline"><code>'r|gz'</code></td>
169 <td class="left" >Open a gzip compressed <em>stream</em> for reading.</td></tr>
170 <tr><td class="center" valign="baseline"><code>'r|bz2'</code></td>
171 <td class="left" >Open a bzip2 compressed <em>stream</em> for reading.</td></tr>
172 <tr><td class="center" valign="baseline"><code>'w|'</code></td>
173 <td class="left" >Open an uncompressed <em>stream</em> for writing.</td></tr>
174 <tr><td class="center" valign="baseline"><code>'w|gz'</code></td>
175 <td class="left" >Open an gzip compressed <em>stream</em> for writing.</td></tr>
176 <tr><td class="center" valign="baseline"><code>'w|bz2'</code></td>
177 <td class="left" >Open an bzip2 compressed <em>stream</em> for writing.</td></tr></tbody>
178</table></div>
179</dl>
180
181<P>
182<dl><dt><b><span class="typelabel">class</span>&nbsp;<tt id='l2h-2890' xml:id='l2h-2890' class="class">TarFile</tt></b>
183<dd>
184 Class for reading and writing tar archives. Do not use this
185 class directly, better use <tt class="function">open()</tt> instead.
186 See ``TarFile Objects'' (section&nbsp;<A href="tarfile-objects.html#tarfile-objects">7.19.1</A>).
187</dl>
188
189<P>
190<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
191 <td><nobr><b><tt id='l2h-2891' xml:id='l2h-2891' class="function">is_tarfile</tt></b>(</nobr></td>
192 <td><var>name</var>)</td></tr></table></dt>
193<dd>
194 Return <tt class="constant">True</tt> if <var>name</var> is a tar archive file, that
195 the <tt class="module">tarfile</tt> module can read.
196</dl>
197
198<P>
199<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
200 <td><nobr><b><span class="typelabel">class</span>&nbsp;<tt id='l2h-2892' xml:id='l2h-2892' class="class">TarFileCompat</tt></b>(</nobr></td>
201 <td><var>filename</var><big>[</big><var>, mode</var><big>[</big><var>,
202 compression</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
203<dd>
204 Class for limited access to tar archives with a
205 <tt class="module"><a href="module-zipfile.html">zipfile</a></tt>-like interface. Please consult the
206 documentation of the <tt class="module"><a href="module-zipfile.html">zipfile</a></tt> module for more details.
207 <var>compression</var> must be one of the following constants:
208 <dl><dt><b><tt id='l2h-2893' xml:id='l2h-2893'>TAR_PLAIN</tt></b></dt>
209<dd>
210 Constant for an uncompressed tar archive.
211 </dd></dl>
212 <dl><dt><b><tt id='l2h-2894' xml:id='l2h-2894'>TAR_GZIPPED</tt></b></dt>
213<dd>
214 Constant for a <tt class="module"><a href="module-gzip.html">gzip</a></tt> compressed tar archive.
215 </dd></dl>
216</dl>
217
218<P>
219<dl><dt><b><span class="typelabel">exception</span>&nbsp;<tt id='l2h-2895' xml:id='l2h-2895' class="exception">TarError</tt></b></dt>
220<dd>
221 Base class for all <tt class="module">tarfile</tt> exceptions.
222</dd></dl>
223
224<P>
225<dl><dt><b><span class="typelabel">exception</span>&nbsp;<tt id='l2h-2896' xml:id='l2h-2896' class="exception">ReadError</tt></b></dt>
226<dd>
227 Is raised when a tar archive is opened, that either cannot be handled by
228 the <tt class="module">tarfile</tt> module or is somehow invalid.
229</dd></dl>
230
231<P>
232<dl><dt><b><span class="typelabel">exception</span>&nbsp;<tt id='l2h-2897' xml:id='l2h-2897' class="exception">CompressionError</tt></b></dt>
233<dd>
234 Is raised when a compression method is not supported or when the data
235 cannot be decoded properly.
236</dd></dl>
237
238<P>
239<dl><dt><b><span class="typelabel">exception</span>&nbsp;<tt id='l2h-2898' xml:id='l2h-2898' class="exception">StreamError</tt></b></dt>
240<dd>
241 Is raised for the limitations that are typical for stream-like
242 <tt class="class">TarFile</tt> objects.
243</dd></dl>
244
245<P>
246<dl><dt><b><span class="typelabel">exception</span>&nbsp;<tt id='l2h-2899' xml:id='l2h-2899' class="exception">ExtractError</tt></b></dt>
247<dd>
248 Is raised for <em>non-fatal</em> errors when using <tt class="method">extract()</tt>, but
249 only if <tt class="member">TarFile.errorlevel</tt><code> == 2</code>.
250</dd></dl>
251
252<P>
253<div class="seealso">
254 <p class="heading">See Also:</p>
255
256 <dl compact="compact" class="seemodule">
257 <dt>Module <b><tt class="module"><a href="module-zipfile.html">zipfile</a></tt>:</b>
258 <dd>Documentation of the <tt class="module"><a href="module-zipfile.html">zipfile</a></tt>
259 standard module.
260 </dl>
261
262<P>
263<dl compact="compact" class="seetitle">
264 <dt><em class="citetitle"><a href="http://www.gnu.org/software/tar/manual/html_chapter/tar_8.html#SEC134"
265 >GNU tar manual, Basic Tar Format</a></em></dt>
266 <dd>Documentation for tar archive files,
267 including GNU tar extensions.</dd>
268 </dl>
269</div>
270
271<P>
272
273<p><br /></p><hr class='online-navigation' />
274<div class='online-navigation'>
275<!--Table of Child-Links-->
276<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a>
277
278<UL CLASS="ChildLinks">
279<LI><A href="tarfile-objects.html">7.19.1 TarFile Objects</a>
280<LI><A href="tarinfo-objects.html">7.19.2 TarInfo Objects</a>
281<LI><A href="tar-examples.html">7.19.3 Examples</a>
282</ul>
283<!--End of Table of Child-Links-->
284</div>
285
286<DIV CLASS="navigation">
287<div class='online-navigation'>
288<p></p><hr />
289<table align="center" width="100%" cellpadding="0" cellspacing="2">
290<tr>
291<td class='online-navigation'><a rel="prev" title="7.18.3 ZipInfo Objects"
292 href="zipinfo-objects.html"><img src='../icons/previous.png'
293 border='0' height='32' alt='Previous Page' width='32' /></A></td>
294<td class='online-navigation'><a rel="parent" title="7. Optional Operating System"
295 href="someos.html"><img src='../icons/up.png'
296 border='0' height='32' alt='Up One Level' width='32' /></A></td>
297<td class='online-navigation'><a rel="next" title="7.19.1 TarFile Objects"
298 href="tarfile-objects.html"><img src='../icons/next.png'
299 border='0' height='32' alt='Next Page' width='32' /></A></td>
300<td align="center" width="100%">Python Library Reference</td>
301<td class='online-navigation'><a rel="contents" title="Table of Contents"
302 href="contents.html"><img src='../icons/contents.png'
303 border='0' height='32' alt='Contents' width='32' /></A></td>
304<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
305 border='0' height='32' alt='Module Index' width='32' /></a></td>
306<td class='online-navigation'><a rel="index" title="Index"
307 href="genindex.html"><img src='../icons/index.png'
308 border='0' height='32' alt='Index' width='32' /></A></td>
309</tr></table>
310<div class='online-navigation'>
311<b class="navlabel">Previous:</b>
312<a class="sectref" rel="prev" href="zipinfo-objects.html">7.18.3 ZipInfo Objects</A>
313<b class="navlabel">Up:</b>
314<a class="sectref" rel="parent" href="someos.html">7. Optional Operating System</A>
315<b class="navlabel">Next:</b>
316<a class="sectref" rel="next" href="tarfile-objects.html">7.19.1 TarFile Objects</A>
317</div>
318</div>
319<hr />
320<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
321</DIV>
322<!--End of Navigation Panel-->
323<ADDRESS>
324See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
325</ADDRESS>
326</BODY>
327</HTML>
Full OpenSPARC design & verification tarball including full HDL.