[OpenSPARC-T2-SAM] / sam-t2 / devtools / v9 / html / python / api / marshalling-utils.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="api.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index' />
<link rel="first" href="api.html" title='Python/C API Reference Manual' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="arg-parsing.html" />
<link rel="prev" href="importing.html" />
<link rel="parent" href="utilities.html" />
<link rel="next" href="arg-parsing.html" />
<meta name='aesop' content='information' />
<title>5.4 Data marshalling support </title>
</head>
<body>
<DIV CLASS="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="5.3 Importing Modules"
  href="importing.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="5. Utilities"
  href="utilities.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="5.5 Parsing arguments and"
  href="arg-parsing.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python/C API Reference Manual</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><img src='../icons/blank.png'
  border='0' height='32'  alt='' width='32' /></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="importing.html">5.3 Importing Modules</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="utilities.html">5. Utilities</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="arg-parsing.html">5.5 Parsing arguments and</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H1><A NAME="SECTION007400000000000000000"></A><A NAME="marshalling-utils"></A>
<BR>
5.4 Data marshalling support 
</H1>

<P>
These routines allow C code to work with serialized objects using the
same data format as the <tt class="module">marshal</tt> module.  There are functions
to write data into the serialization format, and additional functions
that can be used to read the data back.  Files used to store marshalled
data must be opened in binary mode.

<P>
Numeric values are stored with the least significant byte first.

<P>
The module supports two versions of the data format: version 0 is the
historical version, version 1 (new in Python 2.4) shares interned
strings in the file, and upon unmarshalling. <var>Py_MARSHAL_VERSION</var>
indicates the current file format (currently 1).

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>void&nbsp;<b><tt id='l2h-200' xml:id='l2h-200' class="cfunction">PyMarshal_WriteLongToFile</tt></b>(</nobr></td><td>long <var>value</var>, FILE *<var>file</var>, int <var>version</var>)</td></tr></table></dt>
<dd>
  Marshal a <tt class="ctype">long</tt> integer, <var>value</var>, to <var>file</var>.  This
  will only write the least-significant 32 bits of <var>value</var>;
  regardless of the size of the native <tt class="ctype">long</tt> type.

<P>

<span class="versionnote">Changed in version 2.4:
<var>version</var> indicates the file format.</span>

</dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>void&nbsp;<b><tt id='l2h-201' xml:id='l2h-201' class="cfunction">PyMarshal_WriteObjectToFile</tt></b>(</nobr></td><td>PyObject *<var>value</var>,
                                                     FILE *<var>file</var>, int <var>version</var>)</td></tr></table></dt>
<dd>
  Marshal a Python object, <var>value</var>, to <var>file</var>.

<P>

<span class="versionnote">Changed in version 2.4:
<var>version</var> indicates the file format.</span>

</dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject*&nbsp;<b><tt id='l2h-202' xml:id='l2h-202' class="cfunction">PyMarshal_WriteObjectToString</tt></b>(</nobr></td><td>PyObject *<var>value</var>, int <var>version</var>)</td></tr></table></dt>
<dd>
<div class="refcount-info">
  <span class="label">Return value:</span>
  <span class="value">New reference.</span>
</div>
  Return a string object containing the marshalled representation of
  <var>value</var>.

<P>

<span class="versionnote">Changed in version 2.4:
<var>version</var> indicates the file format.</span>

</dd></dl>

<P>
The following functions allow marshalled values to be read back in.

