Extending and Embedding the Python Interpreter

Previous: 1.10.3 Thin Ice Up: 1.10 Reference Counts Next: 1.11 Writing Extensions in

---

1.10.4 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:'' when a pointer that may be NULL is received, for example, 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.4

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

Footnotes

... tuple.^1.4

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

---

Extending and Embedding the Python Interpreter

Previous: 1.10.3 Thin Ice Up: 1.10 Reference Counts Next: 1.11 Writing Extensions in

---

Release 2.4.5, documentation updated on 18 October 2006.