Mercurial > cpython-lru_cache-weakref

annotate Doc/c-api/sys.rst @ 78069:a8aa77458e12 3.2

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add c_size_t and c_ssize_t to the ctypes summary table.
author Antoine Pitrou <solipsis@pitrou.net>
date Thu, 12 Jul 2012 20:31:50 +0200
parents 0b5bfba7a907
children deac156c4dd4
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
1 .. highlightlang:: c
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
2
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
3 .. _os:
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
4
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
5 Operating System Utilities
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
6 ==========================
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
7
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
8
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64112
diff changeset
9 .. c:function:: int Py_FdIsInteractive(FILE *fp, const char *filename)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
10
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
11 Return true (nonzero) if the standard I/O file *fp* with name *filename* is
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
12 deemed interactive. This is the case for files for which ``isatty(fileno(fp))``
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64112
diff changeset
13 is true. If the global flag :c:data:`Py_InteractiveFlag` is true, this function
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
14 also returns true if the *filename* pointer is *NULL* or if the name is equal to
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
15 one of the strings ``'<stdin>'`` or ``'???'``.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
16
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
17
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64112
diff changeset
18 .. c:function:: void PyOS_AfterFork()
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
19
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
20 Function to update some internal state after a process fork; this should be
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
21 called in the new process if the Python interpreter will continue to be used.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
22 If a new executable is loaded into the new process, this function does not need
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
23 to be called.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
24
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
25
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64112
diff changeset
26 .. c:function:: int PyOS_CheckStack()
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
27
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
28 Return true when the interpreter runs out of stack space. This is a reliable
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
29 check, but is only available when :const:`USE_STACKCHECK` is defined (currently
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
30 on Windows using the Microsoft Visual C++ compiler). :const:`USE_STACKCHECK`
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
31 will be defined automatically; you should never change the definition in your
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
32 own code.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
33
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
34
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64112
diff changeset
35 .. c:function:: PyOS_sighandler_t PyOS_getsig(int i)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
36
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
37 Return the current signal handler for signal *i*. This is a thin wrapper around
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64112
diff changeset
38 either :c:func:`sigaction` or :c:func:`signal`. Do not call those functions
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64112
diff changeset
39 directly! :c:type:`PyOS_sighandler_t` is a typedef alias for :c:type:`void
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
40 (\*)(int)`.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
41
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
42
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64112
diff changeset
43 .. c:function:: PyOS_sighandler_t PyOS_setsig(int i, PyOS_sighandler_t h)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
44
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
45 Set the signal handler for signal *i* to be *h*; return the old signal handler.
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64112
diff changeset
46 This is a thin wrapper around either :c:func:`sigaction` or :c:func:`signal`. Do
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64112
diff changeset
47 not call those functions directly! :c:type:`PyOS_sighandler_t` is a typedef
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64112
diff changeset
48 alias for :c:type:`void (\*)(int)`.
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
49
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
50 .. _systemfunctions:
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
51
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
52 System Functions
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
53 ================
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
54
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
55 These are utility functions that make functionality from the :mod:`sys` module
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
56 accessible to C code. They all work with the current interpreter thread's
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
57 :mod:`sys` module's dict, which is contained in the internal thread state structure.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
58
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64112
diff changeset
59 .. c:function:: PyObject *PySys_GetObject(char *name)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
60
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
61 Return the object *name* from the :mod:`sys` module or *NULL* if it does
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
62 not exist, without setting an exception.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
63
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64112
diff changeset
64 .. c:function:: FILE *PySys_GetFile(char *name, FILE *def)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
65
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64112
diff changeset
66 Return the :c:type:`FILE*` associated with the object *name* in the
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
67 :mod:`sys` module, or *def* if *name* is not in the module or is not associated
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64112
diff changeset
68 with a :c:type:`FILE*`.
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
69
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64112
diff changeset
70 .. c:function:: int PySys_SetObject(char *name, PyObject *v)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
71
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
72 Set *name* in the :mod:`sys` module to *v* unless *v* is *NULL*, in which
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
73 case *name* is deleted from the sys module. Returns ``0`` on success, ``-1``
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
74 on error.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
75
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64112
diff changeset
76 .. c:function:: void PySys_ResetWarnOptions()
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
77
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
78 Reset :data:`sys.warnoptions` to an empty list.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
79
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64112
diff changeset
80 .. c:function:: void PySys_AddWarnOption(wchar_t *s)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
81
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
82 Append *s* to :data:`sys.warnoptions`.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
83
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64112
diff changeset
84 .. c:function:: void PySys_AddWarnOptionUnicode(PyObject *unicode)
61751
b7f71f60437b Issue #8589: Decode PYTHONWARNINGS environment variable with the file system
Victor Stinner <victor.stinner@haypocalc.com>
parents: 55580
diff changeset
85
b7f71f60437b Issue #8589: Decode PYTHONWARNINGS environment variable with the file system
Victor Stinner <victor.stinner@haypocalc.com>
parents: 55580
diff changeset
86 Append *unicode* to :data:`sys.warnoptions`.
b7f71f60437b Issue #8589: Decode PYTHONWARNINGS environment variable with the file system
Victor Stinner <victor.stinner@haypocalc.com>
parents: 55580
diff changeset
87
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64112
diff changeset
88 .. c:function:: void PySys_SetPath(wchar_t *path)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
89
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
90 Set :data:`sys.path` to a list object of paths found in *path* which should
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
91 be a list of paths separated with the platform's search path delimiter
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
92 (``:`` on Unix, ``;`` on Windows).
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
93
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64112
diff changeset
94 .. c:function:: void PySys_WriteStdout(const char *format, ...)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
95
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
96 Write the output string described by *format* to :data:`sys.stdout`. No
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
97 exceptions are raised, even if truncation occurs (see below).
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
98
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
99 *format* should limit the total size of the formatted output string to
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
100 1000 bytes or less -- after 1000 bytes, the output string is truncated.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
101 In particular, this means that no unrestricted "%s" formats should occur;
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
102 these should be limited using "%.<N>s" where <N> is a decimal number
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
103 calculated so that <N> plus the maximum size of other formatted text does not
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
104 exceed 1000 bytes. Also watch out for "%f", which can print hundreds of
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
105 digits for very large numbers.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
106
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
107 If a problem occurs, or :data:`sys.stdout` is unset, the formatted message
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
108 is written to the real (C level) *stdout*.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
109
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64112
diff changeset
110 .. c:function:: void PySys_WriteStderr(const char *format, ...)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
111
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64112
diff changeset
112 As :c:func:`PySys_WriteStdout`, but write to :data:`sys.stderr` or *stderr*
64064
5d9bdf5aa07b Issue #9599: Create PySys_FormatStdout() and PySys_FormatStderr()
Victor Stinner <victor.stinner@haypocalc.com>
parents: 61751
diff changeset
113 instead.
5d9bdf5aa07b Issue #9599: Create PySys_FormatStdout() and PySys_FormatStderr()
Victor Stinner <victor.stinner@haypocalc.com>
parents: 61751
diff changeset
114
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64112
diff changeset
115 .. c:function:: void PySys_FormatStdout(const char *format, ...)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
116
64064
5d9bdf5aa07b Issue #9599: Create PySys_FormatStdout() and PySys_FormatStderr()
Victor Stinner <victor.stinner@haypocalc.com>
parents: 61751
diff changeset
117 Function similar to PySys_WriteStdout() but format the message using
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64112
diff changeset
118 :c:func:`PyUnicode_FromFormatV` and don't truncate the message to an
64064
5d9bdf5aa07b Issue #9599: Create PySys_FormatStdout() and PySys_FormatStderr()
Victor Stinner <victor.stinner@haypocalc.com>
parents: 61751
diff changeset
119 arbitrary length.
5d9bdf5aa07b Issue #9599: Create PySys_FormatStdout() and PySys_FormatStderr()
Victor Stinner <victor.stinner@haypocalc.com>
parents: 61751
diff changeset
120
64066
aae3e0c510ff Add versionadded tag to PySys_FormatStd*() functions doc
Victor Stinner <victor.stinner@haypocalc.com>
parents: 64064
diff changeset
121 .. versionadded:: 3.2
aae3e0c510ff Add versionadded tag to PySys_FormatStd*() functions doc
Victor Stinner <victor.stinner@haypocalc.com>
parents: 64064
diff changeset
122
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64112
diff changeset
123 .. c:function:: void PySys_FormatStderr(const char *format, ...)
64064
5d9bdf5aa07b Issue #9599: Create PySys_FormatStdout() and PySys_FormatStderr()
Victor Stinner <victor.stinner@haypocalc.com>
parents: 61751
diff changeset
124
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64112
diff changeset
125 As :c:func:`PySys_FormatStdout`, but write to :data:`sys.stderr` or *stderr*
64064
5d9bdf5aa07b Issue #9599: Create PySys_FormatStdout() and PySys_FormatStderr()
Victor Stinner <victor.stinner@haypocalc.com>
parents: 61751
diff changeset
126 instead.
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
127
64066
aae3e0c510ff Add versionadded tag to PySys_FormatStd*() functions doc
Victor Stinner <victor.stinner@haypocalc.com>
parents: 64064
diff changeset
128 .. versionadded:: 3.2
aae3e0c510ff Add versionadded tag to PySys_FormatStd*() functions doc
Victor Stinner <victor.stinner@haypocalc.com>
parents: 64064
diff changeset
129
65575
0b5bfba7a907 Issue #10089: Add support for arbitrary -X options on the command-line.
Antoine Pitrou <solipsis@pitrou.net>
parents: 65137
diff changeset
130 .. c:function:: void PySys_AddXOption(const wchar_t *s)
0b5bfba7a907 Issue #10089: Add support for arbitrary -X options on the command-line.
Antoine Pitrou <solipsis@pitrou.net>
parents: 65137
diff changeset
131
0b5bfba7a907 Issue #10089: Add support for arbitrary -X options on the command-line.
Antoine Pitrou <solipsis@pitrou.net>
parents: 65137
diff changeset
132 Parse *s* as a set of :option:`-X` options and add them to the current
0b5bfba7a907 Issue #10089: Add support for arbitrary -X options on the command-line.
Antoine Pitrou <solipsis@pitrou.net>
parents: 65137
diff changeset
133 options mapping as returned by :c:func:`PySys_GetXOptions`.
0b5bfba7a907 Issue #10089: Add support for arbitrary -X options on the command-line.
Antoine Pitrou <solipsis@pitrou.net>
parents: 65137
diff changeset
134
0b5bfba7a907 Issue #10089: Add support for arbitrary -X options on the command-line.
Antoine Pitrou <solipsis@pitrou.net>
parents: 65137
diff changeset
135 .. versionadded:: 3.2
0b5bfba7a907 Issue #10089: Add support for arbitrary -X options on the command-line.
Antoine Pitrou <solipsis@pitrou.net>
parents: 65137
diff changeset
136
0b5bfba7a907 Issue #10089: Add support for arbitrary -X options on the command-line.
Antoine Pitrou <solipsis@pitrou.net>
parents: 65137
diff changeset
137 .. c:function:: PyObject *PySys_GetXOptions()
0b5bfba7a907 Issue #10089: Add support for arbitrary -X options on the command-line.
Antoine Pitrou <solipsis@pitrou.net>
parents: 65137
diff changeset
138
0b5bfba7a907 Issue #10089: Add support for arbitrary -X options on the command-line.
Antoine Pitrou <solipsis@pitrou.net>
parents: 65137
diff changeset
139 Return the current dictionary of :option:`-X` options, similarly to
0b5bfba7a907 Issue #10089: Add support for arbitrary -X options on the command-line.
Antoine Pitrou <solipsis@pitrou.net>
parents: 65137
diff changeset
140 :data:`sys._xoptions`. On error, *NULL* is returned and an exception is
0b5bfba7a907 Issue #10089: Add support for arbitrary -X options on the command-line.
Antoine Pitrou <solipsis@pitrou.net>
parents: 65137
diff changeset
141 set.
0b5bfba7a907 Issue #10089: Add support for arbitrary -X options on the command-line.
Antoine Pitrou <solipsis@pitrou.net>
parents: 65137
diff changeset
142
0b5bfba7a907 Issue #10089: Add support for arbitrary -X options on the command-line.
Antoine Pitrou <solipsis@pitrou.net>
parents: 65137
diff changeset
143 .. versionadded:: 3.2
0b5bfba7a907 Issue #10089: Add support for arbitrary -X options on the command-line.
Antoine Pitrou <solipsis@pitrou.net>
parents: 65137
diff changeset
144
64112
990a766ff983 Consistency check for versionadded/changed directives.
Georg Brandl <georg@python.org>
parents: 64066
diff changeset
145
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
146 .. _processcontrol:
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
147
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
148 Process Control
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
149 ===============
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
150
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
151
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64112
diff changeset
152 .. c:function:: void Py_FatalError(const char *message)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
153
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
154 .. index:: single: abort()
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
155
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
156 Print a fatal error message and kill the process. No cleanup is performed.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
157 This function should only be invoked when a condition is detected that would
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
158 make it dangerous to continue using the Python interpreter; e.g., when the
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
159 object administration appears to be corrupted. On Unix, the standard C library
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64112
diff changeset
160 function :c:func:`abort` is called which will attempt to produce a :file:`core`
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
161 file.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
162
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
163
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64112
diff changeset
164 .. c:function:: void Py_Exit(int status)
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
165
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
166 .. index::
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
167 single: Py_Finalize()
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
168 single: exit()
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
169
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64112
diff changeset
170 Exit the current process. This calls :c:func:`Py_Finalize` and then calls the
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
171 standard C library function ``exit(status)``.
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
172
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
173
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64112
diff changeset
174 .. c:function:: int Py_AtExit(void (*func) ())
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
175
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
176 .. index::
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
177 single: Py_Finalize()
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
178 single: cleanup functions
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
179
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64112
diff changeset
180 Register a cleanup function to be called by :c:func:`Py_Finalize`. The cleanup
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
181 function will be called with no arguments and should return no value. At most
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
182 32 cleanup functions can be registered. When the registration is successful,
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64112
diff changeset
183 :c:func:`Py_AtExit` returns ``0``; on failure, it returns ``-1``. The cleanup
44812
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
184 function registered last is called first. Each cleanup function will be called
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
185 at most once. Since Python's internal finalization will have completed before
1e8b9e7c34ce Split C API docs in Py3k branch.
Georg Brandl <georg@python.org>
parents:
diff changeset
186 the cleanup function, no Python APIs should be called by *func*.