<P>
XXX What about error detection?  It appears that reading past the end
of the file will always result in a negative numeric value (where
that's relevant), but it's not clear that negative values won't be
handled properly when there's no error.  What's the right way to tell?
Should only non-negative values be written using these routines?

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>long&nbsp;<b><tt id='l2h-203' xml:id='l2h-203' class="cfunction">PyMarshal_ReadLongFromFile</tt></b>(</nobr></td><td>FILE *<var>file</var>)</td></tr></table></dt>
<dd>
  Return a C <tt class="ctype">long</tt> from the data stream in a <tt class="ctype">FILE*</tt>
  opened for reading.  Only a 32-bit value can be read in using
  this function, regardless of the native size of <tt class="ctype">long</tt>.
</dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int&nbsp;<b><tt id='l2h-204' xml:id='l2h-204' class="cfunction">PyMarshal_ReadShortFromFile</tt></b>(</nobr></td><td>FILE *<var>file</var>)</td></tr></table></dt>
<dd>
  Return a C <tt class="ctype">short</tt> from the data stream in a <tt class="ctype">FILE*</tt>
  opened for reading.  Only a 16-bit value can be read in using
  this function, regardless of the native size of <tt class="ctype">short</tt>.
</dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject*&nbsp;<b><tt id='l2h-205' xml:id='l2h-205' class="cfunction">PyMarshal_ReadObjectFromFile</tt></b>(</nobr></td><td>FILE *<var>file</var>)</td></tr></table></dt>
<dd>
<div class="refcount-info">
  <span class="label">Return value:</span>
  <span class="value">New reference.</span>
</div>
  Return a Python object from the data stream in a <tt class="ctype">FILE*</tt>
  opened for reading.  On error, sets the appropriate exception
  (<tt class="exception">EOFError</tt> or <tt class="exception">TypeError</tt>) and returns <tt class="constant">NULL</tt>.
</dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject*&nbsp;<b><tt id='l2h-206' xml:id='l2h-206' class="cfunction">PyMarshal_ReadLastObjectFromFile</tt></b>(</nobr></td><td>FILE *<var>file</var>)</td></tr></table></dt>
<dd>
<div class="refcount-info">
  <span class="label">Return value:</span>
  <span class="value">New reference.</span>
</div>
  Return a Python object from the data stream in a <tt class="ctype">FILE*</tt>
  opened for reading.  Unlike
  <tt class="cfunction">PyMarshal_ReadObjectFromFile()</tt>, this function assumes
  that no further objects will be read from the file, allowing it to
  aggressively load file data into memory so that the de-serialization
  can operate from data in memory rather than reading a byte at a time
  from the file.  Only use these variant if you are certain that you
  won't be reading anything else from the file.  On error, sets the
  appropriate exception (<tt class="exception">EOFError</tt> or
  <tt class="exception">TypeError</tt>) and returns <tt class="constant">NULL</tt>.
</dd></dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject*&nbsp;<b><tt id='l2h-207' xml:id='l2h-207' class="cfunction">PyMarshal_ReadObjectFromString</tt></b>(</nobr></td><td>char *<var>string</var>,
                                                             int <var>len</var>)</td></tr></table></dt>
<dd>
<div class="refcount-info">
  <span class="label">Return value:</span>
  <span class="value">New reference.</span>
</div>
  Return a Python object from the data stream in a character buffer
  containing <var>len</var> bytes pointed to by <var>string</var>.  On error,
  sets the appropriate exception (<tt class="exception">EOFError</tt> or
  <tt class="exception">TypeError</tt>) and returns <tt class="constant">NULL</tt>.
</dd></dl>

<P>

<DIV CLASS="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="5.3 Importing Modules"
  href="importing.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="5. Utilities"
  href="utilities.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="5.5 Parsing arguments and"
  href="arg-parsing.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python/C API Reference Manual</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><img src='../icons/blank.png'
  border='0' height='32'  alt='' width='32' /></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="importing.html">5.3 Importing Modules</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="utilities.html">5. Utilities</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="arg-parsing.html">5.5 Parsing arguments and</A>
</div>
</div>
<hr />
<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
</DIV>
<!--End of Navigation Panel-->
<ADDRESS>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</ADDRESS>
</BODY>
</HTML>
Commit	Line	Data
920dae64 AT	1	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
	2	<html>
	3	<head>
	4	<link rel="STYLESHEET" href="api.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="api.html" title='Python/C API Reference Manual' />
	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="arg-parsing.html" />
	13	<link rel="prev" href="importing.html" />
	14	<link rel="parent" href="utilities.html" />
	15	<link rel="next" href="arg-parsing.html" />
	16	<meta name='aesop' content='information' />
	17	<title>5.4 Data marshalling support </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="5.3 Importing Modules"
	25	href="importing.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="5. Utilities"
	28	href="utilities.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="5.5 Parsing arguments and"
	31	href="arg-parsing.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/C API Reference Manual</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'><img src='../icons/blank.png'
	38	border='0' height='32' alt='' width='32' /></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="importing.html">5.3 Importing Modules</A>
	46	<b class="navlabel">Up:</b>
	47	<a class="sectref" rel="parent" href="utilities.html">5. Utilities</A>
	48	<b class="navlabel">Next:</b>
	49	<a class="sectref" rel="next" href="arg-parsing.html">5.5 Parsing arguments and</A>
	50	</div>
	51	<hr /></div>
	52	</DIV>
	53	<!--End of Navigation Panel-->
	54
	55	<H1><A NAME="SECTION007400000000000000000"></A><A NAME="marshalling-utils"></A>
	56	<BR>
	57	5.4 Data marshalling support
	58	</H1>
	59
	60	<P>
	61	These routines allow C code to work with serialized objects using the
	62	same data format as the <tt class="module">marshal</tt> module. There are functions
	63	to write data into the serialization format, and additional functions
	64	that can be used to read the data back. Files used to store marshalled
65	data must be opened in binary mode.
66
67	<P>
68	Numeric values are stored with the least significant byte first.
69
70	<P>
71	The module supports two versions of the data format: version 0 is the
72	historical version, version 1 (new in Python 2.4) shares interned
73	strings in the file, and upon unmarshalling. <var>Py_MARSHAL_VERSION</var>
74	indicates the current file format (currently 1).
75
76	<P>
77	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>void <b><tt id='l2h-200' xml:id='l2h-200' class="cfunction">PyMarshal_WriteLongToFile</tt></b>(</nobr></td><td>long <var>value</var>, FILE *<var>file</var>, int <var>version</var>)</td></tr></table></dt>
78	<dd>
79	Marshal a <tt class="ctype">long</tt> integer, <var>value</var>, to <var>file</var>. This
80	will only write the least-significant 32 bits of <var>value</var>;
81	regardless of the size of the native <tt class="ctype">long</tt> type.
82
83	<P>
84
85	<span class="versionnote">Changed in version 2.4:
86	<var>version</var> indicates the file format.</span>
87
88	</dd></dl>
89
90	<P>
91	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>void <b><tt id='l2h-201' xml:id='l2h-201' class="cfunction">PyMarshal_WriteObjectToFile</tt></b>(</nobr></td><td>PyObject *<var>value</var>,
92	FILE *<var>file</var>, int <var>version</var>)</td></tr></table></dt>
93	<dd>
94	Marshal a Python object, <var>value</var>, to <var>file</var>.
95
96	<P>
97
98	<span class="versionnote">Changed in version 2.4:
99	<var>version</var> indicates the file format.</span>
100
101	</dd></dl>
102
103	<P>
104	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-202' xml:id='l2h-202' class="cfunction">PyMarshal_WriteObjectToString</tt></b>(</nobr></td><td>PyObject *<var>value</var>, int <var>version</var>)</td></tr></table></dt>
105	<dd>
106	<div class="refcount-info">
107	<span class="label">Return value:</span>
108	<span class="value">New reference.</span>
109	</div>
110	Return a string object containing the marshalled representation of
111	<var>value</var>.
112
113	<P>
114
115	<span class="versionnote">Changed in version 2.4:
116	<var>version</var> indicates the file format.</span>
117
118	</dd></dl>
119
120	<P>
121	The following functions allow marshalled values to be read back in.
122
123	<P>
124	XXX What about error detection? It appears that reading past the end
125	of the file will always result in a negative numeric value (where
126	that's relevant), but it's not clear that negative values won't be
127	handled properly when there's no error. What's the right way to tell?
128	Should only non-negative values be written using these routines?
129
130	<P>
131	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>long <b><tt id='l2h-203' xml:id='l2h-203' class="cfunction">PyMarshal_ReadLongFromFile</tt></b>(</nobr></td><td>FILE *<var>file</var>)</td></tr></table></dt>
132	<dd>
133	Return a C <tt class="ctype">long</tt> from the data stream in a <tt class="ctype">FILE*</tt>
134	opened for reading. Only a 32-bit value can be read in using
135	this function, regardless of the native size of <tt class="ctype">long</tt>.
136	</dd></dl>
137
138	<P>
139	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-204' xml:id='l2h-204' class="cfunction">PyMarshal_ReadShortFromFile</tt></b>(</nobr></td><td>FILE *<var>file</var>)</td></tr></table></dt>
140	<dd>
141	Return a C <tt class="ctype">short</tt> from the data stream in a <tt class="ctype">FILE*</tt>
142	opened for reading. Only a 16-bit value can be read in using
143	this function, regardless of the native size of <tt class="ctype">short</tt>.
144	</dd></dl>
145
146	<P>
147	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-205' xml:id='l2h-205' class="cfunction">PyMarshal_ReadObjectFromFile</tt></b>(</nobr></td><td>FILE *<var>file</var>)</td></tr></table></dt>
148	<dd>
149	<div class="refcount-info">
150	<span class="label">Return value:</span>
151	<span class="value">New reference.</span>
152	</div>
153	Return a Python object from the data stream in a <tt class="ctype">FILE*</tt>
154	opened for reading. On error, sets the appropriate exception
155	(<tt class="exception">EOFError</tt> or <tt class="exception">TypeError</tt>) and returns <tt class="constant">NULL</tt>.
156	</dd></dl>
157
158	<P>
159	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-206' xml:id='l2h-206' class="cfunction">PyMarshal_ReadLastObjectFromFile</tt></b>(</nobr></td><td>FILE *<var>file</var>)</td></tr></table></dt>
160	<dd>
161	<div class="refcount-info">
162	<span class="label">Return value:</span>
163	<span class="value">New reference.</span>
164	</div>
165	Return a Python object from the data stream in a <tt class="ctype">FILE*</tt>
166	opened for reading. Unlike
167	<tt class="cfunction">PyMarshal_ReadObjectFromFile()</tt>, this function assumes
168	that no further objects will be read from the file, allowing it to
169	aggressively load file data into memory so that the de-serialization
170	can operate from data in memory rather than reading a byte at a time
171	from the file. Only use these variant if you are certain that you
172	won't be reading anything else from the file. On error, sets the
173	appropriate exception (<tt class="exception">EOFError</tt> or
174	<tt class="exception">TypeError</tt>) and returns <tt class="constant">NULL</tt>.
175	</dd></dl>
176
177	<P>
178	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-207' xml:id='l2h-207' class="cfunction">PyMarshal_ReadObjectFromString</tt></b>(</nobr></td><td>char *<var>string</var>,
179	int <var>len</var>)</td></tr></table></dt>
180	<dd>
181	<div class="refcount-info">
182	<span class="label">Return value:</span>
183	<span class="value">New reference.</span>
184	</div>
185	Return a Python object from the data stream in a character buffer
186	containing <var>len</var> bytes pointed to by <var>string</var>. On error,
187	sets the appropriate exception (<tt class="exception">EOFError</tt> or
188	<tt class="exception">TypeError</tt>) and returns <tt class="constant">NULL</tt>.
189	</dd></dl>
190
191	<P>
192
193	<DIV CLASS="navigation">
194	<div class='online-navigation'>
195	<p></p><hr />
196	<table align="center" width="100%" cellpadding="0" cellspacing="2">
197	<tr>
198	<td class='online-navigation'><a rel="prev" title="5.3 Importing Modules"
199	href="importing.html"><img src='../icons/previous.png'
200	border='0' height='32' alt='Previous Page' width='32' /></A></td>
201	<td class='online-navigation'><a rel="parent" title="5. Utilities"
202	href="utilities.html"><img src='../icons/up.png'
203	border='0' height='32' alt='Up One Level' width='32' /></A></td>
204	<td class='online-navigation'><a rel="next" title="5.5 Parsing arguments and"
205	href="arg-parsing.html"><img src='../icons/next.png'
206	border='0' height='32' alt='Next Page' width='32' /></A></td>
207	<td align="center" width="100%">Python/C API Reference Manual</td>
208	<td class='online-navigation'><a rel="contents" title="Table of Contents"
209	href="contents.html"><img src='../icons/contents.png'
210	border='0' height='32' alt='Contents' width='32' /></A></td>
211	<td class='online-navigation'><img src='../icons/blank.png'
212	border='0' height='32' alt='' width='32' /></td>
213	<td class='online-navigation'><a rel="index" title="Index"
214	href="genindex.html"><img src='../icons/index.png'
215	border='0' height='32' alt='Index' width='32' /></A></td>
216	</tr></table>
217	<div class='online-navigation'>
218	<b class="navlabel">Previous:</b>
219	<a class="sectref" rel="prev" href="importing.html">5.3 Importing Modules</A>
220	<b class="navlabel">Up:</b>
221	<a class="sectref" rel="parent" href="utilities.html">5. Utilities</A>
222	<b class="navlabel">Next:</b>
223	<a class="sectref" rel="next" href="arg-parsing.html">5.5 Parsing arguments and</A>
224	</div>
225	</div>
226	<hr />
227	<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
228	</DIV>
229	<!--End of Navigation Panel-->
230	<ADDRESS>
231	See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
232	</ADDRESS>
233	</BODY>
234	</HTML>