GNU Info

(python2.1-ext.info)NULL Pointers

---

Prev: Thin Ice Up: Reference Counts

---

Enter node , (file) or (file)node

NULL Pointers
-------------

In general, functions that take object references as arguments do not
expect you to pass them `NULL' pointers, and will dump core (or cause
later core dumps) if you do so.  Functions that return object
references generally return `NULL' only to indicate that an exception
occurred.  The reason for not testing for `NULL' arguments is that
functions often pass the objects they receive on to other function --
if each function were to test for `NULL', there would be a lot of
redundant tests and the code would run more slowly.

It is better to test for `NULL' only at the "source", i.e. when a
pointer that may be `NULL' is received, e.g. from `malloc()' or from a
function that may raise an exception.

The macros `Py_INCREF()' and `Py_DECREF()' do not check for `NULL'
pointers -- however, their variants `Py_XINCREF()' and `Py_XDECREF()'
do.

The macros for checking for a particular object type (`PyTYPE_Check()')
don't check for `NULL' pointers -- again, there is much code that calls
several of these in a row to test an object against various different
expected types, and this would generate redundant tests.  There are no
variants with `NULL' checking.

The C function calling mechanism guarantees that the argument list
passed to C functions (`args' in the examples) is never `NULL' -- in
fact it guarantees that it is always a tuple.(1)

It is a severe error to ever let a `NULL' pointer "escape" to the
Python user.

---------- Footnotes ----------

(1)  These guarantees don't hold when you use the "old" style calling
convention -- this is still found in much existing code.