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-chunk.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-colorsys.html" />
13<link rel="prev" href="module-wave.html" />
14<link rel="parent" href="mmedia.html" />
15<link rel="next" href="module-colorsys.html" />
16<meta name='aesop' content='information' />
17<title>14.6 chunk -- Read IFF chunked data</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="14.5.2 Wave_write Objects"
25 href="Wave-write-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="14. Multimedia Services"
28 href="mmedia.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="14.7 colorsys "
31 href="module-colorsys.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="Wave-write-objects.html">14.5.2 Wave_write Objects</A>
46<b class="navlabel">Up:</b>
47<a class="sectref" rel="parent" href="mmedia.html">14. Multimedia Services</A>
48<b class="navlabel">Next:</b>
49<a class="sectref" rel="next" href="module-colorsys.html">14.7 colorsys </A>
50</div>
51<hr /></div>
52</DIV>
53<!--End of Navigation Panel-->
54
55<H1><A NAME="SECTION0016600000000000000000">
5614.6 <tt class="module">chunk</tt> --
57 Read IFF chunked data</A>
58</H1>
59
60<P>
61<A NAME="module-chunk"></A>
62
63<P>
64This module provides an interface for reading files that use EA IFF 85
65chunks.<A NAME="tex2html164"
66 HREF="#foot67687"><SUP>14.1</SUP></A> This format is used
67in at least the Audio<a id='l2h-4745' xml:id='l2h-4745'></a> Interchange File Format
68(AIFF/AIFF-C) and the Real<a id='l2h-4746' xml:id='l2h-4746'></a> Media File
69Format<a id='l2h-4747' xml:id='l2h-4747'></a> (RMFF). The WAVE audio file format is closely
70related and can also be read using this module.
71
72<P>
73A chunk has the following structure:
74
75<P>
76<div class="center"><table class="realtable">
77 <thead>
78 <tr>
79 <th class="center">Offset</th>
80 <th class="center">Length</th>
81 <th class="left" >Contents</th>
82 </tr>
83 </thead>
84 <tbody>
85 <tr><td class="center" valign="baseline">0</td>
86 <td class="center">4</td>
87 <td class="left" >Chunk ID</td></tr>
88 <tr><td class="center" valign="baseline">4</td>
89 <td class="center">4</td>
90 <td class="left" >Size of chunk in big-endian byte order, not including the
91 header</td></tr>
92 <tr><td class="center" valign="baseline">8</td>
93 <td class="center"><var>n</var></td>
94 <td class="left" >Data bytes, where <var>n</var> is the size given in
95 the preceding field</td></tr>
96 <tr><td class="center" valign="baseline">8 + <var>n</var></td>
97 <td class="center">0 or 1</td>
98 <td class="left" >Pad byte needed if <var>n</var> is odd and
99 chunk alignment is used</td></tr></tbody>
100</table></div>
101
102<P>
103The ID is a 4-byte string which identifies the type of chunk.
104
105<P>
106The size field (a 32-bit value, encoded using big-endian byte order)
107gives the size of the chunk data, not including the 8-byte header.
108
109<P>
110Usually an IFF-type file consists of one or more chunks. The proposed
111usage of the <tt class="class">Chunk</tt> class defined here is to instantiate an
112instance at the start of each chunk and read from the instance until
113it reaches the end, after which a new instance can be instantiated.
114At the end of the file, creating a new instance will fail with a
115<tt class="exception">EOFError</tt> exception.
116
117<P>
118<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
119 <td><nobr><b><span class="typelabel">class</span>&nbsp;<tt id='l2h-4736' xml:id='l2h-4736' class="class">Chunk</tt></b>(</nobr></td>
120 <td><var>file</var><big>[</big><var>, align, bigendian, inclheader</var><big>]</big><var></var>)</td></tr></table></dt>
121<dd>
122Class which represents a chunk. The <var>file</var> argument is expected
123to be a file-like object. An instance of this class is specifically
124allowed. The only method that is needed is <tt class="method">read()</tt>. If the
125methods <tt class="method">seek()</tt> and <tt class="method">tell()</tt> are present and don't
126raise an exception, they are also used. If these methods are present
127and raise an exception, they are expected to not have altered the
128object. If the optional argument <var>align</var> is true, chunks are
129assumed to be aligned on 2-byte boundaries. If <var>align</var> is
130false, no alignment is assumed. The default value is true. If the
131optional argument <var>bigendian</var> is false, the chunk size is assumed
132to be in little-endian order. This is needed for WAVE audio files.
133The default value is true. If the optional argument <var>inclheader</var>
134is true, the size given in the chunk header includes the size of the
135header. The default value is false.
136</dl>
137
138<P>
139A <tt class="class">Chunk</tt> object supports the following methods:
140
141<P>
142<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
143 <td><nobr><b><tt id='l2h-4737' xml:id='l2h-4737' class="method">getname</tt></b>(</nobr></td>
144 <td><var></var>)</td></tr></table></dt>
145<dd>
146Returns the name (ID) of the chunk. This is the first 4 bytes of the
147chunk.
148</dl>
149
150<P>
151<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
152 <td><nobr><b><tt id='l2h-4738' xml:id='l2h-4738' class="method">getsize</tt></b>(</nobr></td>
153 <td><var></var>)</td></tr></table></dt>
154<dd>
155Returns the size of the chunk.
156</dl>
157
158<P>
159<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
160 <td><nobr><b><tt id='l2h-4739' xml:id='l2h-4739' class="method">close</tt></b>(</nobr></td>
161 <td><var></var>)</td></tr></table></dt>
162<dd>
163Close and skip to the end of the chunk. This does not close the
164underlying file.
165</dl>
166
167<P>
168The remaining methods will raise <tt class="exception">IOError</tt> if called after
169the <tt class="method">close()</tt> method has been called.
170
171<P>
172<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
173 <td><nobr><b><tt id='l2h-4740' xml:id='l2h-4740' class="method">isatty</tt></b>(</nobr></td>
174 <td><var></var>)</td></tr></table></dt>
175<dd>
176Returns <code>False</code>.
177</dl>
178
179<P>
180<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
181 <td><nobr><b><tt id='l2h-4741' xml:id='l2h-4741' class="method">seek</tt></b>(</nobr></td>
182 <td><var>pos</var><big>[</big><var>, whence</var><big>]</big><var></var>)</td></tr></table></dt>
183<dd>
184Set the chunk's current position. The <var>whence</var> argument is
185optional and defaults to <code>0</code> (absolute file positioning); other
186values are <code>1</code> (seek relative to the current position) and
187<code>2</code> (seek relative to the file's end). There is no return value.
188If the underlying file does not allow seek, only forward seeks are
189allowed.
190</dl>
191
192<P>
193<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
194 <td><nobr><b><tt id='l2h-4742' xml:id='l2h-4742' class="method">tell</tt></b>(</nobr></td>
195 <td><var></var>)</td></tr></table></dt>
196<dd>
197Return the current position into the chunk.
198</dl>
199
200<P>
201<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
202 <td><nobr><b><tt id='l2h-4743' xml:id='l2h-4743' class="method">read</tt></b>(</nobr></td>
203 <td><var></var><big>[</big><var>size</var><big>]</big><var></var>)</td></tr></table></dt>
204<dd>
205Read at most <var>size</var> bytes from the chunk (less if the read hits
206the end of the chunk before obtaining <var>size</var> bytes). If the
207<var>size</var> argument is negative or omitted, read all data until the
208end of the chunk. The bytes are returned as a string object. An
209empty string is returned when the end of the chunk is encountered
210immediately.
211</dl>
212
213<P>
214<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
215 <td><nobr><b><tt id='l2h-4744' xml:id='l2h-4744' class="method">skip</tt></b>(</nobr></td>
216 <td><var></var>)</td></tr></table></dt>
217<dd>
218Skip to the end of the chunk. All further calls to <tt class="method">read()</tt>
219for the chunk will return <code>''</code>. If you are not interested in the
220contents of the chunk, this method should be called so that the file
221points to the start of the next chunk.
222</dl>
223<BR><HR><H4>Footnotes</H4>
224<DL>
225<DT><A NAME="foot67687">...
226chunks.</A><A
227 href="module-chunk.html#tex2html164"><SUP>14.1</SUP></A></DT>
228<DD>``EA IFF 85'' Standard for Interchange Format Files,
229Jerry Morrison, Electronic Arts, January 1985.
230
231</DD>
232</DL>
233<DIV CLASS="navigation">
234<div class='online-navigation'>
235<p></p><hr />
236<table align="center" width="100%" cellpadding="0" cellspacing="2">
237<tr>
238<td class='online-navigation'><a rel="prev" title="14.5.2 Wave_write Objects"
239 href="Wave-write-objects.html"><img src='../icons/previous.png'
240 border='0' height='32' alt='Previous Page' width='32' /></A></td>
241<td class='online-navigation'><a rel="parent" title="14. Multimedia Services"
242 href="mmedia.html"><img src='../icons/up.png'
243 border='0' height='32' alt='Up One Level' width='32' /></A></td>
244<td class='online-navigation'><a rel="next" title="14.7 colorsys "
245 href="module-colorsys.html"><img src='../icons/next.png'
246 border='0' height='32' alt='Next Page' width='32' /></A></td>
247<td align="center" width="100%">Python Library Reference</td>
248<td class='online-navigation'><a rel="contents" title="Table of Contents"
249 href="contents.html"><img src='../icons/contents.png'
250 border='0' height='32' alt='Contents' width='32' /></A></td>
251<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
252 border='0' height='32' alt='Module Index' width='32' /></a></td>
253<td class='online-navigation'><a rel="index" title="Index"
254 href="genindex.html"><img src='../icons/index.png'
255 border='0' height='32' alt='Index' width='32' /></A></td>
256</tr></table>
257<div class='online-navigation'>
258<b class="navlabel">Previous:</b>
259<a class="sectref" rel="prev" href="Wave-write-objects.html">14.5.2 Wave_write Objects</A>
260<b class="navlabel">Up:</b>
261<a class="sectref" rel="parent" href="mmedia.html">14. Multimedia Services</A>
262<b class="navlabel">Next:</b>
263<a class="sectref" rel="next" href="module-colorsys.html">14.7 colorsys </A>
264</div>
265</div>
266<hr />
267<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
268</DIV>
269<!--End of Navigation Panel-->
270<ADDRESS>
271See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
272</ADDRESS>
273</BODY>
274</HTML>