summaryrefslogtreecommitdiff
path: root/Doc/c-api/init.rst
diff options
context:
space:
mode:
Diffstat (limited to 'Doc/c-api/init.rst')
-rw-r--r--Doc/c-api/init.rst50
1 files changed, 49 insertions, 1 deletions
diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst
index 4dad2c814d..0587e15d9f 100644
--- a/Doc/c-api/init.rst
+++ b/Doc/c-api/init.rst
@@ -86,6 +86,36 @@ Process-wide parameters
=======================
+.. c:function:: int Py_SetStandardStreamEncoding(char *encoding, char *errors)
+
+ .. index::
+ single: Py_Initialize()
+ single: main()
+ triple: stdin; stdout; sdterr
+
+ This function should be called before :c:func:`Py_Initialize`, if it is
+ called at all. It specifies which encoding and error handling to use
+ with standard IO, with the same meanings as in :func:`str.encode`.
+
+ It overrides :envvar:`PYTHONIOENCODING` values, and allows embedding code
+ to control IO encoding when the environment variable does not work.
+
+ ``encoding`` and/or ``errors`` may be NULL to use
+ :envvar:`PYTHONIOENCODING` and/or default values (depending on other
+ settings).
+
+ Note that :data:`sys.stderr` always uses the "backslashreplace" error
+ handler, regardless of this (or any other) setting.
+
+ If :c:func:`Py_Finalize` is called, this function will need to be called
+ again in order to affect subsequent calls to :c:func:`Py_Initialize`.
+
+ Returns 0 if successful, a nonzero value on error (e.g. calling after the
+ interpreter has already been initialized).
+
+ .. versionadded:: 3.4
+
+
.. c:function:: void Py_SetProgramName(wchar_t *name)
.. index::
@@ -329,7 +359,11 @@ Process-wide parameters
.. c:function:: void PySys_SetArgv(int argc, wchar_t **argv)
- This function works like :c:func:`PySys_SetArgvEx` with *updatepath* set to 1.
+ This function works like :c:func:`PySys_SetArgvEx` with *updatepath* set
+ to 1 unless the :program:`python` interpreter was started with the
+ :option:`-I`.
+
+ .. versionchanged:: 3.4 The *updatepath* value depends on :option:`-I`.
.. c:function:: void Py_SetPythonHome(wchar_t *home)
@@ -658,6 +692,20 @@ with sub-interpreters:
made on the main thread. This is mainly a helper/diagnostic function.
+.. c:function:: int PyGILState_Check()
+
+ Return 1 if the current thread is holding the GIL and 0 otherwise.
+ This function can be called from any thread at any time.
+ Only if it has had its Python thread state initialized and currently is
+ holding the GIL will it return 1.
+ This is mainly a helper/diagnostic function. It can be useful
+ for example in callback contexts or memory allocation functions when
+ knowing that the GIL is locked can allow the caller to perform sensitive
+ actions or otherwise behave differently.
+
+ .. versionadded:: 3.4
+
+
The following macros are normally used without a trailing semicolon; look for
example usage in the Python source distribution.