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