path: root/devdocs/python~3.12/c-api%2Fsys.html

 <span id="os"></span><h1>Operating System Utilities</h1> <dl class="c function"> <dt class="sig sig-object c" id="c.PyOS_FSPath">
<code>PyObject *PyOS_FSPath(PyObject *path)</code> </dt> <dd>
<em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.6.</em><p>Return the file system representation for <em>path</em>. If the object is a <a class="reference internal" href="../library/stdtypes#str" title="str"><code>str</code></a> or <a class="reference internal" href="../library/stdtypes#bytes" title="bytes"><code>bytes</code></a> object, then a new <a class="reference internal" href="../glossary#term-strong-reference"><span class="xref std std-term">strong reference</span></a> is returned. If the object implements the <a class="reference internal" href="../library/os#os.PathLike" title="os.PathLike"><code>os.PathLike</code></a> interface, then <a class="reference internal" href="../library/os#os.PathLike.__fspath__" title="os.PathLike.__fspath__"><code>__fspath__()</code></a> is returned as long as it is a <a class="reference internal" href="../library/stdtypes#str" title="str"><code>str</code></a> or <a class="reference internal" href="../library/stdtypes#bytes" title="bytes"><code>bytes</code></a> object. Otherwise <a class="reference internal" href="../library/exceptions#TypeError" title="TypeError"><code>TypeError</code></a> is raised and <code>NULL</code> is returned.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.6.</span></p> </div> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.Py_FdIsInteractive">
<code>int Py_FdIsInteractive(FILE *fp, const char *filename)</code> </dt> <dd>
<p>Return true (nonzero) if the standard I/O file <em>fp</em> with name <em>filename</em> is deemed interactive. This is the case for files for which <code>isatty(fileno(fp))</code> is true. If the <a class="reference internal" href="init_config#c.PyConfig.interactive" title="PyConfig.interactive"><code>PyConfig.interactive</code></a> is non-zero, this function also returns true if the <em>filename</em> pointer is <code>NULL</code> or if the name is equal to one of the strings <code>'&lt;stdin&gt;'</code> or <code>'???'</code>.</p> <p>This function must not be called before Python is initialized.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyOS_BeforeFork">
<code>void PyOS_BeforeFork()</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a> on platforms with fork() since version 3.7.</em><p>Function to prepare some internal state before a process fork. This should be called before calling <code>fork()</code> or any similar function that clones the current process. Only available on systems where <code>fork()</code> is defined.</p> <div class="admonition warning"> <p class="admonition-title">Warning</p> <p>The C <code>fork()</code> call should only be made from the <a class="reference internal" href="init#fork-and-threads"><span class="std std-ref">“main” thread</span></a> (of the <a class="reference internal" href="init#sub-interpreter-support"><span class="std std-ref">“main” interpreter</span></a>). The same is true for <code>PyOS_BeforeFork()</code>.</p> </div> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.7.</span></p> </div> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyOS_AfterFork_Parent">
<code>void PyOS_AfterFork_Parent()</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a> on platforms with fork() since version 3.7.</em><p>Function to update some internal state after a process fork. This should be called from the parent process after calling <code>fork()</code> or any similar function that clones the current process, regardless of whether process cloning was successful. Only available on systems where <code>fork()</code> is defined.</p> <div class="admonition warning"> <p class="admonition-title">Warning</p> <p>The C <code>fork()</code> call should only be made from the <a class="reference internal" href="init#fork-and-threads"><span class="std std-ref">“main” thread</span></a> (of the <a class="reference internal" href="init#sub-interpreter-support"><span class="std std-ref">“main” interpreter</span></a>). The same is true for <code>PyOS_AfterFork_Parent()</code>.</p> </div> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.7.</span></p> </div> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyOS_AfterFork_Child">
<code>void PyOS_AfterFork_Child()</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a> on platforms with fork() since version 3.7.</em><p>Function to update internal interpreter state after a process fork. This must be called from the child process after calling <code>fork()</code>, or any similar function that clones the current process, if there is any chance the process will call back into the Python interpreter. Only available on systems where <code>fork()</code> is defined.</p> <div class="admonition warning"> <p class="admonition-title">Warning</p> <p>The C <code>fork()</code> call should only be made from the <a class="reference internal" href="init#fork-and-threads"><span class="std std-ref">“main” thread</span></a> (of the <a class="reference internal" href="init#sub-interpreter-support"><span class="std std-ref">“main” interpreter</span></a>). The same is true for <code>PyOS_AfterFork_Child()</code>.</p> </div> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.7.</span></p> </div> <div class="admonition seealso"> <p class="admonition-title">See also</p> <p><a class="reference internal" href="../library/os#os.register_at_fork" title="os.register_at_fork"><code>os.register_at_fork()</code></a> allows registering custom Python functions to be called by <a class="reference internal" href="#c.PyOS_BeforeFork" title="PyOS_BeforeFork"><code>PyOS_BeforeFork()</code></a>, <a class="reference internal" href="#c.PyOS_AfterFork_Parent" title="PyOS_AfterFork_Parent"><code>PyOS_AfterFork_Parent()</code></a> and <a class="reference internal" href="#c.PyOS_AfterFork_Child" title="PyOS_AfterFork_Child"><code>PyOS_AfterFork_Child()</code></a>.</p> </div> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyOS_AfterFork">
<code>void PyOS_AfterFork()</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a> on platforms with fork().</em><p>Function to update some internal state after a process fork; this should be called in the new process if the Python interpreter will continue to be used. If a new executable is loaded into the new process, this function does not need to be called.</p> <div class="deprecated"> <p><span class="versionmodified deprecated">Deprecated since version 3.7: </span>This function is superseded by <a class="reference internal" href="#c.PyOS_AfterFork_Child" title="PyOS_AfterFork_Child"><code>PyOS_AfterFork_Child()</code></a>.</p> </div> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyOS_CheckStack">
<code>int PyOS_CheckStack()</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a> on platforms with USE_STACKCHECK since version 3.7.</em><p>Return true when the interpreter runs out of stack space. This is a reliable check, but is only available when <code>USE_STACKCHECK</code> is defined (currently on certain versions of Windows using the Microsoft Visual C++ compiler). <code>USE_STACKCHECK</code> will be defined automatically; you should never change the definition in your own code.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyOS_getsig">
<code>PyOS_sighandler_t PyOS_getsig(int i)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Return the current signal handler for signal <em>i</em>. This is a thin wrapper around either <code>sigaction()</code> or <code>signal()</code>. Do not call those functions directly! <code>PyOS_sighandler_t</code> is a typedef alias for <span class="c-expr sig sig-inline c"><span class="kt">void</span><span class="w"> </span><span class="p">(</span><span class="p">*</span><span class="p">)</span><span class="p">(</span><span class="kt">int</span><span class="p">)</span></span>.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyOS_setsig">
<code>PyOS_sighandler_t PyOS_setsig(int i, PyOS_sighandler_t h)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Set the signal handler for signal <em>i</em> to be <em>h</em>; return the old signal handler. This is a thin wrapper around either <code>sigaction()</code> or <code>signal()</code>. Do not call those functions directly! <code>PyOS_sighandler_t</code> is a typedef alias for <span class="c-expr sig sig-inline c"><span class="kt">void</span><span class="w"> </span><span class="p">(</span><span class="p">*</span><span class="p">)</span><span class="p">(</span><span class="kt">int</span><span class="p">)</span></span>.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.Py_DecodeLocale">
<code>wchar_t *Py_DecodeLocale(const char *arg, size_t *size)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.7.</em><div class="admonition warning"> <p class="admonition-title">Warning</p> <p>This function should not be called directly: use the <a class="reference internal" href="init_config#c.PyConfig" title="PyConfig"><code>PyConfig</code></a> API with the <a class="reference internal" href="init_config#c.PyConfig_SetBytesString" title="PyConfig_SetBytesString"><code>PyConfig_SetBytesString()</code></a> function which ensures that <a class="reference internal" href="init_config#c-preinit"><span class="std std-ref">Python is preinitialized</span></a>.</p> <p>This function must not be called before <a class="reference internal" href="init_config#c-preinit"><span class="std std-ref">Python is preinitialized</span></a> and so that the LC_CTYPE locale is properly configured: see the <a class="reference internal" href="init_config#c.Py_PreInitialize" title="Py_PreInitialize"><code>Py_PreInitialize()</code></a> function.</p> </div> <p>Decode a byte string from the <a class="reference internal" href="../glossary#term-filesystem-encoding-and-error-handler"><span class="xref std std-term">filesystem encoding and error handler</span></a>. If the error handler is <a class="reference internal" href="../library/codecs#surrogateescape"><span class="std std-ref">surrogateescape error handler</span></a>, undecodable bytes are decoded as characters in range U+DC80..U+DCFF; and if a byte sequence can be decoded as a surrogate character, the bytes are escaped using the surrogateescape error handler instead of decoding them.</p> <p>Return a pointer to a newly allocated wide character string, use <a class="reference internal" href="memory#c.PyMem_RawFree" title="PyMem_RawFree"><code>PyMem_RawFree()</code></a> to free the memory. If size is not <code>NULL</code>, write the number of wide characters excluding the null character into <code>*size</code></p> <p>Return <code>NULL</code> on decoding error or memory allocation error. If <em>size</em> is not <code>NULL</code>, <code>*size</code> is set to <code>(size_t)-1</code> on memory error or set to <code>(size_t)-2</code> on decoding error.</p> <p>The <a class="reference internal" href="../glossary#term-filesystem-encoding-and-error-handler"><span class="xref std std-term">filesystem encoding and error handler</span></a> are selected by <a class="reference internal" href="init_config#c.PyConfig_Read" title="PyConfig_Read"><code>PyConfig_Read()</code></a>: see <a class="reference internal" href="init_config#c.PyConfig.filesystem_encoding" title="PyConfig.filesystem_encoding"><code>filesystem_encoding</code></a> and <a class="reference internal" href="init_config#c.PyConfig.filesystem_errors" title="PyConfig.filesystem_errors"><code>filesystem_errors</code></a> members of <a class="reference internal" href="init_config#c.PyConfig" title="PyConfig"><code>PyConfig</code></a>.</p> <p>Decoding errors should never happen, unless there is a bug in the C library.</p> <p>Use the <a class="reference internal" href="#c.Py_EncodeLocale" title="Py_EncodeLocale"><code>Py_EncodeLocale()</code></a> function to encode the character string back to a byte string.</p> <div class="admonition seealso"> <p class="admonition-title">See also</p> <p>The <a class="reference internal" href="unicode#c.PyUnicode_DecodeFSDefaultAndSize" title="PyUnicode_DecodeFSDefaultAndSize"><code>PyUnicode_DecodeFSDefaultAndSize()</code></a> and <a class="reference internal" href="unicode#c.PyUnicode_DecodeLocaleAndSize" title="PyUnicode_DecodeLocaleAndSize"><code>PyUnicode_DecodeLocaleAndSize()</code></a> functions.</p> </div> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.5.</span></p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.7: </span>The function now uses the UTF-8 encoding in the <a class="reference internal" href="../library/os#utf8-mode"><span class="std std-ref">Python UTF-8 Mode</span></a>.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.8: </span>The function now uses the UTF-8 encoding on Windows if <a class="reference internal" href="init_config#c.PyPreConfig.legacy_windows_fs_encoding" title="PyPreConfig.legacy_windows_fs_encoding"><code>PyPreConfig.legacy_windows_fs_encoding</code></a> is zero;</p> </div> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.Py_EncodeLocale">
<code>char *Py_EncodeLocale(const wchar_t *text, size_t *error_pos)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a> since version 3.7.</em><p>Encode a wide character string to the <a class="reference internal" href="../glossary#term-filesystem-encoding-and-error-handler"><span class="xref std std-term">filesystem encoding and error handler</span></a>. If the error handler is <a class="reference internal" href="../library/codecs#surrogateescape"><span class="std std-ref">surrogateescape error handler</span></a>, surrogate characters in the range U+DC80..U+DCFF are converted to bytes 0x80..0xFF.</p> <p>Return a pointer to a newly allocated byte string, use <a class="reference internal" href="memory#c.PyMem_Free" title="PyMem_Free"><code>PyMem_Free()</code></a> to free the memory. Return <code>NULL</code> on encoding error or memory allocation error.</p> <p>If error_pos is not <code>NULL</code>, <code>*error_pos</code> is set to <code>(size_t)-1</code> on success, or set to the index of the invalid character on encoding error.</p> <p>The <a class="reference internal" href="../glossary#term-filesystem-encoding-and-error-handler"><span class="xref std std-term">filesystem encoding and error handler</span></a> are selected by <a class="reference internal" href="init_config#c.PyConfig_Read" title="PyConfig_Read"><code>PyConfig_Read()</code></a>: see <a class="reference internal" href="init_config#c.PyConfig.filesystem_encoding" title="PyConfig.filesystem_encoding"><code>filesystem_encoding</code></a> and <a class="reference internal" href="init_config#c.PyConfig.filesystem_errors" title="PyConfig.filesystem_errors"><code>filesystem_errors</code></a> members of <a class="reference internal" href="init_config#c.PyConfig" title="PyConfig"><code>PyConfig</code></a>.</p> <p>Use the <a class="reference internal" href="#c.Py_DecodeLocale" title="Py_DecodeLocale"><code>Py_DecodeLocale()</code></a> function to decode the bytes string back to a wide character string.</p> <div class="admonition warning"> <p class="admonition-title">Warning</p> <p>This function must not be called before <a class="reference internal" href="init_config#c-preinit"><span class="std std-ref">Python is preinitialized</span></a> and so that the LC_CTYPE locale is properly configured: see the <a class="reference internal" href="init_config#c.Py_PreInitialize" title="Py_PreInitialize"><code>Py_PreInitialize()</code></a> function.</p> </div> <div class="admonition seealso"> <p class="admonition-title">See also</p> <p>The <a class="reference internal" href="unicode#c.PyUnicode_EncodeFSDefault" title="PyUnicode_EncodeFSDefault"><code>PyUnicode_EncodeFSDefault()</code></a> and <a class="reference internal" href="unicode#c.PyUnicode_EncodeLocale" title="PyUnicode_EncodeLocale"><code>PyUnicode_EncodeLocale()</code></a> functions.</p> </div> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.5.</span></p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.7: </span>The function now uses the UTF-8 encoding in the <a class="reference internal" href="../library/os#utf8-mode"><span class="std std-ref">Python UTF-8 Mode</span></a>.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.8: </span>The function now uses the UTF-8 encoding on Windows if <a class="reference internal" href="init_config#c.PyPreConfig.legacy_windows_fs_encoding" title="PyPreConfig.legacy_windows_fs_encoding"><code>PyPreConfig.legacy_windows_fs_encoding</code></a> is zero.</p> </div> </dd>
</dl> <div class="_attribution">
  <p class="_attribution-p">
    &copy; 2001&ndash;2023 Python Software Foundation<br>Licensed under the PSF License.<br>
    <a href="https://docs.python.org/3.12/c-api/sys.html" class="_attribution-link">https://docs.python.org/3.12/c-api/sys.html</a>
  </p>
</div>