projects / OpenSPARC-T2-SAM / blame
? search:
summary | tags | clone url | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
Initial commit of OpenSPARC T2 architecture model.
[OpenSPARC-T2-SAM] / sam-t2 / devtools / v9 / html / python / api / exceptionHandling.html
CommitLineData
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="utilities.html" />
13<link rel="prev" href="countingRefs.html" />
14<link rel="parent" href="api.html" />
15<link rel="next" href="standardExceptions.html" />
16<meta name='aesop' content='information' />
17<title>4. Exception Handling </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="3. Reference Counting"
25 href="countingRefs.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="Python/C API Reference Manual"
28 href="api.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="4.1 Standard Exceptions"
31 href="standardExceptions.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="countingRefs.html">3. Reference Counting</A>
46<b class="navlabel">Up:</b>
47<a class="sectref" rel="parent" href="api.html">Python/C API Reference Manual</A>
48<b class="navlabel">Next:</b>
49<a class="sectref" rel="next" href="standardExceptions.html">4.1 Standard Exceptions</A>
50</div>
51<hr /></div>
52</DIV>
53<!--End of Navigation Panel-->
54
55<H1><A NAME="SECTION006000000000000000000"></A><A NAME="exceptionHandling"></A>
56<BR>
574. Exception Handling
58</H1>
59
60<P>
61The functions described in this chapter will let you handle and raise Python
62exceptions. It is important to understand some of the basics of
63Python exception handling. It works somewhat like the
64<span class="Unix">Unix</span> <tt class="cdata">errno</tt> variable: there is a global indicator (per
65thread) of the last error that occurred. Most functions don't clear
66this on success, but will set it to indicate the cause of the error on
67failure. Most functions also return an error indicator, usually
68<tt class="constant">NULL</tt> if they are supposed to return a pointer, or <code>-1</code> if they
69return an integer (exception: the <tt class="cfunction">PyArg_*()</tt> functions
70return <code>1</code> for success and <code>0</code> for failure).
71
72<P>
73When a function must fail because some function it called failed, it
74generally doesn't set the error indicator; the function it called
75already set it. It is responsible for either handling the error and
76clearing the exception or returning after cleaning up any resources it
77holds (such as object references or memory allocations); it should
78<em>not</em> continue normally if it is not prepared to handle the
79error. If returning due to an error, it is important to indicate to
80the caller that an error has been set. If the error is not handled or
81carefully propagated, additional calls into the Python/C API may not
82behave as intended and may fail in mysterious ways.
83
84<P>
85The error indicator consists of three Python objects corresponding to
86<a id='l2h-90' xml:id='l2h-90'></a>the Python variables <code>sys.exc_type</code>, <code>sys.exc_value</code> and
87<code>sys.exc_traceback</code>. API functions exist to interact with the
88error indicator in various ways. There is a separate error indicator
89for each thread.
90
91<P>
92<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>void&nbsp;<b><tt id='l2h-91' xml:id='l2h-91' class="cfunction">PyErr_Print</tt></b>(</nobr></td><td>)</td></tr></table></dt>
93<dd>
94 Print a standard traceback to <code>sys.stderr</code> and clear the error
95 indicator. Call this function only when the error indicator is
96 set. (Otherwise it will cause a fatal error!)
97</dd></dl>
98
99<P>
100<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject*&nbsp;<b><tt id='l2h-92' xml:id='l2h-92' class="cfunction">PyErr_Occurred</tt></b>(</nobr></td><td>)</td></tr></table></dt>
101<dd>
102<div class="refcount-info">
103 <span class="label">Return value:</span>
104 <span class="value">Borrowed reference.</span>
105</div>
106 Test whether the error indicator is set. If set, return the
107 exception <em>type</em> (the first argument to the last call to one of
108 the <tt class="cfunction">PyErr_Set*()</tt> functions or to
109 <tt class="cfunction">PyErr_Restore()</tt>). If not set, return <tt class="constant">NULL</tt>. You do
110 not own a reference to the return value, so you do not need to
111 <tt class="cfunction">Py_DECREF()</tt> it. <span class="note"><b class="label">Note:</b>
112Do not compare the return value
113 to a specific exception; use <tt class="cfunction">PyErr_ExceptionMatches()</tt>
114 instead, shown below. (The comparison could easily fail since the
115 exception may be an instance instead of a class, in the case of a
116 class exception, or it may the a subclass of the expected
117 exception.)</span>
118</dd></dl>
119
120<P>
121<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int&nbsp;<b><tt id='l2h-93' xml:id='l2h-93' class="cfunction">PyErr_ExceptionMatches</tt></b>(</nobr></td><td>PyObject *<var>exc</var>)</td></tr></table></dt>
122<dd>
123 Equivalent to "<tt class="samp">PyErr_GivenExceptionMatches(PyErr_Occurred(),
124 <var>exc</var>)</tt>". This should only be called when an exception is
125 actually set; a memory access violation will occur if no exception
126 has been raised.
127</dd></dl>
128
129<P>
130<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int&nbsp;<b><tt id='l2h-94' xml:id='l2h-94' class="cfunction">PyErr_GivenExceptionMatches</tt></b>(</nobr></td><td>PyObject *<var>given</var>, PyObject *<var>exc</var>)</td></tr></table></dt>
131<dd>
132 Return true if the <var>given</var> exception matches the exception in
133 <var>exc</var>. If <var>exc</var> is a class object, this also returns true
134 when <var>given</var> is an instance of a subclass. If <var>exc</var> is a
135 tuple, all exceptions in the tuple (and recursively in subtuples)
136 are searched for a match. If <var>given</var> is <tt class="constant">NULL</tt>, a memory access
137 violation will occur.
138</dd></dl>
139
140<P>
141<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>void&nbsp;<b><tt id='l2h-95' xml:id='l2h-95' class="cfunction">PyErr_NormalizeException</tt></b>(</nobr></td><td>PyObject**<var>exc</var>, PyObject**<var>val</var>, PyObject**<var>tb</var>)</td></tr></table></dt>
142<dd>
143 Under certain circumstances, the values returned by
144 <tt class="cfunction">PyErr_Fetch()</tt> below can be ``unnormalized'', meaning
145 that <code>*<var>exc</var></code> is a class object but <code>*<var>val</var></code> is
146 not an instance of the same class. This function can be used to
147 instantiate the class in that case. If the values are already
148 normalized, nothing happens. The delayed normalization is
149 implemented to improve performance.
150</dd></dl>
151
152<P>
153<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>void&nbsp;<b><tt id='l2h-96' xml:id='l2h-96' class="cfunction">PyErr_Clear</tt></b>(</nobr></td><td>)</td></tr></table></dt>
154<dd>
155 Clear the error indicator. If the error indicator is not set, there
156 is no effect.
157</dd></dl>
158
159<P>
160<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>void&nbsp;<b><tt id='l2h-97' xml:id='l2h-97' class="cfunction">PyErr_Fetch</tt></b>(</nobr></td><td>PyObject **<var>ptype</var>, PyObject **<var>pvalue</var>,
161 PyObject **<var>ptraceback</var>)</td></tr></table></dt>
162<dd>
163 Retrieve the error indicator into three variables whose addresses
164 are passed. If the error indicator is not set, set all three
165 variables to <tt class="constant">NULL</tt>. If it is set, it will be cleared and you own a
166 reference to each object retrieved. The value and traceback object
167 may be <tt class="constant">NULL</tt> even when the type object is not. <span class="note"><b class="label">Note:</b>
168This
169 function is normally only used by code that needs to handle
170 exceptions or by code that needs to save and restore the error
171 indicator temporarily.</span>
172</dd></dl>
173
174<P>
175<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>void&nbsp;<b><tt id='l2h-98' xml:id='l2h-98' class="cfunction">PyErr_Restore</tt></b>(</nobr></td><td>PyObject *<var>type</var>, PyObject *<var>value</var>,
176 PyObject *<var>traceback</var>)</td></tr></table></dt>
177<dd>
178 Set the error indicator from the three objects. If the error
179 indicator is already set, it is cleared first. If the objects are
180 <tt class="constant">NULL</tt>, the error indicator is cleared. Do not pass a <tt class="constant">NULL</tt> type
181 and non-<tt class="constant">NULL</tt> value or traceback. The exception type should be a
182 class. Do not pass an invalid exception type or value.
183 (Violating these rules will cause subtle problems later.) This call
184 takes away a reference to each object: you must own a reference to
185 each object before the call and after the call you no longer own
186 these references. (If you don't understand this, don't use this
187 function. I warned you.) <span class="note"><b class="label">Note:</b>
188This function is normally only used
189 by code that needs to save and restore the error indicator
190 temporarily; use <tt class="cfunction">PyErr_Fetch()</tt> to save the current
191 exception state.</span>
192</dd></dl>
193
194<P>
195<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>void&nbsp;<b><tt id='l2h-99' xml:id='l2h-99' class="cfunction">PyErr_SetString</tt></b>(</nobr></td><td>PyObject *<var>type</var>, char *<var>message</var>)</td></tr></table></dt>
196<dd>
197 This is the most common way to set the error indicator. The first
198 argument specifies the exception type; it is normally one of the
199 standard exceptions, e.g. <tt class="cdata">PyExc_RuntimeError</tt>. You need not
200 increment its reference count. The second argument is an error
201 message; it is converted to a string object.
202</dd></dl>
203
204<P>
205<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>void&nbsp;<b><tt id='l2h-100' xml:id='l2h-100' class="cfunction">PyErr_SetObject</tt></b>(</nobr></td><td>PyObject *<var>type</var>, PyObject *<var>value</var>)</td></tr></table></dt>
206<dd>
207 This function is similar to <tt class="cfunction">PyErr_SetString()</tt> but lets
208 you specify an arbitrary Python object for the ``value'' of the
209 exception.
210</dd></dl>
211
212<P>
213<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject*&nbsp;<b><tt id='l2h-101' xml:id='l2h-101' class="cfunction">PyErr_Format</tt></b>(</nobr></td><td>PyObject *<var>exception</var>,
214 const char *<var>format</var>, ...)</td></tr></table></dt>
215<dd>
216<div class="refcount-info">
217 <span class="label">Return value:</span>
218 <span class="value">Always <tt class="constant">NULL</tt>.</span>
219</div>
220 This function sets the error indicator and returns <tt class="constant">NULL</tt>.
221 <var>exception</var> should be a Python exception (class, not
222 an instance). <var>format</var> should be a string, containing format
223 codes, similar to <tt class="cfunction">printf()</tt>. The <code>width.precision</code>
224 before a format code is parsed, but the width part is ignored.
225
226<P>
227<div class="center"><table class="realtable">
228 <thead>
229 <tr>
230 <th class="center">Character</th>
231 <th class="left" >Meaning</th>
232 </tr>
233 </thead>
234 <tbody>
235 <tr><td class="center" valign="baseline"><tt class="character">c</tt></td>
236 <td class="left" >Character, as an <tt class="ctype">int</tt> parameter</td></tr>
237 <tr><td class="center" valign="baseline"><tt class="character">d</tt></td>
238 <td class="left" >Number in decimal, as an <tt class="ctype">int</tt> parameter</td></tr>
239 <tr><td class="center" valign="baseline"><tt class="character">x</tt></td>
240 <td class="left" >Number in hexadecimal, as an <tt class="ctype">int</tt> parameter</td></tr>
241 <tr><td class="center" valign="baseline"><tt class="character">s</tt></td>
242 <td class="left" >A string, as a <tt class="ctype">char *</tt> parameter</td></tr>
243 <tr><td class="center" valign="baseline"><tt class="character">p</tt></td>
244 <td class="left" >A hex pointer, as a <tt class="ctype">void *</tt> parameter</td></tr></tbody>
245</table></div>
246
247<P>
248An unrecognized format character causes all the rest of the format
249 string to be copied as-is to the result string, and any extra
250 arguments discarded.
251</dd></dl>
252
253<P>
254<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>void&nbsp;<b><tt id='l2h-102' xml:id='l2h-102' class="cfunction">PyErr_SetNone</tt></b>(</nobr></td><td>PyObject *<var>type</var>)</td></tr></table></dt>
255<dd>
256 This is a shorthand for "<tt class="samp">PyErr_SetObject(<var>type</var>,
257 Py_None)</tt>".
258</dd></dl>
259
260<P>
261<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int&nbsp;<b><tt id='l2h-103' xml:id='l2h-103' class="cfunction">PyErr_BadArgument</tt></b>(</nobr></td><td>)</td></tr></table></dt>
262<dd>
263 This is a shorthand for "<tt class="samp">PyErr_SetString(PyExc_TypeError,
264 <var>message</var>)</tt>", where <var>message</var> indicates that a built-in
265 operation was invoked with an illegal argument. It is mostly for
266 internal use.
267</dd></dl>
268
269<P>
270<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject*&nbsp;<b><tt id='l2h-104' xml:id='l2h-104' class="cfunction">PyErr_NoMemory</tt></b>(</nobr></td><td>)</td></tr></table></dt>
271<dd>
272<div class="refcount-info">
273 <span class="label">Return value:</span>
274 <span class="value">Always <tt class="constant">NULL</tt>.</span>
275</div>
276 This is a shorthand for "<tt class="samp">PyErr_SetNone(PyExc_MemoryError)</tt>"; it
277 returns <tt class="constant">NULL</tt> so an object allocation function can write
278 "<tt class="samp">return PyErr_NoMemory();</tt>" when it runs out of memory.
279</dd></dl>
280
281<P>
282<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject*&nbsp;<b><tt id='l2h-105' xml:id='l2h-105' class="cfunction">PyErr_SetFromErrno</tt></b>(</nobr></td><td>PyObject *<var>type</var>)</td></tr></table></dt>
283<dd>
284<div class="refcount-info">
285 <span class="label">Return value:</span>
286 <span class="value">Always <tt class="constant">NULL</tt>.</span>
287</div>
288 This is a convenience function to raise an exception when a C
289 library function has returned an error and set the C variable
290 <tt class="cdata">errno</tt>. It constructs a tuple object whose first item is the
291 integer <tt class="cdata">errno</tt> value and whose second item is the
292 corresponding error message (gotten from
293 <tt class="cfunction">strerror()</tt><a id='l2h-122' xml:id='l2h-122'></a>), and then calls
294 "<tt class="samp">PyErr_SetObject(<var>type</var>, <var>object</var>)</tt>". On <span class="Unix">Unix</span>, when
295 the <tt class="cdata">errno</tt> value is <tt class="constant">EINTR</tt>, indicating an
296 interrupted system call, this calls
297 <tt class="cfunction">PyErr_CheckSignals()</tt>, and if that set the error
298 indicator, leaves it set to that. The function always returns
299 <tt class="constant">NULL</tt>, so a wrapper function around a system call can write
300 "<tt class="samp">return PyErr_SetFromErrno(<var>type</var>);</tt>" when the system call
301 returns an error.
302</dd></dl>
303
304<P>
305<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject*&nbsp;<b><tt id='l2h-106' xml:id='l2h-106' class="cfunction">PyErr_SetFromErrnoWithFilename</tt></b>(</nobr></td><td>PyObject *<var>type</var>,
306 char *<var>filename</var>)</td></tr></table></dt>
307<dd>
308<div class="refcount-info">
309 <span class="label">Return value:</span>
310 <span class="value">Always <tt class="constant">NULL</tt>.</span>
311</div>
312 Similar to <tt class="cfunction">PyErr_SetFromErrno()</tt>, with the additional
313 behavior that if <var>filename</var> is not <tt class="constant">NULL</tt>, it is passed to the
314 constructor of <var>type</var> as a third parameter. In the case of
315 exceptions such as <tt class="exception">IOError</tt> and <tt class="exception">OSError</tt>, this
316 is used to define the <tt class="member">filename</tt> attribute of the exception
317 instance.
318</dd></dl>
319
320<P>
321<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject*&nbsp;<b><tt id='l2h-107' xml:id='l2h-107' class="cfunction">PyErr_SetFromWindowsErr</tt></b>(</nobr></td><td>int <var>ierr</var>)</td></tr></table></dt>
322<dd>
323<div class="refcount-info">
324 <span class="label">Return value:</span>
325 <span class="value">Always <tt class="constant">NULL</tt>.</span>
326</div>
327 This is a convenience function to raise <tt class="exception">WindowsError</tt>.
328 If called with <var>ierr</var> of <tt class="cdata">0</tt>, the error code returned by a
329 call to <tt class="cfunction">GetLastError()</tt> is used instead. It calls the
330 Win32 function <tt class="cfunction">FormatMessage()</tt> to retrieve the Windows
331 description of error code given by <var>ierr</var> or
332 <tt class="cfunction">GetLastError()</tt>, then it constructs a tuple object whose
333 first item is the <var>ierr</var> value and whose second item is the
334 corresponding error message (gotten from
335 <tt class="cfunction">FormatMessage()</tt>), and then calls
336 "<tt class="samp">PyErr_SetObject(<var>PyExc_WindowsError</var>, <var>object</var>)</tt>".
337 This function always returns <tt class="constant">NULL</tt>.
338 Availability: Windows.
339</dd></dl>
340
341<P>
342<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject*&nbsp;<b><tt id='l2h-108' xml:id='l2h-108' class="cfunction">PyErr_SetExcFromWindowsErr</tt></b>(</nobr></td><td>PyObject *<var>type</var>,
343 int <var>ierr</var>)</td></tr></table></dt>
344<dd>
345 Similar to <tt class="cfunction">PyErr_SetFromWindowsErr()</tt>, with an additional
346 parameter specifying the exception type to be raised.
347 Availability: Windows.
348
349<span class="versionnote">New in version 2.3.</span>
350
351</dd></dl>
352
353<P>
354<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject*&nbsp;<b><tt id='l2h-109' xml:id='l2h-109' class="cfunction">PyErr_SetFromWindowsErrWithFilename</tt></b>(</nobr></td><td>int <var>ierr</var>,
355 char *<var>filename</var>)</td></tr></table></dt>
356<dd>
357<div class="refcount-info">
358 <span class="label">Return value:</span>
359 <span class="value">Always <tt class="constant">NULL</tt>.</span>
360</div>
361 Similar to <tt class="cfunction">PyErr_SetFromWindowsErr()</tt>, with the
362 additional behavior that if <var>filename</var> is not <tt class="constant">NULL</tt>, it is
363 passed to the constructor of <tt class="exception">WindowsError</tt> as a third
364 parameter.
365 Availability: Windows.
366</dd></dl>
367
368<P>
369<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject*&nbsp;<b><tt id='l2h-110' xml:id='l2h-110' class="cfunction">PyErr_SetExcFromWindowsErrWithFilename</tt></b>(</nobr></td><td>PyObject *<var>type</var>, int <var>ierr</var>, char *<var>filename</var>)</td></tr></table></dt>
370<dd>
371 Similar to <tt class="cfunction">PyErr_SetFromWindowsErrWithFilename()</tt>, with
372 an additional parameter specifying the exception type to be raised.
373 Availability: Windows.
374
375<span class="versionnote">New in version 2.3.</span>
376
377</dd></dl>
378
379<P>
380<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>void&nbsp;<b><tt id='l2h-111' xml:id='l2h-111' class="cfunction">PyErr_BadInternalCall</tt></b>(</nobr></td><td>)</td></tr></table></dt>
381<dd>
382 This is a shorthand for "<tt class="samp">PyErr_SetString(PyExc_TypeError,
383 <var>message</var>)</tt>", where <var>message</var> indicates that an internal
384 operation (e.g. a Python/C API function) was invoked with an illegal
385 argument. It is mostly for internal use.
386</dd></dl>
387
388<P>
389<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int&nbsp;<b><tt id='l2h-112' xml:id='l2h-112' class="cfunction">PyErr_Warn</tt></b>(</nobr></td><td>PyObject *<var>category</var>, char *<var>message</var>)</td></tr></table></dt>
390<dd>
391 Issue a warning message. The <var>category</var> argument is a warning
392 category (see below) or <tt class="constant">NULL</tt>; the <var>message</var> argument is a
393 message string.
394
395<P>
396This function normally prints a warning message to <var>sys.stderr</var>;
397 however, it is also possible that the user has specified that
398 warnings are to be turned into errors, and in that case this will
399 raise an exception. It is also possible that the function raises an
400 exception because of a problem with the warning machinery (the
401 implementation imports the <tt class="module">warnings</tt> module to do the heavy
402 lifting). The return value is <code>0</code> if no exception is raised,
403 or <code>-1</code> if an exception is raised. (It is not possible to
404 determine whether a warning message is actually printed, nor what
405 the reason is for the exception; this is intentional.) If an
406 exception is raised, the caller should do its normal exception
407 handling (for example, <tt class="cfunction">Py_DECREF()</tt> owned references and
408 return an error value).
409
410<P>
411Warning categories must be subclasses of <tt class="cdata">Warning</tt>; the
412 default warning category is <tt class="cdata">RuntimeWarning</tt>. The standard
413 Python warning categories are available as global variables whose
414 names are "<tt class="samp">PyExc_</tt>" followed by the Python exception name.
415 These have the type <tt class="ctype">PyObject*</tt>; they are all class objects.
416 Their names are <tt class="cdata">PyExc_Warning</tt>, <tt class="cdata">PyExc_UserWarning</tt>,
417 <tt class="cdata">PyExc_DeprecationWarning</tt>, <tt class="cdata">PyExc_SyntaxWarning</tt>,
418 <tt class="cdata">PyExc_RuntimeWarning</tt>, and <tt class="cdata">PyExc_FutureWarning</tt>.
419 <tt class="cdata">PyExc_Warning</tt> is a subclass of <tt class="cdata">PyExc_Exception</tt>; the
420 other warning categories are subclasses of <tt class="cdata">PyExc_Warning</tt>.
421
422<P>
423For information about warning control, see the documentation for the
424 <tt class="module">warnings</tt> module and the <b class="programopt">-W</b> option in the
425 command line documentation. There is no C API for warning control.
426</dd></dl>
427
428<P>
429<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int&nbsp;<b><tt id='l2h-113' xml:id='l2h-113' class="cfunction">PyErr_WarnExplicit</tt></b>(</nobr></td><td>PyObject *<var>category</var>, char *<var>message</var>,
430 char *<var>filename</var>, int <var>lineno</var>, char *<var>module</var>, PyObject *<var>registry</var>)</td></tr></table></dt>
431<dd>
432 Issue a warning message with explicit control over all warning
433 attributes. This is a straightforward wrapper around the Python
434 function <tt class="function">warnings.warn_explicit()</tt>, see there for more
435 information. The <var>module</var> and <var>registry</var> arguments may be
436 set to <tt class="constant">NULL</tt> to get the default effect described there.
437</dd></dl>
438
439<P>
440<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int&nbsp;<b><tt id='l2h-114' xml:id='l2h-114' class="cfunction">PyErr_CheckSignals</tt></b>(</nobr></td><td>)</td></tr></table></dt>
441<dd>
442 This function interacts with Python's signal handling. It checks
443 whether a signal has been sent to the processes and if so, invokes
444 the corresponding signal handler. If the
445 <tt class="module">signal</tt><a id='l2h-123' xml:id='l2h-123'></a> module is supported, this can
446 invoke a signal handler written in Python. In all cases, the
447 default effect for <tt class="constant">SIGINT</tt><a id='l2h-124' xml:id='l2h-124'></a> is to raise the
448 <a id='l2h-116' xml:id='l2h-116'></a> <tt class="exception">KeyboardInterrupt</tt> exception. If an exception is raised
449 the error indicator is set and the function returns <code>1</code>;
450 otherwise the function returns <code>0</code>. The error indicator may or
451 may not be cleared if it was previously set.
452</dd></dl>
453
454<P>
455<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>void&nbsp;<b><tt id='l2h-117' xml:id='l2h-117' class="cfunction">PyErr_SetInterrupt</tt></b>(</nobr></td><td>)</td></tr></table></dt>
456<dd>
457 This function simulates the effect of a
458 <tt class="constant">SIGINT</tt><a id='l2h-125' xml:id='l2h-125'></a> signal arriving -- the next time
459 <tt class="cfunction">PyErr_CheckSignals()</tt> is called,
460 <a id='l2h-119' xml:id='l2h-119'></a> <tt class="exception">KeyboardInterrupt</tt> will be raised. It may be called
461 without holding the interpreter lock.
462 </dd></dl>
463
464<P>
465<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject*&nbsp;<b><tt id='l2h-120' xml:id='l2h-120' class="cfunction">PyErr_NewException</tt></b>(</nobr></td><td>char *<var>name</var>,
466 PyObject *<var>base</var>,
467 PyObject *<var>dict</var>)</td></tr></table></dt>
468<dd>
469<div class="refcount-info">
470 <span class="label">Return value:</span>
471 <span class="value">New reference.</span>
472</div>
473 This utility function creates and returns a new exception object.
474 The <var>name</var> argument must be the name of the new exception, a C
475 string of the form <code>module.class</code>. The <var>base</var> and
476 <var>dict</var> arguments are normally <tt class="constant">NULL</tt>. This creates a class
477 object derived from the root for all exceptions, the built-in name
478 <tt class="exception">Exception</tt> (accessible in C as <tt class="cdata">PyExc_Exception</tt>).
479 The <tt class="member">__module__</tt> attribute of the new class is set to the
480 first part (up to the last dot) of the <var>name</var> argument, and the
481 class name is set to the last part (after the last dot). The
482 <var>base</var> argument can be used to specify an alternate base class.
483 The <var>dict</var> argument can be used to specify a dictionary of class
484 variables and methods.
485</dd></dl>
486
487<P>
488<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>void&nbsp;<b><tt id='l2h-121' xml:id='l2h-121' class="cfunction">PyErr_WriteUnraisable</tt></b>(</nobr></td><td>PyObject *<var>obj</var>)</td></tr></table></dt>
489<dd>
490 This utility function prints a warning message to <code>sys.stderr</code>
491 when an exception has been set but it is impossible for the
492 interpreter to actually raise the exception. It is used, for
493 example, when an exception occurs in an <tt class="method">__del__()</tt> method.
494
495<P>
496The function is called with a single argument <var>obj</var> that
497 identifies the context in which the unraisable exception occurred.
498 The repr of <var>obj</var> will be printed in the warning message.
499</dd></dl>
500
501<P>
502
503<p><br /></p><hr class='online-navigation' />
504<div class='online-navigation'>
505<!--Table of Child-Links-->
506<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a>
507
508<UL CLASS="ChildLinks">
509<LI><A href="standardExceptions.html">4.1 Standard Exceptions</a>
510<LI><A href="node15.html">4.2 Deprecation of String Exceptions</a>
511</ul>
512<!--End of Table of Child-Links-->
513</div>
514
515<DIV CLASS="navigation">
516<div class='online-navigation'>
517<p></p><hr />
518<table align="center" width="100%" cellpadding="0" cellspacing="2">
519<tr>
520<td class='online-navigation'><a rel="prev" title="3. Reference Counting"
521 href="countingRefs.html"><img src='../icons/previous.png'
522 border='0' height='32' alt='Previous Page' width='32' /></A></td>
523<td class='online-navigation'><a rel="parent" title="Python/C API Reference Manual"
524 href="api.html"><img src='../icons/up.png'
525 border='0' height='32' alt='Up One Level' width='32' /></A></td>
526<td class='online-navigation'><a rel="next" title="4.1 Standard Exceptions"
527 href="standardExceptions.html"><img src='../icons/next.png'
528 border='0' height='32' alt='Next Page' width='32' /></A></td>
529<td align="center" width="100%">Python/C API Reference Manual</td>
530<td class='online-navigation'><a rel="contents" title="Table of Contents"
531 href="contents.html"><img src='../icons/contents.png'
532 border='0' height='32' alt='Contents' width='32' /></A></td>
533<td class='online-navigation'><img src='../icons/blank.png'
534 border='0' height='32' alt='' width='32' /></td>
535<td class='online-navigation'><a rel="index" title="Index"
536 href="genindex.html"><img src='../icons/index.png'
537 border='0' height='32' alt='Index' width='32' /></A></td>
538</tr></table>
539<div class='online-navigation'>
540<b class="navlabel">Previous:</b>
541<a class="sectref" rel="prev" href="countingRefs.html">3. Reference Counting</A>
542<b class="navlabel">Up:</b>
543<a class="sectref" rel="parent" href="api.html">Python/C API Reference Manual</A>
544<b class="navlabel">Next:</b>
545<a class="sectref" rel="next" href="standardExceptions.html">4.1 Standard Exceptions</A>
546</div>
547</div>
548<hr />
549<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
550</DIV>
551<!--End of Navigation Panel-->
552<ADDRESS>
553See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
554</ADDRESS>
555</BODY>
556</HTML>
Full OpenSPARC architecture tarball including simulator, hypervisor, and OBP.