Mercurial > cpython-lru_cache-weakref

annotate Doc/c-api/sys.rst @ 79675:c0a2294de787 2.7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Issue #16199: Backport 2to3 typo fix from 3.2.
author Chris Jerdonek <chris.jerdonek@gmail.com>
date Thu, 11 Oct 2012 16:15:46 -0700
parents 74ff71b2f53d
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
1 .. highlightlang:: c
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
2
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
3 .. _os:
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
4
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
5 Operating System Utilities
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
6 ==========================
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
7
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
8
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
9 .. c:function:: int Py_FdIsInteractive(FILE *fp, const char *filename)
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
10
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
11 Return true (nonzero) if the standard I/O file *fp* with name *filename* is
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
12 deemed interactive. This is the case for files for which ``isatty(fileno(fp))``
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
13 is true. If the global flag :c:data:`Py_InteractiveFlag` is true, this function
44797
ec02dbe6b051 Missed one big file to split up.
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
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
15 one of the strings ``'<stdin>'`` or ``'???'``.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
16
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
17
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
18 .. c:function:: void PyOS_AfterFork()
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
19
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
20 Function to update some internal state after a process fork; this should be
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
21 called in the new process if the Python interpreter will continue to be used.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
22 If a new executable is loaded into the new process, this function does not need
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
23 to be called.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
24
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
25
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
26 .. c:function:: int PyOS_CheckStack()
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
27
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
28 Return true when the interpreter runs out of stack space. This is a reliable
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
29 check, but is only available when :const:`USE_STACKCHECK` is defined (currently
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
30 on Windows using the Microsoft Visual C++ compiler). :const:`USE_STACKCHECK`
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
31 will be defined automatically; you should never change the definition in your
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
32 own code.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
33
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
34
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
35 .. c:function:: PyOS_sighandler_t PyOS_getsig(int i)
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
36
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
37 Return the current signal handler for signal *i*. This is a thin wrapper around
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
38 either :c:func:`sigaction` or :c:func:`signal`. Do not call those functions
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
39 directly! :c:type:`PyOS_sighandler_t` is a typedef alias for :c:type:`void
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
40 (\*)(int)`.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
41
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
42
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
43 .. c:function:: PyOS_sighandler_t PyOS_setsig(int i, PyOS_sighandler_t h)
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
44
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
45 Set the signal handler for signal *i* to be *h*; return the old signal handler.
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
46 This is a thin wrapper around either :c:func:`sigaction` or :c:func:`signal`. Do
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
47 not call those functions directly! :c:type:`PyOS_sighandler_t` is a typedef
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
48 alias for :c:type:`void (\*)(int)`.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
49
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
50 .. _systemfunctions:
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
51
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
52 System Functions
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
53 ================
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
54
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
55 These are utility functions that make functionality from the :mod:`sys` module
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
56 accessible to C code. They all work with the current interpreter thread's
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
57 :mod:`sys` module's dict, which is contained in the internal thread state structure.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
58
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
59 .. c:function:: PyObject *PySys_GetObject(char *name)
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
60
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
61 Return the object *name* from the :mod:`sys` module or *NULL* if it does
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
62 not exist, without setting an exception.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
63
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
64 .. c:function:: FILE *PySys_GetFile(char *name, FILE *def)
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
65
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
66 Return the :c:type:`FILE*` associated with the object *name* in the
44797
ec02dbe6b051 Missed one big file to split up.
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
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
68 with a :c:type:`FILE*`.
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
69
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
70 .. c:function:: int PySys_SetObject(char *name, PyObject *v)
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
71
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
72 Set *name* in the :mod:`sys` module to *v* unless *v* is *NULL*, in which
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
73 case *name* is deleted from the sys module. Returns ``0`` on success, ``-1``
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
74 on error.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
75
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
76 .. c:function:: void PySys_ResetWarnOptions()
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
77
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
78 Reset :data:`sys.warnoptions` to an empty list.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
79
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
80 .. c:function:: void PySys_AddWarnOption(char *s)
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
81
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
82 Append *s* to :data:`sys.warnoptions`.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
83
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
84 .. c:function:: void PySys_SetPath(char *path)
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
85
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
86 Set :data:`sys.path` to a list object of paths found in *path* which should
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
87 be a list of paths separated with the platform's search path delimiter
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
88 (``:`` on Unix, ``;`` on Windows).
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
89
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
90 .. c:function:: void PySys_WriteStdout(const char *format, ...)
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
91
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
92 Write the output string described by *format* to :data:`sys.stdout`. No
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
93 exceptions are raised, even if truncation occurs (see below).
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
94
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
95 *format* should limit the total size of the formatted output string to
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
96 1000 bytes or less -- after 1000 bytes, the output string is truncated.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
97 In particular, this means that no unrestricted "%s" formats should occur;
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
98 these should be limited using "%.<N>s" where <N> is a decimal number
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
99 calculated so that <N> plus the maximum size of other formatted text does not
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
100 exceed 1000 bytes. Also watch out for "%f", which can print hundreds of
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
101 digits for very large numbers.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
102
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
103 If a problem occurs, or :data:`sys.stdout` is unset, the formatted message
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
104 is written to the real (C level) *stdout*.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
105
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
106 .. c:function:: void PySys_WriteStderr(const char *format, ...)
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
107
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
108 As above, but write to :data:`sys.stderr` or *stderr* instead.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
109
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
110
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
111 .. _processcontrol:
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
112
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
113 Process Control
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
114 ===============
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
115
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
116
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
117 .. c:function:: void Py_FatalError(const char *message)
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
118
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
119 .. index:: single: abort()
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
120
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
121 Print a fatal error message and kill the process. No cleanup is performed.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
122 This function should only be invoked when a condition is detected that would
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
123 make it dangerous to continue using the Python interpreter; e.g., when the
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
124 object administration appears to be corrupted. On Unix, the standard C library
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
125 function :c:func:`abort` is called which will attempt to produce a :file:`core`
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
126 file.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
127
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
128
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
129 .. c:function:: void Py_Exit(int status)
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
130
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
131 .. index::
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
132 single: Py_Finalize()
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
133 single: exit()
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
134
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
135 Exit the current process. This calls :c:func:`Py_Finalize` and then calls the
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
136 standard C library function ``exit(status)``.
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
137
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
138
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
139 .. c:function:: int Py_AtExit(void (*func) ())
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
140
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
141 .. index::
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
142 single: Py_Finalize()
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
143 single: cleanup functions
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
144
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
145 Register a cleanup function to be called by :c:func:`Py_Finalize`. The cleanup
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
146 function will be called with no arguments and should return no value. At most
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
147 32 cleanup functions can be registered. When the registration is successful,
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 68256
diff changeset
148 :c:func:`Py_AtExit` returns ``0``; on failure, it returns ``-1``. The cleanup
44797
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
149 function registered last is called first. Each cleanup function will be called
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
150 at most once. Since Python's internal finalization will have completed before
ec02dbe6b051 Missed one big file to split up.
Georg Brandl <georg@python.org>
parents:
diff changeset
151 the cleanup function, no Python APIs should be called by *func*.