Add documentation for PySys_* functions.

Written by Charlie Shepherd for GHOP. Also fixes #1245.

4 files changed, 83 insertions, 2 deletions

diff --git a/Doc/ACKS.txt b/Doc/ACKS.txt
index 34c657b..de2fd51 100644
--- a/Doc/ACKS.txt
+++ b/Doc/ACKS.txt
@@ -160,6 +160,7 @@ docs@python.org), and we'll be glad to correct the problem.
 * Barry Scott
 * Joakim Sernbrant
 * Justin Sheehy
+* Charlie Shepherd
 * Michael Simcich
 * Ionel Simionescu
 * Michael Sloan
diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst
index 8dd9a57..bb0e390 100644
--- a/Doc/c-api/init.rst
+++ b/Doc/c-api/init.rst
@@ -364,8 +364,6 @@ Initialization, Finalization, and Threads
    .. % XXX impl. doesn't seem consistent in allowing 0/NULL for the params;
    .. % check w/ Guido.
 
-.. % XXX Other PySys thingies (doesn't really belong in this chapter)
-
 
 .. _threads:
 
diff --git a/Doc/c-api/utilities.rst b/Doc/c-api/utilities.rst
index bcd84b3..269f23a 100644
--- a/Doc/c-api/utilities.rst
+++ b/Doc/c-api/utilities.rst
@@ -66,6 +66,66 @@ Operating System Utilities
    not call those functions directly!  :ctype:`PyOS_sighandler_t` is a typedef
    alias for :ctype:`void (\*)(int)`.
 
+.. _systemfunctions:
+
+System Functions
+================
+
+These are utility functions that make functionality from the :mod:`sys` module
+accessible to C code.  They all work with the current interpreter thread's
+:mod:`sys` module's dict, which is contained in the internal thread state structure.
+
+.. cfunction:: PyObject *PySys_GetObject(char *name)
+
+   Return the object *name* from the :mod:`sys` module or *NULL* if it does
+   not exist, without setting an exception.
+
+.. cfunction:: FILE *PySys_GetFile(char *name, FILE *def)
+
+   Return the :ctype:`FILE*` associated with the object *name* in the
+   :mod:`sys` module, or *def* if *name* is not in the module or is not associated
+   with a :ctype:`FILE*`.
+
+.. cfunction:: int PySys_SetObject(char *name, PyObject *v)
+
+   Set *name* in the :mod:`sys` module to *v* unless *v* is *NULL*, in which
+   case *name* is deleted from the sys module. Returns ``0`` on success, ``-1``
+   on error.
+
+.. cfunction:: void PySys_ResetWarnOptions(void)
+
+   Reset :data:`sys.warnoptions` to an empty list.
+
+.. cfunction:: void PySys_AddWarnOption(char *s)
+
+   Append *s* to :data:`sys.warnoptions`.
+
+.. cfunction:: void PySys_SetPath(char *path)
+
+   Set :data:`sys.path` to a list object of paths found in *path* which should
+   be a list of paths separated with the platform's search path delimiter
+   (``:`` on Unix, ``;`` on Windows).
+
+.. cfunction:: void PySys_WriteStdout(const char *format, ...)
+
+   Write the output string described by *format* to :data:`sys.stdout`.  No
+   exceptions are raised, even if truncation occurs (see below).
+
+   *format* should limit the total size of the formatted output string to
+   1000 bytes or less -- after 1000 bytes, the output string is truncated.
+   In particular, this means that no unrestricted "%s" formats should occur;
+   these should be limited using "%.<N>s" where <N> is a decimal number
+   calculated so that <N> plus the maximum size of other formatted text does not
+   exceed 1000 bytes.  Also watch out for "%f", which can print hundreds of
+   digits for very large numbers.
+
+   If a problem occurs, or :data:`sys.stdout` is unset, the formatted message
+   is written to the real (C level) *stdout*.
+
+.. cfunction:: void PySys_WriteStderr(const char *format, ...)
+
+   As above, but write to :data:`sys.stderr` or *stderr* instead.
+
 
 .. _processcontrol:
 
diff --git a/Doc/data/refcounts.dat b/Doc/data/refcounts.dat
index 7288117..4d889bd 100644
--- a/Doc/data/refcounts.dat
+++ b/Doc/data/refcounts.dat
@@ -1251,10 +1251,32 @@ PyString_AsEncodedString:PyObject*:str::
 PyString_AsEncodedString:const char*:encoding::
 PyString_AsEncodedString:const char*:errors::
 
+PySys_AddWarnOption:void:::
+PySys_AddWarnOption:char*:s::
+
+PySys_GetFile:FILE*:::
+PySys_GetFile:char*:name::
+PySys_GetFile:FILE*:def::
+
+PySys_GetObject:PyObject*::0:
+PySys_GetObject:char*:name::
+
 PySys_SetArgv:int:::
 PySys_SetArgv:int:argc::
 PySys_SetArgv:char**:argv::
 
+PySys_SetObject:int:::
+PySys_SetObject:char*:name::
+PySys_SetObject:PyObject*:v:+1:
+
+PySys_ResetWarnOptions:void:::
+
+PySys_WriteStdout:void:::
+PySys_WriteStdout:char*:format::
+
+PySys_WriteStderr:void:::
+PySys_WriteStderr:char*:format::
+
 PyThreadState_Clear:void:::
 PyThreadState_Clear:PyThreadState*:tstate::