From 6fbd525ef59bf7bfd62b29dcc862fc1f1947dc16 Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Sun, 18 Dec 2011 19:22:31 +0100 Subject: Issue #13617: Document that the result of the conversion of a Unicode object to wchar*, Py_UNICODE* and bytes may contain embedded null characters/bytes. Patch written by Arnaud Calmettes. --- Doc/ACKS.txt | 1 + Doc/c-api/unicode.rst | 28 +++++++++++++++++++--------- 2 files changed, 20 insertions(+), 9 deletions(-) diff --git a/Doc/ACKS.txt b/Doc/ACKS.txt index 81f7c46..70063c0 100644 --- a/Doc/ACKS.txt +++ b/Doc/ACKS.txt @@ -33,6 +33,7 @@ docs@python.org), and we'll be glad to correct the problem. * Keith Briggs * Ian Bruntlett * Lee Busby + * Arnaud Calmettes * Lorenzo M. Catucci * Carl Cerecke * Mauro Cicognini diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst index f48eb73..3500654 100644 --- a/Doc/c-api/unicode.rst +++ b/Doc/c-api/unicode.rst @@ -338,16 +338,21 @@ APIs: .. c:function:: Py_UNICODE* PyUnicode_AsUnicode(PyObject *unicode) - Return a read-only pointer to the Unicode object's internal :c:type:`Py_UNICODE` - buffer, *NULL* if *unicode* is not a Unicode object. + Return a read-only pointer to the Unicode object's internal + :c:type:`Py_UNICODE` buffer, *NULL* if *unicode* is not a Unicode object. + Note that the resulting :c:type:`Py_UNICODE*` string may contain embedded + null characters, which would cause the string to be truncated when used in + most C functions. .. c:function:: Py_UNICODE* PyUnicode_AsUnicodeCopy(PyObject *unicode) Create a copy of a Unicode string ending with a nul character. Return *NULL* and raise a :exc:`MemoryError` exception on memory allocation failure, - otherwise return a new allocated buffer (use :c:func:`PyMem_Free` to free the - buffer). + otherwise return a new allocated buffer (use :c:func:`PyMem_Free` to free + the buffer). Note that the resulting :c:type:`Py_UNICODE*` string may contain + embedded null characters, which would cause the string to be truncated when + used in most C functions. .. versionadded:: 3.2 @@ -447,7 +452,8 @@ used, passing :c:func:`PyUnicode_FSDecoder` as the conversion function: Encode a Unicode object to :c:data:`Py_FileSystemDefaultEncoding` with the ``'surrogateescape'`` error handler, or ``'strict'`` on Windows, and return - :class:`bytes`. + :class:`bytes`. Note that the resulting :class:`bytes` object may contain + null bytes. If :c:data:`Py_FileSystemDefaultEncoding` is not set, fall back to the locale encoding. @@ -476,7 +482,9 @@ wchar_t Support copied or -1 in case of an error. Note that the resulting :c:type:`wchar_t` string may or may not be 0-terminated. It is the responsibility of the caller to make sure that the :c:type:`wchar_t` string is 0-terminated in case this is - required by the application. + required by the application. Also, note that the :c:type:`wchar_t*` string + might contain null characters, which would cause the string to be truncated + when used with most C functions. .. c:function:: wchar_t* PyUnicode_AsWideCharString(PyObject *unicode, Py_ssize_t *size) @@ -486,9 +494,11 @@ wchar_t Support of wide characters (excluding the trailing 0-termination character) into *\*size*. - Returns a buffer allocated by :c:func:`PyMem_Alloc` (use :c:func:`PyMem_Free` - to free it) on success. On error, returns *NULL*, *\*size* is undefined and - raises a :exc:`MemoryError`. + Returns a buffer allocated by :c:func:`PyMem_Alloc` (use + :c:func:`PyMem_Free` to free it) on success. On error, returns *NULL*, + *\*size* is undefined and raises a :exc:`MemoryError`. Note that the + resulting :c:type:`wchar_t*` string might contain null characters, which + would cause the string to be truncated when used with most C functions. .. versionadded:: 3.2 -- cgit v0.12