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