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 certain versions of Windows using the Microsoft Visual C++ compiler). 100 :const:`USE_STACKCHECK` will be defined automatically; you should never 101 change the definition in your 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:expr:`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:expr:`void (\*)(int)`. 118 119.. c:function:: wchar_t* Py_DecodeLocale(const char* arg, size_t *size) 120 121 .. warning:: 122 This function should not be called directly: use the :c:type:`PyConfig` 123 API with the :c:func:`PyConfig_SetBytesString` function which ensures 124 that :ref:`Python is preinitialized <c-preinit>`. 125 126 This function must not be called before :ref:`Python is preinitialized 127 <c-preinit>` and so that the LC_CTYPE locale is properly configured: see 128 the :c:func:`Py_PreInitialize` function. 129 130 Decode a byte string from the :term:`filesystem encoding and error handler`. 131 If the error handler is :ref:`surrogateescape error handler 132 <surrogateescape>`, undecodable bytes are decoded as characters in range 133 U+DC80..U+DCFF; and if a byte sequence can be decoded as a surrogate 134 character, the bytes are escaped using the surrogateescape error handler 135 instead of decoding them. 136 137 Return a pointer to a newly allocated wide character string, use 138 :c:func:`PyMem_RawFree` to free the memory. If size is not ``NULL``, write 139 the number of wide characters excluding the null character into ``*size`` 140 141 Return ``NULL`` on decoding error or memory allocation error. If *size* is 142 not ``NULL``, ``*size`` is set to ``(size_t)-1`` on memory error or set to 143 ``(size_t)-2`` on decoding error. 144 145 The :term:`filesystem encoding and error handler` are selected by 146 :c:func:`PyConfig_Read`: see :c:member:`~PyConfig.filesystem_encoding` and 147 :c:member:`~PyConfig.filesystem_errors` members of :c:type:`PyConfig`. 148 149 Decoding errors should never happen, unless there is a bug in the C 150 library. 151 152 Use the :c:func:`Py_EncodeLocale` function to encode the character string 153 back to a byte string. 154 155 .. seealso:: 156 157 The :c:func:`PyUnicode_DecodeFSDefaultAndSize` and 158 :c:func:`PyUnicode_DecodeLocaleAndSize` functions. 159 160 .. versionadded:: 3.5 161 162 .. versionchanged:: 3.7 163 The function now uses the UTF-8 encoding in the :ref:`Python UTF-8 Mode 164 <utf8-mode>`. 165 166 .. versionchanged:: 3.8 167 The function now uses the UTF-8 encoding on Windows if 168 :c:data:`Py_LegacyWindowsFSEncodingFlag` is zero; 169 170 171.. c:function:: char* Py_EncodeLocale(const wchar_t *text, size_t *error_pos) 172 173 Encode a wide character string to the :term:`filesystem encoding and error 174 handler`. If the error handler is :ref:`surrogateescape error handler 175 <surrogateescape>`, surrogate characters in the range U+DC80..U+DCFF are 176 converted to bytes 0x80..0xFF. 177 178 Return a pointer to a newly allocated byte string, use :c:func:`PyMem_Free` 179 to free the memory. Return ``NULL`` on encoding error or memory allocation 180 error. 181 182 If error_pos is not ``NULL``, ``*error_pos`` is set to ``(size_t)-1`` on 183 success, or set to the index of the invalid character on encoding error. 184 185 The :term:`filesystem encoding and error handler` are selected by 186 :c:func:`PyConfig_Read`: see :c:member:`~PyConfig.filesystem_encoding` and 187 :c:member:`~PyConfig.filesystem_errors` members of :c:type:`PyConfig`. 188 189 Use the :c:func:`Py_DecodeLocale` function to decode the bytes string back 190 to a wide character string. 191 192 .. warning:: 193 This function must not be called before :ref:`Python is preinitialized 194 <c-preinit>` and so that the LC_CTYPE locale is properly configured: see 195 the :c:func:`Py_PreInitialize` function. 196 197 .. seealso:: 198 199 The :c:func:`PyUnicode_EncodeFSDefault` and 200 :c:func:`PyUnicode_EncodeLocale` functions. 201 202 .. versionadded:: 3.5 203 204 .. versionchanged:: 3.7 205 The function now uses the UTF-8 encoding in the :ref:`Python UTF-8 Mode 206 <utf8-mode>`. 207 208 .. versionchanged:: 3.8 209 The function now uses the UTF-8 encoding on Windows if 210 :c:data:`Py_LegacyWindowsFSEncodingFlag` is zero. 211 212 213.. _systemfunctions: 214 215System Functions 216================ 217 218These are utility functions that make functionality from the :mod:`sys` module 219accessible to C code. They all work with the current interpreter thread's 220:mod:`sys` module's dict, which is contained in the internal thread state structure. 221 222.. c:function:: PyObject *PySys_GetObject(const char *name) 223 224 Return the object *name* from the :mod:`sys` module or ``NULL`` if it does 225 not exist, without setting an exception. 226 227.. c:function:: int PySys_SetObject(const char *name, PyObject *v) 228 229 Set *name* in the :mod:`sys` module to *v* unless *v* is ``NULL``, in which 230 case *name* is deleted from the sys module. Returns ``0`` on success, ``-1`` 231 on error. 232 233.. c:function:: void PySys_ResetWarnOptions() 234 235 Reset :data:`sys.warnoptions` to an empty list. This function may be 236 called prior to :c:func:`Py_Initialize`. 237 238.. c:function:: void PySys_AddWarnOption(const wchar_t *s) 239 240 This API is kept for backward compatibility: setting 241 :c:member:`PyConfig.warnoptions` should be used instead, see :ref:`Python 242 Initialization Configuration <init-config>`. 243 244 Append *s* to :data:`sys.warnoptions`. This function must be called prior 245 to :c:func:`Py_Initialize` in order to affect the warnings filter list. 246 247 .. deprecated:: 3.11 248 249.. c:function:: void PySys_AddWarnOptionUnicode(PyObject *unicode) 250 251 This API is kept for backward compatibility: setting 252 :c:member:`PyConfig.warnoptions` should be used instead, see :ref:`Python 253 Initialization Configuration <init-config>`. 254 255 Append *unicode* to :data:`sys.warnoptions`. 256 257 Note: this function is not currently usable from outside the CPython 258 implementation, as it must be called prior to the implicit import of 259 :mod:`warnings` in :c:func:`Py_Initialize` to be effective, but can't be 260 called until enough of the runtime has been initialized to permit the 261 creation of Unicode objects. 262 263 .. deprecated:: 3.11 264 265.. c:function:: void PySys_SetPath(const wchar_t *path) 266 267 This API is kept for backward compatibility: setting 268 :c:member:`PyConfig.module_search_paths` and 269 :c:member:`PyConfig.module_search_paths_set` should be used instead, see 270 :ref:`Python Initialization Configuration <init-config>`. 271 272 Set :data:`sys.path` to a list object of paths found in *path* which should 273 be a list of paths separated with the platform's search path delimiter 274 (``:`` on Unix, ``;`` on Windows). 275 276 .. deprecated:: 3.11 277 278.. c:function:: void PySys_WriteStdout(const char *format, ...) 279 280 Write the output string described by *format* to :data:`sys.stdout`. No 281 exceptions are raised, even if truncation occurs (see below). 282 283 *format* should limit the total size of the formatted output string to 284 1000 bytes or less -- after 1000 bytes, the output string is truncated. 285 In particular, this means that no unrestricted "%s" formats should occur; 286 these should be limited using "%.<N>s" where <N> is a decimal number 287 calculated so that <N> plus the maximum size of other formatted text does not 288 exceed 1000 bytes. Also watch out for "%f", which can print hundreds of 289 digits for very large numbers. 290 291 If a problem occurs, or :data:`sys.stdout` is unset, the formatted message 292 is written to the real (C level) *stdout*. 293 294.. c:function:: void PySys_WriteStderr(const char *format, ...) 295 296 As :c:func:`PySys_WriteStdout`, but write to :data:`sys.stderr` or *stderr* 297 instead. 298 299.. c:function:: void PySys_FormatStdout(const char *format, ...) 300 301 Function similar to PySys_WriteStdout() but format the message using 302 :c:func:`PyUnicode_FromFormatV` and don't truncate the message to an 303 arbitrary length. 304 305 .. versionadded:: 3.2 306 307.. c:function:: void PySys_FormatStderr(const char *format, ...) 308 309 As :c:func:`PySys_FormatStdout`, but write to :data:`sys.stderr` or *stderr* 310 instead. 311 312 .. versionadded:: 3.2 313 314.. c:function:: void PySys_AddXOption(const wchar_t *s) 315 316 This API is kept for backward compatibility: setting 317 :c:member:`PyConfig.xoptions` should be used instead, see :ref:`Python 318 Initialization Configuration <init-config>`. 319 320 Parse *s* as a set of :option:`-X` options and add them to the current 321 options mapping as returned by :c:func:`PySys_GetXOptions`. This function 322 may be called prior to :c:func:`Py_Initialize`. 323 324 .. versionadded:: 3.2 325 326 .. deprecated:: 3.11 327 328.. c:function:: PyObject *PySys_GetXOptions() 329 330 Return the current dictionary of :option:`-X` options, similarly to 331 :data:`sys._xoptions`. On error, ``NULL`` is returned and an exception is 332 set. 333 334 .. versionadded:: 3.2 335 336 337.. c:function:: int PySys_Audit(const char *event, const char *format, ...) 338 339 Raise an auditing event with any active hooks. Return zero for success 340 and non-zero with an exception set on failure. 341 342 If any hooks have been added, *format* and other arguments will be used 343 to construct a tuple to pass. Apart from ``N``, the same format characters 344 as used in :c:func:`Py_BuildValue` are available. If the built value is not 345 a tuple, it will be added into a single-element tuple. (The ``N`` format 346 option consumes a reference, but since there is no way to know whether 347 arguments to this function will be consumed, using it may cause reference 348 leaks.) 349 350 Note that ``#`` format characters should always be treated as 351 :c:type:`Py_ssize_t`, regardless of whether ``PY_SSIZE_T_CLEAN`` was defined. 352 353 :func:`sys.audit` performs the same function from Python code. 354 355 .. versionadded:: 3.8 356 357 .. versionchanged:: 3.8.2 358 359 Require :c:type:`Py_ssize_t` for ``#`` format characters. Previously, an 360 unavoidable deprecation warning was raised. 361 362 363.. c:function:: int PySys_AddAuditHook(Py_AuditHookFunction hook, void *userData) 364 365 Append the callable *hook* to the list of active auditing hooks. 366 Return zero on success 367 and non-zero on failure. If the runtime has been initialized, also set an 368 error on failure. Hooks added through this API are called for all 369 interpreters created by the runtime. 370 371 The *userData* pointer is passed into the hook function. Since hook 372 functions may be called from different runtimes, this pointer should not 373 refer directly to Python state. 374 375 This function is safe to call before :c:func:`Py_Initialize`. When called 376 after runtime initialization, existing audit hooks are notified and may 377 silently abort the operation by raising an error subclassed from 378 :class:`Exception` (other errors will not be silenced). 379 380 The hook function is of type :c:expr:`int (*)(const char *event, PyObject 381 *args, void *userData)`, where *args* is guaranteed to be a 382 :c:type:`PyTupleObject`. The hook function is always called with the GIL 383 held by the Python interpreter that raised the event. 384 385 See :pep:`578` for a detailed description of auditing. Functions in the 386 runtime and standard library that raise events are listed in the 387 :ref:`audit events table <audit-events>`. 388 Details are in each function's documentation. 389 390 .. audit-event:: sys.addaudithook "" c.PySys_AddAuditHook 391 392 If the interpreter is initialized, this function raises a auditing event 393 ``sys.addaudithook`` with no arguments. If any existing hooks raise an 394 exception derived from :class:`Exception`, the new hook will not be 395 added and the exception is cleared. As a result, callers cannot assume 396 that their hook has been added unless they control all existing hooks. 397 398 .. versionadded:: 3.8 399 400 401.. _processcontrol: 402 403Process Control 404=============== 405 406 407.. c:function:: void Py_FatalError(const char *message) 408 409 .. index:: single: abort() 410 411 Print a fatal error message and kill the process. No cleanup is performed. 412 This function should only be invoked when a condition is detected that would 413 make it dangerous to continue using the Python interpreter; e.g., when the 414 object administration appears to be corrupted. On Unix, the standard C library 415 function :c:func:`abort` is called which will attempt to produce a :file:`core` 416 file. 417 418 The ``Py_FatalError()`` function is replaced with a macro which logs 419 automatically the name of the current function, unless the 420 ``Py_LIMITED_API`` macro is defined. 421 422 .. versionchanged:: 3.9 423 Log the function name automatically. 424 425 426.. c:function:: void Py_Exit(int status) 427 428 .. index:: 429 single: Py_FinalizeEx() 430 single: exit() 431 432 Exit the current process. This calls :c:func:`Py_FinalizeEx` and then calls the 433 standard C library function ``exit(status)``. If :c:func:`Py_FinalizeEx` 434 indicates an error, the exit status is set to 120. 435 436 .. versionchanged:: 3.6 437 Errors from finalization no longer ignored. 438 439 440.. c:function:: int Py_AtExit(void (*func) ()) 441 442 .. index:: 443 single: Py_FinalizeEx() 444 single: cleanup functions 445 446 Register a cleanup function to be called by :c:func:`Py_FinalizeEx`. The cleanup 447 function will be called with no arguments and should return no value. At most 448 32 cleanup functions can be registered. When the registration is successful, 449 :c:func:`Py_AtExit` returns ``0``; on failure, it returns ``-1``. The cleanup 450 function registered last is called first. Each cleanup function will be called 451 at most once. Since Python's internal finalization will have completed before 452 the cleanup function, no Python APIs should be called by *func*. 453