Added exception to the rule that the buffer returned by PyString_AsString()

and PyString_AsStringAndSize() for strings that were just created using
PyString_FromStringAndSize(NULL, n).

This closes bug #117377.

Added warning about passing NULL to the concrete object functions; many of
them use the appropriate Py<Type>_Check() test, but do not check for NULL.

"de-allocated" --> "deallocated"

diff --git a/Doc/api/api.tex b/Doc/api/api.tex
index 87ac55cacf08521c06fad1ec3d5c079ea9bdd3da..3f3b65f2bcf090c7fcffaf9e68de2c3260df97a7 100644 (file)
--- a/Doc/api/api.tex
+++ b/Doc/api/api.tex
@@ -2001,6 +2001,13 @@ for example. to check that an object is a dictionary, use
 \cfunction{PyDict_Check()}.  The chapter is structured like the
 ``family tree'' of Python object types.
 
+\strong{Warning:}
+While the functions described in this chapter carefully check the type
+of the objects which are passed in, many of them do not check for
+\NULL{} being passed instead of a valid object.  Allowing \NULL{} to
+be passed in can cause memory access violations and immediate
+termination of the interpreter.
+
 
 \section{Fundamental Objects \label{fundamental}}
 
@@ -2057,6 +2064,9 @@ objects that are intrinsic to the Python language.
 
 \subsection{String Objects \label{stringObjects}}
 
+These functions raise \exception{TypeError} when expecting a string
+parameter and are called with a non-string parameter.
+
 \obindex{string}
 \begin{ctypedesc}{PyStringObject}
 This subtype of \ctype{PyObject} represents a Python string object.
@@ -2096,8 +2106,10 @@ checking.
 \begin{cfuncdesc}{char*}{PyString_AsString}{PyObject *string}
 Returns a null-terminated representation of the contents of
 \var{string}.  The pointer refers to the internal buffer of
-\var{string}, not a copy.  The data must not be modified in any way.
-It must not be de-allocated.
+\var{string}, not a copy.  The data must not be modified in any way,
+unless the string was just created using
+\code{PyString_FromStringAndSize(NULL, \var{size})}.
+It must not be deallocated.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{char*}{PyString_AS_STRING}{PyObject *string}
@@ -2118,8 +2130,9 @@ null characters; if it does, the function returns -1 and a
 TypeError is raised.
 
 The buffer refers to an internal string buffer of \var{obj}, not a
-copy. The data must not be modified in any way.  It must not be
-de-allocated.
+copy. The data must not be modified in any way, unless the string was
+just created using \code{PyString_FromStringAndSize(NULL,
+\var{size})}.  It must not be deallocated.
 \end{cfuncdesc}
 
 \begin{cfuncdesc}{void}{PyString_Concat}{PyObject **string,