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 .. 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 Set :data:`sys.path` to a list object of paths found in *path* which should 268 be a list of paths separated with the platform's search path delimiter 269 (``:`` on Unix, ``;`` on Windows). 270 271.. c:function:: void PySys_WriteStdout(const char *format, ...) 272 273 Write the output string described by *format* to :data:`sys.stdout`. No 274 exceptions are raised, even if truncation occurs (see below). 275 276 *format* should limit the total size of the formatted output string to 277 1000 bytes or less -- after 1000 bytes, the output string is truncated. 278 In particular, this means that no unrestricted "%s" formats should occur; 279 these should be limited using "%.<N>s" where <N> is a decimal number 280 calculated so that <N> plus the maximum size of other formatted text does not 281 exceed 1000 bytes. Also watch out for "%f", which can print hundreds of 282 digits for very large numbers. 283 284 If a problem occurs, or :data:`sys.stdout` is unset, the formatted message 285 is written to the real (C level) *stdout*. 286 287.. c:function:: void PySys_WriteStderr(const char *format, ...) 288 289 As :c:func:`PySys_WriteStdout`, but write to :data:`sys.stderr` or *stderr* 290 instead. 291 292.. c:function:: void PySys_FormatStdout(const char *format, ...) 293 294 Function similar to PySys_WriteStdout() but format the message using 295 :c:func:`PyUnicode_FromFormatV` and don't truncate the message to an 296 arbitrary length. 297 298 .. versionadded:: 3.2 299 300.. c:function:: void PySys_FormatStderr(const char *format, ...) 301 302 As :c:func:`PySys_FormatStdout`, but write to :data:`sys.stderr` or *stderr* 303 instead. 304 305 .. versionadded:: 3.2 306 307.. c:function:: void PySys_AddXOption(const wchar_t *s) 308 309 This API is kept for backward compatibility: setting 310 :c:member:`PyConfig.xoptions` should be used instead, see :ref:`Python 311 Initialization Configuration <init-config>`. 312 313 Parse *s* as a set of :option:`-X` options and add them to the current 314 options mapping as returned by :c:func:`PySys_GetXOptions`. This function 315 may be called prior to :c:func:`Py_Initialize`. 316 317 .. versionadded:: 3.2 318 319 .. deprecated:: 3.11 320 321.. c:function:: PyObject *PySys_GetXOptions() 322 323 Return the current dictionary of :option:`-X` options, similarly to 324 :data:`sys._xoptions`. On error, ``NULL`` is returned and an exception is 325 set. 326 327 .. versionadded:: 3.2 328 329 330.. c:function:: int PySys_Audit(const char *event, const char *format, ...) 331 332 Raise an auditing event with any active hooks. Return zero for success 333 and non-zero with an exception set on failure. 334 335 If any hooks have been added, *format* and other arguments will be used 336 to construct a tuple to pass. Apart from ``N``, the same format characters 337 as used in :c:func:`Py_BuildValue` are available. If the built value is not 338 a tuple, it will be added into a single-element tuple. (The ``N`` format 339 option consumes a reference, but since there is no way to know whether 340 arguments to this function will be consumed, using it may cause reference 341 leaks.) 342 343 Note that ``#`` format characters should always be treated as 344 ``Py_ssize_t``, regardless of whether ``PY_SSIZE_T_CLEAN`` was defined. 345 346 :func:`sys.audit` performs the same function from Python code. 347 348 .. versionadded:: 3.8 349 350 .. versionchanged:: 3.8.2 351 352 Require ``Py_ssize_t`` for ``#`` format characters. Previously, an 353 unavoidable deprecation warning was raised. 354 355 356.. c:function:: int PySys_AddAuditHook(Py_AuditHookFunction hook, void *userData) 357 358 Append the callable *hook* to the list of active auditing hooks. 359 Return zero for success 360 and non-zero on failure. If the runtime has been initialized, also set an 361 error on failure. Hooks added through this API are called for all 362 interpreters created by the runtime. 363 364 The *userData* pointer is passed into the hook function. Since hook 365 functions may be called from different runtimes, this pointer should not 366 refer directly to Python state. 367 368 This function is safe to call before :c:func:`Py_Initialize`. When called 369 after runtime initialization, existing audit hooks are notified and may 370 silently abort the operation by raising an error subclassed from 371 :class:`Exception` (other errors will not be silenced). 372 373 The hook function is of type :c:type:`int (*)(const char *event, PyObject 374 *args, void *userData)`, where *args* is guaranteed to be a 375 :c:type:`PyTupleObject`. The hook function is always called with the GIL 376 held by the Python interpreter that raised the event. 377 378 See :pep:`578` for a detailed description of auditing. Functions in the 379 runtime and standard library that raise events are listed in the 380 :ref:`audit events table <audit-events>`. 381 Details are in each function's documentation. 382 383 .. audit-event:: sys.addaudithook "" c.PySys_AddAuditHook 384 385 If the interpreter is initialized, this function raises a auditing event 386 ``sys.addaudithook`` with no arguments. If any existing hooks raise an 387 exception derived from :class:`Exception`, the new hook will not be 388 added and the exception is cleared. As a result, callers cannot assume 389 that their hook has been added unless they control all existing hooks. 390 391 .. versionadded:: 3.8 392 393 394.. _processcontrol: 395 396Process Control 397=============== 398 399 400.. c:function:: void Py_FatalError(const char *message) 401 402 .. index:: single: abort() 403 404 Print a fatal error message and kill the process. No cleanup is performed. 405 This function should only be invoked when a condition is detected that would 406 make it dangerous to continue using the Python interpreter; e.g., when the 407 object administration appears to be corrupted. On Unix, the standard C library 408 function :c:func:`abort` is called which will attempt to produce a :file:`core` 409 file. 410 411 The ``Py_FatalError()`` function is replaced with a macro which logs 412 automatically the name of the current function, unless the 413 ``Py_LIMITED_API`` macro is defined. 414 415 .. versionchanged:: 3.9 416 Log the function name automatically. 417 418 419.. c:function:: void Py_Exit(int status) 420 421 .. index:: 422 single: Py_FinalizeEx() 423 single: exit() 424 425 Exit the current process. This calls :c:func:`Py_FinalizeEx` and then calls the 426 standard C library function ``exit(status)``. If :c:func:`Py_FinalizeEx` 427 indicates an error, the exit status is set to 120. 428 429 .. versionchanged:: 3.6 430 Errors from finalization no longer ignored. 431 432 433.. c:function:: int Py_AtExit(void (*func) ()) 434 435 .. index:: 436 single: Py_FinalizeEx() 437 single: cleanup functions 438 439 Register a cleanup function to be called by :c:func:`Py_FinalizeEx`. The cleanup 440 function will be called with no arguments and should return no value. At most 441 32 cleanup functions can be registered. When the registration is successful, 442 :c:func:`Py_AtExit` returns ``0``; on failure, it returns ``-1``. The cleanup 443 function registered last is called first. Each cleanup function will be called 444 at most once. Since Python's internal finalization will have completed before 445 the cleanup function, no Python APIs should be called by *func*. 446