Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1 | .. highlightlang:: c |
| 2 | |
| 3 | .. _os: |
| 4 | |
| 5 | Operating System Utilities |
| 6 | ========================== |
| 7 | |
Brett Cannon | 746102b | 2016-06-09 16:58:38 -0700 | [diff] [blame^] | 8 | .. c:function:: PyObject* PyOS_FSPath(PyObject *path) |
| 9 | |
| 10 | Return the file system representation for *path*. If the object is a |
| 11 | :class:`str` or :class:`bytes` object, then its reference count is |
| 12 | incremented. If the object implements the :class:`os.PathLike` interface, |
| 13 | then ``type(path).__fspath__()`` is returned. Otherwise :exc:`TypeError` is |
| 14 | raised and ``NULL`` is returned. |
| 15 | |
| 16 | .. versionadded:: 3.6 |
| 17 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 18 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 19 | .. c:function:: int Py_FdIsInteractive(FILE *fp, const char *filename) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 20 | |
| 21 | Return true (nonzero) if the standard I/O file *fp* with name *filename* is |
| 22 | deemed interactive. This is the case for files for which ``isatty(fileno(fp))`` |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 23 | is true. If the global flag :c:data:`Py_InteractiveFlag` is true, this function |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 24 | also returns true if the *filename* pointer is *NULL* or if the name is equal to |
| 25 | one of the strings ``'<stdin>'`` or ``'???'``. |
| 26 | |
| 27 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 28 | .. c:function:: void PyOS_AfterFork() |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 29 | |
| 30 | Function to update some internal state after a process fork; this should be |
| 31 | called in the new process if the Python interpreter will continue to be used. |
| 32 | If a new executable is loaded into the new process, this function does not need |
| 33 | to be called. |
| 34 | |
| 35 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 36 | .. c:function:: int PyOS_CheckStack() |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 37 | |
| 38 | Return true when the interpreter runs out of stack space. This is a reliable |
| 39 | check, but is only available when :const:`USE_STACKCHECK` is defined (currently |
| 40 | on Windows using the Microsoft Visual C++ compiler). :const:`USE_STACKCHECK` |
| 41 | will be defined automatically; you should never change the definition in your |
| 42 | own code. |
| 43 | |
| 44 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 45 | .. c:function:: PyOS_sighandler_t PyOS_getsig(int i) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 46 | |
| 47 | Return the current signal handler for signal *i*. This is a thin wrapper around |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 48 | either :c:func:`sigaction` or :c:func:`signal`. Do not call those functions |
| 49 | directly! :c:type:`PyOS_sighandler_t` is a typedef alias for :c:type:`void |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 50 | (\*)(int)`. |
| 51 | |
| 52 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 53 | .. c:function:: PyOS_sighandler_t PyOS_setsig(int i, PyOS_sighandler_t h) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 54 | |
| 55 | Set the signal handler for signal *i* to be *h*; return the old signal handler. |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 56 | This is a thin wrapper around either :c:func:`sigaction` or :c:func:`signal`. Do |
| 57 | not call those functions directly! :c:type:`PyOS_sighandler_t` is a typedef |
| 58 | alias for :c:type:`void (\*)(int)`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 59 | |
Victor Stinner | f6a271a | 2014-08-01 12:28:48 +0200 | [diff] [blame] | 60 | .. c:function:: wchar_t* Py_DecodeLocale(const char* arg, size_t *size) |
| 61 | |
| 62 | Decode a byte string from the locale encoding with the :ref:`surrogateescape |
| 63 | error handler <surrogateescape>`: undecodable bytes are decoded as |
| 64 | characters in range U+DC80..U+DCFF. If a byte sequence can be decoded as a |
| 65 | surrogate character, escape the bytes using the surrogateescape error |
| 66 | handler instead of decoding them. |
| 67 | |
| 68 | Return a pointer to a newly allocated wide character string, use |
| 69 | :c:func:`PyMem_RawFree` to free the memory. If size is not ``NULL``, write |
| 70 | the number of wide characters excluding the null character into ``*size`` |
| 71 | |
| 72 | Return ``NULL`` on decoding error or memory allocation error. If *size* is |
| 73 | not ``NULL``, ``*size`` is set to ``(size_t)-1`` on memory error or set to |
| 74 | ``(size_t)-2`` on decoding error. |
| 75 | |
| 76 | Decoding errors should never happen, unless there is a bug in the C |
| 77 | library. |
| 78 | |
| 79 | Use the :c:func:`Py_EncodeLocale` function to encode the character string |
| 80 | back to a byte string. |
| 81 | |
| 82 | .. seealso:: |
| 83 | |
| 84 | The :c:func:`PyUnicode_DecodeFSDefaultAndSize` and |
| 85 | :c:func:`PyUnicode_DecodeLocaleAndSize` functions. |
| 86 | |
| 87 | .. versionadded:: 3.5 |
| 88 | |
| 89 | |
| 90 | .. c:function:: char* Py_EncodeLocale(const wchar_t *text, size_t *error_pos) |
| 91 | |
| 92 | Encode a wide character string to the locale encoding with the |
| 93 | :ref:`surrogateescape error handler <surrogateescape>`: surrogate characters |
| 94 | in the range U+DC80..U+DCFF are converted to bytes 0x80..0xFF. |
| 95 | |
| 96 | Return a pointer to a newly allocated byte string, use :c:func:`PyMem_Free` |
| 97 | to free the memory. Return ``NULL`` on encoding error or memory allocation |
| 98 | error |
| 99 | |
| 100 | If error_pos is not ``NULL``, ``*error_pos`` is set to the index of the |
| 101 | invalid character on encoding error, or set to ``(size_t)-1`` otherwise. |
| 102 | |
| 103 | Use the :c:func:`Py_DecodeLocale` function to decode the bytes string back |
| 104 | to a wide character string. |
| 105 | |
| 106 | .. seealso:: |
| 107 | |
| 108 | The :c:func:`PyUnicode_EncodeFSDefault` and |
| 109 | :c:func:`PyUnicode_EncodeLocale` functions. |
| 110 | |
| 111 | .. versionadded:: 3.5 |
| 112 | |
| 113 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 114 | .. _systemfunctions: |
| 115 | |
| 116 | System Functions |
| 117 | ================ |
| 118 | |
| 119 | These are utility functions that make functionality from the :mod:`sys` module |
| 120 | accessible to C code. They all work with the current interpreter thread's |
| 121 | :mod:`sys` module's dict, which is contained in the internal thread state structure. |
| 122 | |
Serhiy Storchaka | 03863d2 | 2015-06-21 17:11:21 +0300 | [diff] [blame] | 123 | .. c:function:: PyObject *PySys_GetObject(const char *name) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 124 | |
| 125 | Return the object *name* from the :mod:`sys` module or *NULL* if it does |
| 126 | not exist, without setting an exception. |
| 127 | |
Serhiy Storchaka | 03863d2 | 2015-06-21 17:11:21 +0300 | [diff] [blame] | 128 | .. c:function:: int PySys_SetObject(const char *name, PyObject *v) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 129 | |
| 130 | Set *name* in the :mod:`sys` module to *v* unless *v* is *NULL*, in which |
| 131 | case *name* is deleted from the sys module. Returns ``0`` on success, ``-1`` |
| 132 | on error. |
| 133 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 134 | .. c:function:: void PySys_ResetWarnOptions() |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 135 | |
| 136 | Reset :data:`sys.warnoptions` to an empty list. |
| 137 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 138 | .. c:function:: void PySys_AddWarnOption(wchar_t *s) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 139 | |
| 140 | Append *s* to :data:`sys.warnoptions`. |
| 141 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 142 | .. c:function:: void PySys_AddWarnOptionUnicode(PyObject *unicode) |
Victor Stinner | 9ca9c25 | 2010-05-19 16:53:30 +0000 | [diff] [blame] | 143 | |
| 144 | Append *unicode* to :data:`sys.warnoptions`. |
| 145 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 146 | .. c:function:: void PySys_SetPath(wchar_t *path) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 147 | |
| 148 | Set :data:`sys.path` to a list object of paths found in *path* which should |
| 149 | be a list of paths separated with the platform's search path delimiter |
| 150 | (``:`` on Unix, ``;`` on Windows). |
| 151 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 152 | .. c:function:: void PySys_WriteStdout(const char *format, ...) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 153 | |
| 154 | Write the output string described by *format* to :data:`sys.stdout`. No |
| 155 | exceptions are raised, even if truncation occurs (see below). |
| 156 | |
| 157 | *format* should limit the total size of the formatted output string to |
| 158 | 1000 bytes or less -- after 1000 bytes, the output string is truncated. |
| 159 | In particular, this means that no unrestricted "%s" formats should occur; |
| 160 | these should be limited using "%.<N>s" where <N> is a decimal number |
| 161 | calculated so that <N> plus the maximum size of other formatted text does not |
| 162 | exceed 1000 bytes. Also watch out for "%f", which can print hundreds of |
| 163 | digits for very large numbers. |
| 164 | |
| 165 | If a problem occurs, or :data:`sys.stdout` is unset, the formatted message |
| 166 | is written to the real (C level) *stdout*. |
| 167 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 168 | .. c:function:: void PySys_WriteStderr(const char *format, ...) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 169 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 170 | As :c:func:`PySys_WriteStdout`, but write to :data:`sys.stderr` or *stderr* |
Victor Stinner | 7976663 | 2010-08-16 17:36:42 +0000 | [diff] [blame] | 171 | instead. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 172 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 173 | .. c:function:: void PySys_FormatStdout(const char *format, ...) |
Victor Stinner | 7976663 | 2010-08-16 17:36:42 +0000 | [diff] [blame] | 174 | |
| 175 | Function similar to PySys_WriteStdout() but format the message using |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 176 | :c:func:`PyUnicode_FromFormatV` and don't truncate the message to an |
Victor Stinner | 7976663 | 2010-08-16 17:36:42 +0000 | [diff] [blame] | 177 | arbitrary length. |
| 178 | |
Victor Stinner | ad5b1df | 2010-08-16 18:39:49 +0000 | [diff] [blame] | 179 | .. versionadded:: 3.2 |
| 180 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 181 | .. c:function:: void PySys_FormatStderr(const char *format, ...) |
Victor Stinner | 7976663 | 2010-08-16 17:36:42 +0000 | [diff] [blame] | 182 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 183 | As :c:func:`PySys_FormatStdout`, but write to :data:`sys.stderr` or *stderr* |
Victor Stinner | 7976663 | 2010-08-16 17:36:42 +0000 | [diff] [blame] | 184 | instead. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 185 | |
Victor Stinner | ad5b1df | 2010-08-16 18:39:49 +0000 | [diff] [blame] | 186 | .. versionadded:: 3.2 |
| 187 | |
Antoine Pitrou | 9583cac | 2010-10-21 13:42:28 +0000 | [diff] [blame] | 188 | .. c:function:: void PySys_AddXOption(const wchar_t *s) |
| 189 | |
| 190 | Parse *s* as a set of :option:`-X` options and add them to the current |
| 191 | options mapping as returned by :c:func:`PySys_GetXOptions`. |
| 192 | |
| 193 | .. versionadded:: 3.2 |
| 194 | |
| 195 | .. c:function:: PyObject *PySys_GetXOptions() |
| 196 | |
| 197 | Return the current dictionary of :option:`-X` options, similarly to |
| 198 | :data:`sys._xoptions`. On error, *NULL* is returned and an exception is |
| 199 | set. |
| 200 | |
| 201 | .. versionadded:: 3.2 |
| 202 | |
Georg Brandl | 67b21b7 | 2010-08-17 15:07:14 +0000 | [diff] [blame] | 203 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 204 | .. _processcontrol: |
| 205 | |
| 206 | Process Control |
| 207 | =============== |
| 208 | |
| 209 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 210 | .. c:function:: void Py_FatalError(const char *message) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 211 | |
| 212 | .. index:: single: abort() |
| 213 | |
| 214 | Print a fatal error message and kill the process. No cleanup is performed. |
| 215 | This function should only be invoked when a condition is detected that would |
| 216 | make it dangerous to continue using the Python interpreter; e.g., when the |
| 217 | object administration appears to be corrupted. On Unix, the standard C library |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 218 | function :c:func:`abort` is called which will attempt to produce a :file:`core` |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 219 | file. |
| 220 | |
| 221 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 222 | .. c:function:: void Py_Exit(int status) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 223 | |
| 224 | .. index:: |
Martin Panter | b4ce1fc | 2015-11-30 03:18:29 +0000 | [diff] [blame] | 225 | single: Py_FinalizeEx() |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 226 | single: exit() |
| 227 | |
Martin Panter | b4ce1fc | 2015-11-30 03:18:29 +0000 | [diff] [blame] | 228 | Exit the current process. This calls :c:func:`Py_FinalizeEx` and then calls the |
| 229 | standard C library function ``exit(status)``. If :c:func:`Py_FinalizeEx` |
| 230 | indicates an error, the exit status is set to 120. |
| 231 | |
| 232 | .. versionchanged:: 3.6 |
| 233 | Errors from finalization no longer ignored. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 234 | |
| 235 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 236 | .. c:function:: int Py_AtExit(void (*func) ()) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 237 | |
| 238 | .. index:: |
Martin Panter | b4ce1fc | 2015-11-30 03:18:29 +0000 | [diff] [blame] | 239 | single: Py_FinalizeEx() |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 240 | single: cleanup functions |
| 241 | |
Martin Panter | b4ce1fc | 2015-11-30 03:18:29 +0000 | [diff] [blame] | 242 | Register a cleanup function to be called by :c:func:`Py_FinalizeEx`. The cleanup |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 243 | function will be called with no arguments and should return no value. At most |
| 244 | 32 cleanup functions can be registered. When the registration is successful, |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 245 | :c:func:`Py_AtExit` returns ``0``; on failure, it returns ``-1``. The cleanup |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 246 | function registered last is called first. Each cleanup function will be called |
| 247 | at most once. Since Python's internal finalization will have completed before |
| 248 | the cleanup function, no Python APIs should be called by *func*. |