1.. highlight:: c 2 3.. _os: 4 5Operating 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_BeforeFork() 30 31 Function to prepare some internal state before a process fork. This 32 should be called before calling :c:func:`fork` or any similar function 33 that clones the current process. 34 Only available on systems where :c:func:`fork` is defined. 35 36 .. warning:: 37 The C :c:func:`fork` call should only be made from the 38 :ref:`"main" thread <fork-and-threads>` (of the 39 :ref:`"main" interpreter <sub-interpreter-support>`). The same is 40 true for ``PyOS_BeforeFork()``. 41 42 .. versionadded:: 3.7 43 44 45.. c:function:: void PyOS_AfterFork_Parent() 46 47 Function to update some internal state after a process fork. This 48 should be called from the parent process after calling :c:func:`fork` 49 or any similar function that clones the current process, regardless 50 of whether process cloning was successful. 51 Only available on systems where :c:func:`fork` is defined. 52 53 .. warning:: 54 The C :c:func:`fork` call should only be made from the 55 :ref:`"main" thread <fork-and-threads>` (of the 56 :ref:`"main" interpreter <sub-interpreter-support>`). The same is 57 true for ``PyOS_AfterFork_Parent()``. 58 59 .. versionadded:: 3.7 60 61 62.. c:function:: void PyOS_AfterFork_Child() 63 64 Function to update internal interpreter state after a process fork. 65 This must be called from the child process after calling :c:func:`fork`, 66 or any similar function that clones the current process, if there is 67 any chance the process will call back into the Python interpreter. 68 Only available on systems where :c:func:`fork` is defined. 69 70 .. warning:: 71 The C :c:func:`fork` call should only be made from the 72 :ref:`"main" thread <fork-and-threads>` (of the 73 :ref:`"main" interpreter <sub-interpreter-support>`). The same is 74 true for ``PyOS_AfterFork_Child()``. 75 76 .. versionadded:: 3.7 77 78 .. seealso:: 79 :func:`os.register_at_fork` allows registering custom Python functions 80 to be called by :c:func:`PyOS_BeforeFork()`, 81 :c:func:`PyOS_AfterFork_Parent` and :c:func:`PyOS_AfterFork_Child`. 82 83 84.. c:function:: void PyOS_AfterFork() 85 86 Function to update some internal state after a process fork; this should be 87 called in the new process if the Python interpreter will continue to be used. 88 If a new executable is loaded into the new process, this function does not need 89 to be called. 90 91 .. deprecated:: 3.7 92 This function is superseded by :c:func:`PyOS_AfterFork_Child()`. 93 94 95.. c:function:: int PyOS_CheckStack() 96 97 Return true when the interpreter runs out of stack space. This is a reliable 98 check, but is only available when :const:`USE_STACKCHECK` is defined (currently 99 on Windows using the Microsoft Visual C++ compiler). :const:`USE_STACKCHECK` 100 will be defined automatically; you should never change the definition in your 101 own code. 102 103 104.. c:function:: PyOS_sighandler_t PyOS_getsig(int i) 105 106 Return the current signal handler for signal *i*. This is a thin wrapper around 107 either :c:func:`sigaction` or :c:func:`signal`. Do not call those functions 108 directly! :c:type:`PyOS_sighandler_t` is a typedef alias for :c:type:`void 109 (\*)(int)`. 110 111 112.. c:function:: PyOS_sighandler_t PyOS_setsig(int i, PyOS_sighandler_t h) 113 114 Set the signal handler for signal *i* to be *h*; return the old signal handler. 115 This is a thin wrapper around either :c:func:`sigaction` or :c:func:`signal`. Do 116 not call those functions directly! :c:type:`PyOS_sighandler_t` is a typedef 117 alias for :c:type:`void (\*)(int)`. 118 119.. c:function:: wchar_t* Py_DecodeLocale(const char* arg, size_t *size) 120 121 Decode a byte string from the locale encoding with the :ref:`surrogateescape 122 error handler <surrogateescape>`: undecodable bytes are decoded as 123 characters in range U+DC80..U+DCFF. If a byte sequence can be decoded as a 124 surrogate character, escape the bytes using the surrogateescape error 125 handler instead of decoding them. 126 127 Encoding, highest priority to lowest priority: 128 129 * ``UTF-8`` on macOS, Android, and VxWorks; 130 * ``UTF-8`` on Windows if :c:data:`Py_LegacyWindowsFSEncodingFlag` is zero; 131 * ``UTF-8`` if the Python UTF-8 mode is enabled; 132 * ``ASCII`` if the ``LC_CTYPE`` locale is ``"C"``, 133 ``nl_langinfo(CODESET)`` returns the ``ASCII`` encoding (or an alias), 134 and :c:func:`mbstowcs` and :c:func:`wcstombs` functions uses the 135 ``ISO-8859-1`` encoding. 136 * the current locale encoding. 137 138 Return a pointer to a newly allocated wide character string, use 139 :c:func:`PyMem_RawFree` to free the memory. If size is not ``NULL``, write 140 the number of wide characters excluding the null character into ``*size`` 141 142 Return ``NULL`` on decoding error or memory allocation error. If *size* is 143 not ``NULL``, ``*size`` is set to ``(size_t)-1`` on memory error or set to 144 ``(size_t)-2`` on decoding error. 145 146 Decoding errors should never happen, unless there is a bug in the C 147 library. 148 149 Use the :c:func:`Py_EncodeLocale` function to encode the character string 150 back to a byte string. 151 152 .. seealso:: 153 154 The :c:func:`PyUnicode_DecodeFSDefaultAndSize` and 155 :c:func:`PyUnicode_DecodeLocaleAndSize` functions. 156 157 .. versionadded:: 3.5 158 159 .. versionchanged:: 3.7 160 The function now uses the UTF-8 encoding in the UTF-8 mode. 161 162 .. versionchanged:: 3.8 163 The function now uses the UTF-8 encoding on Windows if 164 :c:data:`Py_LegacyWindowsFSEncodingFlag` is zero; 165 166 167.. c:function:: char* Py_EncodeLocale(const wchar_t *text, size_t *error_pos) 168 169 Encode a wide character string to the locale encoding with the 170 :ref:`surrogateescape error handler <surrogateescape>`: surrogate characters 171 in the range U+DC80..U+DCFF are converted to bytes 0x80..0xFF. 172 173 Encoding, highest priority to lowest priority: 174 175 * ``UTF-8`` on macOS, Android, and VxWorks; 176 * ``UTF-8`` on Windows if :c:data:`Py_LegacyWindowsFSEncodingFlag` is zero; 177 * ``UTF-8`` if the Python UTF-8 mode is enabled; 178 * ``ASCII`` if the ``LC_CTYPE`` locale is ``"C"``, 179 ``nl_langinfo(CODESET)`` returns the ``ASCII`` encoding (or an alias), 180 and :c:func:`mbstowcs` and :c:func:`wcstombs` functions uses the 181 ``ISO-8859-1`` encoding. 182 * the current locale encoding. 183 184 The function uses the UTF-8 encoding in the Python UTF-8 mode. 185 186 Return a pointer to a newly allocated byte string, use :c:func:`PyMem_Free` 187 to free the memory. Return ``NULL`` on encoding error or memory allocation 188 error 189 190 If error_pos is not ``NULL``, ``*error_pos`` is set to ``(size_t)-1`` on 191 success, or set to the index of the invalid character on encoding error. 192 193 Use the :c:func:`Py_DecodeLocale` function to decode the bytes string back 194 to a wide character string. 195 196 .. seealso:: 197 198 The :c:func:`PyUnicode_EncodeFSDefault` and 199 :c:func:`PyUnicode_EncodeLocale` functions. 200 201 .. versionadded:: 3.5 202 203 .. versionchanged:: 3.7 204 The function now uses the UTF-8 encoding in the UTF-8 mode. 205 206 .. versionchanged:: 3.8 207 The function now uses the UTF-8 encoding on Windows if 208 :c:data:`Py_LegacyWindowsFSEncodingFlag` is zero; 209 210 211.. _systemfunctions: 212 213System Functions 214================ 215 216These are utility functions that make functionality from the :mod:`sys` module 217accessible to C code. They all work with the current interpreter thread's 218:mod:`sys` module's dict, which is contained in the internal thread state structure. 219 220.. c:function:: PyObject *PySys_GetObject(const char *name) 221 222 Return the object *name* from the :mod:`sys` module or ``NULL`` if it does 223 not exist, without setting an exception. 224 225.. c:function:: int PySys_SetObject(const char *name, PyObject *v) 226 227 Set *name* in the :mod:`sys` module to *v* unless *v* is ``NULL``, in which 228 case *name* is deleted from the sys module. Returns ``0`` on success, ``-1`` 229 on error. 230 231.. c:function:: void PySys_ResetWarnOptions() 232 233 Reset :data:`sys.warnoptions` to an empty list. This function may be 234 called prior to :c:func:`Py_Initialize`. 235 236.. c:function:: void PySys_AddWarnOption(const wchar_t *s) 237 238 Append *s* to :data:`sys.warnoptions`. This function must be called prior 239 to :c:func:`Py_Initialize` in order to affect the warnings filter list. 240 241.. c:function:: void PySys_AddWarnOptionUnicode(PyObject *unicode) 242 243 Append *unicode* to :data:`sys.warnoptions`. 244 245 Note: this function is not currently usable from outside the CPython 246 implementation, as it must be called prior to the implicit import of 247 :mod:`warnings` in :c:func:`Py_Initialize` to be effective, but can't be 248 called until enough of the runtime has been initialized to permit the 249 creation of Unicode objects. 250 251.. c:function:: void PySys_SetPath(const wchar_t *path) 252 253 Set :data:`sys.path` to a list object of paths found in *path* which should 254 be a list of paths separated with the platform's search path delimiter 255 (``:`` on Unix, ``;`` on Windows). 256 257.. c:function:: void PySys_WriteStdout(const char *format, ...) 258 259 Write the output string described by *format* to :data:`sys.stdout`. No 260 exceptions are raised, even if truncation occurs (see below). 261 262 *format* should limit the total size of the formatted output string to 263 1000 bytes or less -- after 1000 bytes, the output string is truncated. 264 In particular, this means that no unrestricted "%s" formats should occur; 265 these should be limited using "%.<N>s" where <N> is a decimal number 266 calculated so that <N> plus the maximum size of other formatted text does not 267 exceed 1000 bytes. Also watch out for "%f", which can print hundreds of 268 digits for very large numbers. 269 270 If a problem occurs, or :data:`sys.stdout` is unset, the formatted message 271 is written to the real (C level) *stdout*. 272 273.. c:function:: void PySys_WriteStderr(const char *format, ...) 274 275 As :c:func:`PySys_WriteStdout`, but write to :data:`sys.stderr` or *stderr* 276 instead. 277 278.. c:function:: void PySys_FormatStdout(const char *format, ...) 279 280 Function similar to PySys_WriteStdout() but format the message using 281 :c:func:`PyUnicode_FromFormatV` and don't truncate the message to an 282 arbitrary length. 283 284 .. versionadded:: 3.2 285 286.. c:function:: void PySys_FormatStderr(const char *format, ...) 287 288 As :c:func:`PySys_FormatStdout`, but write to :data:`sys.stderr` or *stderr* 289 instead. 290 291 .. versionadded:: 3.2 292 293.. c:function:: void PySys_AddXOption(const wchar_t *s) 294 295 Parse *s* as a set of :option:`-X` options and add them to the current 296 options mapping as returned by :c:func:`PySys_GetXOptions`. This function 297 may be called prior to :c:func:`Py_Initialize`. 298 299 .. versionadded:: 3.2 300 301.. c:function:: PyObject *PySys_GetXOptions() 302 303 Return the current dictionary of :option:`-X` options, similarly to 304 :data:`sys._xoptions`. On error, ``NULL`` is returned and an exception is 305 set. 306 307 .. versionadded:: 3.2 308 309 310.. c:function:: int PySys_Audit(const char *event, const char *format, ...) 311 312 Raise an auditing event with any active hooks. Return zero for success 313 and non-zero with an exception set on failure. 314 315 If any hooks have been added, *format* and other arguments will be used 316 to construct a tuple to pass. Apart from ``N``, the same format characters 317 as used in :c:func:`Py_BuildValue` are available. If the built value is not 318 a tuple, it will be added into a single-element tuple. (The ``N`` format 319 option consumes a reference, but since there is no way to know whether 320 arguments to this function will be consumed, using it may cause reference 321 leaks.) 322 323 Note that ``#`` format characters should always be treated as 324 ``Py_ssize_t``, regardless of whether ``PY_SSIZE_T_CLEAN`` was defined. 325 326 :func:`sys.audit` performs the same function from Python code. 327 328 .. versionadded:: 3.8 329 330 .. versionchanged:: 3.8.2 331 332 Require ``Py_ssize_t`` for ``#`` format characters. Previously, an 333 unavoidable deprecation warning was raised. 334 335 336.. c:function:: int PySys_AddAuditHook(Py_AuditHookFunction hook, void *userData) 337 338 Append the callable *hook* to the list of active auditing hooks. 339 Return zero for success 340 and non-zero on failure. If the runtime has been initialized, also set an 341 error on failure. Hooks added through this API are called for all 342 interpreters created by the runtime. 343 344 The *userData* pointer is passed into the hook function. Since hook 345 functions may be called from different runtimes, this pointer should not 346 refer directly to Python state. 347 348 This function is safe to call before :c:func:`Py_Initialize`. When called 349 after runtime initialization, existing audit hooks are notified and may 350 silently abort the operation by raising an error subclassed from 351 :class:`Exception` (other errors will not be silenced). 352 353 The hook function is of type :c:type:`int (*)(const char *event, PyObject 354 *args, void *userData)`, where *args* is guaranteed to be a 355 :c:type:`PyTupleObject`. The hook function is always called with the GIL 356 held by the Python interpreter that raised the event. 357 358 See :pep:`578` for a detailed description of auditing. Functions in the 359 runtime and standard library that raise events are listed in the 360 :ref:`audit events table <audit-events>`. 361 Details are in each function's documentation. 362 363 .. audit-event:: sys.addaudithook "" c.PySys_AddAuditHook 364 365 If the interpreter is initialized, this function raises a auditing event 366 ``sys.addaudithook`` with no arguments. If any existing hooks raise an 367 exception derived from :class:`Exception`, the new hook will not be 368 added and the exception is cleared. As a result, callers cannot assume 369 that their hook has been added unless they control all existing hooks. 370 371 .. versionadded:: 3.8 372 373 374.. _processcontrol: 375 376Process Control 377=============== 378 379 380.. c:function:: void Py_FatalError(const char *message) 381 382 .. index:: single: abort() 383 384 Print a fatal error message and kill the process. No cleanup is performed. 385 This function should only be invoked when a condition is detected that would 386 make it dangerous to continue using the Python interpreter; e.g., when the 387 object administration appears to be corrupted. On Unix, the standard C library 388 function :c:func:`abort` is called which will attempt to produce a :file:`core` 389 file. 390 391 392.. c:function:: void Py_Exit(int status) 393 394 .. index:: 395 single: Py_FinalizeEx() 396 single: exit() 397 398 Exit the current process. This calls :c:func:`Py_FinalizeEx` and then calls the 399 standard C library function ``exit(status)``. If :c:func:`Py_FinalizeEx` 400 indicates an error, the exit status is set to 120. 401 402 .. versionchanged:: 3.6 403 Errors from finalization no longer ignored. 404 405 406.. c:function:: int Py_AtExit(void (*func) ()) 407 408 .. index:: 409 single: Py_FinalizeEx() 410 single: cleanup functions 411 412 Register a cleanup function to be called by :c:func:`Py_FinalizeEx`. The cleanup 413 function will be called with no arguments and should return no value. At most 414 32 cleanup functions can be registered. When the registration is successful, 415 :c:func:`Py_AtExit` returns ``0``; on failure, it returns ``-1``. The cleanup 416 function registered last is called first. Each cleanup function will be called 417 at most once. Since Python's internal finalization will have completed before 418 the cleanup function, no Python APIs should be called by *func*. 419