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