Issue #9738: Document PyErr_SetString() and PyErr_SetFromErrnoWithFilename()

encodings

3 files changed, 13 insertions, 3 deletions

diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst
index 3fce3b2..0094af3 100644
--- a/Doc/c-api/exceptions.rst
+++ b/Doc/c-api/exceptions.rst
@@ -134,7 +134,7 @@ in various ways.  There is a separate error indicator for each thread.
    This is the most common way to set the error indicator.  The first argument
    specifies the exception type; it is normally one of the standard exceptions,
    e.g. :c:data:`PyExc_RuntimeError`.  You need not increment its reference count.
-   The second argument is an error message; it is converted to a string object.
+   The second argument is an error message; it is decoded from ``'utf-8``'.
 
 
 .. c:function:: void PyErr_SetObject(PyObject *type, PyObject *value)
@@ -261,6 +261,8 @@ in various ways.  There is a separate error indicator for each thread.
    *filename* is not *NULL*, it is passed to the constructor of *type* as a third
    parameter.  In the case of exceptions such as :exc:`IOError` and :exc:`OSError`,
    this is used to define the :attr:`filename` attribute of the exception instance.
+   *filename* is decoded from the filesystem encoding
+   (:func:`sys.getfilesystemencoding`).
 
 
 .. c:function:: PyObject* PyErr_SetFromWindowsErr(int ierr)
diff --git a/Include/pyerrors.h b/Include/pyerrors.h
index fb9ce91..58a3df7 100644
--- a/Include/pyerrors.h
+++ b/Include/pyerrors.h
@@ -60,7 +60,10 @@ typedef struct {
 
 PyAPI_FUNC(void) PyErr_SetNone(PyObject *);
 PyAPI_FUNC(void) PyErr_SetObject(PyObject *, PyObject *);
-PyAPI_FUNC(void) PyErr_SetString(PyObject *, const char *);
+PyAPI_FUNC(void) PyErr_SetString(
+    PyObject *exception,
+    const char *string   /* decoded from utf-8 */
+    );
 PyAPI_FUNC(PyObject *) PyErr_Occurred(void);
 PyAPI_FUNC(void) PyErr_Clear(void);
 PyAPI_FUNC(void) PyErr_Fetch(PyObject **, PyObject **, PyObject **);
@@ -177,7 +180,9 @@ PyAPI_FUNC(PyObject *) PyErr_SetFromErrno(PyObject *);
 PyAPI_FUNC(PyObject *) PyErr_SetFromErrnoWithFilenameObject(
     PyObject *, PyObject *);
 PyAPI_FUNC(PyObject *) PyErr_SetFromErrnoWithFilename(
-    PyObject *, const char *);
+    PyObject *exc,
+    const char *filename   /* decoded from the filesystem encoding */
+    );
 #ifdef MS_WINDOWS
 PyAPI_FUNC(PyObject *) PyErr_SetFromErrnoWithUnicodeFilename(
     PyObject *, const Py_UNICODE *);
diff --git a/Misc/NEWS b/Misc/NEWS
index 64e03a0..ac731c5 100644
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -10,6 +10,9 @@ What's New in Python 3.2 Alpha 3?
 Core and Builtins
 -----------------
 
+- Issue #9738: Document PyErr_SetString() and PyErr_SetFromErrnoWithFilename()
+  encodings
+
 - ast.literal_eval() can now handle negative numbers.  It is also a little
   more liberal in what it accepts without compromising the safety of the
   evaluation.  For example, 3j+4 and 3+4+5 are both accepted.