4412 lines
420 KiB
HTML
4412 lines
420 KiB
HTML
|
||
<!DOCTYPE html>
|
||
|
||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
<head>
|
||
<meta charset="utf-8" />
|
||
<title>os — Miscellaneous operating system interfaces — Python 3.7.4 documentation</title>
|
||
<link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
|
||
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
|
||
|
||
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
|
||
<script type="text/javascript" src="../_static/jquery.js"></script>
|
||
<script type="text/javascript" src="../_static/underscore.js"></script>
|
||
<script type="text/javascript" src="../_static/doctools.js"></script>
|
||
<script type="text/javascript" src="../_static/language_data.js"></script>
|
||
|
||
<script type="text/javascript" src="../_static/sidebar.js"></script>
|
||
|
||
<link rel="search" type="application/opensearchdescription+xml"
|
||
title="Search within Python 3.7.4 documentation"
|
||
href="../_static/opensearch.xml"/>
|
||
<link rel="author" title="About these documents" href="../about.html" />
|
||
<link rel="index" title="Index" href="../genindex.html" />
|
||
<link rel="search" title="Search" href="../search.html" />
|
||
<link rel="copyright" title="Copyright" href="../copyright.html" />
|
||
<link rel="next" title="io — Core tools for working with streams" href="io.html" />
|
||
<link rel="prev" title="Generic Operating System Services" href="allos.html" />
|
||
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
|
||
<link rel="canonical" href="https://docs.python.org/3/library/os.html" />
|
||
|
||
<script type="text/javascript" src="../_static/copybutton.js"></script>
|
||
<script type="text/javascript" src="../_static/switchers.js"></script>
|
||
|
||
|
||
|
||
<style>
|
||
@media only screen {
|
||
table.full-width-table {
|
||
width: 100%;
|
||
}
|
||
}
|
||
</style>
|
||
|
||
|
||
</head><body>
|
||
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<h3>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="General Index"
|
||
accesskey="I">index</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python Module Index"
|
||
>modules</a> |</li>
|
||
<li class="right" >
|
||
<a href="io.html" title="io — Core tools for working with streams"
|
||
accesskey="N">next</a> |</li>
|
||
<li class="right" >
|
||
<a href="allos.html" title="Generic Operating System Services"
|
||
accesskey="P">previous</a> |</li>
|
||
<li><img src="../_static/py.png" alt=""
|
||
style="vertical-align: middle; margin-top: -1px"/></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li>
|
||
<span class="language_switcher_placeholder">en</span>
|
||
<span class="version_switcher_placeholder">3.7.4</span>
|
||
<a href="../index.html">Documentation </a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>
|
||
<li class="nav-item nav-item-2"><a href="allos.html" accesskey="U">Generic Operating System Services</a> »</li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" style="display: none" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="Quick search" type="text" name="q" />
|
||
<input type="submit" value="Go" />
|
||
<input type="hidden" name="check_keywords" value="yes" />
|
||
<input type="hidden" name="area" value="default" />
|
||
</form>
|
||
</div>
|
||
<script type="text/javascript">$('.inline-search').show(0);</script>
|
||
|
|
||
</li>
|
||
|
||
</ul>
|
||
</div>
|
||
|
||
<div class="document">
|
||
<div class="documentwrapper">
|
||
<div class="bodywrapper">
|
||
<div class="body" role="main">
|
||
|
||
<div class="section" id="module-os">
|
||
<span id="os-miscellaneous-operating-system-interfaces"></span><h1><a class="reference internal" href="#module-os" title="os: Miscellaneous operating system interfaces."><code class="xref py py-mod docutils literal notranslate"><span class="pre">os</span></code></a> — Miscellaneous operating system interfaces<a class="headerlink" href="#module-os" title="Permalink to this headline">¶</a></h1>
|
||
<p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.7/Lib/os.py">Lib/os.py</a></p>
|
||
<hr class="docutils" />
|
||
<p>This module provides a portable way of using operating system dependent
|
||
functionality. If you just want to read or write a file see <a class="reference internal" href="functions.html#open" title="open"><code class="xref py py-func docutils literal notranslate"><span class="pre">open()</span></code></a>, if
|
||
you want to manipulate paths, see the <a class="reference internal" href="os.path.html#module-os.path" title="os.path: Operations on pathnames."><code class="xref py py-mod docutils literal notranslate"><span class="pre">os.path</span></code></a> module, and if you want to
|
||
read all the lines in all the files on the command line see the <a class="reference internal" href="fileinput.html#module-fileinput" title="fileinput: Loop over standard input or a list of files."><code class="xref py py-mod docutils literal notranslate"><span class="pre">fileinput</span></code></a>
|
||
module. For creating temporary files and directories see the <a class="reference internal" href="tempfile.html#module-tempfile" title="tempfile: Generate temporary files and directories."><code class="xref py py-mod docutils literal notranslate"><span class="pre">tempfile</span></code></a>
|
||
module, and for high-level file and directory handling see the <a class="reference internal" href="shutil.html#module-shutil" title="shutil: High-level file operations, including copying."><code class="xref py py-mod docutils literal notranslate"><span class="pre">shutil</span></code></a>
|
||
module.</p>
|
||
<p>Notes on the availability of these functions:</p>
|
||
<ul class="simple">
|
||
<li><p>The design of all built-in operating system dependent modules of Python is
|
||
such that as long as the same functionality is available, it uses the same
|
||
interface; for example, the function <code class="docutils literal notranslate"><span class="pre">os.stat(path)</span></code> returns stat
|
||
information about <em>path</em> in the same format (which happens to have originated
|
||
with the POSIX interface).</p></li>
|
||
<li><p>Extensions peculiar to a particular operating system are also available
|
||
through the <a class="reference internal" href="#module-os" title="os: Miscellaneous operating system interfaces."><code class="xref py py-mod docutils literal notranslate"><span class="pre">os</span></code></a> module, but using them is of course a threat to
|
||
portability.</p></li>
|
||
<li><p>All functions accepting path or file names accept both bytes and string
|
||
objects, and result in an object of the same type, if a path or file name is
|
||
returned.</p></li>
|
||
</ul>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>All functions in this module raise <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a> (or subclasses thereof) in
|
||
the case of invalid or inaccessible file names and paths, or other arguments
|
||
that have the correct type, but are not accepted by the operating system.</p>
|
||
</div>
|
||
<dl class="exception">
|
||
<dt id="os.error">
|
||
<em class="property">exception </em><code class="descclassname">os.</code><code class="descname">error</code><a class="headerlink" href="#os.error" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>An alias for the built-in <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a> exception.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.name">
|
||
<code class="descclassname">os.</code><code class="descname">name</code><a class="headerlink" href="#os.name" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>The name of the operating system dependent module imported. The following
|
||
names have currently been registered: <code class="docutils literal notranslate"><span class="pre">'posix'</span></code>, <code class="docutils literal notranslate"><span class="pre">'nt'</span></code>,
|
||
<code class="docutils literal notranslate"><span class="pre">'java'</span></code>.</p>
|
||
<div class="admonition seealso">
|
||
<p class="admonition-title">See also</p>
|
||
<p><a class="reference internal" href="sys.html#sys.platform" title="sys.platform"><code class="xref py py-attr docutils literal notranslate"><span class="pre">sys.platform</span></code></a> has a finer granularity. <a class="reference internal" href="#os.uname" title="os.uname"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.uname()</span></code></a> gives
|
||
system-dependent version information.</p>
|
||
<p>The <a class="reference internal" href="platform.html#module-platform" title="platform: Retrieves as much platform identifying data as possible."><code class="xref py py-mod docutils literal notranslate"><span class="pre">platform</span></code></a> module provides detailed checks for the
|
||
system’s identity.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<div class="section" id="file-names-command-line-arguments-and-environment-variables">
|
||
<span id="filesystem-encoding"></span><span id="os-filenames"></span><h2>File Names, Command Line Arguments, and Environment Variables<a class="headerlink" href="#file-names-command-line-arguments-and-environment-variables" title="Permalink to this headline">¶</a></h2>
|
||
<p>In Python, file names, command line arguments, and environment variables are
|
||
represented using the string type. On some systems, decoding these strings to
|
||
and from bytes is necessary before passing them to the operating system. Python
|
||
uses the file system encoding to perform this conversion (see
|
||
<a class="reference internal" href="sys.html#sys.getfilesystemencoding" title="sys.getfilesystemencoding"><code class="xref py py-func docutils literal notranslate"><span class="pre">sys.getfilesystemencoding()</span></code></a>).</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.1: </span>On some systems, conversion using the file system encoding may fail. In this
|
||
case, Python uses the <a class="reference internal" href="codecs.html#surrogateescape"><span class="std std-ref">surrogateescape encoding error handler</span></a>, which means that undecodable bytes are replaced by a
|
||
Unicode character U+DCxx on decoding, and these are again translated to the
|
||
original byte on encoding.</p>
|
||
</div>
|
||
<p>The file system encoding must guarantee to successfully decode all bytes
|
||
below 128. If the file system encoding fails to provide this guarantee, API
|
||
functions may raise UnicodeErrors.</p>
|
||
</div>
|
||
<div class="section" id="process-parameters">
|
||
<span id="os-procinfo"></span><h2>Process Parameters<a class="headerlink" href="#process-parameters" title="Permalink to this headline">¶</a></h2>
|
||
<p>These functions and data items provide information and operate on the current
|
||
process and user.</p>
|
||
<dl class="function">
|
||
<dt id="os.ctermid">
|
||
<code class="descclassname">os.</code><code class="descname">ctermid</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#os.ctermid" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return the filename corresponding to the controlling terminal of the process.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.environ">
|
||
<code class="descclassname">os.</code><code class="descname">environ</code><a class="headerlink" href="#os.environ" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>A <a class="reference internal" href="../glossary.html#term-mapping"><span class="xref std std-term">mapping</span></a> object representing the string environment. For example,
|
||
<code class="docutils literal notranslate"><span class="pre">environ['HOME']</span></code> is the pathname of your home directory (on some platforms),
|
||
and is equivalent to <code class="docutils literal notranslate"><span class="pre">getenv("HOME")</span></code> in C.</p>
|
||
<p>This mapping is captured the first time the <a class="reference internal" href="#module-os" title="os: Miscellaneous operating system interfaces."><code class="xref py py-mod docutils literal notranslate"><span class="pre">os</span></code></a> module is imported,
|
||
typically during Python startup as part of processing <code class="file docutils literal notranslate"><span class="pre">site.py</span></code>. Changes
|
||
to the environment made after this time are not reflected in <code class="docutils literal notranslate"><span class="pre">os.environ</span></code>,
|
||
except for changes made by modifying <code class="docutils literal notranslate"><span class="pre">os.environ</span></code> directly.</p>
|
||
<p>If the platform supports the <a class="reference internal" href="#os.putenv" title="os.putenv"><code class="xref py py-func docutils literal notranslate"><span class="pre">putenv()</span></code></a> function, this mapping may be used
|
||
to modify the environment as well as query the environment. <a class="reference internal" href="#os.putenv" title="os.putenv"><code class="xref py py-func docutils literal notranslate"><span class="pre">putenv()</span></code></a> will
|
||
be called automatically when the mapping is modified.</p>
|
||
<p>On Unix, keys and values use <a class="reference internal" href="sys.html#sys.getfilesystemencoding" title="sys.getfilesystemencoding"><code class="xref py py-func docutils literal notranslate"><span class="pre">sys.getfilesystemencoding()</span></code></a> and
|
||
<code class="docutils literal notranslate"><span class="pre">'surrogateescape'</span></code> error handler. Use <a class="reference internal" href="#os.environb" title="os.environb"><code class="xref py py-data docutils literal notranslate"><span class="pre">environb</span></code></a> if you would like
|
||
to use a different encoding.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>Calling <a class="reference internal" href="#os.putenv" title="os.putenv"><code class="xref py py-func docutils literal notranslate"><span class="pre">putenv()</span></code></a> directly does not change <code class="docutils literal notranslate"><span class="pre">os.environ</span></code>, so it’s better
|
||
to modify <code class="docutils literal notranslate"><span class="pre">os.environ</span></code>.</p>
|
||
</div>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>On some platforms, including FreeBSD and Mac OS X, setting <code class="docutils literal notranslate"><span class="pre">environ</span></code> may
|
||
cause memory leaks. Refer to the system documentation for
|
||
<code class="xref c c-func docutils literal notranslate"><span class="pre">putenv()</span></code>.</p>
|
||
</div>
|
||
<p>If <a class="reference internal" href="#os.putenv" title="os.putenv"><code class="xref py py-func docutils literal notranslate"><span class="pre">putenv()</span></code></a> is not provided, a modified copy of this mapping may be
|
||
passed to the appropriate process-creation functions to cause child processes
|
||
to use a modified environment.</p>
|
||
<p>If the platform supports the <a class="reference internal" href="#os.unsetenv" title="os.unsetenv"><code class="xref py py-func docutils literal notranslate"><span class="pre">unsetenv()</span></code></a> function, you can delete items in
|
||
this mapping to unset environment variables. <a class="reference internal" href="#os.unsetenv" title="os.unsetenv"><code class="xref py py-func docutils literal notranslate"><span class="pre">unsetenv()</span></code></a> will be called
|
||
automatically when an item is deleted from <code class="docutils literal notranslate"><span class="pre">os.environ</span></code>, and when
|
||
one of the <code class="xref py py-meth docutils literal notranslate"><span class="pre">pop()</span></code> or <code class="xref py py-meth docutils literal notranslate"><span class="pre">clear()</span></code> methods is called.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.environb">
|
||
<code class="descclassname">os.</code><code class="descname">environb</code><a class="headerlink" href="#os.environb" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Bytes version of <a class="reference internal" href="#os.environ" title="os.environ"><code class="xref py py-data docutils literal notranslate"><span class="pre">environ</span></code></a>: a <a class="reference internal" href="../glossary.html#term-mapping"><span class="xref std std-term">mapping</span></a> object representing the
|
||
environment as byte strings. <a class="reference internal" href="#os.environ" title="os.environ"><code class="xref py py-data docutils literal notranslate"><span class="pre">environ</span></code></a> and <a class="reference internal" href="#os.environb" title="os.environb"><code class="xref py py-data docutils literal notranslate"><span class="pre">environb</span></code></a> are
|
||
synchronized (modify <a class="reference internal" href="#os.environb" title="os.environb"><code class="xref py py-data docutils literal notranslate"><span class="pre">environb</span></code></a> updates <a class="reference internal" href="#os.environ" title="os.environ"><code class="xref py py-data docutils literal notranslate"><span class="pre">environ</span></code></a>, and vice
|
||
versa).</p>
|
||
<p><a class="reference internal" href="#os.environb" title="os.environb"><code class="xref py py-data docutils literal notranslate"><span class="pre">environb</span></code></a> is only available if <a class="reference internal" href="#os.supports_bytes_environ" title="os.supports_bytes_environ"><code class="xref py py-data docutils literal notranslate"><span class="pre">supports_bytes_environ</span></code></a> is
|
||
True.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.2.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt>
|
||
<code class="descclassname">os.</code><code class="descname">chdir</code><span class="sig-paren">(</span><em>path</em><span class="sig-paren">)</span></dt>
|
||
<dt>
|
||
<code class="descclassname">os.</code><code class="descname">fchdir</code><span class="sig-paren">(</span><em>fd</em><span class="sig-paren">)</span></dt>
|
||
<dt>
|
||
<code class="descclassname">os.</code><code class="descname">getcwd</code><span class="sig-paren">(</span><span class="sig-paren">)</span></dt>
|
||
<dd><p>These functions are described in <a class="reference internal" href="#os-file-dir"><span class="std std-ref">Files and Directories</span></a>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.fsencode">
|
||
<code class="descclassname">os.</code><code class="descname">fsencode</code><span class="sig-paren">(</span><em>filename</em><span class="sig-paren">)</span><a class="headerlink" href="#os.fsencode" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Encode <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like</span></a> <em>filename</em> to the filesystem
|
||
encoding with <code class="docutils literal notranslate"><span class="pre">'surrogateescape'</span></code> error handler, or <code class="docutils literal notranslate"><span class="pre">'strict'</span></code> on
|
||
Windows; return <a class="reference internal" href="stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> unchanged.</p>
|
||
<p><a class="reference internal" href="#os.fsdecode" title="os.fsdecode"><code class="xref py py-func docutils literal notranslate"><span class="pre">fsdecode()</span></code></a> is the reverse function.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.2.</span></p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>Support added to accept objects implementing the <a class="reference internal" href="#os.PathLike" title="os.PathLike"><code class="xref py py-class docutils literal notranslate"><span class="pre">os.PathLike</span></code></a>
|
||
interface.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.fsdecode">
|
||
<code class="descclassname">os.</code><code class="descname">fsdecode</code><span class="sig-paren">(</span><em>filename</em><span class="sig-paren">)</span><a class="headerlink" href="#os.fsdecode" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Decode the <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like</span></a> <em>filename</em> from the
|
||
filesystem encoding with <code class="docutils literal notranslate"><span class="pre">'surrogateescape'</span></code> error handler, or <code class="docutils literal notranslate"><span class="pre">'strict'</span></code>
|
||
on Windows; return <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> unchanged.</p>
|
||
<p><a class="reference internal" href="#os.fsencode" title="os.fsencode"><code class="xref py py-func docutils literal notranslate"><span class="pre">fsencode()</span></code></a> is the reverse function.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.2.</span></p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>Support added to accept objects implementing the <a class="reference internal" href="#os.PathLike" title="os.PathLike"><code class="xref py py-class docutils literal notranslate"><span class="pre">os.PathLike</span></code></a>
|
||
interface.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.fspath">
|
||
<code class="descclassname">os.</code><code class="descname">fspath</code><span class="sig-paren">(</span><em>path</em><span class="sig-paren">)</span><a class="headerlink" href="#os.fspath" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return the file system representation of the path.</p>
|
||
<p>If <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> or <a class="reference internal" href="stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> is passed in, it is returned unchanged.
|
||
Otherwise <a class="reference internal" href="#os.PathLike.__fspath__" title="os.PathLike.__fspath__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__fspath__()</span></code></a> is called and its value is
|
||
returned as long as it is a <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> or <a class="reference internal" href="stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> object.
|
||
In all other cases, <a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> is raised.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.6.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="class">
|
||
<dt id="os.PathLike">
|
||
<em class="property">class </em><code class="descclassname">os.</code><code class="descname">PathLike</code><a class="headerlink" href="#os.PathLike" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>An <a class="reference internal" href="../glossary.html#term-abstract-base-class"><span class="xref std std-term">abstract base class</span></a> for objects representing a file system path,
|
||
e.g. <a class="reference internal" href="pathlib.html#pathlib.PurePath" title="pathlib.PurePath"><code class="xref py py-class docutils literal notranslate"><span class="pre">pathlib.PurePath</span></code></a>.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.6.</span></p>
|
||
</div>
|
||
<dl class="method">
|
||
<dt id="os.PathLike.__fspath__">
|
||
<em class="property">abstractmethod </em><code class="descname">__fspath__</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#os.PathLike.__fspath__" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return the file system path representation of the object.</p>
|
||
<p>The method should only return a <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> or <a class="reference internal" href="stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> object,
|
||
with the preference being for <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.getenv">
|
||
<code class="descclassname">os.</code><code class="descname">getenv</code><span class="sig-paren">(</span><em>key</em>, <em>default=None</em><span class="sig-paren">)</span><a class="headerlink" href="#os.getenv" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return the value of the environment variable <em>key</em> if it exists, or
|
||
<em>default</em> if it doesn’t. <em>key</em>, <em>default</em> and the result are str.</p>
|
||
<p>On Unix, keys and values are decoded with <a class="reference internal" href="sys.html#sys.getfilesystemencoding" title="sys.getfilesystemencoding"><code class="xref py py-func docutils literal notranslate"><span class="pre">sys.getfilesystemencoding()</span></code></a>
|
||
and <code class="docutils literal notranslate"><span class="pre">'surrogateescape'</span></code> error handler. Use <a class="reference internal" href="#os.getenvb" title="os.getenvb"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.getenvb()</span></code></a> if you
|
||
would like to use a different encoding.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: most flavors of Unix, Windows.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.getenvb">
|
||
<code class="descclassname">os.</code><code class="descname">getenvb</code><span class="sig-paren">(</span><em>key</em>, <em>default=None</em><span class="sig-paren">)</span><a class="headerlink" href="#os.getenvb" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return the value of the environment variable <em>key</em> if it exists, or
|
||
<em>default</em> if it doesn’t. <em>key</em>, <em>default</em> and the result are bytes.</p>
|
||
<p><a class="reference internal" href="#os.getenvb" title="os.getenvb"><code class="xref py py-func docutils literal notranslate"><span class="pre">getenvb()</span></code></a> is only available if <a class="reference internal" href="#os.supports_bytes_environ" title="os.supports_bytes_environ"><code class="xref py py-data docutils literal notranslate"><span class="pre">supports_bytes_environ</span></code></a>
|
||
is True.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: most flavors of Unix.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.2.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.get_exec_path">
|
||
<code class="descclassname">os.</code><code class="descname">get_exec_path</code><span class="sig-paren">(</span><em>env=None</em><span class="sig-paren">)</span><a class="headerlink" href="#os.get_exec_path" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Returns the list of directories that will be searched for a named
|
||
executable, similar to a shell, when launching a process.
|
||
<em>env</em>, when specified, should be an environment variable dictionary
|
||
to lookup the PATH in.
|
||
By default, when <em>env</em> is <code class="docutils literal notranslate"><span class="pre">None</span></code>, <a class="reference internal" href="#os.environ" title="os.environ"><code class="xref py py-data docutils literal notranslate"><span class="pre">environ</span></code></a> is used.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.2.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.getegid">
|
||
<code class="descclassname">os.</code><code class="descname">getegid</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#os.getegid" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return the effective group id of the current process. This corresponds to the
|
||
“set id” bit on the file being executed in the current process.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.geteuid">
|
||
<code class="descclassname">os.</code><code class="descname">geteuid</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#os.geteuid" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p id="index-0">Return the current process’s effective user id.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.getgid">
|
||
<code class="descclassname">os.</code><code class="descname">getgid</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#os.getgid" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p id="index-1">Return the real group id of the current process.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.getgrouplist">
|
||
<code class="descclassname">os.</code><code class="descname">getgrouplist</code><span class="sig-paren">(</span><em>user</em>, <em>group</em><span class="sig-paren">)</span><a class="headerlink" href="#os.getgrouplist" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return list of group ids that <em>user</em> belongs to. If <em>group</em> is not in the
|
||
list, it is included; typically, <em>group</em> is specified as the group ID
|
||
field from the password record for <em>user</em>.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.getgroups">
|
||
<code class="descclassname">os.</code><code class="descname">getgroups</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#os.getgroups" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return list of supplemental group ids associated with the current process.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>On Mac OS X, <a class="reference internal" href="#os.getgroups" title="os.getgroups"><code class="xref py py-func docutils literal notranslate"><span class="pre">getgroups()</span></code></a> behavior differs somewhat from
|
||
other Unix platforms. If the Python interpreter was built with a
|
||
deployment target of <code class="xref py py-const docutils literal notranslate"><span class="pre">10.5</span></code> or earlier, <a class="reference internal" href="#os.getgroups" title="os.getgroups"><code class="xref py py-func docutils literal notranslate"><span class="pre">getgroups()</span></code></a> returns
|
||
the list of effective group ids associated with the current user process;
|
||
this list is limited to a system-defined number of entries, typically 16,
|
||
and may be modified by calls to <a class="reference internal" href="#os.setgroups" title="os.setgroups"><code class="xref py py-func docutils literal notranslate"><span class="pre">setgroups()</span></code></a> if suitably privileged.
|
||
If built with a deployment target greater than <code class="xref py py-const docutils literal notranslate"><span class="pre">10.5</span></code>,
|
||
<a class="reference internal" href="#os.getgroups" title="os.getgroups"><code class="xref py py-func docutils literal notranslate"><span class="pre">getgroups()</span></code></a> returns the current group access list for the user
|
||
associated with the effective user id of the process; the group access
|
||
list may change over the lifetime of the process, it is not affected by
|
||
calls to <a class="reference internal" href="#os.setgroups" title="os.setgroups"><code class="xref py py-func docutils literal notranslate"><span class="pre">setgroups()</span></code></a>, and its length is not limited to 16. The
|
||
deployment target value, <code class="xref py py-const docutils literal notranslate"><span class="pre">MACOSX_DEPLOYMENT_TARGET</span></code>, can be
|
||
obtained with <a class="reference internal" href="sysconfig.html#sysconfig.get_config_var" title="sysconfig.get_config_var"><code class="xref py py-func docutils literal notranslate"><span class="pre">sysconfig.get_config_var()</span></code></a>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.getlogin">
|
||
<code class="descclassname">os.</code><code class="descname">getlogin</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#os.getlogin" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return the name of the user logged in on the controlling terminal of the
|
||
process. For most purposes, it is more useful to use
|
||
<a class="reference internal" href="getpass.html#getpass.getuser" title="getpass.getuser"><code class="xref py py-func docutils literal notranslate"><span class="pre">getpass.getuser()</span></code></a> since the latter checks the environment variables
|
||
<span class="target" id="index-2"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">LOGNAME</span></code> or <span class="target" id="index-3"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">USERNAME</span></code> to find out who the user is, and
|
||
falls back to <code class="docutils literal notranslate"><span class="pre">pwd.getpwuid(os.getuid())[0]</span></code> to get the login name of the
|
||
current real user id.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix, Windows.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.getpgid">
|
||
<code class="descclassname">os.</code><code class="descname">getpgid</code><span class="sig-paren">(</span><em>pid</em><span class="sig-paren">)</span><a class="headerlink" href="#os.getpgid" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return the process group id of the process with process id <em>pid</em>. If <em>pid</em> is 0,
|
||
the process group id of the current process is returned.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.getpgrp">
|
||
<code class="descclassname">os.</code><code class="descname">getpgrp</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#os.getpgrp" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p id="index-4">Return the id of the current process group.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.getpid">
|
||
<code class="descclassname">os.</code><code class="descname">getpid</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#os.getpid" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p id="index-5">Return the current process id.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.getppid">
|
||
<code class="descclassname">os.</code><code class="descname">getppid</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#os.getppid" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p id="index-6">Return the parent’s process id. When the parent process has exited, on Unix
|
||
the id returned is the one of the init process (1), on Windows it is still
|
||
the same id, which may be already reused by another process.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix, Windows.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.2: </span>Added support for Windows.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.getpriority">
|
||
<code class="descclassname">os.</code><code class="descname">getpriority</code><span class="sig-paren">(</span><em>which</em>, <em>who</em><span class="sig-paren">)</span><a class="headerlink" href="#os.getpriority" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p id="index-7">Get program scheduling priority. The value <em>which</em> is one of
|
||
<a class="reference internal" href="#os.PRIO_PROCESS" title="os.PRIO_PROCESS"><code class="xref py py-const docutils literal notranslate"><span class="pre">PRIO_PROCESS</span></code></a>, <a class="reference internal" href="#os.PRIO_PGRP" title="os.PRIO_PGRP"><code class="xref py py-const docutils literal notranslate"><span class="pre">PRIO_PGRP</span></code></a>, or <a class="reference internal" href="#os.PRIO_USER" title="os.PRIO_USER"><code class="xref py py-const docutils literal notranslate"><span class="pre">PRIO_USER</span></code></a>, and <em>who</em>
|
||
is interpreted relative to <em>which</em> (a process identifier for
|
||
<a class="reference internal" href="#os.PRIO_PROCESS" title="os.PRIO_PROCESS"><code class="xref py py-const docutils literal notranslate"><span class="pre">PRIO_PROCESS</span></code></a>, process group identifier for <a class="reference internal" href="#os.PRIO_PGRP" title="os.PRIO_PGRP"><code class="xref py py-const docutils literal notranslate"><span class="pre">PRIO_PGRP</span></code></a>, and a
|
||
user ID for <a class="reference internal" href="#os.PRIO_USER" title="os.PRIO_USER"><code class="xref py py-const docutils literal notranslate"><span class="pre">PRIO_USER</span></code></a>). A zero value for <em>who</em> denotes
|
||
(respectively) the calling process, the process group of the calling process,
|
||
or the real user ID of the calling process.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.PRIO_PROCESS">
|
||
<code class="descclassname">os.</code><code class="descname">PRIO_PROCESS</code><a class="headerlink" href="#os.PRIO_PROCESS" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.PRIO_PGRP">
|
||
<code class="descclassname">os.</code><code class="descname">PRIO_PGRP</code><a class="headerlink" href="#os.PRIO_PGRP" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.PRIO_USER">
|
||
<code class="descclassname">os.</code><code class="descname">PRIO_USER</code><a class="headerlink" href="#os.PRIO_USER" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Parameters for the <a class="reference internal" href="#os.getpriority" title="os.getpriority"><code class="xref py py-func docutils literal notranslate"><span class="pre">getpriority()</span></code></a> and <a class="reference internal" href="#os.setpriority" title="os.setpriority"><code class="xref py py-func docutils literal notranslate"><span class="pre">setpriority()</span></code></a> functions.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.getresuid">
|
||
<code class="descclassname">os.</code><code class="descname">getresuid</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#os.getresuid" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return a tuple (ruid, euid, suid) denoting the current process’s
|
||
real, effective, and saved user ids.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.2.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.getresgid">
|
||
<code class="descclassname">os.</code><code class="descname">getresgid</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#os.getresgid" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return a tuple (rgid, egid, sgid) denoting the current process’s
|
||
real, effective, and saved group ids.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.2.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.getuid">
|
||
<code class="descclassname">os.</code><code class="descname">getuid</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#os.getuid" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p id="index-8">Return the current process’s real user id.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.initgroups">
|
||
<code class="descclassname">os.</code><code class="descname">initgroups</code><span class="sig-paren">(</span><em>username</em>, <em>gid</em><span class="sig-paren">)</span><a class="headerlink" href="#os.initgroups" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Call the system initgroups() to initialize the group access list with all of
|
||
the groups of which the specified username is a member, plus the specified
|
||
group id.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.2.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.putenv">
|
||
<code class="descclassname">os.</code><code class="descname">putenv</code><span class="sig-paren">(</span><em>key</em>, <em>value</em><span class="sig-paren">)</span><a class="headerlink" href="#os.putenv" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p id="index-9">Set the environment variable named <em>key</em> to the string <em>value</em>. Such
|
||
changes to the environment affect subprocesses started with <a class="reference internal" href="#os.system" title="os.system"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.system()</span></code></a>,
|
||
<a class="reference internal" href="#os.popen" title="os.popen"><code class="xref py py-func docutils literal notranslate"><span class="pre">popen()</span></code></a> or <a class="reference internal" href="#os.fork" title="os.fork"><code class="xref py py-func docutils literal notranslate"><span class="pre">fork()</span></code></a> and <a class="reference internal" href="#os.execv" title="os.execv"><code class="xref py py-func docutils literal notranslate"><span class="pre">execv()</span></code></a>.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: most flavors of Unix, Windows.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>On some platforms, including FreeBSD and Mac OS X, setting <code class="docutils literal notranslate"><span class="pre">environ</span></code> may
|
||
cause memory leaks. Refer to the system documentation for putenv.</p>
|
||
</div>
|
||
<p>When <a class="reference internal" href="#os.putenv" title="os.putenv"><code class="xref py py-func docutils literal notranslate"><span class="pre">putenv()</span></code></a> is supported, assignments to items in <code class="docutils literal notranslate"><span class="pre">os.environ</span></code> are
|
||
automatically translated into corresponding calls to <a class="reference internal" href="#os.putenv" title="os.putenv"><code class="xref py py-func docutils literal notranslate"><span class="pre">putenv()</span></code></a>; however,
|
||
calls to <a class="reference internal" href="#os.putenv" title="os.putenv"><code class="xref py py-func docutils literal notranslate"><span class="pre">putenv()</span></code></a> don’t update <code class="docutils literal notranslate"><span class="pre">os.environ</span></code>, so it is actually
|
||
preferable to assign to items of <code class="docutils literal notranslate"><span class="pre">os.environ</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.setegid">
|
||
<code class="descclassname">os.</code><code class="descname">setegid</code><span class="sig-paren">(</span><em>egid</em><span class="sig-paren">)</span><a class="headerlink" href="#os.setegid" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Set the current process’s effective group id.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.seteuid">
|
||
<code class="descclassname">os.</code><code class="descname">seteuid</code><span class="sig-paren">(</span><em>euid</em><span class="sig-paren">)</span><a class="headerlink" href="#os.seteuid" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Set the current process’s effective user id.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.setgid">
|
||
<code class="descclassname">os.</code><code class="descname">setgid</code><span class="sig-paren">(</span><em>gid</em><span class="sig-paren">)</span><a class="headerlink" href="#os.setgid" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Set the current process’ group id.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.setgroups">
|
||
<code class="descclassname">os.</code><code class="descname">setgroups</code><span class="sig-paren">(</span><em>groups</em><span class="sig-paren">)</span><a class="headerlink" href="#os.setgroups" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Set the list of supplemental group ids associated with the current process to
|
||
<em>groups</em>. <em>groups</em> must be a sequence, and each element must be an integer
|
||
identifying a group. This operation is typically available only to the superuser.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>On Mac OS X, the length of <em>groups</em> may not exceed the
|
||
system-defined maximum number of effective group ids, typically 16.
|
||
See the documentation for <a class="reference internal" href="#os.getgroups" title="os.getgroups"><code class="xref py py-func docutils literal notranslate"><span class="pre">getgroups()</span></code></a> for cases where it may not
|
||
return the same group list set by calling setgroups().</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.setpgrp">
|
||
<code class="descclassname">os.</code><code class="descname">setpgrp</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#os.setpgrp" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Call the system call <code class="xref c c-func docutils literal notranslate"><span class="pre">setpgrp()</span></code> or <code class="docutils literal notranslate"><span class="pre">setpgrp(0,</span> <span class="pre">0)</span></code> depending on
|
||
which version is implemented (if any). See the Unix manual for the semantics.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.setpgid">
|
||
<code class="descclassname">os.</code><code class="descname">setpgid</code><span class="sig-paren">(</span><em>pid</em>, <em>pgrp</em><span class="sig-paren">)</span><a class="headerlink" href="#os.setpgid" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Call the system call <code class="xref c c-func docutils literal notranslate"><span class="pre">setpgid()</span></code> to set the process group id of the
|
||
process with id <em>pid</em> to the process group with id <em>pgrp</em>. See the Unix manual
|
||
for the semantics.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.setpriority">
|
||
<code class="descclassname">os.</code><code class="descname">setpriority</code><span class="sig-paren">(</span><em>which</em>, <em>who</em>, <em>priority</em><span class="sig-paren">)</span><a class="headerlink" href="#os.setpriority" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p id="index-10">Set program scheduling priority. The value <em>which</em> is one of
|
||
<a class="reference internal" href="#os.PRIO_PROCESS" title="os.PRIO_PROCESS"><code class="xref py py-const docutils literal notranslate"><span class="pre">PRIO_PROCESS</span></code></a>, <a class="reference internal" href="#os.PRIO_PGRP" title="os.PRIO_PGRP"><code class="xref py py-const docutils literal notranslate"><span class="pre">PRIO_PGRP</span></code></a>, or <a class="reference internal" href="#os.PRIO_USER" title="os.PRIO_USER"><code class="xref py py-const docutils literal notranslate"><span class="pre">PRIO_USER</span></code></a>, and <em>who</em>
|
||
is interpreted relative to <em>which</em> (a process identifier for
|
||
<a class="reference internal" href="#os.PRIO_PROCESS" title="os.PRIO_PROCESS"><code class="xref py py-const docutils literal notranslate"><span class="pre">PRIO_PROCESS</span></code></a>, process group identifier for <a class="reference internal" href="#os.PRIO_PGRP" title="os.PRIO_PGRP"><code class="xref py py-const docutils literal notranslate"><span class="pre">PRIO_PGRP</span></code></a>, and a
|
||
user ID for <a class="reference internal" href="#os.PRIO_USER" title="os.PRIO_USER"><code class="xref py py-const docutils literal notranslate"><span class="pre">PRIO_USER</span></code></a>). A zero value for <em>who</em> denotes
|
||
(respectively) the calling process, the process group of the calling process,
|
||
or the real user ID of the calling process.
|
||
<em>priority</em> is a value in the range -20 to 19. The default priority is 0;
|
||
lower priorities cause more favorable scheduling.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.setregid">
|
||
<code class="descclassname">os.</code><code class="descname">setregid</code><span class="sig-paren">(</span><em>rgid</em>, <em>egid</em><span class="sig-paren">)</span><a class="headerlink" href="#os.setregid" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Set the current process’s real and effective group ids.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.setresgid">
|
||
<code class="descclassname">os.</code><code class="descname">setresgid</code><span class="sig-paren">(</span><em>rgid</em>, <em>egid</em>, <em>sgid</em><span class="sig-paren">)</span><a class="headerlink" href="#os.setresgid" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Set the current process’s real, effective, and saved group ids.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.2.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.setresuid">
|
||
<code class="descclassname">os.</code><code class="descname">setresuid</code><span class="sig-paren">(</span><em>ruid</em>, <em>euid</em>, <em>suid</em><span class="sig-paren">)</span><a class="headerlink" href="#os.setresuid" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Set the current process’s real, effective, and saved user ids.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.2.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.setreuid">
|
||
<code class="descclassname">os.</code><code class="descname">setreuid</code><span class="sig-paren">(</span><em>ruid</em>, <em>euid</em><span class="sig-paren">)</span><a class="headerlink" href="#os.setreuid" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Set the current process’s real and effective user ids.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.getsid">
|
||
<code class="descclassname">os.</code><code class="descname">getsid</code><span class="sig-paren">(</span><em>pid</em><span class="sig-paren">)</span><a class="headerlink" href="#os.getsid" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Call the system call <code class="xref c c-func docutils literal notranslate"><span class="pre">getsid()</span></code>. See the Unix manual for the semantics.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.setsid">
|
||
<code class="descclassname">os.</code><code class="descname">setsid</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#os.setsid" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Call the system call <code class="xref c c-func docutils literal notranslate"><span class="pre">setsid()</span></code>. See the Unix manual for the semantics.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.setuid">
|
||
<code class="descclassname">os.</code><code class="descname">setuid</code><span class="sig-paren">(</span><em>uid</em><span class="sig-paren">)</span><a class="headerlink" href="#os.setuid" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p id="index-11">Set the current process’s user id.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.strerror">
|
||
<code class="descclassname">os.</code><code class="descname">strerror</code><span class="sig-paren">(</span><em>code</em><span class="sig-paren">)</span><a class="headerlink" href="#os.strerror" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return the error message corresponding to the error code in <em>code</em>.
|
||
On platforms where <code class="xref c c-func docutils literal notranslate"><span class="pre">strerror()</span></code> returns <code class="docutils literal notranslate"><span class="pre">NULL</span></code> when given an unknown
|
||
error number, <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> is raised.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.supports_bytes_environ">
|
||
<code class="descclassname">os.</code><code class="descname">supports_bytes_environ</code><a class="headerlink" href="#os.supports_bytes_environ" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p><code class="docutils literal notranslate"><span class="pre">True</span></code> if the native OS type of the environment is bytes (eg. <code class="docutils literal notranslate"><span class="pre">False</span></code> on
|
||
Windows).</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.2.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.umask">
|
||
<code class="descclassname">os.</code><code class="descname">umask</code><span class="sig-paren">(</span><em>mask</em><span class="sig-paren">)</span><a class="headerlink" href="#os.umask" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Set the current numeric umask and return the previous umask.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.uname">
|
||
<code class="descclassname">os.</code><code class="descname">uname</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#os.uname" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p id="index-12">Returns information identifying the current operating system.
|
||
The return value is an object with five attributes:</p>
|
||
<ul class="simple">
|
||
<li><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">sysname</span></code> - operating system name</p></li>
|
||
<li><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">nodename</span></code> - name of machine on network (implementation-defined)</p></li>
|
||
<li><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">release</span></code> - operating system release</p></li>
|
||
<li><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">version</span></code> - operating system version</p></li>
|
||
<li><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">machine</span></code> - hardware identifier</p></li>
|
||
</ul>
|
||
<p>For backwards compatibility, this object is also iterable, behaving
|
||
like a five-tuple containing <code class="xref py py-attr docutils literal notranslate"><span class="pre">sysname</span></code>, <code class="xref py py-attr docutils literal notranslate"><span class="pre">nodename</span></code>,
|
||
<code class="xref py py-attr docutils literal notranslate"><span class="pre">release</span></code>, <code class="xref py py-attr docutils literal notranslate"><span class="pre">version</span></code>, and <code class="xref py py-attr docutils literal notranslate"><span class="pre">machine</span></code>
|
||
in that order.</p>
|
||
<p>Some systems truncate <code class="xref py py-attr docutils literal notranslate"><span class="pre">nodename</span></code> to 8 characters or to the
|
||
leading component; a better way to get the hostname is
|
||
<a class="reference internal" href="socket.html#socket.gethostname" title="socket.gethostname"><code class="xref py py-func docutils literal notranslate"><span class="pre">socket.gethostname()</span></code></a> or even
|
||
<code class="docutils literal notranslate"><span class="pre">socket.gethostbyaddr(socket.gethostname())</span></code>.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: recent flavors of Unix.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.3: </span>Return type changed from a tuple to a tuple-like object
|
||
with named attributes.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.unsetenv">
|
||
<code class="descclassname">os.</code><code class="descname">unsetenv</code><span class="sig-paren">(</span><em>key</em><span class="sig-paren">)</span><a class="headerlink" href="#os.unsetenv" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p id="index-13">Unset (delete) the environment variable named <em>key</em>. Such changes to the
|
||
environment affect subprocesses started with <a class="reference internal" href="#os.system" title="os.system"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.system()</span></code></a>, <a class="reference internal" href="#os.popen" title="os.popen"><code class="xref py py-func docutils literal notranslate"><span class="pre">popen()</span></code></a> or
|
||
<a class="reference internal" href="#os.fork" title="os.fork"><code class="xref py py-func docutils literal notranslate"><span class="pre">fork()</span></code></a> and <a class="reference internal" href="#os.execv" title="os.execv"><code class="xref py py-func docutils literal notranslate"><span class="pre">execv()</span></code></a>.</p>
|
||
<p>When <a class="reference internal" href="#os.unsetenv" title="os.unsetenv"><code class="xref py py-func docutils literal notranslate"><span class="pre">unsetenv()</span></code></a> is supported, deletion of items in <code class="docutils literal notranslate"><span class="pre">os.environ</span></code> is
|
||
automatically translated into a corresponding call to <a class="reference internal" href="#os.unsetenv" title="os.unsetenv"><code class="xref py py-func docutils literal notranslate"><span class="pre">unsetenv()</span></code></a>; however,
|
||
calls to <a class="reference internal" href="#os.unsetenv" title="os.unsetenv"><code class="xref py py-func docutils literal notranslate"><span class="pre">unsetenv()</span></code></a> don’t update <code class="docutils literal notranslate"><span class="pre">os.environ</span></code>, so it is actually
|
||
preferable to delete items of <code class="docutils literal notranslate"><span class="pre">os.environ</span></code>.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: most flavors of Unix, Windows.</p>
|
||
</dd></dl>
|
||
|
||
</div>
|
||
<div class="section" id="file-object-creation">
|
||
<span id="os-newstreams"></span><h2>File Object Creation<a class="headerlink" href="#file-object-creation" title="Permalink to this headline">¶</a></h2>
|
||
<p>This function creates new <a class="reference internal" href="../glossary.html#term-file-object"><span class="xref std std-term">file objects</span></a>. (See also
|
||
<a class="reference internal" href="#os.open" title="os.open"><code class="xref py py-func docutils literal notranslate"><span class="pre">open()</span></code></a> for opening file descriptors.)</p>
|
||
<dl class="function">
|
||
<dt id="os.fdopen">
|
||
<code class="descclassname">os.</code><code class="descname">fdopen</code><span class="sig-paren">(</span><em>fd</em>, <em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#os.fdopen" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return an open file object connected to the file descriptor <em>fd</em>. This is an
|
||
alias of the <a class="reference internal" href="functions.html#open" title="open"><code class="xref py py-func docutils literal notranslate"><span class="pre">open()</span></code></a> built-in function and accepts the same arguments.
|
||
The only difference is that the first argument of <a class="reference internal" href="#os.fdopen" title="os.fdopen"><code class="xref py py-func docutils literal notranslate"><span class="pre">fdopen()</span></code></a> must always
|
||
be an integer.</p>
|
||
</dd></dl>
|
||
|
||
</div>
|
||
<div class="section" id="file-descriptor-operations">
|
||
<span id="os-fd-ops"></span><h2>File Descriptor Operations<a class="headerlink" href="#file-descriptor-operations" title="Permalink to this headline">¶</a></h2>
|
||
<p>These functions operate on I/O streams referenced using file descriptors.</p>
|
||
<p>File descriptors are small integers corresponding to a file that has been opened
|
||
by the current process. For example, standard input is usually file descriptor
|
||
0, standard output is 1, and standard error is 2. Further files opened by a
|
||
process will then be assigned 3, 4, 5, and so forth. The name “file descriptor”
|
||
is slightly deceptive; on Unix platforms, sockets and pipes are also referenced
|
||
by file descriptors.</p>
|
||
<p>The <a class="reference internal" href="io.html#io.IOBase.fileno" title="io.IOBase.fileno"><code class="xref py py-meth docutils literal notranslate"><span class="pre">fileno()</span></code></a> method can be used to obtain the file descriptor
|
||
associated with a <a class="reference internal" href="../glossary.html#term-file-object"><span class="xref std std-term">file object</span></a> when required. Note that using the file
|
||
descriptor directly will bypass the file object methods, ignoring aspects such
|
||
as internal buffering of data.</p>
|
||
<dl class="function">
|
||
<dt id="os.close">
|
||
<code class="descclassname">os.</code><code class="descname">close</code><span class="sig-paren">(</span><em>fd</em><span class="sig-paren">)</span><a class="headerlink" href="#os.close" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Close file descriptor <em>fd</em>.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>This function is intended for low-level I/O and must be applied to a file
|
||
descriptor as returned by <a class="reference internal" href="#os.open" title="os.open"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.open()</span></code></a> or <a class="reference internal" href="#os.pipe" title="os.pipe"><code class="xref py py-func docutils literal notranslate"><span class="pre">pipe()</span></code></a>. To close a “file
|
||
object” returned by the built-in function <a class="reference internal" href="functions.html#open" title="open"><code class="xref py py-func docutils literal notranslate"><span class="pre">open()</span></code></a> or by <a class="reference internal" href="#os.popen" title="os.popen"><code class="xref py py-func docutils literal notranslate"><span class="pre">popen()</span></code></a> or
|
||
<a class="reference internal" href="#os.fdopen" title="os.fdopen"><code class="xref py py-func docutils literal notranslate"><span class="pre">fdopen()</span></code></a>, use its <a class="reference internal" href="io.html#io.IOBase.close" title="io.IOBase.close"><code class="xref py py-meth docutils literal notranslate"><span class="pre">close()</span></code></a> method.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.closerange">
|
||
<code class="descclassname">os.</code><code class="descname">closerange</code><span class="sig-paren">(</span><em>fd_low</em>, <em>fd_high</em><span class="sig-paren">)</span><a class="headerlink" href="#os.closerange" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Close all file descriptors from <em>fd_low</em> (inclusive) to <em>fd_high</em> (exclusive),
|
||
ignoring errors. Equivalent to (but much faster than):</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">for</span> <span class="n">fd</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="n">fd_low</span><span class="p">,</span> <span class="n">fd_high</span><span class="p">):</span>
|
||
<span class="k">try</span><span class="p">:</span>
|
||
<span class="n">os</span><span class="o">.</span><span class="n">close</span><span class="p">(</span><span class="n">fd</span><span class="p">)</span>
|
||
<span class="k">except</span> <span class="ne">OSError</span><span class="p">:</span>
|
||
<span class="k">pass</span>
|
||
</pre></div>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.device_encoding">
|
||
<code class="descclassname">os.</code><code class="descname">device_encoding</code><span class="sig-paren">(</span><em>fd</em><span class="sig-paren">)</span><a class="headerlink" href="#os.device_encoding" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return a string describing the encoding of the device associated with <em>fd</em>
|
||
if it is connected to a terminal; else return <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal notranslate"><span class="pre">None</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.dup">
|
||
<code class="descclassname">os.</code><code class="descname">dup</code><span class="sig-paren">(</span><em>fd</em><span class="sig-paren">)</span><a class="headerlink" href="#os.dup" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return a duplicate of file descriptor <em>fd</em>. The new file descriptor is
|
||
<a class="reference internal" href="#fd-inheritance"><span class="std std-ref">non-inheritable</span></a>.</p>
|
||
<p>On Windows, when duplicating a standard stream (0: stdin, 1: stdout,
|
||
2: stderr), the new file descriptor is <a class="reference internal" href="#fd-inheritance"><span class="std std-ref">inheritable</span></a>.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.4: </span>The new file descriptor is now non-inheritable.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.dup2">
|
||
<code class="descclassname">os.</code><code class="descname">dup2</code><span class="sig-paren">(</span><em>fd</em>, <em>fd2</em>, <em>inheritable=True</em><span class="sig-paren">)</span><a class="headerlink" href="#os.dup2" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Duplicate file descriptor <em>fd</em> to <em>fd2</em>, closing the latter first if
|
||
necessary. Return <em>fd2</em>. The new file descriptor is <a class="reference internal" href="#fd-inheritance"><span class="std std-ref">inheritable</span></a> by default or non-inheritable if <em>inheritable</em>
|
||
is <code class="docutils literal notranslate"><span class="pre">False</span></code>.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.4: </span>Add the optional <em>inheritable</em> parameter.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.7: </span>Return <em>fd2</em> on success. Previously, <code class="docutils literal notranslate"><span class="pre">None</span></code> was always returned.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.fchmod">
|
||
<code class="descclassname">os.</code><code class="descname">fchmod</code><span class="sig-paren">(</span><em>fd</em>, <em>mode</em><span class="sig-paren">)</span><a class="headerlink" href="#os.fchmod" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Change the mode of the file given by <em>fd</em> to the numeric <em>mode</em>. See the
|
||
docs for <a class="reference internal" href="#os.chmod" title="os.chmod"><code class="xref py py-func docutils literal notranslate"><span class="pre">chmod()</span></code></a> for possible values of <em>mode</em>. As of Python 3.3, this
|
||
is equivalent to <code class="docutils literal notranslate"><span class="pre">os.chmod(fd,</span> <span class="pre">mode)</span></code>.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.fchown">
|
||
<code class="descclassname">os.</code><code class="descname">fchown</code><span class="sig-paren">(</span><em>fd</em>, <em>uid</em>, <em>gid</em><span class="sig-paren">)</span><a class="headerlink" href="#os.fchown" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Change the owner and group id of the file given by <em>fd</em> to the numeric <em>uid</em>
|
||
and <em>gid</em>. To leave one of the ids unchanged, set it to -1. See
|
||
<a class="reference internal" href="#os.chown" title="os.chown"><code class="xref py py-func docutils literal notranslate"><span class="pre">chown()</span></code></a>. As of Python 3.3, this is equivalent to <code class="docutils literal notranslate"><span class="pre">os.chown(fd,</span> <span class="pre">uid,</span>
|
||
<span class="pre">gid)</span></code>.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.fdatasync">
|
||
<code class="descclassname">os.</code><code class="descname">fdatasync</code><span class="sig-paren">(</span><em>fd</em><span class="sig-paren">)</span><a class="headerlink" href="#os.fdatasync" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Force write of file with filedescriptor <em>fd</em> to disk. Does not force update of
|
||
metadata.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>This function is not available on MacOS.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.fpathconf">
|
||
<code class="descclassname">os.</code><code class="descname">fpathconf</code><span class="sig-paren">(</span><em>fd</em>, <em>name</em><span class="sig-paren">)</span><a class="headerlink" href="#os.fpathconf" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return system configuration information relevant to an open file. <em>name</em>
|
||
specifies the configuration value to retrieve; it may be a string which is the
|
||
name of a defined system value; these names are specified in a number of
|
||
standards (POSIX.1, Unix 95, Unix 98, and others). Some platforms define
|
||
additional names as well. The names known to the host operating system are
|
||
given in the <code class="docutils literal notranslate"><span class="pre">pathconf_names</span></code> dictionary. For configuration variables not
|
||
included in that mapping, passing an integer for <em>name</em> is also accepted.</p>
|
||
<p>If <em>name</em> is a string and is not known, <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> is raised. If a
|
||
specific value for <em>name</em> is not supported by the host system, even if it is
|
||
included in <code class="docutils literal notranslate"><span class="pre">pathconf_names</span></code>, an <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a> is raised with
|
||
<a class="reference internal" href="errno.html#errno.EINVAL" title="errno.EINVAL"><code class="xref py py-const docutils literal notranslate"><span class="pre">errno.EINVAL</span></code></a> for the error number.</p>
|
||
<p>As of Python 3.3, this is equivalent to <code class="docutils literal notranslate"><span class="pre">os.pathconf(fd,</span> <span class="pre">name)</span></code>.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.fstat">
|
||
<code class="descclassname">os.</code><code class="descname">fstat</code><span class="sig-paren">(</span><em>fd</em><span class="sig-paren">)</span><a class="headerlink" href="#os.fstat" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Get the status of the file descriptor <em>fd</em>. Return a <a class="reference internal" href="#os.stat_result" title="os.stat_result"><code class="xref py py-class docutils literal notranslate"><span class="pre">stat_result</span></code></a>
|
||
object.</p>
|
||
<p>As of Python 3.3, this is equivalent to <code class="docutils literal notranslate"><span class="pre">os.stat(fd)</span></code>.</p>
|
||
<div class="admonition seealso">
|
||
<p class="admonition-title">See also</p>
|
||
<p>The <a class="reference internal" href="#os.stat" title="os.stat"><code class="xref py py-func docutils literal notranslate"><span class="pre">stat()</span></code></a> function.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.fstatvfs">
|
||
<code class="descclassname">os.</code><code class="descname">fstatvfs</code><span class="sig-paren">(</span><em>fd</em><span class="sig-paren">)</span><a class="headerlink" href="#os.fstatvfs" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return information about the filesystem containing the file associated with
|
||
file descriptor <em>fd</em>, like <a class="reference internal" href="#os.statvfs" title="os.statvfs"><code class="xref py py-func docutils literal notranslate"><span class="pre">statvfs()</span></code></a>. As of Python 3.3, this is
|
||
equivalent to <code class="docutils literal notranslate"><span class="pre">os.statvfs(fd)</span></code>.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.fsync">
|
||
<code class="descclassname">os.</code><code class="descname">fsync</code><span class="sig-paren">(</span><em>fd</em><span class="sig-paren">)</span><a class="headerlink" href="#os.fsync" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Force write of file with filedescriptor <em>fd</em> to disk. On Unix, this calls the
|
||
native <code class="xref c c-func docutils literal notranslate"><span class="pre">fsync()</span></code> function; on Windows, the MS <code class="xref c c-func docutils literal notranslate"><span class="pre">_commit()</span></code> function.</p>
|
||
<p>If you’re starting with a buffered Python <a class="reference internal" href="../glossary.html#term-file-object"><span class="xref std std-term">file object</span></a> <em>f</em>, first do
|
||
<code class="docutils literal notranslate"><span class="pre">f.flush()</span></code>, and then do <code class="docutils literal notranslate"><span class="pre">os.fsync(f.fileno())</span></code>, to ensure that all internal
|
||
buffers associated with <em>f</em> are written to disk.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix, Windows.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.ftruncate">
|
||
<code class="descclassname">os.</code><code class="descname">ftruncate</code><span class="sig-paren">(</span><em>fd</em>, <em>length</em><span class="sig-paren">)</span><a class="headerlink" href="#os.ftruncate" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Truncate the file corresponding to file descriptor <em>fd</em>, so that it is at
|
||
most <em>length</em> bytes in size. As of Python 3.3, this is equivalent to
|
||
<code class="docutils literal notranslate"><span class="pre">os.truncate(fd,</span> <span class="pre">length)</span></code>.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix, Windows.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.5: </span>Added support for Windows</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.get_blocking">
|
||
<code class="descclassname">os.</code><code class="descname">get_blocking</code><span class="sig-paren">(</span><em>fd</em><span class="sig-paren">)</span><a class="headerlink" href="#os.get_blocking" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Get the blocking mode of the file descriptor: <code class="docutils literal notranslate"><span class="pre">False</span></code> if the
|
||
<a class="reference internal" href="#os.O_NONBLOCK" title="os.O_NONBLOCK"><code class="xref py py-data docutils literal notranslate"><span class="pre">O_NONBLOCK</span></code></a> flag is set, <code class="docutils literal notranslate"><span class="pre">True</span></code> if the flag is cleared.</p>
|
||
<p>See also <a class="reference internal" href="#os.set_blocking" title="os.set_blocking"><code class="xref py py-func docutils literal notranslate"><span class="pre">set_blocking()</span></code></a> and <a class="reference internal" href="socket.html#socket.socket.setblocking" title="socket.socket.setblocking"><code class="xref py py-meth docutils literal notranslate"><span class="pre">socket.socket.setblocking()</span></code></a>.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.5.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.isatty">
|
||
<code class="descclassname">os.</code><code class="descname">isatty</code><span class="sig-paren">(</span><em>fd</em><span class="sig-paren">)</span><a class="headerlink" href="#os.isatty" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return <code class="docutils literal notranslate"><span class="pre">True</span></code> if the file descriptor <em>fd</em> is open and connected to a
|
||
tty(-like) device, else <code class="docutils literal notranslate"><span class="pre">False</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.lockf">
|
||
<code class="descclassname">os.</code><code class="descname">lockf</code><span class="sig-paren">(</span><em>fd</em>, <em>cmd</em>, <em>len</em><span class="sig-paren">)</span><a class="headerlink" href="#os.lockf" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Apply, test or remove a POSIX lock on an open file descriptor.
|
||
<em>fd</em> is an open file descriptor.
|
||
<em>cmd</em> specifies the command to use - one of <a class="reference internal" href="#os.F_LOCK" title="os.F_LOCK"><code class="xref py py-data docutils literal notranslate"><span class="pre">F_LOCK</span></code></a>, <a class="reference internal" href="#os.F_TLOCK" title="os.F_TLOCK"><code class="xref py py-data docutils literal notranslate"><span class="pre">F_TLOCK</span></code></a>,
|
||
<a class="reference internal" href="#os.F_ULOCK" title="os.F_ULOCK"><code class="xref py py-data docutils literal notranslate"><span class="pre">F_ULOCK</span></code></a> or <a class="reference internal" href="#os.F_TEST" title="os.F_TEST"><code class="xref py py-data docutils literal notranslate"><span class="pre">F_TEST</span></code></a>.
|
||
<em>len</em> specifies the section of the file to lock.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.F_LOCK">
|
||
<code class="descclassname">os.</code><code class="descname">F_LOCK</code><a class="headerlink" href="#os.F_LOCK" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.F_TLOCK">
|
||
<code class="descclassname">os.</code><code class="descname">F_TLOCK</code><a class="headerlink" href="#os.F_TLOCK" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.F_ULOCK">
|
||
<code class="descclassname">os.</code><code class="descname">F_ULOCK</code><a class="headerlink" href="#os.F_ULOCK" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.F_TEST">
|
||
<code class="descclassname">os.</code><code class="descname">F_TEST</code><a class="headerlink" href="#os.F_TEST" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Flags that specify what action <a class="reference internal" href="#os.lockf" title="os.lockf"><code class="xref py py-func docutils literal notranslate"><span class="pre">lockf()</span></code></a> will take.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.lseek">
|
||
<code class="descclassname">os.</code><code class="descname">lseek</code><span class="sig-paren">(</span><em>fd</em>, <em>pos</em>, <em>how</em><span class="sig-paren">)</span><a class="headerlink" href="#os.lseek" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Set the current position of file descriptor <em>fd</em> to position <em>pos</em>, modified
|
||
by <em>how</em>: <a class="reference internal" href="#os.SEEK_SET" title="os.SEEK_SET"><code class="xref py py-const docutils literal notranslate"><span class="pre">SEEK_SET</span></code></a> or <code class="docutils literal notranslate"><span class="pre">0</span></code> to set the position relative to the
|
||
beginning of the file; <a class="reference internal" href="#os.SEEK_CUR" title="os.SEEK_CUR"><code class="xref py py-const docutils literal notranslate"><span class="pre">SEEK_CUR</span></code></a> or <code class="docutils literal notranslate"><span class="pre">1</span></code> to set it relative to the
|
||
current position; <a class="reference internal" href="#os.SEEK_END" title="os.SEEK_END"><code class="xref py py-const docutils literal notranslate"><span class="pre">SEEK_END</span></code></a> or <code class="docutils literal notranslate"><span class="pre">2</span></code> to set it relative to the end of
|
||
the file. Return the new cursor position in bytes, starting from the beginning.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.SEEK_SET">
|
||
<code class="descclassname">os.</code><code class="descname">SEEK_SET</code><a class="headerlink" href="#os.SEEK_SET" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.SEEK_CUR">
|
||
<code class="descclassname">os.</code><code class="descname">SEEK_CUR</code><a class="headerlink" href="#os.SEEK_CUR" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.SEEK_END">
|
||
<code class="descclassname">os.</code><code class="descname">SEEK_END</code><a class="headerlink" href="#os.SEEK_END" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Parameters to the <a class="reference internal" href="#os.lseek" title="os.lseek"><code class="xref py py-func docutils literal notranslate"><span class="pre">lseek()</span></code></a> function. Their values are 0, 1, and 2,
|
||
respectively.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3: </span>Some operating systems could support additional values, like
|
||
<code class="xref py py-data docutils literal notranslate"><span class="pre">os.SEEK_HOLE</span></code> or <code class="xref py py-data docutils literal notranslate"><span class="pre">os.SEEK_DATA</span></code>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.open">
|
||
<code class="descclassname">os.</code><code class="descname">open</code><span class="sig-paren">(</span><em>path</em>, <em>flags</em>, <em>mode=0o777</em>, <em>*</em>, <em>dir_fd=None</em><span class="sig-paren">)</span><a class="headerlink" href="#os.open" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Open the file <em>path</em> and set various flags according to <em>flags</em> and possibly
|
||
its mode according to <em>mode</em>. When computing <em>mode</em>, the current umask value
|
||
is first masked out. Return the file descriptor for the newly opened file.
|
||
The new file descriptor is <a class="reference internal" href="#fd-inheritance"><span class="std std-ref">non-inheritable</span></a>.</p>
|
||
<p>For a description of the flag and mode values, see the C run-time documentation;
|
||
flag constants (like <a class="reference internal" href="#os.O_RDONLY" title="os.O_RDONLY"><code class="xref py py-const docutils literal notranslate"><span class="pre">O_RDONLY</span></code></a> and <a class="reference internal" href="#os.O_WRONLY" title="os.O_WRONLY"><code class="xref py py-const docutils literal notranslate"><span class="pre">O_WRONLY</span></code></a>) are defined in
|
||
the <a class="reference internal" href="#module-os" title="os: Miscellaneous operating system interfaces."><code class="xref py py-mod docutils literal notranslate"><span class="pre">os</span></code></a> module. In particular, on Windows adding
|
||
<a class="reference internal" href="#os.O_BINARY" title="os.O_BINARY"><code class="xref py py-const docutils literal notranslate"><span class="pre">O_BINARY</span></code></a> is needed to open files in binary mode.</p>
|
||
<p>This function can support <a class="reference internal" href="#dir-fd"><span class="std std-ref">paths relative to directory descriptors</span></a> with the <em>dir_fd</em> parameter.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.4: </span>The new file descriptor is now non-inheritable.</p>
|
||
</div>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>This function is intended for low-level I/O. For normal usage, use the
|
||
built-in function <a class="reference internal" href="functions.html#open" title="open"><code class="xref py py-func docutils literal notranslate"><span class="pre">open()</span></code></a>, which returns a <a class="reference internal" href="../glossary.html#term-file-object"><span class="xref std std-term">file object</span></a> with
|
||
<code class="xref py py-meth docutils literal notranslate"><span class="pre">read()</span></code> and <code class="xref py py-meth docutils literal notranslate"><span class="pre">write()</span></code> methods (and many more). To
|
||
wrap a file descriptor in a file object, use <a class="reference internal" href="#os.fdopen" title="os.fdopen"><code class="xref py py-func docutils literal notranslate"><span class="pre">fdopen()</span></code></a>.</p>
|
||
</div>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3: </span>The <em>dir_fd</em> argument.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.5: </span>If the system call is interrupted and the signal handler does not raise an
|
||
exception, the function now retries the system call instead of raising an
|
||
<a class="reference internal" href="exceptions.html#InterruptedError" title="InterruptedError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">InterruptedError</span></code></a> exception (see <span class="target" id="index-14"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0475"><strong>PEP 475</strong></a> for the rationale).</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>Accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<p>The following constants are options for the <em>flags</em> parameter to the
|
||
<a class="reference internal" href="#os.open" title="os.open"><code class="xref py py-func docutils literal notranslate"><span class="pre">open()</span></code></a> function. They can be combined using the bitwise OR operator
|
||
<code class="docutils literal notranslate"><span class="pre">|</span></code>. Some of them are not available on all platforms. For descriptions of
|
||
their availability and use, consult the <em class="manpage">open(2)</em> manual page on Unix
|
||
or <a class="reference external" href="https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx">the MSDN</a> on Windows.</p>
|
||
<dl class="data">
|
||
<dt id="os.O_RDONLY">
|
||
<code class="descclassname">os.</code><code class="descname">O_RDONLY</code><a class="headerlink" href="#os.O_RDONLY" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.O_WRONLY">
|
||
<code class="descclassname">os.</code><code class="descname">O_WRONLY</code><a class="headerlink" href="#os.O_WRONLY" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.O_RDWR">
|
||
<code class="descclassname">os.</code><code class="descname">O_RDWR</code><a class="headerlink" href="#os.O_RDWR" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.O_APPEND">
|
||
<code class="descclassname">os.</code><code class="descname">O_APPEND</code><a class="headerlink" href="#os.O_APPEND" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.O_CREAT">
|
||
<code class="descclassname">os.</code><code class="descname">O_CREAT</code><a class="headerlink" href="#os.O_CREAT" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.O_EXCL">
|
||
<code class="descclassname">os.</code><code class="descname">O_EXCL</code><a class="headerlink" href="#os.O_EXCL" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.O_TRUNC">
|
||
<code class="descclassname">os.</code><code class="descname">O_TRUNC</code><a class="headerlink" href="#os.O_TRUNC" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>The above constants are available on Unix and Windows.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.O_DSYNC">
|
||
<code class="descclassname">os.</code><code class="descname">O_DSYNC</code><a class="headerlink" href="#os.O_DSYNC" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.O_RSYNC">
|
||
<code class="descclassname">os.</code><code class="descname">O_RSYNC</code><a class="headerlink" href="#os.O_RSYNC" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.O_SYNC">
|
||
<code class="descclassname">os.</code><code class="descname">O_SYNC</code><a class="headerlink" href="#os.O_SYNC" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.O_NDELAY">
|
||
<code class="descclassname">os.</code><code class="descname">O_NDELAY</code><a class="headerlink" href="#os.O_NDELAY" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.O_NONBLOCK">
|
||
<code class="descclassname">os.</code><code class="descname">O_NONBLOCK</code><a class="headerlink" href="#os.O_NONBLOCK" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.O_NOCTTY">
|
||
<code class="descclassname">os.</code><code class="descname">O_NOCTTY</code><a class="headerlink" href="#os.O_NOCTTY" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.O_CLOEXEC">
|
||
<code class="descclassname">os.</code><code class="descname">O_CLOEXEC</code><a class="headerlink" href="#os.O_CLOEXEC" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>The above constants are only available on Unix.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.3: </span>Add <a class="reference internal" href="#os.O_CLOEXEC" title="os.O_CLOEXEC"><code class="xref py py-data docutils literal notranslate"><span class="pre">O_CLOEXEC</span></code></a> constant.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.O_BINARY">
|
||
<code class="descclassname">os.</code><code class="descname">O_BINARY</code><a class="headerlink" href="#os.O_BINARY" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.O_NOINHERIT">
|
||
<code class="descclassname">os.</code><code class="descname">O_NOINHERIT</code><a class="headerlink" href="#os.O_NOINHERIT" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.O_SHORT_LIVED">
|
||
<code class="descclassname">os.</code><code class="descname">O_SHORT_LIVED</code><a class="headerlink" href="#os.O_SHORT_LIVED" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.O_TEMPORARY">
|
||
<code class="descclassname">os.</code><code class="descname">O_TEMPORARY</code><a class="headerlink" href="#os.O_TEMPORARY" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.O_RANDOM">
|
||
<code class="descclassname">os.</code><code class="descname">O_RANDOM</code><a class="headerlink" href="#os.O_RANDOM" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.O_SEQUENTIAL">
|
||
<code class="descclassname">os.</code><code class="descname">O_SEQUENTIAL</code><a class="headerlink" href="#os.O_SEQUENTIAL" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.O_TEXT">
|
||
<code class="descclassname">os.</code><code class="descname">O_TEXT</code><a class="headerlink" href="#os.O_TEXT" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>The above constants are only available on Windows.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.O_ASYNC">
|
||
<code class="descclassname">os.</code><code class="descname">O_ASYNC</code><a class="headerlink" href="#os.O_ASYNC" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.O_DIRECT">
|
||
<code class="descclassname">os.</code><code class="descname">O_DIRECT</code><a class="headerlink" href="#os.O_DIRECT" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.O_DIRECTORY">
|
||
<code class="descclassname">os.</code><code class="descname">O_DIRECTORY</code><a class="headerlink" href="#os.O_DIRECTORY" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.O_NOFOLLOW">
|
||
<code class="descclassname">os.</code><code class="descname">O_NOFOLLOW</code><a class="headerlink" href="#os.O_NOFOLLOW" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.O_NOATIME">
|
||
<code class="descclassname">os.</code><code class="descname">O_NOATIME</code><a class="headerlink" href="#os.O_NOATIME" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.O_PATH">
|
||
<code class="descclassname">os.</code><code class="descname">O_PATH</code><a class="headerlink" href="#os.O_PATH" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.O_TMPFILE">
|
||
<code class="descclassname">os.</code><code class="descname">O_TMPFILE</code><a class="headerlink" href="#os.O_TMPFILE" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.O_SHLOCK">
|
||
<code class="descclassname">os.</code><code class="descname">O_SHLOCK</code><a class="headerlink" href="#os.O_SHLOCK" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.O_EXLOCK">
|
||
<code class="descclassname">os.</code><code class="descname">O_EXLOCK</code><a class="headerlink" href="#os.O_EXLOCK" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>The above constants are extensions and not present if they are not defined by
|
||
the C library.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.4: </span>Add <a class="reference internal" href="#os.O_PATH" title="os.O_PATH"><code class="xref py py-data docutils literal notranslate"><span class="pre">O_PATH</span></code></a> on systems that support it.
|
||
Add <a class="reference internal" href="#os.O_TMPFILE" title="os.O_TMPFILE"><code class="xref py py-data docutils literal notranslate"><span class="pre">O_TMPFILE</span></code></a>, only available on Linux Kernel 3.11
|
||
or newer.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.openpty">
|
||
<code class="descclassname">os.</code><code class="descname">openpty</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#os.openpty" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p id="index-15">Open a new pseudo-terminal pair. Return a pair of file descriptors
|
||
<code class="docutils literal notranslate"><span class="pre">(master,</span> <span class="pre">slave)</span></code> for the pty and the tty, respectively. The new file
|
||
descriptors are <a class="reference internal" href="#fd-inheritance"><span class="std std-ref">non-inheritable</span></a>. For a (slightly) more
|
||
portable approach, use the <a class="reference internal" href="pty.html#module-pty" title="pty: Pseudo-Terminal Handling for Linux. (Linux)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">pty</span></code></a> module.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: some flavors of Unix.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.4: </span>The new file descriptors are now non-inheritable.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.pipe">
|
||
<code class="descclassname">os.</code><code class="descname">pipe</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#os.pipe" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Create a pipe. Return a pair of file descriptors <code class="docutils literal notranslate"><span class="pre">(r,</span> <span class="pre">w)</span></code> usable for
|
||
reading and writing, respectively. The new file descriptor is
|
||
<a class="reference internal" href="#fd-inheritance"><span class="std std-ref">non-inheritable</span></a>.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix, Windows.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.4: </span>The new file descriptors are now non-inheritable.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.pipe2">
|
||
<code class="descclassname">os.</code><code class="descname">pipe2</code><span class="sig-paren">(</span><em>flags</em><span class="sig-paren">)</span><a class="headerlink" href="#os.pipe2" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Create a pipe with <em>flags</em> set atomically.
|
||
<em>flags</em> can be constructed by ORing together one or more of these values:
|
||
<a class="reference internal" href="#os.O_NONBLOCK" title="os.O_NONBLOCK"><code class="xref py py-data docutils literal notranslate"><span class="pre">O_NONBLOCK</span></code></a>, <a class="reference internal" href="#os.O_CLOEXEC" title="os.O_CLOEXEC"><code class="xref py py-data docutils literal notranslate"><span class="pre">O_CLOEXEC</span></code></a>.
|
||
Return a pair of file descriptors <code class="docutils literal notranslate"><span class="pre">(r,</span> <span class="pre">w)</span></code> usable for reading and writing,
|
||
respectively.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: some flavors of Unix.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.posix_fallocate">
|
||
<code class="descclassname">os.</code><code class="descname">posix_fallocate</code><span class="sig-paren">(</span><em>fd</em>, <em>offset</em>, <em>len</em><span class="sig-paren">)</span><a class="headerlink" href="#os.posix_fallocate" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Ensures that enough disk space is allocated for the file specified by <em>fd</em>
|
||
starting from <em>offset</em> and continuing for <em>len</em> bytes.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.posix_fadvise">
|
||
<code class="descclassname">os.</code><code class="descname">posix_fadvise</code><span class="sig-paren">(</span><em>fd</em>, <em>offset</em>, <em>len</em>, <em>advice</em><span class="sig-paren">)</span><a class="headerlink" href="#os.posix_fadvise" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Announces an intention to access data in a specific pattern thus allowing
|
||
the kernel to make optimizations.
|
||
The advice applies to the region of the file specified by <em>fd</em> starting at
|
||
<em>offset</em> and continuing for <em>len</em> bytes.
|
||
<em>advice</em> is one of <a class="reference internal" href="#os.POSIX_FADV_NORMAL" title="os.POSIX_FADV_NORMAL"><code class="xref py py-data docutils literal notranslate"><span class="pre">POSIX_FADV_NORMAL</span></code></a>, <a class="reference internal" href="#os.POSIX_FADV_SEQUENTIAL" title="os.POSIX_FADV_SEQUENTIAL"><code class="xref py py-data docutils literal notranslate"><span class="pre">POSIX_FADV_SEQUENTIAL</span></code></a>,
|
||
<a class="reference internal" href="#os.POSIX_FADV_RANDOM" title="os.POSIX_FADV_RANDOM"><code class="xref py py-data docutils literal notranslate"><span class="pre">POSIX_FADV_RANDOM</span></code></a>, <a class="reference internal" href="#os.POSIX_FADV_NOREUSE" title="os.POSIX_FADV_NOREUSE"><code class="xref py py-data docutils literal notranslate"><span class="pre">POSIX_FADV_NOREUSE</span></code></a>,
|
||
<a class="reference internal" href="#os.POSIX_FADV_WILLNEED" title="os.POSIX_FADV_WILLNEED"><code class="xref py py-data docutils literal notranslate"><span class="pre">POSIX_FADV_WILLNEED</span></code></a> or <a class="reference internal" href="#os.POSIX_FADV_DONTNEED" title="os.POSIX_FADV_DONTNEED"><code class="xref py py-data docutils literal notranslate"><span class="pre">POSIX_FADV_DONTNEED</span></code></a>.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.POSIX_FADV_NORMAL">
|
||
<code class="descclassname">os.</code><code class="descname">POSIX_FADV_NORMAL</code><a class="headerlink" href="#os.POSIX_FADV_NORMAL" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.POSIX_FADV_SEQUENTIAL">
|
||
<code class="descclassname">os.</code><code class="descname">POSIX_FADV_SEQUENTIAL</code><a class="headerlink" href="#os.POSIX_FADV_SEQUENTIAL" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.POSIX_FADV_RANDOM">
|
||
<code class="descclassname">os.</code><code class="descname">POSIX_FADV_RANDOM</code><a class="headerlink" href="#os.POSIX_FADV_RANDOM" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.POSIX_FADV_NOREUSE">
|
||
<code class="descclassname">os.</code><code class="descname">POSIX_FADV_NOREUSE</code><a class="headerlink" href="#os.POSIX_FADV_NOREUSE" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.POSIX_FADV_WILLNEED">
|
||
<code class="descclassname">os.</code><code class="descname">POSIX_FADV_WILLNEED</code><a class="headerlink" href="#os.POSIX_FADV_WILLNEED" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.POSIX_FADV_DONTNEED">
|
||
<code class="descclassname">os.</code><code class="descname">POSIX_FADV_DONTNEED</code><a class="headerlink" href="#os.POSIX_FADV_DONTNEED" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Flags that can be used in <em>advice</em> in <a class="reference internal" href="#os.posix_fadvise" title="os.posix_fadvise"><code class="xref py py-func docutils literal notranslate"><span class="pre">posix_fadvise()</span></code></a> that specify
|
||
the access pattern that is likely to be used.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.pread">
|
||
<code class="descclassname">os.</code><code class="descname">pread</code><span class="sig-paren">(</span><em>fd</em>, <em>n</em>, <em>offset</em><span class="sig-paren">)</span><a class="headerlink" href="#os.pread" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Read at most <em>n</em> bytes from file descriptor <em>fd</em> at a position of <em>offset</em>,
|
||
leaving the file offset unchanged.</p>
|
||
<p>Return a bytestring containing the bytes read. If the end of the file
|
||
referred to by <em>fd</em> has been reached, an empty bytes object is returned.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.preadv">
|
||
<code class="descclassname">os.</code><code class="descname">preadv</code><span class="sig-paren">(</span><em>fd</em>, <em>buffers</em>, <em>offset</em>, <em>flags=0</em><span class="sig-paren">)</span><a class="headerlink" href="#os.preadv" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Read from a file descriptor <em>fd</em> at a position of <em>offset</em> into mutable
|
||
<a class="reference internal" href="../glossary.html#term-bytes-like-object"><span class="xref std std-term">bytes-like objects</span></a> <em>buffers</em>, leaving the file
|
||
offset unchanged. Transfer data into each buffer until it is full and then
|
||
move on to the next buffer in the sequence to hold the rest of the data.</p>
|
||
<p>The flags argument contains a bitwise OR of zero or more of the following
|
||
flags:</p>
|
||
<ul class="simple">
|
||
<li><p><a class="reference internal" href="#os.RWF_HIPRI" title="os.RWF_HIPRI"><code class="xref py py-data docutils literal notranslate"><span class="pre">RWF_HIPRI</span></code></a></p></li>
|
||
<li><p><a class="reference internal" href="#os.RWF_NOWAIT" title="os.RWF_NOWAIT"><code class="xref py py-data docutils literal notranslate"><span class="pre">RWF_NOWAIT</span></code></a></p></li>
|
||
</ul>
|
||
<p>Return the total number of bytes actually read which can be less than the
|
||
total capacity of all the objects.</p>
|
||
<p>The operating system may set a limit (<a class="reference internal" href="#os.sysconf" title="os.sysconf"><code class="xref py py-func docutils literal notranslate"><span class="pre">sysconf()</span></code></a> value
|
||
<code class="docutils literal notranslate"><span class="pre">'SC_IOV_MAX'</span></code>) on the number of buffers that can be used.</p>
|
||
<p>Combine the functionality of <a class="reference internal" href="#os.readv" title="os.readv"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.readv()</span></code></a> and <a class="reference internal" href="#os.pread" title="os.pread"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.pread()</span></code></a>.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Linux 2.6.30 and newer, FreeBSD 6.0 and newer,
|
||
OpenBSD 2.7 and newer. Using flags requires Linux 4.6 or newer.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.7.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.RWF_NOWAIT">
|
||
<code class="descclassname">os.</code><code class="descname">RWF_NOWAIT</code><a class="headerlink" href="#os.RWF_NOWAIT" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Do not wait for data which is not immediately available. If this flag is
|
||
specified, the system call will return instantly if it would have to read
|
||
data from the backing storage or wait for a lock.</p>
|
||
<p>If some data was successfully read, it will return the number of bytes read.
|
||
If no bytes were read, it will return <code class="docutils literal notranslate"><span class="pre">-1</span></code> and set errno to
|
||
<a class="reference internal" href="errno.html#errno.EAGAIN" title="errno.EAGAIN"><code class="xref py py-data docutils literal notranslate"><span class="pre">errno.EAGAIN</span></code></a>.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Linux 4.14 and newer.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.7.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.RWF_HIPRI">
|
||
<code class="descclassname">os.</code><code class="descname">RWF_HIPRI</code><a class="headerlink" href="#os.RWF_HIPRI" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>High priority read/write. Allows block-based filesystems to use polling
|
||
of the device, which provides lower latency, but may use additional
|
||
resources.</p>
|
||
<p>Currently, on Linux, this feature is usable only on a file descriptor opened
|
||
using the <a class="reference internal" href="#os.O_DIRECT" title="os.O_DIRECT"><code class="xref py py-data docutils literal notranslate"><span class="pre">O_DIRECT</span></code></a> flag.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Linux 4.6 and newer.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.7.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.pwrite">
|
||
<code class="descclassname">os.</code><code class="descname">pwrite</code><span class="sig-paren">(</span><em>fd</em>, <em>str</em>, <em>offset</em><span class="sig-paren">)</span><a class="headerlink" href="#os.pwrite" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Write the bytestring in <em>str</em> to file descriptor <em>fd</em> at position of
|
||
<em>offset</em>, leaving the file offset unchanged.</p>
|
||
<p>Return the number of bytes actually written.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.pwritev">
|
||
<code class="descclassname">os.</code><code class="descname">pwritev</code><span class="sig-paren">(</span><em>fd</em>, <em>buffers</em>, <em>offset</em>, <em>flags=0</em><span class="sig-paren">)</span><a class="headerlink" href="#os.pwritev" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Write the <em>buffers</em> contents to file descriptor <em>fd</em> at a offset <em>offset</em>,
|
||
leaving the file offset unchanged. <em>buffers</em> must be a sequence of
|
||
<a class="reference internal" href="../glossary.html#term-bytes-like-object"><span class="xref std std-term">bytes-like objects</span></a>. Buffers are processed in
|
||
array order. Entire contents of the first buffer is written before
|
||
proceeding to the second, and so on.</p>
|
||
<p>The flags argument contains a bitwise OR of zero or more of the following
|
||
flags:</p>
|
||
<ul class="simple">
|
||
<li><p><a class="reference internal" href="#os.RWF_DSYNC" title="os.RWF_DSYNC"><code class="xref py py-data docutils literal notranslate"><span class="pre">RWF_DSYNC</span></code></a></p></li>
|
||
<li><p><a class="reference internal" href="#os.RWF_SYNC" title="os.RWF_SYNC"><code class="xref py py-data docutils literal notranslate"><span class="pre">RWF_SYNC</span></code></a></p></li>
|
||
</ul>
|
||
<p>Return the total number of bytes actually written.</p>
|
||
<p>The operating system may set a limit (<a class="reference internal" href="#os.sysconf" title="os.sysconf"><code class="xref py py-func docutils literal notranslate"><span class="pre">sysconf()</span></code></a> value
|
||
<code class="docutils literal notranslate"><span class="pre">'SC_IOV_MAX'</span></code>) on the number of buffers that can be used.</p>
|
||
<p>Combine the functionality of <a class="reference internal" href="#os.writev" title="os.writev"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.writev()</span></code></a> and <a class="reference internal" href="#os.pwrite" title="os.pwrite"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.pwrite()</span></code></a>.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Linux 2.6.30 and newer, FreeBSD 6.0 and newer,
|
||
OpenBSD 2.7 and newer. Using flags requires Linux 4.7 or newer.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.7.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.RWF_DSYNC">
|
||
<code class="descclassname">os.</code><code class="descname">RWF_DSYNC</code><a class="headerlink" href="#os.RWF_DSYNC" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Provide a per-write equivalent of the <a class="reference internal" href="#os.O_DSYNC" title="os.O_DSYNC"><code class="xref py py-data docutils literal notranslate"><span class="pre">O_DSYNC</span></code></a> <code class="docutils literal notranslate"><span class="pre">open(2)</span></code> flag. This
|
||
flag effect applies only to the data range written by the system call.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Linux 4.7 and newer.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.7.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.RWF_SYNC">
|
||
<code class="descclassname">os.</code><code class="descname">RWF_SYNC</code><a class="headerlink" href="#os.RWF_SYNC" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Provide a per-write equivalent of the <a class="reference internal" href="#os.O_SYNC" title="os.O_SYNC"><code class="xref py py-data docutils literal notranslate"><span class="pre">O_SYNC</span></code></a> <code class="docutils literal notranslate"><span class="pre">open(2)</span></code> flag. This
|
||
flag effect applies only to the data range written by the system call.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Linux 4.7 and newer.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.7.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.read">
|
||
<code class="descclassname">os.</code><code class="descname">read</code><span class="sig-paren">(</span><em>fd</em>, <em>n</em><span class="sig-paren">)</span><a class="headerlink" href="#os.read" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Read at most <em>n</em> bytes from file descriptor <em>fd</em>.</p>
|
||
<p>Return a bytestring containing the bytes read. If the end of the file
|
||
referred to by <em>fd</em> has been reached, an empty bytes object is returned.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>This function is intended for low-level I/O and must be applied to a file
|
||
descriptor as returned by <a class="reference internal" href="#os.open" title="os.open"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.open()</span></code></a> or <a class="reference internal" href="#os.pipe" title="os.pipe"><code class="xref py py-func docutils literal notranslate"><span class="pre">pipe()</span></code></a>. To read a
|
||
“file object” returned by the built-in function <a class="reference internal" href="functions.html#open" title="open"><code class="xref py py-func docutils literal notranslate"><span class="pre">open()</span></code></a> or by
|
||
<a class="reference internal" href="#os.popen" title="os.popen"><code class="xref py py-func docutils literal notranslate"><span class="pre">popen()</span></code></a> or <a class="reference internal" href="#os.fdopen" title="os.fdopen"><code class="xref py py-func docutils literal notranslate"><span class="pre">fdopen()</span></code></a>, or <a class="reference internal" href="sys.html#sys.stdin" title="sys.stdin"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.stdin</span></code></a>, use its
|
||
<code class="xref py py-meth docutils literal notranslate"><span class="pre">read()</span></code> or <code class="xref py py-meth docutils literal notranslate"><span class="pre">readline()</span></code> methods.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.5: </span>If the system call is interrupted and the signal handler does not raise an
|
||
exception, the function now retries the system call instead of raising an
|
||
<a class="reference internal" href="exceptions.html#InterruptedError" title="InterruptedError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">InterruptedError</span></code></a> exception (see <span class="target" id="index-16"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0475"><strong>PEP 475</strong></a> for the rationale).</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.sendfile">
|
||
<code class="descclassname">os.</code><code class="descname">sendfile</code><span class="sig-paren">(</span><em>out</em>, <em>in</em>, <em>offset</em>, <em>count</em><span class="sig-paren">)</span><a class="headerlink" href="#os.sendfile" title="Permalink to this definition">¶</a></dt>
|
||
<dt>
|
||
<code class="descclassname">os.</code><code class="descname">sendfile</code><span class="sig-paren">(</span><em>out</em>, <em>in</em>, <em>offset</em>, <em>count</em>, <span class="optional">[</span><em>headers</em>, <span class="optional">]</span><span class="optional">[</span><em>trailers</em>, <span class="optional">]</span><em>flags=0</em><span class="sig-paren">)</span></dt>
|
||
<dd><p>Copy <em>count</em> bytes from file descriptor <em>in</em> to file descriptor <em>out</em>
|
||
starting at <em>offset</em>.
|
||
Return the number of bytes sent. When EOF is reached return 0.</p>
|
||
<p>The first function notation is supported by all platforms that define
|
||
<a class="reference internal" href="#os.sendfile" title="os.sendfile"><code class="xref py py-func docutils literal notranslate"><span class="pre">sendfile()</span></code></a>.</p>
|
||
<p>On Linux, if <em>offset</em> is given as <code class="docutils literal notranslate"><span class="pre">None</span></code>, the bytes are read from the
|
||
current position of <em>in</em> and the position of <em>in</em> is updated.</p>
|
||
<p>The second case may be used on Mac OS X and FreeBSD where <em>headers</em> and
|
||
<em>trailers</em> are arbitrary sequences of buffers that are written before and
|
||
after the data from <em>in</em> is written. It returns the same as the first case.</p>
|
||
<p>On Mac OS X and FreeBSD, a value of 0 for <em>count</em> specifies to send until
|
||
the end of <em>in</em> is reached.</p>
|
||
<p>All platforms support sockets as <em>out</em> file descriptor, and some platforms
|
||
allow other types (e.g. regular file, pipe) as well.</p>
|
||
<p>Cross-platform applications should not use <em>headers</em>, <em>trailers</em> and <em>flags</em>
|
||
arguments.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>For a higher-level wrapper of <a class="reference internal" href="#os.sendfile" title="os.sendfile"><code class="xref py py-func docutils literal notranslate"><span class="pre">sendfile()</span></code></a>, see
|
||
<a class="reference internal" href="socket.html#socket.socket.sendfile" title="socket.socket.sendfile"><code class="xref py py-meth docutils literal notranslate"><span class="pre">socket.socket.sendfile()</span></code></a>.</p>
|
||
</div>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.set_blocking">
|
||
<code class="descclassname">os.</code><code class="descname">set_blocking</code><span class="sig-paren">(</span><em>fd</em>, <em>blocking</em><span class="sig-paren">)</span><a class="headerlink" href="#os.set_blocking" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Set the blocking mode of the specified file descriptor. Set the
|
||
<a class="reference internal" href="#os.O_NONBLOCK" title="os.O_NONBLOCK"><code class="xref py py-data docutils literal notranslate"><span class="pre">O_NONBLOCK</span></code></a> flag if blocking is <code class="docutils literal notranslate"><span class="pre">False</span></code>, clear the flag otherwise.</p>
|
||
<p>See also <a class="reference internal" href="#os.get_blocking" title="os.get_blocking"><code class="xref py py-func docutils literal notranslate"><span class="pre">get_blocking()</span></code></a> and <a class="reference internal" href="socket.html#socket.socket.setblocking" title="socket.socket.setblocking"><code class="xref py py-meth docutils literal notranslate"><span class="pre">socket.socket.setblocking()</span></code></a>.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.5.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.SF_NODISKIO">
|
||
<code class="descclassname">os.</code><code class="descname">SF_NODISKIO</code><a class="headerlink" href="#os.SF_NODISKIO" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.SF_MNOWAIT">
|
||
<code class="descclassname">os.</code><code class="descname">SF_MNOWAIT</code><a class="headerlink" href="#os.SF_MNOWAIT" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.SF_SYNC">
|
||
<code class="descclassname">os.</code><code class="descname">SF_SYNC</code><a class="headerlink" href="#os.SF_SYNC" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Parameters to the <a class="reference internal" href="#os.sendfile" title="os.sendfile"><code class="xref py py-func docutils literal notranslate"><span class="pre">sendfile()</span></code></a> function, if the implementation supports
|
||
them.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.readv">
|
||
<code class="descclassname">os.</code><code class="descname">readv</code><span class="sig-paren">(</span><em>fd</em>, <em>buffers</em><span class="sig-paren">)</span><a class="headerlink" href="#os.readv" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Read from a file descriptor <em>fd</em> into a number of mutable <a class="reference internal" href="../glossary.html#term-bytes-like-object"><span class="xref std std-term">bytes-like
|
||
objects</span></a> <em>buffers</em>. Transfer data into each buffer until
|
||
it is full and then move on to the next buffer in the sequence to hold the
|
||
rest of the data.</p>
|
||
<p>Return the total number of bytes actually read which can be less than the
|
||
total capacity of all the objects.</p>
|
||
<p>The operating system may set a limit (<a class="reference internal" href="#os.sysconf" title="os.sysconf"><code class="xref py py-func docutils literal notranslate"><span class="pre">sysconf()</span></code></a> value
|
||
<code class="docutils literal notranslate"><span class="pre">'SC_IOV_MAX'</span></code>) on the number of buffers that can be used.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.tcgetpgrp">
|
||
<code class="descclassname">os.</code><code class="descname">tcgetpgrp</code><span class="sig-paren">(</span><em>fd</em><span class="sig-paren">)</span><a class="headerlink" href="#os.tcgetpgrp" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return the process group associated with the terminal given by <em>fd</em> (an open
|
||
file descriptor as returned by <a class="reference internal" href="#os.open" title="os.open"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.open()</span></code></a>).</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.tcsetpgrp">
|
||
<code class="descclassname">os.</code><code class="descname">tcsetpgrp</code><span class="sig-paren">(</span><em>fd</em>, <em>pg</em><span class="sig-paren">)</span><a class="headerlink" href="#os.tcsetpgrp" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Set the process group associated with the terminal given by <em>fd</em> (an open file
|
||
descriptor as returned by <a class="reference internal" href="#os.open" title="os.open"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.open()</span></code></a>) to <em>pg</em>.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.ttyname">
|
||
<code class="descclassname">os.</code><code class="descname">ttyname</code><span class="sig-paren">(</span><em>fd</em><span class="sig-paren">)</span><a class="headerlink" href="#os.ttyname" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return a string which specifies the terminal device associated with
|
||
file descriptor <em>fd</em>. If <em>fd</em> is not associated with a terminal device, an
|
||
exception is raised.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.write">
|
||
<code class="descclassname">os.</code><code class="descname">write</code><span class="sig-paren">(</span><em>fd</em>, <em>str</em><span class="sig-paren">)</span><a class="headerlink" href="#os.write" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Write the bytestring in <em>str</em> to file descriptor <em>fd</em>.</p>
|
||
<p>Return the number of bytes actually written.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>This function is intended for low-level I/O and must be applied to a file
|
||
descriptor as returned by <a class="reference internal" href="#os.open" title="os.open"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.open()</span></code></a> or <a class="reference internal" href="#os.pipe" title="os.pipe"><code class="xref py py-func docutils literal notranslate"><span class="pre">pipe()</span></code></a>. To write a “file
|
||
object” returned by the built-in function <a class="reference internal" href="functions.html#open" title="open"><code class="xref py py-func docutils literal notranslate"><span class="pre">open()</span></code></a> or by <a class="reference internal" href="#os.popen" title="os.popen"><code class="xref py py-func docutils literal notranslate"><span class="pre">popen()</span></code></a> or
|
||
<a class="reference internal" href="#os.fdopen" title="os.fdopen"><code class="xref py py-func docutils literal notranslate"><span class="pre">fdopen()</span></code></a>, or <a class="reference internal" href="sys.html#sys.stdout" title="sys.stdout"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.stdout</span></code></a> or <a class="reference internal" href="sys.html#sys.stderr" title="sys.stderr"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.stderr</span></code></a>, use its
|
||
<code class="xref py py-meth docutils literal notranslate"><span class="pre">write()</span></code> method.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.5: </span>If the system call is interrupted and the signal handler does not raise an
|
||
exception, the function now retries the system call instead of raising an
|
||
<a class="reference internal" href="exceptions.html#InterruptedError" title="InterruptedError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">InterruptedError</span></code></a> exception (see <span class="target" id="index-17"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0475"><strong>PEP 475</strong></a> for the rationale).</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.writev">
|
||
<code class="descclassname">os.</code><code class="descname">writev</code><span class="sig-paren">(</span><em>fd</em>, <em>buffers</em><span class="sig-paren">)</span><a class="headerlink" href="#os.writev" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Write the contents of <em>buffers</em> to file descriptor <em>fd</em>. <em>buffers</em> must be
|
||
a sequence of <a class="reference internal" href="../glossary.html#term-bytes-like-object"><span class="xref std std-term">bytes-like objects</span></a>. Buffers are
|
||
processed in array order. Entire contents of the first buffer is written
|
||
before proceeding to the second, and so on.</p>
|
||
<p>Returns the total number of bytes actually written.</p>
|
||
<p>The operating system may set a limit (<a class="reference internal" href="#os.sysconf" title="os.sysconf"><code class="xref py py-func docutils literal notranslate"><span class="pre">sysconf()</span></code></a> value
|
||
<code class="docutils literal notranslate"><span class="pre">'SC_IOV_MAX'</span></code>) on the number of buffers that can be used.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<div class="section" id="querying-the-size-of-a-terminal">
|
||
<span id="terminal-size"></span><h3>Querying the size of a terminal<a class="headerlink" href="#querying-the-size-of-a-terminal" title="Permalink to this headline">¶</a></h3>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3.</span></p>
|
||
</div>
|
||
<dl class="function">
|
||
<dt id="os.get_terminal_size">
|
||
<code class="descclassname">os.</code><code class="descname">get_terminal_size</code><span class="sig-paren">(</span><em>fd=STDOUT_FILENO</em><span class="sig-paren">)</span><a class="headerlink" href="#os.get_terminal_size" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return the size of the terminal window as <code class="docutils literal notranslate"><span class="pre">(columns,</span> <span class="pre">lines)</span></code>,
|
||
tuple of type <a class="reference internal" href="#os.terminal_size" title="os.terminal_size"><code class="xref py py-class docutils literal notranslate"><span class="pre">terminal_size</span></code></a>.</p>
|
||
<p>The optional argument <code class="docutils literal notranslate"><span class="pre">fd</span></code> (default <code class="docutils literal notranslate"><span class="pre">STDOUT_FILENO</span></code>, or standard
|
||
output) specifies which file descriptor should be queried.</p>
|
||
<p>If the file descriptor is not connected to a terminal, an <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a>
|
||
is raised.</p>
|
||
<p><a class="reference internal" href="shutil.html#shutil.get_terminal_size" title="shutil.get_terminal_size"><code class="xref py py-func docutils literal notranslate"><span class="pre">shutil.get_terminal_size()</span></code></a> is the high-level function which
|
||
should normally be used, <code class="docutils literal notranslate"><span class="pre">os.get_terminal_size</span></code> is the low-level
|
||
implementation.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix, Windows.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="class">
|
||
<dt id="os.terminal_size">
|
||
<em class="property">class </em><code class="descclassname">os.</code><code class="descname">terminal_size</code><a class="headerlink" href="#os.terminal_size" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>A subclass of tuple, holding <code class="docutils literal notranslate"><span class="pre">(columns,</span> <span class="pre">lines)</span></code> of the terminal window size.</p>
|
||
<dl class="attribute">
|
||
<dt id="os.terminal_size.columns">
|
||
<code class="descname">columns</code><a class="headerlink" href="#os.terminal_size.columns" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Width of the terminal window in characters.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="os.terminal_size.lines">
|
||
<code class="descname">lines</code><a class="headerlink" href="#os.terminal_size.lines" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Height of the terminal window in characters.</p>
|
||
</dd></dl>
|
||
|
||
</dd></dl>
|
||
|
||
</div>
|
||
<div class="section" id="inheritance-of-file-descriptors">
|
||
<span id="fd-inheritance"></span><h3>Inheritance of File Descriptors<a class="headerlink" href="#inheritance-of-file-descriptors" title="Permalink to this headline">¶</a></h3>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.4.</span></p>
|
||
</div>
|
||
<p>A file descriptor has an “inheritable” flag which indicates if the file descriptor
|
||
can be inherited by child processes. Since Python 3.4, file descriptors
|
||
created by Python are non-inheritable by default.</p>
|
||
<p>On UNIX, non-inheritable file descriptors are closed in child processes at the
|
||
execution of a new program, other file descriptors are inherited.</p>
|
||
<p>On Windows, non-inheritable handles and file descriptors are closed in child
|
||
processes, except for standard streams (file descriptors 0, 1 and 2: stdin, stdout
|
||
and stderr), which are always inherited. Using <a class="reference internal" href="#os.spawnl" title="os.spawnl"><code class="xref py py-func docutils literal notranslate"><span class="pre">spawn*</span></code></a> functions,
|
||
all inheritable handles and all inheritable file descriptors are inherited.
|
||
Using the <a class="reference internal" href="subprocess.html#module-subprocess" title="subprocess: Subprocess management."><code class="xref py py-mod docutils literal notranslate"><span class="pre">subprocess</span></code></a> module, all file descriptors except standard
|
||
streams are closed, and inheritable handles are only inherited if the
|
||
<em>close_fds</em> parameter is <code class="docutils literal notranslate"><span class="pre">False</span></code>.</p>
|
||
<dl class="function">
|
||
<dt id="os.get_inheritable">
|
||
<code class="descclassname">os.</code><code class="descname">get_inheritable</code><span class="sig-paren">(</span><em>fd</em><span class="sig-paren">)</span><a class="headerlink" href="#os.get_inheritable" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Get the “inheritable” flag of the specified file descriptor (a boolean).</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.set_inheritable">
|
||
<code class="descclassname">os.</code><code class="descname">set_inheritable</code><span class="sig-paren">(</span><em>fd</em>, <em>inheritable</em><span class="sig-paren">)</span><a class="headerlink" href="#os.set_inheritable" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Set the “inheritable” flag of the specified file descriptor.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.get_handle_inheritable">
|
||
<code class="descclassname">os.</code><code class="descname">get_handle_inheritable</code><span class="sig-paren">(</span><em>handle</em><span class="sig-paren">)</span><a class="headerlink" href="#os.get_handle_inheritable" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Get the “inheritable” flag of the specified handle (a boolean).</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Windows.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.set_handle_inheritable">
|
||
<code class="descclassname">os.</code><code class="descname">set_handle_inheritable</code><span class="sig-paren">(</span><em>handle</em>, <em>inheritable</em><span class="sig-paren">)</span><a class="headerlink" href="#os.set_handle_inheritable" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Set the “inheritable” flag of the specified handle.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Windows.</p>
|
||
</dd></dl>
|
||
|
||
</div>
|
||
</div>
|
||
<div class="section" id="files-and-directories">
|
||
<span id="os-file-dir"></span><h2>Files and Directories<a class="headerlink" href="#files-and-directories" title="Permalink to this headline">¶</a></h2>
|
||
<p>On some Unix platforms, many of these functions support one or more of these
|
||
features:</p>
|
||
<ul id="path-fd">
|
||
<li><p><strong>specifying a file descriptor:</strong>
|
||
For some functions, the <em>path</em> argument can be not only a string giving a path
|
||
name, but also a file descriptor. The function will then operate on the file
|
||
referred to by the descriptor. (For POSIX systems, Python will call the
|
||
<code class="docutils literal notranslate"><span class="pre">f...</span></code> version of the function.)</p>
|
||
<p>You can check whether or not <em>path</em> can be specified as a file descriptor on
|
||
your platform using <a class="reference internal" href="#os.supports_fd" title="os.supports_fd"><code class="xref py py-data docutils literal notranslate"><span class="pre">os.supports_fd</span></code></a>. If it is unavailable, using it
|
||
will raise a <a class="reference internal" href="exceptions.html#NotImplementedError" title="NotImplementedError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">NotImplementedError</span></code></a>.</p>
|
||
<p>If the function also supports <em>dir_fd</em> or <em>follow_symlinks</em> arguments, it is
|
||
an error to specify one of those when supplying <em>path</em> as a file descriptor.</p>
|
||
</li>
|
||
</ul>
|
||
<ul id="dir-fd">
|
||
<li><p><strong>paths relative to directory descriptors:</strong> If <em>dir_fd</em> is not <code class="docutils literal notranslate"><span class="pre">None</span></code>, it
|
||
should be a file descriptor referring to a directory, and the path to operate
|
||
on should be relative; path will then be relative to that directory. If the
|
||
path is absolute, <em>dir_fd</em> is ignored. (For POSIX systems, Python will call
|
||
the <code class="docutils literal notranslate"><span class="pre">...at</span></code> or <code class="docutils literal notranslate"><span class="pre">f...at</span></code> version of the function.)</p>
|
||
<p>You can check whether or not <em>dir_fd</em> is supported on your platform using
|
||
<a class="reference internal" href="#os.supports_dir_fd" title="os.supports_dir_fd"><code class="xref py py-data docutils literal notranslate"><span class="pre">os.supports_dir_fd</span></code></a>. If it is unavailable, using it will raise a
|
||
<a class="reference internal" href="exceptions.html#NotImplementedError" title="NotImplementedError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">NotImplementedError</span></code></a>.</p>
|
||
</li>
|
||
</ul>
|
||
<ul id="follow-symlinks">
|
||
<li><p><strong>not following symlinks:</strong> If <em>follow_symlinks</em> is
|
||
<code class="docutils literal notranslate"><span class="pre">False</span></code>, and the last element of the path to operate on is a symbolic link,
|
||
the function will operate on the symbolic link itself instead of the file the
|
||
link points to. (For POSIX systems, Python will call the <code class="docutils literal notranslate"><span class="pre">l...</span></code> version of
|
||
the function.)</p>
|
||
<p>You can check whether or not <em>follow_symlinks</em> is supported on your platform
|
||
using <a class="reference internal" href="#os.supports_follow_symlinks" title="os.supports_follow_symlinks"><code class="xref py py-data docutils literal notranslate"><span class="pre">os.supports_follow_symlinks</span></code></a>. If it is unavailable, using it
|
||
will raise a <a class="reference internal" href="exceptions.html#NotImplementedError" title="NotImplementedError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">NotImplementedError</span></code></a>.</p>
|
||
</li>
|
||
</ul>
|
||
<dl class="function">
|
||
<dt id="os.access">
|
||
<code class="descclassname">os.</code><code class="descname">access</code><span class="sig-paren">(</span><em>path</em>, <em>mode</em>, <em>*</em>, <em>dir_fd=None</em>, <em>effective_ids=False</em>, <em>follow_symlinks=True</em><span class="sig-paren">)</span><a class="headerlink" href="#os.access" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Use the real uid/gid to test for access to <em>path</em>. Note that most operations
|
||
will use the effective uid/gid, therefore this routine can be used in a
|
||
suid/sgid environment to test if the invoking user has the specified access to
|
||
<em>path</em>. <em>mode</em> should be <a class="reference internal" href="#os.F_OK" title="os.F_OK"><code class="xref py py-const docutils literal notranslate"><span class="pre">F_OK</span></code></a> to test the existence of <em>path</em>, or it
|
||
can be the inclusive OR of one or more of <a class="reference internal" href="#os.R_OK" title="os.R_OK"><code class="xref py py-const docutils literal notranslate"><span class="pre">R_OK</span></code></a>, <a class="reference internal" href="#os.W_OK" title="os.W_OK"><code class="xref py py-const docutils literal notranslate"><span class="pre">W_OK</span></code></a>, and
|
||
<a class="reference internal" href="#os.X_OK" title="os.X_OK"><code class="xref py py-const docutils literal notranslate"><span class="pre">X_OK</span></code></a> to test permissions. Return <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a> if access is allowed,
|
||
<a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal notranslate"><span class="pre">False</span></code></a> if not. See the Unix man page <em class="manpage">access(2)</em> for more
|
||
information.</p>
|
||
<p>This function can support specifying <a class="reference internal" href="#dir-fd"><span class="std std-ref">paths relative to directory
|
||
descriptors</span></a> and <a class="reference internal" href="#follow-symlinks"><span class="std std-ref">not following symlinks</span></a>.</p>
|
||
<p>If <em>effective_ids</em> is <code class="docutils literal notranslate"><span class="pre">True</span></code>, <a class="reference internal" href="#os.access" title="os.access"><code class="xref py py-func docutils literal notranslate"><span class="pre">access()</span></code></a> will perform its access
|
||
checks using the effective uid/gid instead of the real uid/gid.
|
||
<em>effective_ids</em> may not be supported on your platform; you can check whether
|
||
or not it is available using <a class="reference internal" href="#os.supports_effective_ids" title="os.supports_effective_ids"><code class="xref py py-data docutils literal notranslate"><span class="pre">os.supports_effective_ids</span></code></a>. If it is
|
||
unavailable, using it will raise a <a class="reference internal" href="exceptions.html#NotImplementedError" title="NotImplementedError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">NotImplementedError</span></code></a>.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>Using <a class="reference internal" href="#os.access" title="os.access"><code class="xref py py-func docutils literal notranslate"><span class="pre">access()</span></code></a> to check if a user is authorized to e.g. open a file
|
||
before actually doing so using <a class="reference internal" href="functions.html#open" title="open"><code class="xref py py-func docutils literal notranslate"><span class="pre">open()</span></code></a> creates a security hole,
|
||
because the user might exploit the short time interval between checking
|
||
and opening the file to manipulate it. It’s preferable to use <a class="reference internal" href="../glossary.html#term-eafp"><span class="xref std std-term">EAFP</span></a>
|
||
techniques. For example:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">if</span> <span class="n">os</span><span class="o">.</span><span class="n">access</span><span class="p">(</span><span class="s2">"myfile"</span><span class="p">,</span> <span class="n">os</span><span class="o">.</span><span class="n">R_OK</span><span class="p">):</span>
|
||
<span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s2">"myfile"</span><span class="p">)</span> <span class="k">as</span> <span class="n">fp</span><span class="p">:</span>
|
||
<span class="k">return</span> <span class="n">fp</span><span class="o">.</span><span class="n">read</span><span class="p">()</span>
|
||
<span class="k">return</span> <span class="s2">"some default data"</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>is better written as:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">try</span><span class="p">:</span>
|
||
<span class="n">fp</span> <span class="o">=</span> <span class="nb">open</span><span class="p">(</span><span class="s2">"myfile"</span><span class="p">)</span>
|
||
<span class="k">except</span> <span class="ne">PermissionError</span><span class="p">:</span>
|
||
<span class="k">return</span> <span class="s2">"some default data"</span>
|
||
<span class="k">else</span><span class="p">:</span>
|
||
<span class="k">with</span> <span class="n">fp</span><span class="p">:</span>
|
||
<span class="k">return</span> <span class="n">fp</span><span class="o">.</span><span class="n">read</span><span class="p">()</span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>I/O operations may fail even when <a class="reference internal" href="#os.access" title="os.access"><code class="xref py py-func docutils literal notranslate"><span class="pre">access()</span></code></a> indicates that they would
|
||
succeed, particularly for operations on network filesystems which may have
|
||
permissions semantics beyond the usual POSIX permission-bit model.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.3: </span>Added the <em>dir_fd</em>, <em>effective_ids</em>, and <em>follow_symlinks</em> parameters.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>Accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.F_OK">
|
||
<code class="descclassname">os.</code><code class="descname">F_OK</code><a class="headerlink" href="#os.F_OK" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.R_OK">
|
||
<code class="descclassname">os.</code><code class="descname">R_OK</code><a class="headerlink" href="#os.R_OK" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.W_OK">
|
||
<code class="descclassname">os.</code><code class="descname">W_OK</code><a class="headerlink" href="#os.W_OK" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.X_OK">
|
||
<code class="descclassname">os.</code><code class="descname">X_OK</code><a class="headerlink" href="#os.X_OK" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Values to pass as the <em>mode</em> parameter of <a class="reference internal" href="#os.access" title="os.access"><code class="xref py py-func docutils literal notranslate"><span class="pre">access()</span></code></a> to test the
|
||
existence, readability, writability and executability of <em>path</em>,
|
||
respectively.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.chdir">
|
||
<code class="descclassname">os.</code><code class="descname">chdir</code><span class="sig-paren">(</span><em>path</em><span class="sig-paren">)</span><a class="headerlink" href="#os.chdir" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p id="index-18">Change the current working directory to <em>path</em>.</p>
|
||
<p>This function can support <a class="reference internal" href="#path-fd"><span class="std std-ref">specifying a file descriptor</span></a>. The
|
||
descriptor must refer to an opened directory, not an open file.</p>
|
||
<p>This function can raise <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a> and subclasses such as
|
||
<a class="reference internal" href="exceptions.html#FileNotFoundError" title="FileNotFoundError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">FileNotFoundError</span></code></a>, <a class="reference internal" href="exceptions.html#PermissionError" title="PermissionError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">PermissionError</span></code></a>, and <a class="reference internal" href="exceptions.html#NotADirectoryError" title="NotADirectoryError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">NotADirectoryError</span></code></a>.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3: </span>Added support for specifying <em>path</em> as a file descriptor
|
||
on some platforms.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>Accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.chflags">
|
||
<code class="descclassname">os.</code><code class="descname">chflags</code><span class="sig-paren">(</span><em>path</em>, <em>flags</em>, <em>*</em>, <em>follow_symlinks=True</em><span class="sig-paren">)</span><a class="headerlink" href="#os.chflags" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Set the flags of <em>path</em> to the numeric <em>flags</em>. <em>flags</em> may take a combination
|
||
(bitwise OR) of the following values (as defined in the <a class="reference internal" href="stat.html#module-stat" title="stat: Utilities for interpreting the results of os.stat(), os.lstat() and os.fstat()."><code class="xref py py-mod docutils literal notranslate"><span class="pre">stat</span></code></a> module):</p>
|
||
<ul class="simple">
|
||
<li><p><a class="reference internal" href="stat.html#stat.UF_NODUMP" title="stat.UF_NODUMP"><code class="xref py py-data docutils literal notranslate"><span class="pre">stat.UF_NODUMP</span></code></a></p></li>
|
||
<li><p><a class="reference internal" href="stat.html#stat.UF_IMMUTABLE" title="stat.UF_IMMUTABLE"><code class="xref py py-data docutils literal notranslate"><span class="pre">stat.UF_IMMUTABLE</span></code></a></p></li>
|
||
<li><p><a class="reference internal" href="stat.html#stat.UF_APPEND" title="stat.UF_APPEND"><code class="xref py py-data docutils literal notranslate"><span class="pre">stat.UF_APPEND</span></code></a></p></li>
|
||
<li><p><a class="reference internal" href="stat.html#stat.UF_OPAQUE" title="stat.UF_OPAQUE"><code class="xref py py-data docutils literal notranslate"><span class="pre">stat.UF_OPAQUE</span></code></a></p></li>
|
||
<li><p><a class="reference internal" href="stat.html#stat.UF_NOUNLINK" title="stat.UF_NOUNLINK"><code class="xref py py-data docutils literal notranslate"><span class="pre">stat.UF_NOUNLINK</span></code></a></p></li>
|
||
<li><p><a class="reference internal" href="stat.html#stat.UF_COMPRESSED" title="stat.UF_COMPRESSED"><code class="xref py py-data docutils literal notranslate"><span class="pre">stat.UF_COMPRESSED</span></code></a></p></li>
|
||
<li><p><a class="reference internal" href="stat.html#stat.UF_HIDDEN" title="stat.UF_HIDDEN"><code class="xref py py-data docutils literal notranslate"><span class="pre">stat.UF_HIDDEN</span></code></a></p></li>
|
||
<li><p><a class="reference internal" href="stat.html#stat.SF_ARCHIVED" title="stat.SF_ARCHIVED"><code class="xref py py-data docutils literal notranslate"><span class="pre">stat.SF_ARCHIVED</span></code></a></p></li>
|
||
<li><p><a class="reference internal" href="stat.html#stat.SF_IMMUTABLE" title="stat.SF_IMMUTABLE"><code class="xref py py-data docutils literal notranslate"><span class="pre">stat.SF_IMMUTABLE</span></code></a></p></li>
|
||
<li><p><a class="reference internal" href="stat.html#stat.SF_APPEND" title="stat.SF_APPEND"><code class="xref py py-data docutils literal notranslate"><span class="pre">stat.SF_APPEND</span></code></a></p></li>
|
||
<li><p><a class="reference internal" href="stat.html#stat.SF_NOUNLINK" title="stat.SF_NOUNLINK"><code class="xref py py-data docutils literal notranslate"><span class="pre">stat.SF_NOUNLINK</span></code></a></p></li>
|
||
<li><p><a class="reference internal" href="stat.html#stat.SF_SNAPSHOT" title="stat.SF_SNAPSHOT"><code class="xref py py-data docutils literal notranslate"><span class="pre">stat.SF_SNAPSHOT</span></code></a></p></li>
|
||
</ul>
|
||
<p>This function can support <a class="reference internal" href="#follow-symlinks"><span class="std std-ref">not following symlinks</span></a>.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3: </span>The <em>follow_symlinks</em> argument.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>Accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.chmod">
|
||
<code class="descclassname">os.</code><code class="descname">chmod</code><span class="sig-paren">(</span><em>path</em>, <em>mode</em>, <em>*</em>, <em>dir_fd=None</em>, <em>follow_symlinks=True</em><span class="sig-paren">)</span><a class="headerlink" href="#os.chmod" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Change the mode of <em>path</em> to the numeric <em>mode</em>. <em>mode</em> may take one of the
|
||
following values (as defined in the <a class="reference internal" href="stat.html#module-stat" title="stat: Utilities for interpreting the results of os.stat(), os.lstat() and os.fstat()."><code class="xref py py-mod docutils literal notranslate"><span class="pre">stat</span></code></a> module) or bitwise ORed
|
||
combinations of them:</p>
|
||
<ul class="simple">
|
||
<li><p><a class="reference internal" href="stat.html#stat.S_ISUID" title="stat.S_ISUID"><code class="xref py py-data docutils literal notranslate"><span class="pre">stat.S_ISUID</span></code></a></p></li>
|
||
<li><p><a class="reference internal" href="stat.html#stat.S_ISGID" title="stat.S_ISGID"><code class="xref py py-data docutils literal notranslate"><span class="pre">stat.S_ISGID</span></code></a></p></li>
|
||
<li><p><a class="reference internal" href="stat.html#stat.S_ENFMT" title="stat.S_ENFMT"><code class="xref py py-data docutils literal notranslate"><span class="pre">stat.S_ENFMT</span></code></a></p></li>
|
||
<li><p><a class="reference internal" href="stat.html#stat.S_ISVTX" title="stat.S_ISVTX"><code class="xref py py-data docutils literal notranslate"><span class="pre">stat.S_ISVTX</span></code></a></p></li>
|
||
<li><p><a class="reference internal" href="stat.html#stat.S_IREAD" title="stat.S_IREAD"><code class="xref py py-data docutils literal notranslate"><span class="pre">stat.S_IREAD</span></code></a></p></li>
|
||
<li><p><a class="reference internal" href="stat.html#stat.S_IWRITE" title="stat.S_IWRITE"><code class="xref py py-data docutils literal notranslate"><span class="pre">stat.S_IWRITE</span></code></a></p></li>
|
||
<li><p><a class="reference internal" href="stat.html#stat.S_IEXEC" title="stat.S_IEXEC"><code class="xref py py-data docutils literal notranslate"><span class="pre">stat.S_IEXEC</span></code></a></p></li>
|
||
<li><p><a class="reference internal" href="stat.html#stat.S_IRWXU" title="stat.S_IRWXU"><code class="xref py py-data docutils literal notranslate"><span class="pre">stat.S_IRWXU</span></code></a></p></li>
|
||
<li><p><a class="reference internal" href="stat.html#stat.S_IRUSR" title="stat.S_IRUSR"><code class="xref py py-data docutils literal notranslate"><span class="pre">stat.S_IRUSR</span></code></a></p></li>
|
||
<li><p><a class="reference internal" href="stat.html#stat.S_IWUSR" title="stat.S_IWUSR"><code class="xref py py-data docutils literal notranslate"><span class="pre">stat.S_IWUSR</span></code></a></p></li>
|
||
<li><p><a class="reference internal" href="stat.html#stat.S_IXUSR" title="stat.S_IXUSR"><code class="xref py py-data docutils literal notranslate"><span class="pre">stat.S_IXUSR</span></code></a></p></li>
|
||
<li><p><a class="reference internal" href="stat.html#stat.S_IRWXG" title="stat.S_IRWXG"><code class="xref py py-data docutils literal notranslate"><span class="pre">stat.S_IRWXG</span></code></a></p></li>
|
||
<li><p><a class="reference internal" href="stat.html#stat.S_IRGRP" title="stat.S_IRGRP"><code class="xref py py-data docutils literal notranslate"><span class="pre">stat.S_IRGRP</span></code></a></p></li>
|
||
<li><p><a class="reference internal" href="stat.html#stat.S_IWGRP" title="stat.S_IWGRP"><code class="xref py py-data docutils literal notranslate"><span class="pre">stat.S_IWGRP</span></code></a></p></li>
|
||
<li><p><a class="reference internal" href="stat.html#stat.S_IXGRP" title="stat.S_IXGRP"><code class="xref py py-data docutils literal notranslate"><span class="pre">stat.S_IXGRP</span></code></a></p></li>
|
||
<li><p><a class="reference internal" href="stat.html#stat.S_IRWXO" title="stat.S_IRWXO"><code class="xref py py-data docutils literal notranslate"><span class="pre">stat.S_IRWXO</span></code></a></p></li>
|
||
<li><p><a class="reference internal" href="stat.html#stat.S_IROTH" title="stat.S_IROTH"><code class="xref py py-data docutils literal notranslate"><span class="pre">stat.S_IROTH</span></code></a></p></li>
|
||
<li><p><a class="reference internal" href="stat.html#stat.S_IWOTH" title="stat.S_IWOTH"><code class="xref py py-data docutils literal notranslate"><span class="pre">stat.S_IWOTH</span></code></a></p></li>
|
||
<li><p><a class="reference internal" href="stat.html#stat.S_IXOTH" title="stat.S_IXOTH"><code class="xref py py-data docutils literal notranslate"><span class="pre">stat.S_IXOTH</span></code></a></p></li>
|
||
</ul>
|
||
<p>This function can support <a class="reference internal" href="#path-fd"><span class="std std-ref">specifying a file descriptor</span></a>,
|
||
<a class="reference internal" href="#dir-fd"><span class="std std-ref">paths relative to directory descriptors</span></a> and <a class="reference internal" href="#follow-symlinks"><span class="std std-ref">not
|
||
following symlinks</span></a>.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>Although Windows supports <a class="reference internal" href="#os.chmod" title="os.chmod"><code class="xref py py-func docutils literal notranslate"><span class="pre">chmod()</span></code></a>, you can only set the file’s
|
||
read-only flag with it (via the <code class="docutils literal notranslate"><span class="pre">stat.S_IWRITE</span></code> and <code class="docutils literal notranslate"><span class="pre">stat.S_IREAD</span></code>
|
||
constants or a corresponding integer value). All other bits are ignored.</p>
|
||
</div>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3: </span>Added support for specifying <em>path</em> as an open file descriptor,
|
||
and the <em>dir_fd</em> and <em>follow_symlinks</em> arguments.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>Accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.chown">
|
||
<code class="descclassname">os.</code><code class="descname">chown</code><span class="sig-paren">(</span><em>path</em>, <em>uid</em>, <em>gid</em>, <em>*</em>, <em>dir_fd=None</em>, <em>follow_symlinks=True</em><span class="sig-paren">)</span><a class="headerlink" href="#os.chown" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Change the owner and group id of <em>path</em> to the numeric <em>uid</em> and <em>gid</em>. To
|
||
leave one of the ids unchanged, set it to -1.</p>
|
||
<p>This function can support <a class="reference internal" href="#path-fd"><span class="std std-ref">specifying a file descriptor</span></a>,
|
||
<a class="reference internal" href="#dir-fd"><span class="std std-ref">paths relative to directory descriptors</span></a> and <a class="reference internal" href="#follow-symlinks"><span class="std std-ref">not
|
||
following symlinks</span></a>.</p>
|
||
<p>See <a class="reference internal" href="shutil.html#shutil.chown" title="shutil.chown"><code class="xref py py-func docutils literal notranslate"><span class="pre">shutil.chown()</span></code></a> for a higher-level function that accepts names in
|
||
addition to numeric ids.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3: </span>Added support for specifying an open file descriptor for <em>path</em>,
|
||
and the <em>dir_fd</em> and <em>follow_symlinks</em> arguments.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>Supports a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.chroot">
|
||
<code class="descclassname">os.</code><code class="descname">chroot</code><span class="sig-paren">(</span><em>path</em><span class="sig-paren">)</span><a class="headerlink" href="#os.chroot" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Change the root directory of the current process to <em>path</em>.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>Accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.fchdir">
|
||
<code class="descclassname">os.</code><code class="descname">fchdir</code><span class="sig-paren">(</span><em>fd</em><span class="sig-paren">)</span><a class="headerlink" href="#os.fchdir" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Change the current working directory to the directory represented by the file
|
||
descriptor <em>fd</em>. The descriptor must refer to an opened directory, not an
|
||
open file. As of Python 3.3, this is equivalent to <code class="docutils literal notranslate"><span class="pre">os.chdir(fd)</span></code>.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.getcwd">
|
||
<code class="descclassname">os.</code><code class="descname">getcwd</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#os.getcwd" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return a string representing the current working directory.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.getcwdb">
|
||
<code class="descclassname">os.</code><code class="descname">getcwdb</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#os.getcwdb" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return a bytestring representing the current working directory.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.lchflags">
|
||
<code class="descclassname">os.</code><code class="descname">lchflags</code><span class="sig-paren">(</span><em>path</em>, <em>flags</em><span class="sig-paren">)</span><a class="headerlink" href="#os.lchflags" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Set the flags of <em>path</em> to the numeric <em>flags</em>, like <a class="reference internal" href="#os.chflags" title="os.chflags"><code class="xref py py-func docutils literal notranslate"><span class="pre">chflags()</span></code></a>, but do
|
||
not follow symbolic links. As of Python 3.3, this is equivalent to
|
||
<code class="docutils literal notranslate"><span class="pre">os.chflags(path,</span> <span class="pre">flags,</span> <span class="pre">follow_symlinks=False)</span></code>.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>Accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.lchmod">
|
||
<code class="descclassname">os.</code><code class="descname">lchmod</code><span class="sig-paren">(</span><em>path</em>, <em>mode</em><span class="sig-paren">)</span><a class="headerlink" href="#os.lchmod" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Change the mode of <em>path</em> to the numeric <em>mode</em>. If path is a symlink, this
|
||
affects the symlink rather than the target. See the docs for <a class="reference internal" href="#os.chmod" title="os.chmod"><code class="xref py py-func docutils literal notranslate"><span class="pre">chmod()</span></code></a>
|
||
for possible values of <em>mode</em>. As of Python 3.3, this is equivalent to
|
||
<code class="docutils literal notranslate"><span class="pre">os.chmod(path,</span> <span class="pre">mode,</span> <span class="pre">follow_symlinks=False)</span></code>.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>Accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.lchown">
|
||
<code class="descclassname">os.</code><code class="descname">lchown</code><span class="sig-paren">(</span><em>path</em>, <em>uid</em>, <em>gid</em><span class="sig-paren">)</span><a class="headerlink" href="#os.lchown" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Change the owner and group id of <em>path</em> to the numeric <em>uid</em> and <em>gid</em>. This
|
||
function will not follow symbolic links. As of Python 3.3, this is equivalent
|
||
to <code class="docutils literal notranslate"><span class="pre">os.chown(path,</span> <span class="pre">uid,</span> <span class="pre">gid,</span> <span class="pre">follow_symlinks=False)</span></code>.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>Accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.link">
|
||
<code class="descclassname">os.</code><code class="descname">link</code><span class="sig-paren">(</span><em>src</em>, <em>dst</em>, <em>*</em>, <em>src_dir_fd=None</em>, <em>dst_dir_fd=None</em>, <em>follow_symlinks=True</em><span class="sig-paren">)</span><a class="headerlink" href="#os.link" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Create a hard link pointing to <em>src</em> named <em>dst</em>.</p>
|
||
<p>This function can support specifying <em>src_dir_fd</em> and/or <em>dst_dir_fd</em> to
|
||
supply <a class="reference internal" href="#dir-fd"><span class="std std-ref">paths relative to directory descriptors</span></a>, and <a class="reference internal" href="#follow-symlinks"><span class="std std-ref">not
|
||
following symlinks</span></a>.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix, Windows.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.2: </span>Added Windows support.</p>
|
||
</div>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3: </span>Added the <em>src_dir_fd</em>, <em>dst_dir_fd</em>, and <em>follow_symlinks</em> arguments.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>Accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a> for <em>src</em> and <em>dst</em>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.listdir">
|
||
<code class="descclassname">os.</code><code class="descname">listdir</code><span class="sig-paren">(</span><em>path='.'</em><span class="sig-paren">)</span><a class="headerlink" href="#os.listdir" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return a list containing the names of the entries in the directory given by
|
||
<em>path</em>. The list is in arbitrary order, and does not include the special
|
||
entries <code class="docutils literal notranslate"><span class="pre">'.'</span></code> and <code class="docutils literal notranslate"><span class="pre">'..'</span></code> even if they are present in the directory.</p>
|
||
<p><em>path</em> may be a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>. If <em>path</em> is of type <code class="docutils literal notranslate"><span class="pre">bytes</span></code>
|
||
(directly or indirectly through the <a class="reference internal" href="#os.PathLike" title="os.PathLike"><code class="xref py py-class docutils literal notranslate"><span class="pre">PathLike</span></code></a> interface),
|
||
the filenames returned will also be of type <code class="docutils literal notranslate"><span class="pre">bytes</span></code>;
|
||
in all other circumstances, they will be of type <code class="docutils literal notranslate"><span class="pre">str</span></code>.</p>
|
||
<p>This function can also support <a class="reference internal" href="#path-fd"><span class="std std-ref">specifying a file descriptor</span></a>; the file descriptor must refer to a directory.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>To encode <code class="docutils literal notranslate"><span class="pre">str</span></code> filenames to <code class="docutils literal notranslate"><span class="pre">bytes</span></code>, use <a class="reference internal" href="#os.fsencode" title="os.fsencode"><code class="xref py py-func docutils literal notranslate"><span class="pre">fsencode()</span></code></a>.</p>
|
||
</div>
|
||
<div class="admonition seealso">
|
||
<p class="admonition-title">See also</p>
|
||
<p>The <a class="reference internal" href="#os.scandir" title="os.scandir"><code class="xref py py-func docutils literal notranslate"><span class="pre">scandir()</span></code></a> function returns directory entries along with
|
||
file attribute information, giving better performance for many
|
||
common use cases.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.2: </span>The <em>path</em> parameter became optional.</p>
|
||
</div>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3: </span>Added support for specifying an open file descriptor for <em>path</em>.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>Accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.lstat">
|
||
<code class="descclassname">os.</code><code class="descname">lstat</code><span class="sig-paren">(</span><em>path</em>, <em>*</em>, <em>dir_fd=None</em><span class="sig-paren">)</span><a class="headerlink" href="#os.lstat" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Perform the equivalent of an <code class="xref c c-func docutils literal notranslate"><span class="pre">lstat()</span></code> system call on the given path.
|
||
Similar to <a class="reference internal" href="#os.stat" title="os.stat"><code class="xref py py-func docutils literal notranslate"><span class="pre">stat()</span></code></a>, but does not follow symbolic links. Return a
|
||
<a class="reference internal" href="#os.stat_result" title="os.stat_result"><code class="xref py py-class docutils literal notranslate"><span class="pre">stat_result</span></code></a> object.</p>
|
||
<p>On platforms that do not support symbolic links, this is an alias for
|
||
<a class="reference internal" href="#os.stat" title="os.stat"><code class="xref py py-func docutils literal notranslate"><span class="pre">stat()</span></code></a>.</p>
|
||
<p>As of Python 3.3, this is equivalent to <code class="docutils literal notranslate"><span class="pre">os.stat(path,</span> <span class="pre">dir_fd=dir_fd,</span>
|
||
<span class="pre">follow_symlinks=False)</span></code>.</p>
|
||
<p>This function can also support <a class="reference internal" href="#dir-fd"><span class="std std-ref">paths relative to directory descriptors</span></a>.</p>
|
||
<div class="admonition seealso">
|
||
<p class="admonition-title">See also</p>
|
||
<p>The <a class="reference internal" href="#os.stat" title="os.stat"><code class="xref py py-func docutils literal notranslate"><span class="pre">stat()</span></code></a> function.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.2: </span>Added support for Windows 6.0 (Vista) symbolic links.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.3: </span>Added the <em>dir_fd</em> parameter.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>Accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a> for <em>src</em> and <em>dst</em>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.mkdir">
|
||
<code class="descclassname">os.</code><code class="descname">mkdir</code><span class="sig-paren">(</span><em>path</em>, <em>mode=0o777</em>, <em>*</em>, <em>dir_fd=None</em><span class="sig-paren">)</span><a class="headerlink" href="#os.mkdir" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Create a directory named <em>path</em> with numeric mode <em>mode</em>.</p>
|
||
<p>If the directory already exists, <a class="reference internal" href="exceptions.html#FileExistsError" title="FileExistsError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">FileExistsError</span></code></a> is raised.</p>
|
||
<p id="mkdir-modebits">On some systems, <em>mode</em> is ignored. Where it is used, the current umask
|
||
value is first masked out. If bits other than the last 9 (i.e. the last 3
|
||
digits of the octal representation of the <em>mode</em>) are set, their meaning is
|
||
platform-dependent. On some platforms, they are ignored and you should call
|
||
<a class="reference internal" href="#os.chmod" title="os.chmod"><code class="xref py py-func docutils literal notranslate"><span class="pre">chmod()</span></code></a> explicitly to set them.</p>
|
||
<p>This function can also support <a class="reference internal" href="#dir-fd"><span class="std std-ref">paths relative to directory descriptors</span></a>.</p>
|
||
<p>It is also possible to create temporary directories; see the
|
||
<a class="reference internal" href="tempfile.html#module-tempfile" title="tempfile: Generate temporary files and directories."><code class="xref py py-mod docutils literal notranslate"><span class="pre">tempfile</span></code></a> module’s <a class="reference internal" href="tempfile.html#tempfile.mkdtemp" title="tempfile.mkdtemp"><code class="xref py py-func docutils literal notranslate"><span class="pre">tempfile.mkdtemp()</span></code></a> function.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3: </span>The <em>dir_fd</em> argument.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>Accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.makedirs">
|
||
<code class="descclassname">os.</code><code class="descname">makedirs</code><span class="sig-paren">(</span><em>name</em>, <em>mode=0o777</em>, <em>exist_ok=False</em><span class="sig-paren">)</span><a class="headerlink" href="#os.makedirs" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p id="index-19">Recursive directory creation function. Like <a class="reference internal" href="#os.mkdir" title="os.mkdir"><code class="xref py py-func docutils literal notranslate"><span class="pre">mkdir()</span></code></a>, but makes all
|
||
intermediate-level directories needed to contain the leaf directory.</p>
|
||
<p>The <em>mode</em> parameter is passed to <a class="reference internal" href="#os.mkdir" title="os.mkdir"><code class="xref py py-func docutils literal notranslate"><span class="pre">mkdir()</span></code></a> for creating the leaf
|
||
directory; see <a class="reference internal" href="#mkdir-modebits"><span class="std std-ref">the mkdir() description</span></a> for how it
|
||
is interpreted. To set the file permission bits of any newly-created parent
|
||
directories you can set the umask before invoking <a class="reference internal" href="#os.makedirs" title="os.makedirs"><code class="xref py py-func docutils literal notranslate"><span class="pre">makedirs()</span></code></a>. The
|
||
file permission bits of existing parent directories are not changed.</p>
|
||
<p>If <em>exist_ok</em> is <code class="docutils literal notranslate"><span class="pre">False</span></code> (the default), an <a class="reference internal" href="exceptions.html#FileExistsError" title="FileExistsError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">FileExistsError</span></code></a> is
|
||
raised if the target directory already exists.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p><a class="reference internal" href="#os.makedirs" title="os.makedirs"><code class="xref py py-func docutils literal notranslate"><span class="pre">makedirs()</span></code></a> will become confused if the path elements to create
|
||
include <a class="reference internal" href="#os.pardir" title="os.pardir"><code class="xref py py-data docutils literal notranslate"><span class="pre">pardir</span></code></a> (eg. “..” on UNIX systems).</p>
|
||
</div>
|
||
<p>This function handles UNC paths correctly.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.2: </span>The <em>exist_ok</em> parameter.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.4.1: </span>Before Python 3.4.1, if <em>exist_ok</em> was <code class="docutils literal notranslate"><span class="pre">True</span></code> and the directory existed,
|
||
<a class="reference internal" href="#os.makedirs" title="os.makedirs"><code class="xref py py-func docutils literal notranslate"><span class="pre">makedirs()</span></code></a> would still raise an error if <em>mode</em> did not match the
|
||
mode of the existing directory. Since this behavior was impossible to
|
||
implement safely, it was removed in Python 3.4.1. See <a class="reference external" href="https://bugs.python.org/issue21082">bpo-21082</a>.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>Accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.7: </span>The <em>mode</em> argument no longer affects the file permission bits of
|
||
newly-created intermediate-level directories.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.mkfifo">
|
||
<code class="descclassname">os.</code><code class="descname">mkfifo</code><span class="sig-paren">(</span><em>path</em>, <em>mode=0o666</em>, <em>*</em>, <em>dir_fd=None</em><span class="sig-paren">)</span><a class="headerlink" href="#os.mkfifo" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Create a FIFO (a named pipe) named <em>path</em> with numeric mode <em>mode</em>.
|
||
The current umask value is first masked out from the mode.</p>
|
||
<p>This function can also support <a class="reference internal" href="#dir-fd"><span class="std std-ref">paths relative to directory descriptors</span></a>.</p>
|
||
<p>FIFOs are pipes that can be accessed like regular files. FIFOs exist until they
|
||
are deleted (for example with <a class="reference internal" href="#os.unlink" title="os.unlink"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.unlink()</span></code></a>). Generally, FIFOs are used as
|
||
rendezvous between “client” and “server” type processes: the server opens the
|
||
FIFO for reading, and the client opens it for writing. Note that <a class="reference internal" href="#os.mkfifo" title="os.mkfifo"><code class="xref py py-func docutils literal notranslate"><span class="pre">mkfifo()</span></code></a>
|
||
doesn’t open the FIFO — it just creates the rendezvous point.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3: </span>The <em>dir_fd</em> argument.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>Accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.mknod">
|
||
<code class="descclassname">os.</code><code class="descname">mknod</code><span class="sig-paren">(</span><em>path</em>, <em>mode=0o600</em>, <em>device=0</em>, <em>*</em>, <em>dir_fd=None</em><span class="sig-paren">)</span><a class="headerlink" href="#os.mknod" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Create a filesystem node (file, device special file or named pipe) named
|
||
<em>path</em>. <em>mode</em> specifies both the permissions to use and the type of node
|
||
to be created, being combined (bitwise OR) with one of <code class="docutils literal notranslate"><span class="pre">stat.S_IFREG</span></code>,
|
||
<code class="docutils literal notranslate"><span class="pre">stat.S_IFCHR</span></code>, <code class="docutils literal notranslate"><span class="pre">stat.S_IFBLK</span></code>, and <code class="docutils literal notranslate"><span class="pre">stat.S_IFIFO</span></code> (those constants are
|
||
available in <a class="reference internal" href="stat.html#module-stat" title="stat: Utilities for interpreting the results of os.stat(), os.lstat() and os.fstat()."><code class="xref py py-mod docutils literal notranslate"><span class="pre">stat</span></code></a>). For <code class="docutils literal notranslate"><span class="pre">stat.S_IFCHR</span></code> and <code class="docutils literal notranslate"><span class="pre">stat.S_IFBLK</span></code>,
|
||
<em>device</em> defines the newly created device special file (probably using
|
||
<a class="reference internal" href="#os.makedev" title="os.makedev"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.makedev()</span></code></a>), otherwise it is ignored.</p>
|
||
<p>This function can also support <a class="reference internal" href="#dir-fd"><span class="std std-ref">paths relative to directory descriptors</span></a>.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3: </span>The <em>dir_fd</em> argument.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>Accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.major">
|
||
<code class="descclassname">os.</code><code class="descname">major</code><span class="sig-paren">(</span><em>device</em><span class="sig-paren">)</span><a class="headerlink" href="#os.major" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Extract the device major number from a raw device number (usually the
|
||
<code class="xref py py-attr docutils literal notranslate"><span class="pre">st_dev</span></code> or <code class="xref py py-attr docutils literal notranslate"><span class="pre">st_rdev</span></code> field from <code class="xref c c-type docutils literal notranslate"><span class="pre">stat</span></code>).</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.minor">
|
||
<code class="descclassname">os.</code><code class="descname">minor</code><span class="sig-paren">(</span><em>device</em><span class="sig-paren">)</span><a class="headerlink" href="#os.minor" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Extract the device minor number from a raw device number (usually the
|
||
<code class="xref py py-attr docutils literal notranslate"><span class="pre">st_dev</span></code> or <code class="xref py py-attr docutils literal notranslate"><span class="pre">st_rdev</span></code> field from <code class="xref c c-type docutils literal notranslate"><span class="pre">stat</span></code>).</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.makedev">
|
||
<code class="descclassname">os.</code><code class="descname">makedev</code><span class="sig-paren">(</span><em>major</em>, <em>minor</em><span class="sig-paren">)</span><a class="headerlink" href="#os.makedev" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Compose a raw device number from the major and minor device numbers.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.pathconf">
|
||
<code class="descclassname">os.</code><code class="descname">pathconf</code><span class="sig-paren">(</span><em>path</em>, <em>name</em><span class="sig-paren">)</span><a class="headerlink" href="#os.pathconf" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return system configuration information relevant to a named file. <em>name</em>
|
||
specifies the configuration value to retrieve; it may be a string which is the
|
||
name of a defined system value; these names are specified in a number of
|
||
standards (POSIX.1, Unix 95, Unix 98, and others). Some platforms define
|
||
additional names as well. The names known to the host operating system are
|
||
given in the <code class="docutils literal notranslate"><span class="pre">pathconf_names</span></code> dictionary. For configuration variables not
|
||
included in that mapping, passing an integer for <em>name</em> is also accepted.</p>
|
||
<p>If <em>name</em> is a string and is not known, <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> is raised. If a
|
||
specific value for <em>name</em> is not supported by the host system, even if it is
|
||
included in <code class="docutils literal notranslate"><span class="pre">pathconf_names</span></code>, an <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a> is raised with
|
||
<a class="reference internal" href="errno.html#errno.EINVAL" title="errno.EINVAL"><code class="xref py py-const docutils literal notranslate"><span class="pre">errno.EINVAL</span></code></a> for the error number.</p>
|
||
<p>This function can support <a class="reference internal" href="#path-fd"><span class="std std-ref">specifying a file descriptor</span></a>.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>Accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.pathconf_names">
|
||
<code class="descclassname">os.</code><code class="descname">pathconf_names</code><a class="headerlink" href="#os.pathconf_names" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Dictionary mapping names accepted by <a class="reference internal" href="#os.pathconf" title="os.pathconf"><code class="xref py py-func docutils literal notranslate"><span class="pre">pathconf()</span></code></a> and <a class="reference internal" href="#os.fpathconf" title="os.fpathconf"><code class="xref py py-func docutils literal notranslate"><span class="pre">fpathconf()</span></code></a> to
|
||
the integer values defined for those names by the host operating system. This
|
||
can be used to determine the set of names known to the system.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.readlink">
|
||
<code class="descclassname">os.</code><code class="descname">readlink</code><span class="sig-paren">(</span><em>path</em>, <em>*</em>, <em>dir_fd=None</em><span class="sig-paren">)</span><a class="headerlink" href="#os.readlink" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return a string representing the path to which the symbolic link points. The
|
||
result may be either an absolute or relative pathname; if it is relative, it
|
||
may be converted to an absolute pathname using
|
||
<code class="docutils literal notranslate"><span class="pre">os.path.join(os.path.dirname(path),</span> <span class="pre">result)</span></code>.</p>
|
||
<p>If the <em>path</em> is a string object (directly or indirectly through a
|
||
<a class="reference internal" href="#os.PathLike" title="os.PathLike"><code class="xref py py-class docutils literal notranslate"><span class="pre">PathLike</span></code></a> interface), the result will also be a string object,
|
||
and the call may raise a UnicodeDecodeError. If the <em>path</em> is a bytes
|
||
object (direct or indirectly), the result will be a bytes object.</p>
|
||
<p>This function can also support <a class="reference internal" href="#dir-fd"><span class="std std-ref">paths relative to directory descriptors</span></a>.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix, Windows.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.2: </span>Added support for Windows 6.0 (Vista) symbolic links.</p>
|
||
</div>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3: </span>The <em>dir_fd</em> argument.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>Accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.remove">
|
||
<code class="descclassname">os.</code><code class="descname">remove</code><span class="sig-paren">(</span><em>path</em>, <em>*</em>, <em>dir_fd=None</em><span class="sig-paren">)</span><a class="headerlink" href="#os.remove" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Remove (delete) the file <em>path</em>. If <em>path</em> is a directory, an
|
||
<a class="reference internal" href="exceptions.html#IsADirectoryError" title="IsADirectoryError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">IsADirectoryError</span></code></a> is raised. Use <a class="reference internal" href="#os.rmdir" title="os.rmdir"><code class="xref py py-func docutils literal notranslate"><span class="pre">rmdir()</span></code></a> to remove directories.</p>
|
||
<p>This function can support <a class="reference internal" href="#dir-fd"><span class="std std-ref">paths relative to directory descriptors</span></a>.</p>
|
||
<p>On Windows, attempting to remove a file that is in use causes an exception to
|
||
be raised; on Unix, the directory entry is removed but the storage allocated
|
||
to the file is not made available until the original file is no longer in use.</p>
|
||
<p>This function is semantically identical to <a class="reference internal" href="#os.unlink" title="os.unlink"><code class="xref py py-func docutils literal notranslate"><span class="pre">unlink()</span></code></a>.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3: </span>The <em>dir_fd</em> argument.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>Accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.removedirs">
|
||
<code class="descclassname">os.</code><code class="descname">removedirs</code><span class="sig-paren">(</span><em>name</em><span class="sig-paren">)</span><a class="headerlink" href="#os.removedirs" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p id="index-20">Remove directories recursively. Works like <a class="reference internal" href="#os.rmdir" title="os.rmdir"><code class="xref py py-func docutils literal notranslate"><span class="pre">rmdir()</span></code></a> except that, if the
|
||
leaf directory is successfully removed, <a class="reference internal" href="#os.removedirs" title="os.removedirs"><code class="xref py py-func docutils literal notranslate"><span class="pre">removedirs()</span></code></a> tries to
|
||
successively remove every parent directory mentioned in <em>path</em> until an error
|
||
is raised (which is ignored, because it generally means that a parent directory
|
||
is not empty). For example, <code class="docutils literal notranslate"><span class="pre">os.removedirs('foo/bar/baz')</span></code> will first remove
|
||
the directory <code class="docutils literal notranslate"><span class="pre">'foo/bar/baz'</span></code>, and then remove <code class="docutils literal notranslate"><span class="pre">'foo/bar'</span></code> and <code class="docutils literal notranslate"><span class="pre">'foo'</span></code> if
|
||
they are empty. Raises <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a> if the leaf directory could not be
|
||
successfully removed.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>Accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.rename">
|
||
<code class="descclassname">os.</code><code class="descname">rename</code><span class="sig-paren">(</span><em>src</em>, <em>dst</em>, <em>*</em>, <em>src_dir_fd=None</em>, <em>dst_dir_fd=None</em><span class="sig-paren">)</span><a class="headerlink" href="#os.rename" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Rename the file or directory <em>src</em> to <em>dst</em>. If <em>dst</em> exists, the operation
|
||
will fail with an <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a> subclass in a number of cases:</p>
|
||
<p>On Windows, if <em>dst</em> exists a <a class="reference internal" href="exceptions.html#FileExistsError" title="FileExistsError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">FileExistsError</span></code></a> is always raised.</p>
|
||
<p>On Unix, if <em>src</em> is a file and <em>dst</em> is a directory or vice-versa, an
|
||
<a class="reference internal" href="exceptions.html#IsADirectoryError" title="IsADirectoryError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">IsADirectoryError</span></code></a> or a <a class="reference internal" href="exceptions.html#NotADirectoryError" title="NotADirectoryError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">NotADirectoryError</span></code></a> will be raised
|
||
respectively. If both are directories and <em>dst</em> is empty, <em>dst</em> will be
|
||
silently replaced. If <em>dst</em> is a non-empty directory, an <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a>
|
||
is raised. If both are files, <em>dst</em> it will be replaced silently if the user
|
||
has permission. The operation may fail on some Unix flavors if <em>src</em> and
|
||
<em>dst</em> are on different filesystems. If successful, the renaming will be an
|
||
atomic operation (this is a POSIX requirement).</p>
|
||
<p>This function can support specifying <em>src_dir_fd</em> and/or <em>dst_dir_fd</em> to
|
||
supply <a class="reference internal" href="#dir-fd"><span class="std std-ref">paths relative to directory descriptors</span></a>.</p>
|
||
<p>If you want cross-platform overwriting of the destination, use <a class="reference internal" href="#os.replace" title="os.replace"><code class="xref py py-func docutils literal notranslate"><span class="pre">replace()</span></code></a>.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3: </span>The <em>src_dir_fd</em> and <em>dst_dir_fd</em> arguments.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>Accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a> for <em>src</em> and <em>dst</em>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.renames">
|
||
<code class="descclassname">os.</code><code class="descname">renames</code><span class="sig-paren">(</span><em>old</em>, <em>new</em><span class="sig-paren">)</span><a class="headerlink" href="#os.renames" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Recursive directory or file renaming function. Works like <a class="reference internal" href="#os.rename" title="os.rename"><code class="xref py py-func docutils literal notranslate"><span class="pre">rename()</span></code></a>, except
|
||
creation of any intermediate directories needed to make the new pathname good is
|
||
attempted first. After the rename, directories corresponding to rightmost path
|
||
segments of the old name will be pruned away using <a class="reference internal" href="#os.removedirs" title="os.removedirs"><code class="xref py py-func docutils literal notranslate"><span class="pre">removedirs()</span></code></a>.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>This function can fail with the new directory structure made if you lack
|
||
permissions needed to remove the leaf directory or file.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>Accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a> for <em>old</em> and <em>new</em>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.replace">
|
||
<code class="descclassname">os.</code><code class="descname">replace</code><span class="sig-paren">(</span><em>src</em>, <em>dst</em>, <em>*</em>, <em>src_dir_fd=None</em>, <em>dst_dir_fd=None</em><span class="sig-paren">)</span><a class="headerlink" href="#os.replace" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Rename the file or directory <em>src</em> to <em>dst</em>. If <em>dst</em> is a directory,
|
||
<a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a> will be raised. If <em>dst</em> exists and is a file, it will
|
||
be replaced silently if the user has permission. The operation may fail
|
||
if <em>src</em> and <em>dst</em> are on different filesystems. If successful,
|
||
the renaming will be an atomic operation (this is a POSIX requirement).</p>
|
||
<p>This function can support specifying <em>src_dir_fd</em> and/or <em>dst_dir_fd</em> to
|
||
supply <a class="reference internal" href="#dir-fd"><span class="std std-ref">paths relative to directory descriptors</span></a>.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3.</span></p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>Accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a> for <em>src</em> and <em>dst</em>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.rmdir">
|
||
<code class="descclassname">os.</code><code class="descname">rmdir</code><span class="sig-paren">(</span><em>path</em>, <em>*</em>, <em>dir_fd=None</em><span class="sig-paren">)</span><a class="headerlink" href="#os.rmdir" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Remove (delete) the directory <em>path</em>. If the directory does not exist or is
|
||
not empty, an <a class="reference internal" href="exceptions.html#FileNotFoundError" title="FileNotFoundError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">FileNotFoundError</span></code></a> or an <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a> is raised
|
||
respectively. In order to remove whole directory trees,
|
||
<a class="reference internal" href="shutil.html#shutil.rmtree" title="shutil.rmtree"><code class="xref py py-func docutils literal notranslate"><span class="pre">shutil.rmtree()</span></code></a> can be used.</p>
|
||
<p>This function can support <a class="reference internal" href="#dir-fd"><span class="std std-ref">paths relative to directory descriptors</span></a>.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3: </span>The <em>dir_fd</em> parameter.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>Accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.scandir">
|
||
<code class="descclassname">os.</code><code class="descname">scandir</code><span class="sig-paren">(</span><em>path='.'</em><span class="sig-paren">)</span><a class="headerlink" href="#os.scandir" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return an iterator of <a class="reference internal" href="#os.DirEntry" title="os.DirEntry"><code class="xref py py-class docutils literal notranslate"><span class="pre">os.DirEntry</span></code></a> objects corresponding to the
|
||
entries in the directory given by <em>path</em>. The entries are yielded in
|
||
arbitrary order, and the special entries <code class="docutils literal notranslate"><span class="pre">'.'</span></code> and <code class="docutils literal notranslate"><span class="pre">'..'</span></code> are not
|
||
included.</p>
|
||
<p>Using <a class="reference internal" href="#os.scandir" title="os.scandir"><code class="xref py py-func docutils literal notranslate"><span class="pre">scandir()</span></code></a> instead of <a class="reference internal" href="#os.listdir" title="os.listdir"><code class="xref py py-func docutils literal notranslate"><span class="pre">listdir()</span></code></a> can significantly
|
||
increase the performance of code that also needs file type or file
|
||
attribute information, because <a class="reference internal" href="#os.DirEntry" title="os.DirEntry"><code class="xref py py-class docutils literal notranslate"><span class="pre">os.DirEntry</span></code></a> objects expose this
|
||
information if the operating system provides it when scanning a directory.
|
||
All <a class="reference internal" href="#os.DirEntry" title="os.DirEntry"><code class="xref py py-class docutils literal notranslate"><span class="pre">os.DirEntry</span></code></a> methods may perform a system call, but
|
||
<a class="reference internal" href="#os.DirEntry.is_dir" title="os.DirEntry.is_dir"><code class="xref py py-func docutils literal notranslate"><span class="pre">is_dir()</span></code></a> and <a class="reference internal" href="#os.DirEntry.is_file" title="os.DirEntry.is_file"><code class="xref py py-func docutils literal notranslate"><span class="pre">is_file()</span></code></a> usually only
|
||
require a system call for symbolic links; <a class="reference internal" href="#os.DirEntry.stat" title="os.DirEntry.stat"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.DirEntry.stat()</span></code></a>
|
||
always requires a system call on Unix but only requires one for
|
||
symbolic links on Windows.</p>
|
||
<p><em>path</em> may be a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>. If <em>path</em> is of type <code class="docutils literal notranslate"><span class="pre">bytes</span></code>
|
||
(directly or indirectly through the <a class="reference internal" href="#os.PathLike" title="os.PathLike"><code class="xref py py-class docutils literal notranslate"><span class="pre">PathLike</span></code></a> interface),
|
||
the type of the <a class="reference internal" href="#os.DirEntry.name" title="os.DirEntry.name"><code class="xref py py-attr docutils literal notranslate"><span class="pre">name</span></code></a> and <a class="reference internal" href="#os.DirEntry.path" title="os.DirEntry.path"><code class="xref py py-attr docutils literal notranslate"><span class="pre">path</span></code></a>
|
||
attributes of each <a class="reference internal" href="#os.DirEntry" title="os.DirEntry"><code class="xref py py-class docutils literal notranslate"><span class="pre">os.DirEntry</span></code></a> will be <code class="docutils literal notranslate"><span class="pre">bytes</span></code>; in all other
|
||
circumstances, they will be of type <code class="docutils literal notranslate"><span class="pre">str</span></code>.</p>
|
||
<p>This function can also support <a class="reference internal" href="#path-fd"><span class="std std-ref">specifying a file descriptor</span></a>; the file descriptor must refer to a directory.</p>
|
||
<p>The <a class="reference internal" href="#os.scandir" title="os.scandir"><code class="xref py py-func docutils literal notranslate"><span class="pre">scandir()</span></code></a> iterator supports the <a class="reference internal" href="../glossary.html#term-context-manager"><span class="xref std std-term">context manager</span></a> protocol
|
||
and has the following method:</p>
|
||
<dl class="method">
|
||
<dt id="os.scandir.close">
|
||
<code class="descclassname">scandir.</code><code class="descname">close</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#os.scandir.close" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Close the iterator and free acquired resources.</p>
|
||
<p>This is called automatically when the iterator is exhausted or garbage
|
||
collected, or when an error happens during iterating. However it
|
||
is advisable to call it explicitly or use the <a class="reference internal" href="../reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code></a>
|
||
statement.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.6.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<p>The following example shows a simple use of <a class="reference internal" href="#os.scandir" title="os.scandir"><code class="xref py py-func docutils literal notranslate"><span class="pre">scandir()</span></code></a> to display all
|
||
the files (excluding directories) in the given <em>path</em> that don’t start with
|
||
<code class="docutils literal notranslate"><span class="pre">'.'</span></code>. The <code class="docutils literal notranslate"><span class="pre">entry.is_file()</span></code> call will generally not make an additional
|
||
system call:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="n">os</span><span class="o">.</span><span class="n">scandir</span><span class="p">(</span><span class="n">path</span><span class="p">)</span> <span class="k">as</span> <span class="n">it</span><span class="p">:</span>
|
||
<span class="k">for</span> <span class="n">entry</span> <span class="ow">in</span> <span class="n">it</span><span class="p">:</span>
|
||
<span class="k">if</span> <span class="ow">not</span> <span class="n">entry</span><span class="o">.</span><span class="n">name</span><span class="o">.</span><span class="n">startswith</span><span class="p">(</span><span class="s1">'.'</span><span class="p">)</span> <span class="ow">and</span> <span class="n">entry</span><span class="o">.</span><span class="n">is_file</span><span class="p">():</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="n">entry</span><span class="o">.</span><span class="n">name</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>On Unix-based systems, <a class="reference internal" href="#os.scandir" title="os.scandir"><code class="xref py py-func docutils literal notranslate"><span class="pre">scandir()</span></code></a> uses the system’s
|
||
<a class="reference external" href="http://pubs.opengroup.org/onlinepubs/009695399/functions/opendir.html">opendir()</a>
|
||
and
|
||
<a class="reference external" href="http://pubs.opengroup.org/onlinepubs/009695399/functions/readdir_r.html">readdir()</a>
|
||
functions. On Windows, it uses the Win32
|
||
<a class="reference external" href="https://msdn.microsoft.com/en-us/library/windows/desktop/aa364418(v=vs.85).aspx">FindFirstFileW</a>
|
||
and
|
||
<a class="reference external" href="https://msdn.microsoft.com/en-us/library/windows/desktop/aa364428(v=vs.85).aspx">FindNextFileW</a>
|
||
functions.</p>
|
||
</div>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.5.</span></p>
|
||
</div>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.6: </span>Added support for the <a class="reference internal" href="../glossary.html#term-context-manager"><span class="xref std std-term">context manager</span></a> protocol and the
|
||
<a class="reference internal" href="#os.scandir.close" title="os.scandir.close"><code class="xref py py-func docutils literal notranslate"><span class="pre">close()</span></code></a> method. If a <a class="reference internal" href="#os.scandir" title="os.scandir"><code class="xref py py-func docutils literal notranslate"><span class="pre">scandir()</span></code></a> iterator is neither
|
||
exhausted nor explicitly closed a <a class="reference internal" href="exceptions.html#ResourceWarning" title="ResourceWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ResourceWarning</span></code></a> will be emitted
|
||
in its destructor.</p>
|
||
<p>The function accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.7: </span>Added support for <a class="reference internal" href="#path-fd"><span class="std std-ref">file descriptors</span></a> on Unix.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="class">
|
||
<dt id="os.DirEntry">
|
||
<em class="property">class </em><code class="descclassname">os.</code><code class="descname">DirEntry</code><a class="headerlink" href="#os.DirEntry" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Object yielded by <a class="reference internal" href="#os.scandir" title="os.scandir"><code class="xref py py-func docutils literal notranslate"><span class="pre">scandir()</span></code></a> to expose the file path and other file
|
||
attributes of a directory entry.</p>
|
||
<p><a class="reference internal" href="#os.scandir" title="os.scandir"><code class="xref py py-func docutils literal notranslate"><span class="pre">scandir()</span></code></a> will provide as much of this information as possible without
|
||
making additional system calls. When a <code class="docutils literal notranslate"><span class="pre">stat()</span></code> or <code class="docutils literal notranslate"><span class="pre">lstat()</span></code> system call
|
||
is made, the <code class="docutils literal notranslate"><span class="pre">os.DirEntry</span></code> object will cache the result.</p>
|
||
<p><code class="docutils literal notranslate"><span class="pre">os.DirEntry</span></code> instances are not intended to be stored in long-lived data
|
||
structures; if you know the file metadata has changed or if a long time has
|
||
elapsed since calling <a class="reference internal" href="#os.scandir" title="os.scandir"><code class="xref py py-func docutils literal notranslate"><span class="pre">scandir()</span></code></a>, call <code class="docutils literal notranslate"><span class="pre">os.stat(entry.path)</span></code> to fetch
|
||
up-to-date information.</p>
|
||
<p>Because the <code class="docutils literal notranslate"><span class="pre">os.DirEntry</span></code> methods can make operating system calls, they may
|
||
also raise <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a>. If you need very fine-grained
|
||
control over errors, you can catch <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a> when calling one of the
|
||
<code class="docutils literal notranslate"><span class="pre">os.DirEntry</span></code> methods and handle as appropriate.</p>
|
||
<p>To be directly usable as a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>, <code class="docutils literal notranslate"><span class="pre">os.DirEntry</span></code>
|
||
implements the <a class="reference internal" href="#os.PathLike" title="os.PathLike"><code class="xref py py-class docutils literal notranslate"><span class="pre">PathLike</span></code></a> interface.</p>
|
||
<p>Attributes and methods on a <code class="docutils literal notranslate"><span class="pre">os.DirEntry</span></code> instance are as follows:</p>
|
||
<dl class="attribute">
|
||
<dt id="os.DirEntry.name">
|
||
<code class="descname">name</code><a class="headerlink" href="#os.DirEntry.name" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>The entry’s base filename, relative to the <a class="reference internal" href="#os.scandir" title="os.scandir"><code class="xref py py-func docutils literal notranslate"><span class="pre">scandir()</span></code></a> <em>path</em>
|
||
argument.</p>
|
||
<p>The <a class="reference internal" href="#os.name" title="os.name"><code class="xref py py-attr docutils literal notranslate"><span class="pre">name</span></code></a> attribute will be <code class="docutils literal notranslate"><span class="pre">bytes</span></code> if the <a class="reference internal" href="#os.scandir" title="os.scandir"><code class="xref py py-func docutils literal notranslate"><span class="pre">scandir()</span></code></a>
|
||
<em>path</em> argument is of type <code class="docutils literal notranslate"><span class="pre">bytes</span></code> and <code class="docutils literal notranslate"><span class="pre">str</span></code> otherwise. Use
|
||
<a class="reference internal" href="#os.fsdecode" title="os.fsdecode"><code class="xref py py-func docutils literal notranslate"><span class="pre">fsdecode()</span></code></a> to decode byte filenames.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="os.DirEntry.path">
|
||
<code class="descname">path</code><a class="headerlink" href="#os.DirEntry.path" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>The entry’s full path name: equivalent to <code class="docutils literal notranslate"><span class="pre">os.path.join(scandir_path,</span>
|
||
<span class="pre">entry.name)</span></code> where <em>scandir_path</em> is the <a class="reference internal" href="#os.scandir" title="os.scandir"><code class="xref py py-func docutils literal notranslate"><span class="pre">scandir()</span></code></a> <em>path</em>
|
||
argument. The path is only absolute if the <a class="reference internal" href="#os.scandir" title="os.scandir"><code class="xref py py-func docutils literal notranslate"><span class="pre">scandir()</span></code></a> <em>path</em>
|
||
argument was absolute. If the <a class="reference internal" href="#os.scandir" title="os.scandir"><code class="xref py py-func docutils literal notranslate"><span class="pre">scandir()</span></code></a> <em>path</em>
|
||
argument was a <a class="reference internal" href="#path-fd"><span class="std std-ref">file descriptor</span></a>, the <a class="reference internal" href="os.path.html#module-os.path" title="os.path: Operations on pathnames."><code class="xref py py-attr docutils literal notranslate"><span class="pre">path</span></code></a>
|
||
attribute is the same as the <a class="reference internal" href="#os.name" title="os.name"><code class="xref py py-attr docutils literal notranslate"><span class="pre">name</span></code></a> attribute.</p>
|
||
<p>The <a class="reference internal" href="os.path.html#module-os.path" title="os.path: Operations on pathnames."><code class="xref py py-attr docutils literal notranslate"><span class="pre">path</span></code></a> attribute will be <code class="docutils literal notranslate"><span class="pre">bytes</span></code> if the <a class="reference internal" href="#os.scandir" title="os.scandir"><code class="xref py py-func docutils literal notranslate"><span class="pre">scandir()</span></code></a>
|
||
<em>path</em> argument is of type <code class="docutils literal notranslate"><span class="pre">bytes</span></code> and <code class="docutils literal notranslate"><span class="pre">str</span></code> otherwise. Use
|
||
<a class="reference internal" href="#os.fsdecode" title="os.fsdecode"><code class="xref py py-func docutils literal notranslate"><span class="pre">fsdecode()</span></code></a> to decode byte filenames.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="os.DirEntry.inode">
|
||
<code class="descname">inode</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#os.DirEntry.inode" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return the inode number of the entry.</p>
|
||
<p>The result is cached on the <code class="docutils literal notranslate"><span class="pre">os.DirEntry</span></code> object. Use
|
||
<code class="docutils literal notranslate"><span class="pre">os.stat(entry.path,</span> <span class="pre">follow_symlinks=False).st_ino</span></code> to fetch up-to-date
|
||
information.</p>
|
||
<p>On the first, uncached call, a system call is required on Windows but
|
||
not on Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="os.DirEntry.is_dir">
|
||
<code class="descname">is_dir</code><span class="sig-paren">(</span><em>*</em>, <em>follow_symlinks=True</em><span class="sig-paren">)</span><a class="headerlink" href="#os.DirEntry.is_dir" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return <code class="docutils literal notranslate"><span class="pre">True</span></code> if this entry is a directory or a symbolic link pointing
|
||
to a directory; return <code class="docutils literal notranslate"><span class="pre">False</span></code> if the entry is or points to any other
|
||
kind of file, or if it doesn’t exist anymore.</p>
|
||
<p>If <em>follow_symlinks</em> is <code class="docutils literal notranslate"><span class="pre">False</span></code>, return <code class="docutils literal notranslate"><span class="pre">True</span></code> only if this entry
|
||
is a directory (without following symlinks); return <code class="docutils literal notranslate"><span class="pre">False</span></code> if the
|
||
entry is any other kind of file or if it doesn’t exist anymore.</p>
|
||
<p>The result is cached on the <code class="docutils literal notranslate"><span class="pre">os.DirEntry</span></code> object, with a separate cache
|
||
for <em>follow_symlinks</em> <code class="docutils literal notranslate"><span class="pre">True</span></code> and <code class="docutils literal notranslate"><span class="pre">False</span></code>. Call <a class="reference internal" href="#os.stat" title="os.stat"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.stat()</span></code></a> along
|
||
with <a class="reference internal" href="stat.html#stat.S_ISDIR" title="stat.S_ISDIR"><code class="xref py py-func docutils literal notranslate"><span class="pre">stat.S_ISDIR()</span></code></a> to fetch up-to-date information.</p>
|
||
<p>On the first, uncached call, no system call is required in most cases.
|
||
Specifically, for non-symlinks, neither Windows or Unix require a system
|
||
call, except on certain Unix file systems, such as network file systems,
|
||
that return <code class="docutils literal notranslate"><span class="pre">dirent.d_type</span> <span class="pre">==</span> <span class="pre">DT_UNKNOWN</span></code>. If the entry is a symlink,
|
||
a system call will be required to follow the symlink unless
|
||
<em>follow_symlinks</em> is <code class="docutils literal notranslate"><span class="pre">False</span></code>.</p>
|
||
<p>This method can raise <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a>, such as <a class="reference internal" href="exceptions.html#PermissionError" title="PermissionError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">PermissionError</span></code></a>,
|
||
but <a class="reference internal" href="exceptions.html#FileNotFoundError" title="FileNotFoundError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">FileNotFoundError</span></code></a> is caught and not raised.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="os.DirEntry.is_file">
|
||
<code class="descname">is_file</code><span class="sig-paren">(</span><em>*</em>, <em>follow_symlinks=True</em><span class="sig-paren">)</span><a class="headerlink" href="#os.DirEntry.is_file" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return <code class="docutils literal notranslate"><span class="pre">True</span></code> if this entry is a file or a symbolic link pointing to a
|
||
file; return <code class="docutils literal notranslate"><span class="pre">False</span></code> if the entry is or points to a directory or other
|
||
non-file entry, or if it doesn’t exist anymore.</p>
|
||
<p>If <em>follow_symlinks</em> is <code class="docutils literal notranslate"><span class="pre">False</span></code>, return <code class="docutils literal notranslate"><span class="pre">True</span></code> only if this entry
|
||
is a file (without following symlinks); return <code class="docutils literal notranslate"><span class="pre">False</span></code> if the entry is
|
||
a directory or other non-file entry, or if it doesn’t exist anymore.</p>
|
||
<p>The result is cached on the <code class="docutils literal notranslate"><span class="pre">os.DirEntry</span></code> object. Caching, system calls
|
||
made, and exceptions raised are as per <a class="reference internal" href="#os.DirEntry.is_dir" title="os.DirEntry.is_dir"><code class="xref py py-func docutils literal notranslate"><span class="pre">is_dir()</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="os.DirEntry.is_symlink">
|
||
<code class="descname">is_symlink</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#os.DirEntry.is_symlink" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return <code class="docutils literal notranslate"><span class="pre">True</span></code> if this entry is a symbolic link (even if broken);
|
||
return <code class="docutils literal notranslate"><span class="pre">False</span></code> if the entry points to a directory or any kind of file,
|
||
or if it doesn’t exist anymore.</p>
|
||
<p>The result is cached on the <code class="docutils literal notranslate"><span class="pre">os.DirEntry</span></code> object. Call
|
||
<a class="reference internal" href="os.path.html#os.path.islink" title="os.path.islink"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.path.islink()</span></code></a> to fetch up-to-date information.</p>
|
||
<p>On the first, uncached call, no system call is required in most cases.
|
||
Specifically, neither Windows or Unix require a system call, except on
|
||
certain Unix file systems, such as network file systems, that return
|
||
<code class="docutils literal notranslate"><span class="pre">dirent.d_type</span> <span class="pre">==</span> <span class="pre">DT_UNKNOWN</span></code>.</p>
|
||
<p>This method can raise <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a>, such as <a class="reference internal" href="exceptions.html#PermissionError" title="PermissionError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">PermissionError</span></code></a>,
|
||
but <a class="reference internal" href="exceptions.html#FileNotFoundError" title="FileNotFoundError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">FileNotFoundError</span></code></a> is caught and not raised.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="os.DirEntry.stat">
|
||
<code class="descname">stat</code><span class="sig-paren">(</span><em>*</em>, <em>follow_symlinks=True</em><span class="sig-paren">)</span><a class="headerlink" href="#os.DirEntry.stat" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return a <a class="reference internal" href="#os.stat_result" title="os.stat_result"><code class="xref py py-class docutils literal notranslate"><span class="pre">stat_result</span></code></a> object for this entry. This method
|
||
follows symbolic links by default; to stat a symbolic link add the
|
||
<code class="docutils literal notranslate"><span class="pre">follow_symlinks=False</span></code> argument.</p>
|
||
<p>On Unix, this method always requires a system call. On Windows, it
|
||
only requires a system call if <em>follow_symlinks</em> is <code class="docutils literal notranslate"><span class="pre">True</span></code> and the
|
||
entry is a symbolic link.</p>
|
||
<p>On Windows, the <code class="docutils literal notranslate"><span class="pre">st_ino</span></code>, <code class="docutils literal notranslate"><span class="pre">st_dev</span></code> and <code class="docutils literal notranslate"><span class="pre">st_nlink</span></code> attributes of the
|
||
<a class="reference internal" href="#os.stat_result" title="os.stat_result"><code class="xref py py-class docutils literal notranslate"><span class="pre">stat_result</span></code></a> are always set to zero. Call <a class="reference internal" href="#os.stat" title="os.stat"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.stat()</span></code></a> to
|
||
get these attributes.</p>
|
||
<p>The result is cached on the <code class="docutils literal notranslate"><span class="pre">os.DirEntry</span></code> object, with a separate cache
|
||
for <em>follow_symlinks</em> <code class="docutils literal notranslate"><span class="pre">True</span></code> and <code class="docutils literal notranslate"><span class="pre">False</span></code>. Call <a class="reference internal" href="#os.stat" title="os.stat"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.stat()</span></code></a> to
|
||
fetch up-to-date information.</p>
|
||
</dd></dl>
|
||
|
||
<p>Note that there is a nice correspondence between several attributes
|
||
and methods of <code class="docutils literal notranslate"><span class="pre">os.DirEntry</span></code> and of <a class="reference internal" href="pathlib.html#pathlib.Path" title="pathlib.Path"><code class="xref py py-class docutils literal notranslate"><span class="pre">pathlib.Path</span></code></a>. In
|
||
particular, the <code class="docutils literal notranslate"><span class="pre">name</span></code> attribute has the same
|
||
meaning, as do the <code class="docutils literal notranslate"><span class="pre">is_dir()</span></code>, <code class="docutils literal notranslate"><span class="pre">is_file()</span></code>, <code class="docutils literal notranslate"><span class="pre">is_symlink()</span></code>
|
||
and <code class="docutils literal notranslate"><span class="pre">stat()</span></code> methods.</p>
|
||
<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.6: </span>Added support for the <a class="reference internal" href="#os.PathLike" title="os.PathLike"><code class="xref py py-class docutils literal notranslate"><span class="pre">PathLike</span></code></a> interface. Added support
|
||
for <a class="reference internal" href="stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> paths on Windows.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.stat">
|
||
<code class="descclassname">os.</code><code class="descname">stat</code><span class="sig-paren">(</span><em>path</em>, <em>*</em>, <em>dir_fd=None</em>, <em>follow_symlinks=True</em><span class="sig-paren">)</span><a class="headerlink" href="#os.stat" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Get the status of a file or a file descriptor. Perform the equivalent of a
|
||
<code class="xref c c-func docutils literal notranslate"><span class="pre">stat()</span></code> system call on the given path. <em>path</em> may be specified as
|
||
either a string or bytes – directly or indirectly through the <a class="reference internal" href="#os.PathLike" title="os.PathLike"><code class="xref py py-class docutils literal notranslate"><span class="pre">PathLike</span></code></a>
|
||
interface – or as an open file descriptor. Return a <a class="reference internal" href="#os.stat_result" title="os.stat_result"><code class="xref py py-class docutils literal notranslate"><span class="pre">stat_result</span></code></a>
|
||
object.</p>
|
||
<p>This function normally follows symlinks; to stat a symlink add the argument
|
||
<code class="docutils literal notranslate"><span class="pre">follow_symlinks=False</span></code>, or use <a class="reference internal" href="#os.lstat" title="os.lstat"><code class="xref py py-func docutils literal notranslate"><span class="pre">lstat()</span></code></a>.</p>
|
||
<p>This function can support <a class="reference internal" href="#path-fd"><span class="std std-ref">specifying a file descriptor</span></a> and
|
||
<a class="reference internal" href="#follow-symlinks"><span class="std std-ref">not following symlinks</span></a>.</p>
|
||
<p id="index-21">Example:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">import</span> <span class="nn">os</span>
|
||
<span class="gp">>>> </span><span class="n">statinfo</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">stat</span><span class="p">(</span><span class="s1">'somefile.txt'</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">statinfo</span>
|
||
<span class="go">os.stat_result(st_mode=33188, st_ino=7876932, st_dev=234881026,</span>
|
||
<span class="go">st_nlink=1, st_uid=501, st_gid=501, st_size=264, st_atime=1297230295,</span>
|
||
<span class="go">st_mtime=1297230027, st_ctime=1297230027)</span>
|
||
<span class="gp">>>> </span><span class="n">statinfo</span><span class="o">.</span><span class="n">st_size</span>
|
||
<span class="go">264</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="admonition seealso">
|
||
<p class="admonition-title">See also</p>
|
||
<p><a class="reference internal" href="#os.fstat" title="os.fstat"><code class="xref py py-func docutils literal notranslate"><span class="pre">fstat()</span></code></a> and <a class="reference internal" href="#os.lstat" title="os.lstat"><code class="xref py py-func docutils literal notranslate"><span class="pre">lstat()</span></code></a> functions.</p>
|
||
</div>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3: </span>Added the <em>dir_fd</em> and <em>follow_symlinks</em> arguments, specifying a file
|
||
descriptor instead of a path.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>Accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="class">
|
||
<dt id="os.stat_result">
|
||
<em class="property">class </em><code class="descclassname">os.</code><code class="descname">stat_result</code><a class="headerlink" href="#os.stat_result" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Object whose attributes correspond roughly to the members of the
|
||
<code class="xref c c-type docutils literal notranslate"><span class="pre">stat</span></code> structure. It is used for the result of <a class="reference internal" href="#os.stat" title="os.stat"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.stat()</span></code></a>,
|
||
<a class="reference internal" href="#os.fstat" title="os.fstat"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.fstat()</span></code></a> and <a class="reference internal" href="#os.lstat" title="os.lstat"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.lstat()</span></code></a>.</p>
|
||
<p>Attributes:</p>
|
||
<dl class="attribute">
|
||
<dt id="os.stat_result.st_mode">
|
||
<code class="descname">st_mode</code><a class="headerlink" href="#os.stat_result.st_mode" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>File mode: file type and file mode bits (permissions).</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="os.stat_result.st_ino">
|
||
<code class="descname">st_ino</code><a class="headerlink" href="#os.stat_result.st_ino" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Platform dependent, but if non-zero, uniquely identifies the
|
||
file for a given value of <code class="docutils literal notranslate"><span class="pre">st_dev</span></code>. Typically:</p>
|
||
<ul class="simple">
|
||
<li><p>the inode number on Unix,</p></li>
|
||
<li><p>the <a class="reference external" href="https://msdn.microsoft.com/en-us/library/aa363788">file index</a> on
|
||
Windows</p></li>
|
||
</ul>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="os.stat_result.st_dev">
|
||
<code class="descname">st_dev</code><a class="headerlink" href="#os.stat_result.st_dev" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Identifier of the device on which this file resides.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="os.stat_result.st_nlink">
|
||
<code class="descname">st_nlink</code><a class="headerlink" href="#os.stat_result.st_nlink" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Number of hard links.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="os.stat_result.st_uid">
|
||
<code class="descname">st_uid</code><a class="headerlink" href="#os.stat_result.st_uid" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>User identifier of the file owner.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="os.stat_result.st_gid">
|
||
<code class="descname">st_gid</code><a class="headerlink" href="#os.stat_result.st_gid" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Group identifier of the file owner.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="os.stat_result.st_size">
|
||
<code class="descname">st_size</code><a class="headerlink" href="#os.stat_result.st_size" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Size of the file in bytes, if it is a regular file or a symbolic link.
|
||
The size of a symbolic link is the length of the pathname it contains,
|
||
without a terminating null byte.</p>
|
||
</dd></dl>
|
||
|
||
<p>Timestamps:</p>
|
||
<dl class="attribute">
|
||
<dt id="os.stat_result.st_atime">
|
||
<code class="descname">st_atime</code><a class="headerlink" href="#os.stat_result.st_atime" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Time of most recent access expressed in seconds.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="os.stat_result.st_mtime">
|
||
<code class="descname">st_mtime</code><a class="headerlink" href="#os.stat_result.st_mtime" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Time of most recent content modification expressed in seconds.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="os.stat_result.st_ctime">
|
||
<code class="descname">st_ctime</code><a class="headerlink" href="#os.stat_result.st_ctime" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Platform dependent:</p>
|
||
<ul class="simple">
|
||
<li><p>the time of most recent metadata change on Unix,</p></li>
|
||
<li><p>the time of creation on Windows, expressed in seconds.</p></li>
|
||
</ul>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="os.stat_result.st_atime_ns">
|
||
<code class="descname">st_atime_ns</code><a class="headerlink" href="#os.stat_result.st_atime_ns" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Time of most recent access expressed in nanoseconds as an integer.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="os.stat_result.st_mtime_ns">
|
||
<code class="descname">st_mtime_ns</code><a class="headerlink" href="#os.stat_result.st_mtime_ns" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Time of most recent content modification expressed in nanoseconds as an
|
||
integer.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="os.stat_result.st_ctime_ns">
|
||
<code class="descname">st_ctime_ns</code><a class="headerlink" href="#os.stat_result.st_ctime_ns" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Platform dependent:</p>
|
||
<ul class="simple">
|
||
<li><p>the time of most recent metadata change on Unix,</p></li>
|
||
<li><p>the time of creation on Windows, expressed in nanoseconds as an
|
||
integer.</p></li>
|
||
</ul>
|
||
</dd></dl>
|
||
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>The exact meaning and resolution of the <a class="reference internal" href="#os.stat_result.st_atime" title="os.stat_result.st_atime"><code class="xref py py-attr docutils literal notranslate"><span class="pre">st_atime</span></code></a>,
|
||
<a class="reference internal" href="#os.stat_result.st_mtime" title="os.stat_result.st_mtime"><code class="xref py py-attr docutils literal notranslate"><span class="pre">st_mtime</span></code></a>, and <a class="reference internal" href="#os.stat_result.st_ctime" title="os.stat_result.st_ctime"><code class="xref py py-attr docutils literal notranslate"><span class="pre">st_ctime</span></code></a> attributes depend on the operating
|
||
system and the file system. For example, on Windows systems using the FAT
|
||
or FAT32 file systems, <a class="reference internal" href="#os.stat_result.st_mtime" title="os.stat_result.st_mtime"><code class="xref py py-attr docutils literal notranslate"><span class="pre">st_mtime</span></code></a> has 2-second resolution, and
|
||
<a class="reference internal" href="#os.stat_result.st_atime" title="os.stat_result.st_atime"><code class="xref py py-attr docutils literal notranslate"><span class="pre">st_atime</span></code></a> has only 1-day resolution. See your operating system
|
||
documentation for details.</p>
|
||
<p>Similarly, although <a class="reference internal" href="#os.stat_result.st_atime_ns" title="os.stat_result.st_atime_ns"><code class="xref py py-attr docutils literal notranslate"><span class="pre">st_atime_ns</span></code></a>, <a class="reference internal" href="#os.stat_result.st_mtime_ns" title="os.stat_result.st_mtime_ns"><code class="xref py py-attr docutils literal notranslate"><span class="pre">st_mtime_ns</span></code></a>,
|
||
and <a class="reference internal" href="#os.stat_result.st_ctime_ns" title="os.stat_result.st_ctime_ns"><code class="xref py py-attr docutils literal notranslate"><span class="pre">st_ctime_ns</span></code></a> are always expressed in nanoseconds, many
|
||
systems do not provide nanosecond precision. On systems that do
|
||
provide nanosecond precision, the floating-point object used to
|
||
store <a class="reference internal" href="#os.stat_result.st_atime" title="os.stat_result.st_atime"><code class="xref py py-attr docutils literal notranslate"><span class="pre">st_atime</span></code></a>, <a class="reference internal" href="#os.stat_result.st_mtime" title="os.stat_result.st_mtime"><code class="xref py py-attr docutils literal notranslate"><span class="pre">st_mtime</span></code></a>, and <a class="reference internal" href="#os.stat_result.st_ctime" title="os.stat_result.st_ctime"><code class="xref py py-attr docutils literal notranslate"><span class="pre">st_ctime</span></code></a>
|
||
cannot preserve all of it, and as such will be slightly inexact.
|
||
If you need the exact timestamps you should always use
|
||
<a class="reference internal" href="#os.stat_result.st_atime_ns" title="os.stat_result.st_atime_ns"><code class="xref py py-attr docutils literal notranslate"><span class="pre">st_atime_ns</span></code></a>, <a class="reference internal" href="#os.stat_result.st_mtime_ns" title="os.stat_result.st_mtime_ns"><code class="xref py py-attr docutils literal notranslate"><span class="pre">st_mtime_ns</span></code></a>, and <a class="reference internal" href="#os.stat_result.st_ctime_ns" title="os.stat_result.st_ctime_ns"><code class="xref py py-attr docutils literal notranslate"><span class="pre">st_ctime_ns</span></code></a>.</p>
|
||
</div>
|
||
<p>On some Unix systems (such as Linux), the following attributes may also be
|
||
available:</p>
|
||
<dl class="attribute">
|
||
<dt id="os.stat_result.st_blocks">
|
||
<code class="descname">st_blocks</code><a class="headerlink" href="#os.stat_result.st_blocks" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Number of 512-byte blocks allocated for file.
|
||
This may be smaller than <a class="reference internal" href="#os.stat_result.st_size" title="os.stat_result.st_size"><code class="xref py py-attr docutils literal notranslate"><span class="pre">st_size</span></code></a>/512 when the file has holes.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="os.stat_result.st_blksize">
|
||
<code class="descname">st_blksize</code><a class="headerlink" href="#os.stat_result.st_blksize" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>“Preferred” blocksize for efficient file system I/O. Writing to a file in
|
||
smaller chunks may cause an inefficient read-modify-rewrite.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="os.stat_result.st_rdev">
|
||
<code class="descname">st_rdev</code><a class="headerlink" href="#os.stat_result.st_rdev" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Type of device if an inode device.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="os.stat_result.st_flags">
|
||
<code class="descname">st_flags</code><a class="headerlink" href="#os.stat_result.st_flags" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>User defined flags for file.</p>
|
||
</dd></dl>
|
||
|
||
<p>On other Unix systems (such as FreeBSD), the following attributes may be
|
||
available (but may be only filled out if root tries to use them):</p>
|
||
<dl class="attribute">
|
||
<dt id="os.stat_result.st_gen">
|
||
<code class="descname">st_gen</code><a class="headerlink" href="#os.stat_result.st_gen" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>File generation number.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="os.stat_result.st_birthtime">
|
||
<code class="descname">st_birthtime</code><a class="headerlink" href="#os.stat_result.st_birthtime" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Time of file creation.</p>
|
||
</dd></dl>
|
||
|
||
<p>On Solaris and derivatives, the following attributes may also be
|
||
available:</p>
|
||
<dl class="attribute">
|
||
<dt id="os.stat_result.st_fstype">
|
||
<code class="descname">st_fstype</code><a class="headerlink" href="#os.stat_result.st_fstype" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>String that uniquely identifies the type of the filesystem that
|
||
contains the file.</p>
|
||
</dd></dl>
|
||
|
||
<p>On Mac OS systems, the following attributes may also be available:</p>
|
||
<dl class="attribute">
|
||
<dt id="os.stat_result.st_rsize">
|
||
<code class="descname">st_rsize</code><a class="headerlink" href="#os.stat_result.st_rsize" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Real size of the file.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="os.stat_result.st_creator">
|
||
<code class="descname">st_creator</code><a class="headerlink" href="#os.stat_result.st_creator" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Creator of the file.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="os.stat_result.st_type">
|
||
<code class="descname">st_type</code><a class="headerlink" href="#os.stat_result.st_type" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>File type.</p>
|
||
</dd></dl>
|
||
|
||
<p>On Windows systems, the following attribute is also available:</p>
|
||
<dl class="attribute">
|
||
<dt id="os.stat_result.st_file_attributes">
|
||
<code class="descname">st_file_attributes</code><a class="headerlink" href="#os.stat_result.st_file_attributes" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Windows file attributes: <code class="docutils literal notranslate"><span class="pre">dwFileAttributes</span></code> member of the
|
||
<code class="docutils literal notranslate"><span class="pre">BY_HANDLE_FILE_INFORMATION</span></code> structure returned by
|
||
<code class="xref c c-func docutils literal notranslate"><span class="pre">GetFileInformationByHandle()</span></code>. See the <code class="docutils literal notranslate"><span class="pre">FILE_ATTRIBUTE_*</span></code>
|
||
constants in the <a class="reference internal" href="stat.html#module-stat" title="stat: Utilities for interpreting the results of os.stat(), os.lstat() and os.fstat()."><code class="xref py py-mod docutils literal notranslate"><span class="pre">stat</span></code></a> module.</p>
|
||
</dd></dl>
|
||
|
||
<p>The standard module <a class="reference internal" href="stat.html#module-stat" title="stat: Utilities for interpreting the results of os.stat(), os.lstat() and os.fstat()."><code class="xref py py-mod docutils literal notranslate"><span class="pre">stat</span></code></a> defines functions and constants that are
|
||
useful for extracting information from a <code class="xref c c-type docutils literal notranslate"><span class="pre">stat</span></code> structure. (On
|
||
Windows, some items are filled with dummy values.)</p>
|
||
<p>For backward compatibility, a <a class="reference internal" href="#os.stat_result" title="os.stat_result"><code class="xref py py-class docutils literal notranslate"><span class="pre">stat_result</span></code></a> instance is also
|
||
accessible as a tuple of at least 10 integers giving the most important (and
|
||
portable) members of the <code class="xref c c-type docutils literal notranslate"><span class="pre">stat</span></code> structure, in the order
|
||
<a class="reference internal" href="#os.stat_result.st_mode" title="os.stat_result.st_mode"><code class="xref py py-attr docutils literal notranslate"><span class="pre">st_mode</span></code></a>, <a class="reference internal" href="#os.stat_result.st_ino" title="os.stat_result.st_ino"><code class="xref py py-attr docutils literal notranslate"><span class="pre">st_ino</span></code></a>, <a class="reference internal" href="#os.stat_result.st_dev" title="os.stat_result.st_dev"><code class="xref py py-attr docutils literal notranslate"><span class="pre">st_dev</span></code></a>, <a class="reference internal" href="#os.stat_result.st_nlink" title="os.stat_result.st_nlink"><code class="xref py py-attr docutils literal notranslate"><span class="pre">st_nlink</span></code></a>,
|
||
<a class="reference internal" href="#os.stat_result.st_uid" title="os.stat_result.st_uid"><code class="xref py py-attr docutils literal notranslate"><span class="pre">st_uid</span></code></a>, <a class="reference internal" href="#os.stat_result.st_gid" title="os.stat_result.st_gid"><code class="xref py py-attr docutils literal notranslate"><span class="pre">st_gid</span></code></a>, <a class="reference internal" href="#os.stat_result.st_size" title="os.stat_result.st_size"><code class="xref py py-attr docutils literal notranslate"><span class="pre">st_size</span></code></a>, <a class="reference internal" href="#os.stat_result.st_atime" title="os.stat_result.st_atime"><code class="xref py py-attr docutils literal notranslate"><span class="pre">st_atime</span></code></a>,
|
||
<a class="reference internal" href="#os.stat_result.st_mtime" title="os.stat_result.st_mtime"><code class="xref py py-attr docutils literal notranslate"><span class="pre">st_mtime</span></code></a>, <a class="reference internal" href="#os.stat_result.st_ctime" title="os.stat_result.st_ctime"><code class="xref py py-attr docutils literal notranslate"><span class="pre">st_ctime</span></code></a>. More items may be added at the end by
|
||
some implementations. For compatibility with older Python versions,
|
||
accessing <a class="reference internal" href="#os.stat_result" title="os.stat_result"><code class="xref py py-class docutils literal notranslate"><span class="pre">stat_result</span></code></a> as a tuple always returns integers.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3: </span>Added the <a class="reference internal" href="#os.stat_result.st_atime_ns" title="os.stat_result.st_atime_ns"><code class="xref py py-attr docutils literal notranslate"><span class="pre">st_atime_ns</span></code></a>, <a class="reference internal" href="#os.stat_result.st_mtime_ns" title="os.stat_result.st_mtime_ns"><code class="xref py py-attr docutils literal notranslate"><span class="pre">st_mtime_ns</span></code></a>, and
|
||
<a class="reference internal" href="#os.stat_result.st_ctime_ns" title="os.stat_result.st_ctime_ns"><code class="xref py py-attr docutils literal notranslate"><span class="pre">st_ctime_ns</span></code></a> members.</p>
|
||
</div>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.5: </span>Added the <a class="reference internal" href="#os.stat_result.st_file_attributes" title="os.stat_result.st_file_attributes"><code class="xref py py-attr docutils literal notranslate"><span class="pre">st_file_attributes</span></code></a> member on Windows.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.5: </span>Windows now returns the file index as <a class="reference internal" href="#os.stat_result.st_ino" title="os.stat_result.st_ino"><code class="xref py py-attr docutils literal notranslate"><span class="pre">st_ino</span></code></a> when
|
||
available.</p>
|
||
</div>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.7: </span>Added the <a class="reference internal" href="#os.stat_result.st_fstype" title="os.stat_result.st_fstype"><code class="xref py py-attr docutils literal notranslate"><span class="pre">st_fstype</span></code></a> member to Solaris/derivatives.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.statvfs">
|
||
<code class="descclassname">os.</code><code class="descname">statvfs</code><span class="sig-paren">(</span><em>path</em><span class="sig-paren">)</span><a class="headerlink" href="#os.statvfs" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Perform a <code class="xref c c-func docutils literal notranslate"><span class="pre">statvfs()</span></code> system call on the given path. The return value is
|
||
an object whose attributes describe the filesystem on the given path, and
|
||
correspond to the members of the <code class="xref c c-type docutils literal notranslate"><span class="pre">statvfs</span></code> structure, namely:
|
||
<code class="xref py py-attr docutils literal notranslate"><span class="pre">f_bsize</span></code>, <code class="xref py py-attr docutils literal notranslate"><span class="pre">f_frsize</span></code>, <code class="xref py py-attr docutils literal notranslate"><span class="pre">f_blocks</span></code>, <code class="xref py py-attr docutils literal notranslate"><span class="pre">f_bfree</span></code>,
|
||
<code class="xref py py-attr docutils literal notranslate"><span class="pre">f_bavail</span></code>, <code class="xref py py-attr docutils literal notranslate"><span class="pre">f_files</span></code>, <code class="xref py py-attr docutils literal notranslate"><span class="pre">f_ffree</span></code>, <code class="xref py py-attr docutils literal notranslate"><span class="pre">f_favail</span></code>,
|
||
<code class="xref py py-attr docutils literal notranslate"><span class="pre">f_flag</span></code>, <code class="xref py py-attr docutils literal notranslate"><span class="pre">f_namemax</span></code>, <code class="xref py py-attr docutils literal notranslate"><span class="pre">f_fsid</span></code>.</p>
|
||
<p>Two module-level constants are defined for the <code class="xref py py-attr docutils literal notranslate"><span class="pre">f_flag</span></code> attribute’s
|
||
bit-flags: if <code class="xref py py-const docutils literal notranslate"><span class="pre">ST_RDONLY</span></code> is set, the filesystem is mounted
|
||
read-only, and if <code class="xref py py-const docutils literal notranslate"><span class="pre">ST_NOSUID</span></code> is set, the semantics of
|
||
setuid/setgid bits are disabled or not supported.</p>
|
||
<p>Additional module-level constants are defined for GNU/glibc based systems.
|
||
These are <code class="xref py py-const docutils literal notranslate"><span class="pre">ST_NODEV</span></code> (disallow access to device special files),
|
||
<code class="xref py py-const docutils literal notranslate"><span class="pre">ST_NOEXEC</span></code> (disallow program execution), <code class="xref py py-const docutils literal notranslate"><span class="pre">ST_SYNCHRONOUS</span></code>
|
||
(writes are synced at once), <code class="xref py py-const docutils literal notranslate"><span class="pre">ST_MANDLOCK</span></code> (allow mandatory locks on an FS),
|
||
<code class="xref py py-const docutils literal notranslate"><span class="pre">ST_WRITE</span></code> (write on file/directory/symlink), <code class="xref py py-const docutils literal notranslate"><span class="pre">ST_APPEND</span></code>
|
||
(append-only file), <code class="xref py py-const docutils literal notranslate"><span class="pre">ST_IMMUTABLE</span></code> (immutable file), <code class="xref py py-const docutils literal notranslate"><span class="pre">ST_NOATIME</span></code>
|
||
(do not update access times), <code class="xref py py-const docutils literal notranslate"><span class="pre">ST_NODIRATIME</span></code> (do not update directory access
|
||
times), <code class="xref py py-const docutils literal notranslate"><span class="pre">ST_RELATIME</span></code> (update atime relative to mtime/ctime).</p>
|
||
<p>This function can support <a class="reference internal" href="#path-fd"><span class="std std-ref">specifying a file descriptor</span></a>.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.2: </span>The <code class="xref py py-const docutils literal notranslate"><span class="pre">ST_RDONLY</span></code> and <code class="xref py py-const docutils literal notranslate"><span class="pre">ST_NOSUID</span></code> constants were added.</p>
|
||
</div>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3: </span>Added support for specifying an open file descriptor for <em>path</em>.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.4: </span>The <code class="xref py py-const docutils literal notranslate"><span class="pre">ST_NODEV</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">ST_NOEXEC</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">ST_SYNCHRONOUS</span></code>,
|
||
<code class="xref py py-const docutils literal notranslate"><span class="pre">ST_MANDLOCK</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">ST_WRITE</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">ST_APPEND</span></code>,
|
||
<code class="xref py py-const docutils literal notranslate"><span class="pre">ST_IMMUTABLE</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">ST_NOATIME</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">ST_NODIRATIME</span></code>,
|
||
and <code class="xref py py-const docutils literal notranslate"><span class="pre">ST_RELATIME</span></code> constants were added.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>Accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>.</p>
|
||
</div>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.7: </span>Added <code class="xref py py-attr docutils literal notranslate"><span class="pre">f_fsid</span></code>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.supports_dir_fd">
|
||
<code class="descclassname">os.</code><code class="descname">supports_dir_fd</code><a class="headerlink" href="#os.supports_dir_fd" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>A <a class="reference internal" href="collections.abc.html#collections.abc.Set" title="collections.abc.Set"><code class="xref py py-class docutils literal notranslate"><span class="pre">Set</span></code></a> object indicating which functions in the
|
||
<a class="reference internal" href="#module-os" title="os: Miscellaneous operating system interfaces."><code class="xref py py-mod docutils literal notranslate"><span class="pre">os</span></code></a> module permit use of their <em>dir_fd</em> parameter. Different platforms
|
||
provide different functionality, and an option that might work on one might
|
||
be unsupported on another. For consistency’s sakes, functions that support
|
||
<em>dir_fd</em> always allow specifying the parameter, but will raise an exception
|
||
if the functionality is not actually available.</p>
|
||
<p>To check whether a particular function permits use of its <em>dir_fd</em>
|
||
parameter, use the <code class="docutils literal notranslate"><span class="pre">in</span></code> operator on <code class="docutils literal notranslate"><span class="pre">supports_dir_fd</span></code>. As an example,
|
||
this expression determines whether the <em>dir_fd</em> parameter of <a class="reference internal" href="#os.stat" title="os.stat"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.stat()</span></code></a>
|
||
is locally available:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">os</span><span class="o">.</span><span class="n">stat</span> <span class="ow">in</span> <span class="n">os</span><span class="o">.</span><span class="n">supports_dir_fd</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Currently <em>dir_fd</em> parameters only work on Unix platforms; none of them work
|
||
on Windows.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.supports_effective_ids">
|
||
<code class="descclassname">os.</code><code class="descname">supports_effective_ids</code><a class="headerlink" href="#os.supports_effective_ids" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>A <a class="reference internal" href="collections.abc.html#collections.abc.Set" title="collections.abc.Set"><code class="xref py py-class docutils literal notranslate"><span class="pre">Set</span></code></a> object indicating which functions in the
|
||
<a class="reference internal" href="#module-os" title="os: Miscellaneous operating system interfaces."><code class="xref py py-mod docutils literal notranslate"><span class="pre">os</span></code></a> module permit use of the <em>effective_ids</em> parameter for
|
||
<a class="reference internal" href="#os.access" title="os.access"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.access()</span></code></a>. If the local platform supports it, the collection will
|
||
contain <a class="reference internal" href="#os.access" title="os.access"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.access()</span></code></a>, otherwise it will be empty.</p>
|
||
<p>To check whether you can use the <em>effective_ids</em> parameter for
|
||
<a class="reference internal" href="#os.access" title="os.access"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.access()</span></code></a>, use the <code class="docutils literal notranslate"><span class="pre">in</span></code> operator on <code class="docutils literal notranslate"><span class="pre">supports_effective_ids</span></code>,
|
||
like so:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">os</span><span class="o">.</span><span class="n">access</span> <span class="ow">in</span> <span class="n">os</span><span class="o">.</span><span class="n">supports_effective_ids</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Currently <em>effective_ids</em> only works on Unix platforms; it does not work on
|
||
Windows.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.supports_fd">
|
||
<code class="descclassname">os.</code><code class="descname">supports_fd</code><a class="headerlink" href="#os.supports_fd" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>A <a class="reference internal" href="collections.abc.html#collections.abc.Set" title="collections.abc.Set"><code class="xref py py-class docutils literal notranslate"><span class="pre">Set</span></code></a> object indicating which functions in the
|
||
<a class="reference internal" href="#module-os" title="os: Miscellaneous operating system interfaces."><code class="xref py py-mod docutils literal notranslate"><span class="pre">os</span></code></a> module permit specifying their <em>path</em> parameter as an open file
|
||
descriptor. Different platforms provide different functionality, and an
|
||
option that might work on one might be unsupported on another. For
|
||
consistency’s sakes, functions that support <em>fd</em> always allow specifying
|
||
the parameter, but will raise an exception if the functionality is not
|
||
actually available.</p>
|
||
<p>To check whether a particular function permits specifying an open file
|
||
descriptor for its <em>path</em> parameter, use the <code class="docutils literal notranslate"><span class="pre">in</span></code> operator on
|
||
<code class="docutils literal notranslate"><span class="pre">supports_fd</span></code>. As an example, this expression determines whether
|
||
<a class="reference internal" href="#os.chdir" title="os.chdir"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.chdir()</span></code></a> accepts open file descriptors when called on your local
|
||
platform:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">os</span><span class="o">.</span><span class="n">chdir</span> <span class="ow">in</span> <span class="n">os</span><span class="o">.</span><span class="n">supports_fd</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.supports_follow_symlinks">
|
||
<code class="descclassname">os.</code><code class="descname">supports_follow_symlinks</code><a class="headerlink" href="#os.supports_follow_symlinks" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>A <a class="reference internal" href="collections.abc.html#collections.abc.Set" title="collections.abc.Set"><code class="xref py py-class docutils literal notranslate"><span class="pre">Set</span></code></a> object indicating which functions in the
|
||
<a class="reference internal" href="#module-os" title="os: Miscellaneous operating system interfaces."><code class="xref py py-mod docutils literal notranslate"><span class="pre">os</span></code></a> module permit use of their <em>follow_symlinks</em> parameter. Different
|
||
platforms provide different functionality, and an option that might work on
|
||
one might be unsupported on another. For consistency’s sakes, functions that
|
||
support <em>follow_symlinks</em> always allow specifying the parameter, but will
|
||
raise an exception if the functionality is not actually available.</p>
|
||
<p>To check whether a particular function permits use of its <em>follow_symlinks</em>
|
||
parameter, use the <code class="docutils literal notranslate"><span class="pre">in</span></code> operator on <code class="docutils literal notranslate"><span class="pre">supports_follow_symlinks</span></code>. As an
|
||
example, this expression determines whether the <em>follow_symlinks</em> parameter
|
||
of <a class="reference internal" href="#os.stat" title="os.stat"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.stat()</span></code></a> is locally available:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">os</span><span class="o">.</span><span class="n">stat</span> <span class="ow">in</span> <span class="n">os</span><span class="o">.</span><span class="n">supports_follow_symlinks</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.symlink">
|
||
<code class="descclassname">os.</code><code class="descname">symlink</code><span class="sig-paren">(</span><em>src</em>, <em>dst</em>, <em>target_is_directory=False</em>, <em>*</em>, <em>dir_fd=None</em><span class="sig-paren">)</span><a class="headerlink" href="#os.symlink" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Create a symbolic link pointing to <em>src</em> named <em>dst</em>.</p>
|
||
<p>On Windows, a symlink represents either a file or a directory, and does not
|
||
morph to the target dynamically. If the target is present, the type of the
|
||
symlink will be created to match. Otherwise, the symlink will be created
|
||
as a directory if <em>target_is_directory</em> is <code class="docutils literal notranslate"><span class="pre">True</span></code> or a file symlink (the
|
||
default) otherwise. On non-Windows platforms, <em>target_is_directory</em> is ignored.</p>
|
||
<p>Symbolic link support was introduced in Windows 6.0 (Vista). <a class="reference internal" href="#os.symlink" title="os.symlink"><code class="xref py py-func docutils literal notranslate"><span class="pre">symlink()</span></code></a>
|
||
will raise a <a class="reference internal" href="exceptions.html#NotImplementedError" title="NotImplementedError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">NotImplementedError</span></code></a> on Windows versions earlier than 6.0.</p>
|
||
<p>This function can support <a class="reference internal" href="#dir-fd"><span class="std std-ref">paths relative to directory descriptors</span></a>.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>On Windows, the <em>SeCreateSymbolicLinkPrivilege</em> is required in order to
|
||
successfully create symlinks. This privilege is not typically granted to
|
||
regular users but is available to accounts which can escalate privileges
|
||
to the administrator level. Either obtaining the privilege or running your
|
||
application as an administrator are ways to successfully create symlinks.</p>
|
||
<p><a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a> is raised when the function is called by an unprivileged
|
||
user.</p>
|
||
</div>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix, Windows.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.2: </span>Added support for Windows 6.0 (Vista) symbolic links.</p>
|
||
</div>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3: </span>Added the <em>dir_fd</em> argument, and now allow <em>target_is_directory</em>
|
||
on non-Windows platforms.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>Accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a> for <em>src</em> and <em>dst</em>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.sync">
|
||
<code class="descclassname">os.</code><code class="descname">sync</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#os.sync" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Force write of everything to disk.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.truncate">
|
||
<code class="descclassname">os.</code><code class="descname">truncate</code><span class="sig-paren">(</span><em>path</em>, <em>length</em><span class="sig-paren">)</span><a class="headerlink" href="#os.truncate" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Truncate the file corresponding to <em>path</em>, so that it is at most
|
||
<em>length</em> bytes in size.</p>
|
||
<p>This function can support <a class="reference internal" href="#path-fd"><span class="std std-ref">specifying a file descriptor</span></a>.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix, Windows.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3.</span></p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.5: </span>Added support for Windows</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>Accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.unlink">
|
||
<code class="descclassname">os.</code><code class="descname">unlink</code><span class="sig-paren">(</span><em>path</em>, <em>*</em>, <em>dir_fd=None</em><span class="sig-paren">)</span><a class="headerlink" href="#os.unlink" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Remove (delete) the file <em>path</em>. This function is semantically
|
||
identical to <a class="reference internal" href="#os.remove" title="os.remove"><code class="xref py py-func docutils literal notranslate"><span class="pre">remove()</span></code></a>; the <code class="docutils literal notranslate"><span class="pre">unlink</span></code> name is its
|
||
traditional Unix name. Please see the documentation for
|
||
<a class="reference internal" href="#os.remove" title="os.remove"><code class="xref py py-func docutils literal notranslate"><span class="pre">remove()</span></code></a> for further information.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3: </span>The <em>dir_fd</em> parameter.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>Accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.utime">
|
||
<code class="descclassname">os.</code><code class="descname">utime</code><span class="sig-paren">(</span><em>path</em>, <em>times=None</em>, <em>*</em>, <span class="optional">[</span><em>ns</em>, <span class="optional">]</span><em>dir_fd=None</em>, <em>follow_symlinks=True</em><span class="sig-paren">)</span><a class="headerlink" href="#os.utime" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Set the access and modified times of the file specified by <em>path</em>.</p>
|
||
<p><a class="reference internal" href="#os.utime" title="os.utime"><code class="xref py py-func docutils literal notranslate"><span class="pre">utime()</span></code></a> takes two optional parameters, <em>times</em> and <em>ns</em>.
|
||
These specify the times set on <em>path</em> and are used as follows:</p>
|
||
<ul class="simple">
|
||
<li><p>If <em>ns</em> is specified,
|
||
it must be a 2-tuple of the form <code class="docutils literal notranslate"><span class="pre">(atime_ns,</span> <span class="pre">mtime_ns)</span></code>
|
||
where each member is an int expressing nanoseconds.</p></li>
|
||
<li><p>If <em>times</em> is not <code class="docutils literal notranslate"><span class="pre">None</span></code>,
|
||
it must be a 2-tuple of the form <code class="docutils literal notranslate"><span class="pre">(atime,</span> <span class="pre">mtime)</span></code>
|
||
where each member is an int or float expressing seconds.</p></li>
|
||
<li><p>If <em>times</em> is <code class="docutils literal notranslate"><span class="pre">None</span></code> and <em>ns</em> is unspecified,
|
||
this is equivalent to specifying <code class="docutils literal notranslate"><span class="pre">ns=(atime_ns,</span> <span class="pre">mtime_ns)</span></code>
|
||
where both times are the current time.</p></li>
|
||
</ul>
|
||
<p>It is an error to specify tuples for both <em>times</em> and <em>ns</em>.</p>
|
||
<p>Whether a directory can be given for <em>path</em>
|
||
depends on whether the operating system implements directories as files
|
||
(for example, Windows does not). Note that the exact times you set here may
|
||
not be returned by a subsequent <a class="reference internal" href="#os.stat" title="os.stat"><code class="xref py py-func docutils literal notranslate"><span class="pre">stat()</span></code></a> call, depending on the
|
||
resolution with which your operating system records access and modification
|
||
times; see <a class="reference internal" href="#os.stat" title="os.stat"><code class="xref py py-func docutils literal notranslate"><span class="pre">stat()</span></code></a>. The best way to preserve exact times is to
|
||
use the <em>st_atime_ns</em> and <em>st_mtime_ns</em> fields from the <a class="reference internal" href="#os.stat" title="os.stat"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.stat()</span></code></a>
|
||
result object with the <em>ns</em> parameter to <cite>utime</cite>.</p>
|
||
<p>This function can support <a class="reference internal" href="#path-fd"><span class="std std-ref">specifying a file descriptor</span></a>,
|
||
<a class="reference internal" href="#dir-fd"><span class="std std-ref">paths relative to directory descriptors</span></a> and <a class="reference internal" href="#follow-symlinks"><span class="std std-ref">not
|
||
following symlinks</span></a>.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3: </span>Added support for specifying an open file descriptor for <em>path</em>,
|
||
and the <em>dir_fd</em>, <em>follow_symlinks</em>, and <em>ns</em> parameters.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>Accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.walk">
|
||
<code class="descclassname">os.</code><code class="descname">walk</code><span class="sig-paren">(</span><em>top</em>, <em>topdown=True</em>, <em>onerror=None</em>, <em>followlinks=False</em><span class="sig-paren">)</span><a class="headerlink" href="#os.walk" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p id="index-22">Generate the file names in a directory tree by walking the tree
|
||
either top-down or bottom-up. For each directory in the tree rooted at directory
|
||
<em>top</em> (including <em>top</em> itself), it yields a 3-tuple <code class="docutils literal notranslate"><span class="pre">(dirpath,</span> <span class="pre">dirnames,</span>
|
||
<span class="pre">filenames)</span></code>.</p>
|
||
<p><em>dirpath</em> is a string, the path to the directory. <em>dirnames</em> is a list of the
|
||
names of the subdirectories in <em>dirpath</em> (excluding <code class="docutils literal notranslate"><span class="pre">'.'</span></code> and <code class="docutils literal notranslate"><span class="pre">'..'</span></code>).
|
||
<em>filenames</em> is a list of the names of the non-directory files in <em>dirpath</em>.
|
||
Note that the names in the lists contain no path components. To get a full path
|
||
(which begins with <em>top</em>) to a file or directory in <em>dirpath</em>, do
|
||
<code class="docutils literal notranslate"><span class="pre">os.path.join(dirpath,</span> <span class="pre">name)</span></code>.</p>
|
||
<p>If optional argument <em>topdown</em> is <code class="docutils literal notranslate"><span class="pre">True</span></code> or not specified, the triple for a
|
||
directory is generated before the triples for any of its subdirectories
|
||
(directories are generated top-down). If <em>topdown</em> is <code class="docutils literal notranslate"><span class="pre">False</span></code>, the triple
|
||
for a directory is generated after the triples for all of its subdirectories
|
||
(directories are generated bottom-up). No matter the value of <em>topdown</em>, the
|
||
list of subdirectories is retrieved before the tuples for the directory and
|
||
its subdirectories are generated.</p>
|
||
<p>When <em>topdown</em> is <code class="docutils literal notranslate"><span class="pre">True</span></code>, the caller can modify the <em>dirnames</em> list in-place
|
||
(perhaps using <a class="reference internal" href="../reference/simple_stmts.html#del"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">del</span></code></a> or slice assignment), and <a class="reference internal" href="#os.walk" title="os.walk"><code class="xref py py-func docutils literal notranslate"><span class="pre">walk()</span></code></a> will only
|
||
recurse into the subdirectories whose names remain in <em>dirnames</em>; this can be
|
||
used to prune the search, impose a specific order of visiting, or even to inform
|
||
<a class="reference internal" href="#os.walk" title="os.walk"><code class="xref py py-func docutils literal notranslate"><span class="pre">walk()</span></code></a> about directories the caller creates or renames before it resumes
|
||
<a class="reference internal" href="#os.walk" title="os.walk"><code class="xref py py-func docutils literal notranslate"><span class="pre">walk()</span></code></a> again. Modifying <em>dirnames</em> when <em>topdown</em> is <code class="docutils literal notranslate"><span class="pre">False</span></code> has
|
||
no effect on the behavior of the walk, because in bottom-up mode the directories
|
||
in <em>dirnames</em> are generated before <em>dirpath</em> itself is generated.</p>
|
||
<p>By default, errors from the <a class="reference internal" href="#os.scandir" title="os.scandir"><code class="xref py py-func docutils literal notranslate"><span class="pre">scandir()</span></code></a> call are ignored. If optional
|
||
argument <em>onerror</em> is specified, it should be a function; it will be called with
|
||
one argument, an <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a> instance. It can report the error to continue
|
||
with the walk, or raise the exception to abort the walk. Note that the filename
|
||
is available as the <code class="docutils literal notranslate"><span class="pre">filename</span></code> attribute of the exception object.</p>
|
||
<p>By default, <a class="reference internal" href="#os.walk" title="os.walk"><code class="xref py py-func docutils literal notranslate"><span class="pre">walk()</span></code></a> will not walk down into symbolic links that resolve to
|
||
directories. Set <em>followlinks</em> to <code class="docutils literal notranslate"><span class="pre">True</span></code> to visit directories pointed to by
|
||
symlinks, on systems that support them.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>Be aware that setting <em>followlinks</em> to <code class="docutils literal notranslate"><span class="pre">True</span></code> can lead to infinite
|
||
recursion if a link points to a parent directory of itself. <a class="reference internal" href="#os.walk" title="os.walk"><code class="xref py py-func docutils literal notranslate"><span class="pre">walk()</span></code></a>
|
||
does not keep track of the directories it visited already.</p>
|
||
</div>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>If you pass a relative pathname, don’t change the current working directory
|
||
between resumptions of <a class="reference internal" href="#os.walk" title="os.walk"><code class="xref py py-func docutils literal notranslate"><span class="pre">walk()</span></code></a>. <a class="reference internal" href="#os.walk" title="os.walk"><code class="xref py py-func docutils literal notranslate"><span class="pre">walk()</span></code></a> never changes the current
|
||
directory, and assumes that its caller doesn’t either.</p>
|
||
</div>
|
||
<p>This example displays the number of bytes taken by non-directory files in each
|
||
directory under the starting directory, except that it doesn’t look under any
|
||
CVS subdirectory:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">os</span>
|
||
<span class="kn">from</span> <span class="nn">os.path</span> <span class="k">import</span> <span class="n">join</span><span class="p">,</span> <span class="n">getsize</span>
|
||
<span class="k">for</span> <span class="n">root</span><span class="p">,</span> <span class="n">dirs</span><span class="p">,</span> <span class="n">files</span> <span class="ow">in</span> <span class="n">os</span><span class="o">.</span><span class="n">walk</span><span class="p">(</span><span class="s1">'python/Lib/email'</span><span class="p">):</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="s2">"consumes"</span><span class="p">,</span> <span class="n">end</span><span class="o">=</span><span class="s2">" "</span><span class="p">)</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="nb">sum</span><span class="p">(</span><span class="n">getsize</span><span class="p">(</span><span class="n">join</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="n">name</span><span class="p">))</span> <span class="k">for</span> <span class="n">name</span> <span class="ow">in</span> <span class="n">files</span><span class="p">),</span> <span class="n">end</span><span class="o">=</span><span class="s2">" "</span><span class="p">)</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="s2">"bytes in"</span><span class="p">,</span> <span class="nb">len</span><span class="p">(</span><span class="n">files</span><span class="p">),</span> <span class="s2">"non-directory files"</span><span class="p">)</span>
|
||
<span class="k">if</span> <span class="s1">'CVS'</span> <span class="ow">in</span> <span class="n">dirs</span><span class="p">:</span>
|
||
<span class="n">dirs</span><span class="o">.</span><span class="n">remove</span><span class="p">(</span><span class="s1">'CVS'</span><span class="p">)</span> <span class="c1"># don't visit CVS directories</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>In the next example (simple implementation of <a class="reference internal" href="shutil.html#shutil.rmtree" title="shutil.rmtree"><code class="xref py py-func docutils literal notranslate"><span class="pre">shutil.rmtree()</span></code></a>),
|
||
walking the tree bottom-up is essential, <a class="reference internal" href="#os.rmdir" title="os.rmdir"><code class="xref py py-func docutils literal notranslate"><span class="pre">rmdir()</span></code></a> doesn’t allow
|
||
deleting a directory before the directory is empty:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="c1"># Delete everything reachable from the directory named in "top",</span>
|
||
<span class="c1"># assuming there are no symbolic links.</span>
|
||
<span class="c1"># CAUTION: This is dangerous! For example, if top == '/', it</span>
|
||
<span class="c1"># could delete all your disk files.</span>
|
||
<span class="kn">import</span> <span class="nn">os</span>
|
||
<span class="k">for</span> <span class="n">root</span><span class="p">,</span> <span class="n">dirs</span><span class="p">,</span> <span class="n">files</span> <span class="ow">in</span> <span class="n">os</span><span class="o">.</span><span class="n">walk</span><span class="p">(</span><span class="n">top</span><span class="p">,</span> <span class="n">topdown</span><span class="o">=</span><span class="kc">False</span><span class="p">):</span>
|
||
<span class="k">for</span> <span class="n">name</span> <span class="ow">in</span> <span class="n">files</span><span class="p">:</span>
|
||
<span class="n">os</span><span class="o">.</span><span class="n">remove</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="n">name</span><span class="p">))</span>
|
||
<span class="k">for</span> <span class="n">name</span> <span class="ow">in</span> <span class="n">dirs</span><span class="p">:</span>
|
||
<span class="n">os</span><span class="o">.</span><span class="n">rmdir</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="n">name</span><span class="p">))</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.5: </span>This function now calls <a class="reference internal" href="#os.scandir" title="os.scandir"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.scandir()</span></code></a> instead of <a class="reference internal" href="#os.listdir" title="os.listdir"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.listdir()</span></code></a>,
|
||
making it faster by reducing the number of calls to <a class="reference internal" href="#os.stat" title="os.stat"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.stat()</span></code></a>.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>Accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.fwalk">
|
||
<code class="descclassname">os.</code><code class="descname">fwalk</code><span class="sig-paren">(</span><em>top='.'</em>, <em>topdown=True</em>, <em>onerror=None</em>, <em>*</em>, <em>follow_symlinks=False</em>, <em>dir_fd=None</em><span class="sig-paren">)</span><a class="headerlink" href="#os.fwalk" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p id="index-23">This behaves exactly like <a class="reference internal" href="#os.walk" title="os.walk"><code class="xref py py-func docutils literal notranslate"><span class="pre">walk()</span></code></a>, except that it yields a 4-tuple
|
||
<code class="docutils literal notranslate"><span class="pre">(dirpath,</span> <span class="pre">dirnames,</span> <span class="pre">filenames,</span> <span class="pre">dirfd)</span></code>, and it supports <code class="docutils literal notranslate"><span class="pre">dir_fd</span></code>.</p>
|
||
<p><em>dirpath</em>, <em>dirnames</em> and <em>filenames</em> are identical to <a class="reference internal" href="#os.walk" title="os.walk"><code class="xref py py-func docutils literal notranslate"><span class="pre">walk()</span></code></a> output,
|
||
and <em>dirfd</em> is a file descriptor referring to the directory <em>dirpath</em>.</p>
|
||
<p>This function always supports <a class="reference internal" href="#dir-fd"><span class="std std-ref">paths relative to directory descriptors</span></a> and <a class="reference internal" href="#follow-symlinks"><span class="std std-ref">not following symlinks</span></a>. Note however
|
||
that, unlike other functions, the <a class="reference internal" href="#os.fwalk" title="os.fwalk"><code class="xref py py-func docutils literal notranslate"><span class="pre">fwalk()</span></code></a> default value for
|
||
<em>follow_symlinks</em> is <code class="docutils literal notranslate"><span class="pre">False</span></code>.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>Since <a class="reference internal" href="#os.fwalk" title="os.fwalk"><code class="xref py py-func docutils literal notranslate"><span class="pre">fwalk()</span></code></a> yields file descriptors, those are only valid until
|
||
the next iteration step, so you should duplicate them (e.g. with
|
||
<a class="reference internal" href="#os.dup" title="os.dup"><code class="xref py py-func docutils literal notranslate"><span class="pre">dup()</span></code></a>) if you want to keep them longer.</p>
|
||
</div>
|
||
<p>This example displays the number of bytes taken by non-directory files in each
|
||
directory under the starting directory, except that it doesn’t look under any
|
||
CVS subdirectory:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">os</span>
|
||
<span class="k">for</span> <span class="n">root</span><span class="p">,</span> <span class="n">dirs</span><span class="p">,</span> <span class="n">files</span><span class="p">,</span> <span class="n">rootfd</span> <span class="ow">in</span> <span class="n">os</span><span class="o">.</span><span class="n">fwalk</span><span class="p">(</span><span class="s1">'python/Lib/email'</span><span class="p">):</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="s2">"consumes"</span><span class="p">,</span> <span class="n">end</span><span class="o">=</span><span class="s2">""</span><span class="p">)</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="nb">sum</span><span class="p">([</span><span class="n">os</span><span class="o">.</span><span class="n">stat</span><span class="p">(</span><span class="n">name</span><span class="p">,</span> <span class="n">dir_fd</span><span class="o">=</span><span class="n">rootfd</span><span class="p">)</span><span class="o">.</span><span class="n">st_size</span> <span class="k">for</span> <span class="n">name</span> <span class="ow">in</span> <span class="n">files</span><span class="p">]),</span>
|
||
<span class="n">end</span><span class="o">=</span><span class="s2">""</span><span class="p">)</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="s2">"bytes in"</span><span class="p">,</span> <span class="nb">len</span><span class="p">(</span><span class="n">files</span><span class="p">),</span> <span class="s2">"non-directory files"</span><span class="p">)</span>
|
||
<span class="k">if</span> <span class="s1">'CVS'</span> <span class="ow">in</span> <span class="n">dirs</span><span class="p">:</span>
|
||
<span class="n">dirs</span><span class="o">.</span><span class="n">remove</span><span class="p">(</span><span class="s1">'CVS'</span><span class="p">)</span> <span class="c1"># don't visit CVS directories</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>In the next example, walking the tree bottom-up is essential:
|
||
<a class="reference internal" href="#os.rmdir" title="os.rmdir"><code class="xref py py-func docutils literal notranslate"><span class="pre">rmdir()</span></code></a> doesn’t allow deleting a directory before the directory is
|
||
empty:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="c1"># Delete everything reachable from the directory named in "top",</span>
|
||
<span class="c1"># assuming there are no symbolic links.</span>
|
||
<span class="c1"># CAUTION: This is dangerous! For example, if top == '/', it</span>
|
||
<span class="c1"># could delete all your disk files.</span>
|
||
<span class="kn">import</span> <span class="nn">os</span>
|
||
<span class="k">for</span> <span class="n">root</span><span class="p">,</span> <span class="n">dirs</span><span class="p">,</span> <span class="n">files</span><span class="p">,</span> <span class="n">rootfd</span> <span class="ow">in</span> <span class="n">os</span><span class="o">.</span><span class="n">fwalk</span><span class="p">(</span><span class="n">top</span><span class="p">,</span> <span class="n">topdown</span><span class="o">=</span><span class="kc">False</span><span class="p">):</span>
|
||
<span class="k">for</span> <span class="n">name</span> <span class="ow">in</span> <span class="n">files</span><span class="p">:</span>
|
||
<span class="n">os</span><span class="o">.</span><span class="n">unlink</span><span class="p">(</span><span class="n">name</span><span class="p">,</span> <span class="n">dir_fd</span><span class="o">=</span><span class="n">rootfd</span><span class="p">)</span>
|
||
<span class="k">for</span> <span class="n">name</span> <span class="ow">in</span> <span class="n">dirs</span><span class="p">:</span>
|
||
<span class="n">os</span><span class="o">.</span><span class="n">rmdir</span><span class="p">(</span><span class="n">name</span><span class="p">,</span> <span class="n">dir_fd</span><span class="o">=</span><span class="n">rootfd</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3.</span></p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>Accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.7: </span>Added support for <a class="reference internal" href="stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> paths.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<div class="section" id="linux-extended-attributes">
|
||
<h3>Linux extended attributes<a class="headerlink" href="#linux-extended-attributes" title="Permalink to this headline">¶</a></h3>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3.</span></p>
|
||
</div>
|
||
<p>These functions are all available on Linux only.</p>
|
||
<dl class="function">
|
||
<dt id="os.getxattr">
|
||
<code class="descclassname">os.</code><code class="descname">getxattr</code><span class="sig-paren">(</span><em>path</em>, <em>attribute</em>, <em>*</em>, <em>follow_symlinks=True</em><span class="sig-paren">)</span><a class="headerlink" href="#os.getxattr" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return the value of the extended filesystem attribute <em>attribute</em> for
|
||
<em>path</em>. <em>attribute</em> can be bytes or str (directly or indirectly through the
|
||
<a class="reference internal" href="#os.PathLike" title="os.PathLike"><code class="xref py py-class docutils literal notranslate"><span class="pre">PathLike</span></code></a> interface). If it is str, it is encoded with the filesystem
|
||
encoding.</p>
|
||
<p>This function can support <a class="reference internal" href="#path-fd"><span class="std std-ref">specifying a file descriptor</span></a> and
|
||
<a class="reference internal" href="#follow-symlinks"><span class="std std-ref">not following symlinks</span></a>.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>Accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a> for <em>path</em> and <em>attribute</em>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.listxattr">
|
||
<code class="descclassname">os.</code><code class="descname">listxattr</code><span class="sig-paren">(</span><em>path=None</em>, <em>*</em>, <em>follow_symlinks=True</em><span class="sig-paren">)</span><a class="headerlink" href="#os.listxattr" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return a list of the extended filesystem attributes on <em>path</em>. The
|
||
attributes in the list are represented as strings decoded with the filesystem
|
||
encoding. If <em>path</em> is <code class="docutils literal notranslate"><span class="pre">None</span></code>, <a class="reference internal" href="#os.listxattr" title="os.listxattr"><code class="xref py py-func docutils literal notranslate"><span class="pre">listxattr()</span></code></a> will examine the current
|
||
directory.</p>
|
||
<p>This function can support <a class="reference internal" href="#path-fd"><span class="std std-ref">specifying a file descriptor</span></a> and
|
||
<a class="reference internal" href="#follow-symlinks"><span class="std std-ref">not following symlinks</span></a>.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>Accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.removexattr">
|
||
<code class="descclassname">os.</code><code class="descname">removexattr</code><span class="sig-paren">(</span><em>path</em>, <em>attribute</em>, <em>*</em>, <em>follow_symlinks=True</em><span class="sig-paren">)</span><a class="headerlink" href="#os.removexattr" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Removes the extended filesystem attribute <em>attribute</em> from <em>path</em>.
|
||
<em>attribute</em> should be bytes or str (directly or indirectly through the
|
||
<a class="reference internal" href="#os.PathLike" title="os.PathLike"><code class="xref py py-class docutils literal notranslate"><span class="pre">PathLike</span></code></a> interface). If it is a string, it is encoded
|
||
with the filesystem encoding.</p>
|
||
<p>This function can support <a class="reference internal" href="#path-fd"><span class="std std-ref">specifying a file descriptor</span></a> and
|
||
<a class="reference internal" href="#follow-symlinks"><span class="std std-ref">not following symlinks</span></a>.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>Accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a> for <em>path</em> and <em>attribute</em>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.setxattr">
|
||
<code class="descclassname">os.</code><code class="descname">setxattr</code><span class="sig-paren">(</span><em>path</em>, <em>attribute</em>, <em>value</em>, <em>flags=0</em>, <em>*</em>, <em>follow_symlinks=True</em><span class="sig-paren">)</span><a class="headerlink" href="#os.setxattr" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Set the extended filesystem attribute <em>attribute</em> on <em>path</em> to <em>value</em>.
|
||
<em>attribute</em> must be a bytes or str with no embedded NULs (directly or
|
||
indirectly through the <a class="reference internal" href="#os.PathLike" title="os.PathLike"><code class="xref py py-class docutils literal notranslate"><span class="pre">PathLike</span></code></a> interface). If it is a str,
|
||
it is encoded with the filesystem encoding. <em>flags</em> may be
|
||
<a class="reference internal" href="#os.XATTR_REPLACE" title="os.XATTR_REPLACE"><code class="xref py py-data docutils literal notranslate"><span class="pre">XATTR_REPLACE</span></code></a> or <a class="reference internal" href="#os.XATTR_CREATE" title="os.XATTR_CREATE"><code class="xref py py-data docutils literal notranslate"><span class="pre">XATTR_CREATE</span></code></a>. If <a class="reference internal" href="#os.XATTR_REPLACE" title="os.XATTR_REPLACE"><code class="xref py py-data docutils literal notranslate"><span class="pre">XATTR_REPLACE</span></code></a> is
|
||
given and the attribute does not exist, <code class="docutils literal notranslate"><span class="pre">EEXISTS</span></code> will be raised.
|
||
If <a class="reference internal" href="#os.XATTR_CREATE" title="os.XATTR_CREATE"><code class="xref py py-data docutils literal notranslate"><span class="pre">XATTR_CREATE</span></code></a> is given and the attribute already exists, the
|
||
attribute will not be created and <code class="docutils literal notranslate"><span class="pre">ENODATA</span></code> will be raised.</p>
|
||
<p>This function can support <a class="reference internal" href="#path-fd"><span class="std std-ref">specifying a file descriptor</span></a> and
|
||
<a class="reference internal" href="#follow-symlinks"><span class="std std-ref">not following symlinks</span></a>.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>A bug in Linux kernel versions less than 2.6.39 caused the flags argument
|
||
to be ignored on some filesystems.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>Accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a> for <em>path</em> and <em>attribute</em>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.XATTR_SIZE_MAX">
|
||
<code class="descclassname">os.</code><code class="descname">XATTR_SIZE_MAX</code><a class="headerlink" href="#os.XATTR_SIZE_MAX" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>The maximum size the value of an extended attribute can be. Currently, this
|
||
is 64 KiB on Linux.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.XATTR_CREATE">
|
||
<code class="descclassname">os.</code><code class="descname">XATTR_CREATE</code><a class="headerlink" href="#os.XATTR_CREATE" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>This is a possible value for the flags argument in <a class="reference internal" href="#os.setxattr" title="os.setxattr"><code class="xref py py-func docutils literal notranslate"><span class="pre">setxattr()</span></code></a>. It
|
||
indicates the operation must create an attribute.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.XATTR_REPLACE">
|
||
<code class="descclassname">os.</code><code class="descname">XATTR_REPLACE</code><a class="headerlink" href="#os.XATTR_REPLACE" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>This is a possible value for the flags argument in <a class="reference internal" href="#os.setxattr" title="os.setxattr"><code class="xref py py-func docutils literal notranslate"><span class="pre">setxattr()</span></code></a>. It
|
||
indicates the operation must replace an existing attribute.</p>
|
||
</dd></dl>
|
||
|
||
</div>
|
||
</div>
|
||
<div class="section" id="process-management">
|
||
<span id="os-process"></span><h2>Process Management<a class="headerlink" href="#process-management" title="Permalink to this headline">¶</a></h2>
|
||
<p>These functions may be used to create and manage processes.</p>
|
||
<p>The various <a class="reference internal" href="#os.execl" title="os.execl"><code class="xref py py-func docutils literal notranslate"><span class="pre">exec*</span></code></a> functions take a list of arguments for the new
|
||
program loaded into the process. In each case, the first of these arguments is
|
||
passed to the new program as its own name rather than as an argument a user may
|
||
have typed on a command line. For the C programmer, this is the <code class="docutils literal notranslate"><span class="pre">argv[0]</span></code>
|
||
passed to a program’s <code class="xref c c-func docutils literal notranslate"><span class="pre">main()</span></code>. For example, <code class="docutils literal notranslate"><span class="pre">os.execv('/bin/echo',</span>
|
||
<span class="pre">['foo',</span> <span class="pre">'bar'])</span></code> will only print <code class="docutils literal notranslate"><span class="pre">bar</span></code> on standard output; <code class="docutils literal notranslate"><span class="pre">foo</span></code> will seem
|
||
to be ignored.</p>
|
||
<dl class="function">
|
||
<dt id="os.abort">
|
||
<code class="descclassname">os.</code><code class="descname">abort</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#os.abort" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Generate a <code class="xref py py-const docutils literal notranslate"><span class="pre">SIGABRT</span></code> signal to the current process. On Unix, the default
|
||
behavior is to produce a core dump; on Windows, the process immediately returns
|
||
an exit code of <code class="docutils literal notranslate"><span class="pre">3</span></code>. Be aware that calling this function will not call the
|
||
Python signal handler registered for <code class="xref py py-const docutils literal notranslate"><span class="pre">SIGABRT</span></code> with
|
||
<a class="reference internal" href="signal.html#signal.signal" title="signal.signal"><code class="xref py py-func docutils literal notranslate"><span class="pre">signal.signal()</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.execl">
|
||
<code class="descclassname">os.</code><code class="descname">execl</code><span class="sig-paren">(</span><em>path</em>, <em>arg0</em>, <em>arg1</em>, <em>...</em><span class="sig-paren">)</span><a class="headerlink" href="#os.execl" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.execle">
|
||
<code class="descclassname">os.</code><code class="descname">execle</code><span class="sig-paren">(</span><em>path</em>, <em>arg0</em>, <em>arg1</em>, <em>...</em>, <em>env</em><span class="sig-paren">)</span><a class="headerlink" href="#os.execle" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.execlp">
|
||
<code class="descclassname">os.</code><code class="descname">execlp</code><span class="sig-paren">(</span><em>file</em>, <em>arg0</em>, <em>arg1</em>, <em>...</em><span class="sig-paren">)</span><a class="headerlink" href="#os.execlp" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.execlpe">
|
||
<code class="descclassname">os.</code><code class="descname">execlpe</code><span class="sig-paren">(</span><em>file</em>, <em>arg0</em>, <em>arg1</em>, <em>...</em>, <em>env</em><span class="sig-paren">)</span><a class="headerlink" href="#os.execlpe" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.execv">
|
||
<code class="descclassname">os.</code><code class="descname">execv</code><span class="sig-paren">(</span><em>path</em>, <em>args</em><span class="sig-paren">)</span><a class="headerlink" href="#os.execv" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.execve">
|
||
<code class="descclassname">os.</code><code class="descname">execve</code><span class="sig-paren">(</span><em>path</em>, <em>args</em>, <em>env</em><span class="sig-paren">)</span><a class="headerlink" href="#os.execve" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.execvp">
|
||
<code class="descclassname">os.</code><code class="descname">execvp</code><span class="sig-paren">(</span><em>file</em>, <em>args</em><span class="sig-paren">)</span><a class="headerlink" href="#os.execvp" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.execvpe">
|
||
<code class="descclassname">os.</code><code class="descname">execvpe</code><span class="sig-paren">(</span><em>file</em>, <em>args</em>, <em>env</em><span class="sig-paren">)</span><a class="headerlink" href="#os.execvpe" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>These functions all execute a new program, replacing the current process; they
|
||
do not return. On Unix, the new executable is loaded into the current process,
|
||
and will have the same process id as the caller. Errors will be reported as
|
||
<a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a> exceptions.</p>
|
||
<p>The current process is replaced immediately. Open file objects and
|
||
descriptors are not flushed, so if there may be data buffered
|
||
on these open files, you should flush them using
|
||
<code class="xref py py-func docutils literal notranslate"><span class="pre">sys.stdout.flush()</span></code> or <a class="reference internal" href="#os.fsync" title="os.fsync"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.fsync()</span></code></a> before calling an
|
||
<a class="reference internal" href="#os.execl" title="os.execl"><code class="xref py py-func docutils literal notranslate"><span class="pre">exec*</span></code></a> function.</p>
|
||
<p>The “l” and “v” variants of the <a class="reference internal" href="#os.execl" title="os.execl"><code class="xref py py-func docutils literal notranslate"><span class="pre">exec*</span></code></a> functions differ in how
|
||
command-line arguments are passed. The “l” variants are perhaps the easiest
|
||
to work with if the number of parameters is fixed when the code is written; the
|
||
individual parameters simply become additional parameters to the <code class="xref py py-func docutils literal notranslate"><span class="pre">execl*()</span></code>
|
||
functions. The “v” variants are good when the number of parameters is
|
||
variable, with the arguments being passed in a list or tuple as the <em>args</em>
|
||
parameter. In either case, the arguments to the child process should start with
|
||
the name of the command being run, but this is not enforced.</p>
|
||
<p>The variants which include a “p” near the end (<a class="reference internal" href="#os.execlp" title="os.execlp"><code class="xref py py-func docutils literal notranslate"><span class="pre">execlp()</span></code></a>,
|
||
<a class="reference internal" href="#os.execlpe" title="os.execlpe"><code class="xref py py-func docutils literal notranslate"><span class="pre">execlpe()</span></code></a>, <a class="reference internal" href="#os.execvp" title="os.execvp"><code class="xref py py-func docutils literal notranslate"><span class="pre">execvp()</span></code></a>, and <a class="reference internal" href="#os.execvpe" title="os.execvpe"><code class="xref py py-func docutils literal notranslate"><span class="pre">execvpe()</span></code></a>) will use the
|
||
<span class="target" id="index-24"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PATH</span></code> environment variable to locate the program <em>file</em>. When the
|
||
environment is being replaced (using one of the <a class="reference internal" href="#os.execl" title="os.execl"><code class="xref py py-func docutils literal notranslate"><span class="pre">exec*e</span></code></a> variants,
|
||
discussed in the next paragraph), the new environment is used as the source of
|
||
the <span class="target" id="index-25"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PATH</span></code> variable. The other variants, <a class="reference internal" href="#os.execl" title="os.execl"><code class="xref py py-func docutils literal notranslate"><span class="pre">execl()</span></code></a>, <a class="reference internal" href="#os.execle" title="os.execle"><code class="xref py py-func docutils literal notranslate"><span class="pre">execle()</span></code></a>,
|
||
<a class="reference internal" href="#os.execv" title="os.execv"><code class="xref py py-func docutils literal notranslate"><span class="pre">execv()</span></code></a>, and <a class="reference internal" href="#os.execve" title="os.execve"><code class="xref py py-func docutils literal notranslate"><span class="pre">execve()</span></code></a>, will not use the <span class="target" id="index-26"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PATH</span></code> variable to
|
||
locate the executable; <em>path</em> must contain an appropriate absolute or relative
|
||
path.</p>
|
||
<p>For <a class="reference internal" href="#os.execle" title="os.execle"><code class="xref py py-func docutils literal notranslate"><span class="pre">execle()</span></code></a>, <a class="reference internal" href="#os.execlpe" title="os.execlpe"><code class="xref py py-func docutils literal notranslate"><span class="pre">execlpe()</span></code></a>, <a class="reference internal" href="#os.execve" title="os.execve"><code class="xref py py-func docutils literal notranslate"><span class="pre">execve()</span></code></a>, and <a class="reference internal" href="#os.execvpe" title="os.execvpe"><code class="xref py py-func docutils literal notranslate"><span class="pre">execvpe()</span></code></a> (note
|
||
that these all end in “e”), the <em>env</em> parameter must be a mapping which is
|
||
used to define the environment variables for the new process (these are used
|
||
instead of the current process’ environment); the functions <a class="reference internal" href="#os.execl" title="os.execl"><code class="xref py py-func docutils literal notranslate"><span class="pre">execl()</span></code></a>,
|
||
<a class="reference internal" href="#os.execlp" title="os.execlp"><code class="xref py py-func docutils literal notranslate"><span class="pre">execlp()</span></code></a>, <a class="reference internal" href="#os.execv" title="os.execv"><code class="xref py py-func docutils literal notranslate"><span class="pre">execv()</span></code></a>, and <a class="reference internal" href="#os.execvp" title="os.execvp"><code class="xref py py-func docutils literal notranslate"><span class="pre">execvp()</span></code></a> all cause the new process to
|
||
inherit the environment of the current process.</p>
|
||
<p>For <a class="reference internal" href="#os.execve" title="os.execve"><code class="xref py py-func docutils literal notranslate"><span class="pre">execve()</span></code></a> on some platforms, <em>path</em> may also be specified as an open
|
||
file descriptor. This functionality may not be supported on your platform;
|
||
you can check whether or not it is available using <a class="reference internal" href="#os.supports_fd" title="os.supports_fd"><code class="xref py py-data docutils literal notranslate"><span class="pre">os.supports_fd</span></code></a>.
|
||
If it is unavailable, using it will raise a <a class="reference internal" href="exceptions.html#NotImplementedError" title="NotImplementedError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">NotImplementedError</span></code></a>.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix, Windows.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3: </span>Added support for specifying an open file descriptor for <em>path</em>
|
||
for <a class="reference internal" href="#os.execve" title="os.execve"><code class="xref py py-func docutils literal notranslate"><span class="pre">execve()</span></code></a>.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>Accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os._exit">
|
||
<code class="descclassname">os.</code><code class="descname">_exit</code><span class="sig-paren">(</span><em>n</em><span class="sig-paren">)</span><a class="headerlink" href="#os._exit" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Exit the process with status <em>n</em>, without calling cleanup handlers, flushing
|
||
stdio buffers, etc.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>The standard way to exit is <code class="docutils literal notranslate"><span class="pre">sys.exit(n)</span></code>. <a class="reference internal" href="#os._exit" title="os._exit"><code class="xref py py-func docutils literal notranslate"><span class="pre">_exit()</span></code></a> should
|
||
normally only be used in the child process after a <a class="reference internal" href="#os.fork" title="os.fork"><code class="xref py py-func docutils literal notranslate"><span class="pre">fork()</span></code></a>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<p>The following exit codes are defined and can be used with <a class="reference internal" href="#os._exit" title="os._exit"><code class="xref py py-func docutils literal notranslate"><span class="pre">_exit()</span></code></a>,
|
||
although they are not required. These are typically used for system programs
|
||
written in Python, such as a mail server’s external command delivery program.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>Some of these may not be available on all Unix platforms, since there is some
|
||
variation. These constants are defined where they are defined by the underlying
|
||
platform.</p>
|
||
</div>
|
||
<dl class="data">
|
||
<dt id="os.EX_OK">
|
||
<code class="descclassname">os.</code><code class="descname">EX_OK</code><a class="headerlink" href="#os.EX_OK" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Exit code that means no error occurred.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.EX_USAGE">
|
||
<code class="descclassname">os.</code><code class="descname">EX_USAGE</code><a class="headerlink" href="#os.EX_USAGE" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Exit code that means the command was used incorrectly, such as when the wrong
|
||
number of arguments are given.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.EX_DATAERR">
|
||
<code class="descclassname">os.</code><code class="descname">EX_DATAERR</code><a class="headerlink" href="#os.EX_DATAERR" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Exit code that means the input data was incorrect.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.EX_NOINPUT">
|
||
<code class="descclassname">os.</code><code class="descname">EX_NOINPUT</code><a class="headerlink" href="#os.EX_NOINPUT" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Exit code that means an input file did not exist or was not readable.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.EX_NOUSER">
|
||
<code class="descclassname">os.</code><code class="descname">EX_NOUSER</code><a class="headerlink" href="#os.EX_NOUSER" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Exit code that means a specified user did not exist.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.EX_NOHOST">
|
||
<code class="descclassname">os.</code><code class="descname">EX_NOHOST</code><a class="headerlink" href="#os.EX_NOHOST" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Exit code that means a specified host did not exist.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.EX_UNAVAILABLE">
|
||
<code class="descclassname">os.</code><code class="descname">EX_UNAVAILABLE</code><a class="headerlink" href="#os.EX_UNAVAILABLE" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Exit code that means that a required service is unavailable.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.EX_SOFTWARE">
|
||
<code class="descclassname">os.</code><code class="descname">EX_SOFTWARE</code><a class="headerlink" href="#os.EX_SOFTWARE" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Exit code that means an internal software error was detected.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.EX_OSERR">
|
||
<code class="descclassname">os.</code><code class="descname">EX_OSERR</code><a class="headerlink" href="#os.EX_OSERR" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Exit code that means an operating system error was detected, such as the
|
||
inability to fork or create a pipe.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.EX_OSFILE">
|
||
<code class="descclassname">os.</code><code class="descname">EX_OSFILE</code><a class="headerlink" href="#os.EX_OSFILE" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Exit code that means some system file did not exist, could not be opened, or had
|
||
some other kind of error.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.EX_CANTCREAT">
|
||
<code class="descclassname">os.</code><code class="descname">EX_CANTCREAT</code><a class="headerlink" href="#os.EX_CANTCREAT" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Exit code that means a user specified output file could not be created.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.EX_IOERR">
|
||
<code class="descclassname">os.</code><code class="descname">EX_IOERR</code><a class="headerlink" href="#os.EX_IOERR" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Exit code that means that an error occurred while doing I/O on some file.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.EX_TEMPFAIL">
|
||
<code class="descclassname">os.</code><code class="descname">EX_TEMPFAIL</code><a class="headerlink" href="#os.EX_TEMPFAIL" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Exit code that means a temporary failure occurred. This indicates something
|
||
that may not really be an error, such as a network connection that couldn’t be
|
||
made during a retryable operation.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.EX_PROTOCOL">
|
||
<code class="descclassname">os.</code><code class="descname">EX_PROTOCOL</code><a class="headerlink" href="#os.EX_PROTOCOL" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Exit code that means that a protocol exchange was illegal, invalid, or not
|
||
understood.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.EX_NOPERM">
|
||
<code class="descclassname">os.</code><code class="descname">EX_NOPERM</code><a class="headerlink" href="#os.EX_NOPERM" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Exit code that means that there were insufficient permissions to perform the
|
||
operation (but not intended for file system problems).</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.EX_CONFIG">
|
||
<code class="descclassname">os.</code><code class="descname">EX_CONFIG</code><a class="headerlink" href="#os.EX_CONFIG" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Exit code that means that some kind of configuration error occurred.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.EX_NOTFOUND">
|
||
<code class="descclassname">os.</code><code class="descname">EX_NOTFOUND</code><a class="headerlink" href="#os.EX_NOTFOUND" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Exit code that means something like “an entry was not found”.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.fork">
|
||
<code class="descclassname">os.</code><code class="descname">fork</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#os.fork" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Fork a child process. Return <code class="docutils literal notranslate"><span class="pre">0</span></code> in the child and the child’s process id in the
|
||
parent. If an error occurs <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a> is raised.</p>
|
||
<p>Note that some platforms including FreeBSD <= 6.3 and Cygwin have
|
||
known issues when using fork() from a thread.</p>
|
||
<div class="admonition warning">
|
||
<p class="admonition-title">Warning</p>
|
||
<p>See <a class="reference internal" href="ssl.html#module-ssl" title="ssl: TLS/SSL wrapper for socket objects"><code class="xref py py-mod docutils literal notranslate"><span class="pre">ssl</span></code></a> for applications that use the SSL module with fork().</p>
|
||
</div>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.forkpty">
|
||
<code class="descclassname">os.</code><code class="descname">forkpty</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#os.forkpty" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Fork a child process, using a new pseudo-terminal as the child’s controlling
|
||
terminal. Return a pair of <code class="docutils literal notranslate"><span class="pre">(pid,</span> <span class="pre">fd)</span></code>, where <em>pid</em> is <code class="docutils literal notranslate"><span class="pre">0</span></code> in the child, the
|
||
new child’s process id in the parent, and <em>fd</em> is the file descriptor of the
|
||
master end of the pseudo-terminal. For a more portable approach, use the
|
||
<a class="reference internal" href="pty.html#module-pty" title="pty: Pseudo-Terminal Handling for Linux. (Linux)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">pty</span></code></a> module. If an error occurs <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a> is raised.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: some flavors of Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.kill">
|
||
<code class="descclassname">os.</code><code class="descname">kill</code><span class="sig-paren">(</span><em>pid</em>, <em>sig</em><span class="sig-paren">)</span><a class="headerlink" href="#os.kill" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p id="index-27">Send signal <em>sig</em> to the process <em>pid</em>. Constants for the specific signals
|
||
available on the host platform are defined in the <a class="reference internal" href="signal.html#module-signal" title="signal: Set handlers for asynchronous events."><code class="xref py py-mod docutils literal notranslate"><span class="pre">signal</span></code></a> module.</p>
|
||
<p>Windows: The <a class="reference internal" href="signal.html#signal.CTRL_C_EVENT" title="signal.CTRL_C_EVENT"><code class="xref py py-data docutils literal notranslate"><span class="pre">signal.CTRL_C_EVENT</span></code></a> and
|
||
<a class="reference internal" href="signal.html#signal.CTRL_BREAK_EVENT" title="signal.CTRL_BREAK_EVENT"><code class="xref py py-data docutils literal notranslate"><span class="pre">signal.CTRL_BREAK_EVENT</span></code></a> signals are special signals which can
|
||
only be sent to console processes which share a common console window,
|
||
e.g., some subprocesses. Any other value for <em>sig</em> will cause the process
|
||
to be unconditionally killed by the TerminateProcess API, and the exit code
|
||
will be set to <em>sig</em>. The Windows version of <a class="reference internal" href="#os.kill" title="os.kill"><code class="xref py py-func docutils literal notranslate"><span class="pre">kill()</span></code></a> additionally takes
|
||
process handles to be killed.</p>
|
||
<p>See also <a class="reference internal" href="signal.html#signal.pthread_kill" title="signal.pthread_kill"><code class="xref py py-func docutils literal notranslate"><span class="pre">signal.pthread_kill()</span></code></a>.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.2: </span>Windows support.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.killpg">
|
||
<code class="descclassname">os.</code><code class="descname">killpg</code><span class="sig-paren">(</span><em>pgid</em>, <em>sig</em><span class="sig-paren">)</span><a class="headerlink" href="#os.killpg" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p id="index-28">Send the signal <em>sig</em> to the process group <em>pgid</em>.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.nice">
|
||
<code class="descclassname">os.</code><code class="descname">nice</code><span class="sig-paren">(</span><em>increment</em><span class="sig-paren">)</span><a class="headerlink" href="#os.nice" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Add <em>increment</em> to the process’s “niceness”. Return the new niceness.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.plock">
|
||
<code class="descclassname">os.</code><code class="descname">plock</code><span class="sig-paren">(</span><em>op</em><span class="sig-paren">)</span><a class="headerlink" href="#os.plock" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Lock program segments into memory. The value of <em>op</em> (defined in
|
||
<code class="docutils literal notranslate"><span class="pre"><sys/lock.h></span></code>) determines which segments are locked.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.popen">
|
||
<code class="descclassname">os.</code><code class="descname">popen</code><span class="sig-paren">(</span><em>cmd</em>, <em>mode='r'</em>, <em>buffering=-1</em><span class="sig-paren">)</span><a class="headerlink" href="#os.popen" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Open a pipe to or from command <em>cmd</em>.
|
||
The return value is an open file object
|
||
connected to the pipe, which can be read or written depending on whether <em>mode</em>
|
||
is <code class="docutils literal notranslate"><span class="pre">'r'</span></code> (default) or <code class="docutils literal notranslate"><span class="pre">'w'</span></code>. The <em>buffering</em> argument has the same meaning as
|
||
the corresponding argument to the built-in <a class="reference internal" href="functions.html#open" title="open"><code class="xref py py-func docutils literal notranslate"><span class="pre">open()</span></code></a> function. The
|
||
returned file object reads or writes text strings rather than bytes.</p>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">close</span></code> method returns <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal notranslate"><span class="pre">None</span></code></a> if the subprocess exited
|
||
successfully, or the subprocess’s return code if there was an
|
||
error. On POSIX systems, if the return code is positive it
|
||
represents the return value of the process left-shifted by one
|
||
byte. If the return code is negative, the process was terminated
|
||
by the signal given by the negated value of the return code. (For
|
||
example, the return value might be <code class="docutils literal notranslate"><span class="pre">-</span> <span class="pre">signal.SIGKILL</span></code> if the
|
||
subprocess was killed.) On Windows systems, the return value
|
||
contains the signed integer return code from the child process.</p>
|
||
<p>This is implemented using <a class="reference internal" href="subprocess.html#subprocess.Popen" title="subprocess.Popen"><code class="xref py py-class docutils literal notranslate"><span class="pre">subprocess.Popen</span></code></a>; see that class’s
|
||
documentation for more powerful ways to manage and communicate with
|
||
subprocesses.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.register_at_fork">
|
||
<code class="descclassname">os.</code><code class="descname">register_at_fork</code><span class="sig-paren">(</span><em>*</em>, <em>before=None</em>, <em>after_in_parent=None</em>, <em>after_in_child=None</em><span class="sig-paren">)</span><a class="headerlink" href="#os.register_at_fork" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Register callables to be executed when a new child process is forked
|
||
using <a class="reference internal" href="#os.fork" title="os.fork"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.fork()</span></code></a> or similar process cloning APIs.
|
||
The parameters are optional and keyword-only.
|
||
Each specifies a different call point.</p>
|
||
<ul class="simple">
|
||
<li><p><em>before</em> is a function called before forking a child process.</p></li>
|
||
<li><p><em>after_in_parent</em> is a function called from the parent process
|
||
after forking a child process.</p></li>
|
||
<li><p><em>after_in_child</em> is a function called from the child process.</p></li>
|
||
</ul>
|
||
<p>These calls are only made if control is expected to return to the
|
||
Python interpreter. A typical <a class="reference internal" href="subprocess.html#module-subprocess" title="subprocess: Subprocess management."><code class="xref py py-mod docutils literal notranslate"><span class="pre">subprocess</span></code></a> launch will not
|
||
trigger them as the child is not going to re-enter the interpreter.</p>
|
||
<p>Functions registered for execution before forking are called in
|
||
reverse registration order. Functions registered for execution
|
||
after forking (either in the parent or in the child) are called
|
||
in registration order.</p>
|
||
<p>Note that <code class="xref c c-func docutils literal notranslate"><span class="pre">fork()</span></code> calls made by third-party C code may not
|
||
call those functions, unless it explicitly calls <a class="reference internal" href="../c-api/sys.html#c.PyOS_BeforeFork" title="PyOS_BeforeFork"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyOS_BeforeFork()</span></code></a>,
|
||
<a class="reference internal" href="../c-api/sys.html#c.PyOS_AfterFork_Parent" title="PyOS_AfterFork_Parent"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyOS_AfterFork_Parent()</span></code></a> and <a class="reference internal" href="../c-api/sys.html#c.PyOS_AfterFork_Child" title="PyOS_AfterFork_Child"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyOS_AfterFork_Child()</span></code></a>.</p>
|
||
<p>There is no way to unregister a function.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.7.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.spawnl">
|
||
<code class="descclassname">os.</code><code class="descname">spawnl</code><span class="sig-paren">(</span><em>mode</em>, <em>path</em>, <em>...</em><span class="sig-paren">)</span><a class="headerlink" href="#os.spawnl" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.spawnle">
|
||
<code class="descclassname">os.</code><code class="descname">spawnle</code><span class="sig-paren">(</span><em>mode</em>, <em>path</em>, <em>...</em>, <em>env</em><span class="sig-paren">)</span><a class="headerlink" href="#os.spawnle" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.spawnlp">
|
||
<code class="descclassname">os.</code><code class="descname">spawnlp</code><span class="sig-paren">(</span><em>mode</em>, <em>file</em>, <em>...</em><span class="sig-paren">)</span><a class="headerlink" href="#os.spawnlp" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.spawnlpe">
|
||
<code class="descclassname">os.</code><code class="descname">spawnlpe</code><span class="sig-paren">(</span><em>mode</em>, <em>file</em>, <em>...</em>, <em>env</em><span class="sig-paren">)</span><a class="headerlink" href="#os.spawnlpe" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.spawnv">
|
||
<code class="descclassname">os.</code><code class="descname">spawnv</code><span class="sig-paren">(</span><em>mode</em>, <em>path</em>, <em>args</em><span class="sig-paren">)</span><a class="headerlink" href="#os.spawnv" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.spawnve">
|
||
<code class="descclassname">os.</code><code class="descname">spawnve</code><span class="sig-paren">(</span><em>mode</em>, <em>path</em>, <em>args</em>, <em>env</em><span class="sig-paren">)</span><a class="headerlink" href="#os.spawnve" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.spawnvp">
|
||
<code class="descclassname">os.</code><code class="descname">spawnvp</code><span class="sig-paren">(</span><em>mode</em>, <em>file</em>, <em>args</em><span class="sig-paren">)</span><a class="headerlink" href="#os.spawnvp" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.spawnvpe">
|
||
<code class="descclassname">os.</code><code class="descname">spawnvpe</code><span class="sig-paren">(</span><em>mode</em>, <em>file</em>, <em>args</em>, <em>env</em><span class="sig-paren">)</span><a class="headerlink" href="#os.spawnvpe" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Execute the program <em>path</em> in a new process.</p>
|
||
<p>(Note that the <a class="reference internal" href="subprocess.html#module-subprocess" title="subprocess: Subprocess management."><code class="xref py py-mod docutils literal notranslate"><span class="pre">subprocess</span></code></a> module provides more powerful facilities for
|
||
spawning new processes and retrieving their results; using that module is
|
||
preferable to using these functions. Check especially the
|
||
<a class="reference internal" href="subprocess.html#subprocess-replacements"><span class="std std-ref">Replacing Older Functions with the subprocess Module</span></a> section.)</p>
|
||
<p>If <em>mode</em> is <a class="reference internal" href="#os.P_NOWAIT" title="os.P_NOWAIT"><code class="xref py py-const docutils literal notranslate"><span class="pre">P_NOWAIT</span></code></a>, this function returns the process id of the new
|
||
process; if <em>mode</em> is <a class="reference internal" href="#os.P_WAIT" title="os.P_WAIT"><code class="xref py py-const docutils literal notranslate"><span class="pre">P_WAIT</span></code></a>, returns the process’s exit code if it
|
||
exits normally, or <code class="docutils literal notranslate"><span class="pre">-signal</span></code>, where <em>signal</em> is the signal that killed the
|
||
process. On Windows, the process id will actually be the process handle, so can
|
||
be used with the <a class="reference internal" href="#os.waitpid" title="os.waitpid"><code class="xref py py-func docutils literal notranslate"><span class="pre">waitpid()</span></code></a> function.</p>
|
||
<p>The “l” and “v” variants of the <a class="reference internal" href="#os.spawnl" title="os.spawnl"><code class="xref py py-func docutils literal notranslate"><span class="pre">spawn*</span></code></a> functions differ in how
|
||
command-line arguments are passed. The “l” variants are perhaps the easiest
|
||
to work with if the number of parameters is fixed when the code is written; the
|
||
individual parameters simply become additional parameters to the
|
||
<code class="xref py py-func docutils literal notranslate"><span class="pre">spawnl*()</span></code> functions. The “v” variants are good when the number of
|
||
parameters is variable, with the arguments being passed in a list or tuple as
|
||
the <em>args</em> parameter. In either case, the arguments to the child process must
|
||
start with the name of the command being run.</p>
|
||
<p>The variants which include a second “p” near the end (<a class="reference internal" href="#os.spawnlp" title="os.spawnlp"><code class="xref py py-func docutils literal notranslate"><span class="pre">spawnlp()</span></code></a>,
|
||
<a class="reference internal" href="#os.spawnlpe" title="os.spawnlpe"><code class="xref py py-func docutils literal notranslate"><span class="pre">spawnlpe()</span></code></a>, <a class="reference internal" href="#os.spawnvp" title="os.spawnvp"><code class="xref py py-func docutils literal notranslate"><span class="pre">spawnvp()</span></code></a>, and <a class="reference internal" href="#os.spawnvpe" title="os.spawnvpe"><code class="xref py py-func docutils literal notranslate"><span class="pre">spawnvpe()</span></code></a>) will use the
|
||
<span class="target" id="index-29"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PATH</span></code> environment variable to locate the program <em>file</em>. When the
|
||
environment is being replaced (using one of the <a class="reference internal" href="#os.spawnl" title="os.spawnl"><code class="xref py py-func docutils literal notranslate"><span class="pre">spawn*e</span></code></a> variants,
|
||
discussed in the next paragraph), the new environment is used as the source of
|
||
the <span class="target" id="index-30"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PATH</span></code> variable. The other variants, <a class="reference internal" href="#os.spawnl" title="os.spawnl"><code class="xref py py-func docutils literal notranslate"><span class="pre">spawnl()</span></code></a>,
|
||
<a class="reference internal" href="#os.spawnle" title="os.spawnle"><code class="xref py py-func docutils literal notranslate"><span class="pre">spawnle()</span></code></a>, <a class="reference internal" href="#os.spawnv" title="os.spawnv"><code class="xref py py-func docutils literal notranslate"><span class="pre">spawnv()</span></code></a>, and <a class="reference internal" href="#os.spawnve" title="os.spawnve"><code class="xref py py-func docutils literal notranslate"><span class="pre">spawnve()</span></code></a>, will not use the
|
||
<span class="target" id="index-31"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PATH</span></code> variable to locate the executable; <em>path</em> must contain an
|
||
appropriate absolute or relative path.</p>
|
||
<p>For <a class="reference internal" href="#os.spawnle" title="os.spawnle"><code class="xref py py-func docutils literal notranslate"><span class="pre">spawnle()</span></code></a>, <a class="reference internal" href="#os.spawnlpe" title="os.spawnlpe"><code class="xref py py-func docutils literal notranslate"><span class="pre">spawnlpe()</span></code></a>, <a class="reference internal" href="#os.spawnve" title="os.spawnve"><code class="xref py py-func docutils literal notranslate"><span class="pre">spawnve()</span></code></a>, and <a class="reference internal" href="#os.spawnvpe" title="os.spawnvpe"><code class="xref py py-func docutils literal notranslate"><span class="pre">spawnvpe()</span></code></a>
|
||
(note that these all end in “e”), the <em>env</em> parameter must be a mapping
|
||
which is used to define the environment variables for the new process (they are
|
||
used instead of the current process’ environment); the functions
|
||
<a class="reference internal" href="#os.spawnl" title="os.spawnl"><code class="xref py py-func docutils literal notranslate"><span class="pre">spawnl()</span></code></a>, <a class="reference internal" href="#os.spawnlp" title="os.spawnlp"><code class="xref py py-func docutils literal notranslate"><span class="pre">spawnlp()</span></code></a>, <a class="reference internal" href="#os.spawnv" title="os.spawnv"><code class="xref py py-func docutils literal notranslate"><span class="pre">spawnv()</span></code></a>, and <a class="reference internal" href="#os.spawnvp" title="os.spawnvp"><code class="xref py py-func docutils literal notranslate"><span class="pre">spawnvp()</span></code></a> all cause
|
||
the new process to inherit the environment of the current process. Note that
|
||
keys and values in the <em>env</em> dictionary must be strings; invalid keys or
|
||
values will cause the function to fail, with a return value of <code class="docutils literal notranslate"><span class="pre">127</span></code>.</p>
|
||
<p>As an example, the following calls to <a class="reference internal" href="#os.spawnlp" title="os.spawnlp"><code class="xref py py-func docutils literal notranslate"><span class="pre">spawnlp()</span></code></a> and <a class="reference internal" href="#os.spawnvpe" title="os.spawnvpe"><code class="xref py py-func docutils literal notranslate"><span class="pre">spawnvpe()</span></code></a> are
|
||
equivalent:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">os</span>
|
||
<span class="n">os</span><span class="o">.</span><span class="n">spawnlp</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">P_WAIT</span><span class="p">,</span> <span class="s1">'cp'</span><span class="p">,</span> <span class="s1">'cp'</span><span class="p">,</span> <span class="s1">'index.html'</span><span class="p">,</span> <span class="s1">'/dev/null'</span><span class="p">)</span>
|
||
|
||
<span class="n">L</span> <span class="o">=</span> <span class="p">[</span><span class="s1">'cp'</span><span class="p">,</span> <span class="s1">'index.html'</span><span class="p">,</span> <span class="s1">'/dev/null'</span><span class="p">]</span>
|
||
<span class="n">os</span><span class="o">.</span><span class="n">spawnvpe</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">P_WAIT</span><span class="p">,</span> <span class="s1">'cp'</span><span class="p">,</span> <span class="n">L</span><span class="p">,</span> <span class="n">os</span><span class="o">.</span><span class="n">environ</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix, Windows. <a class="reference internal" href="#os.spawnlp" title="os.spawnlp"><code class="xref py py-func docutils literal notranslate"><span class="pre">spawnlp()</span></code></a>, <a class="reference internal" href="#os.spawnlpe" title="os.spawnlpe"><code class="xref py py-func docutils literal notranslate"><span class="pre">spawnlpe()</span></code></a>, <a class="reference internal" href="#os.spawnvp" title="os.spawnvp"><code class="xref py py-func docutils literal notranslate"><span class="pre">spawnvp()</span></code></a>
|
||
and <a class="reference internal" href="#os.spawnvpe" title="os.spawnvpe"><code class="xref py py-func docutils literal notranslate"><span class="pre">spawnvpe()</span></code></a> are not available on Windows. <a class="reference internal" href="#os.spawnle" title="os.spawnle"><code class="xref py py-func docutils literal notranslate"><span class="pre">spawnle()</span></code></a> and
|
||
<a class="reference internal" href="#os.spawnve" title="os.spawnve"><code class="xref py py-func docutils literal notranslate"><span class="pre">spawnve()</span></code></a> are not thread-safe on Windows; we advise you to use the
|
||
<a class="reference internal" href="subprocess.html#module-subprocess" title="subprocess: Subprocess management."><code class="xref py py-mod docutils literal notranslate"><span class="pre">subprocess</span></code></a> module instead.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>Accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.P_NOWAIT">
|
||
<code class="descclassname">os.</code><code class="descname">P_NOWAIT</code><a class="headerlink" href="#os.P_NOWAIT" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.P_NOWAITO">
|
||
<code class="descclassname">os.</code><code class="descname">P_NOWAITO</code><a class="headerlink" href="#os.P_NOWAITO" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Possible values for the <em>mode</em> parameter to the <a class="reference internal" href="#os.spawnl" title="os.spawnl"><code class="xref py py-func docutils literal notranslate"><span class="pre">spawn*</span></code></a> family of
|
||
functions. If either of these values is given, the <code class="xref py py-func docutils literal notranslate"><span class="pre">spawn*()</span></code> functions
|
||
will return as soon as the new process has been created, with the process id as
|
||
the return value.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix, Windows.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.P_WAIT">
|
||
<code class="descclassname">os.</code><code class="descname">P_WAIT</code><a class="headerlink" href="#os.P_WAIT" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Possible value for the <em>mode</em> parameter to the <a class="reference internal" href="#os.spawnl" title="os.spawnl"><code class="xref py py-func docutils literal notranslate"><span class="pre">spawn*</span></code></a> family of
|
||
functions. If this is given as <em>mode</em>, the <code class="xref py py-func docutils literal notranslate"><span class="pre">spawn*()</span></code> functions will not
|
||
return until the new process has run to completion and will return the exit code
|
||
of the process the run is successful, or <code class="docutils literal notranslate"><span class="pre">-signal</span></code> if a signal kills the
|
||
process.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix, Windows.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.P_DETACH">
|
||
<code class="descclassname">os.</code><code class="descname">P_DETACH</code><a class="headerlink" href="#os.P_DETACH" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.P_OVERLAY">
|
||
<code class="descclassname">os.</code><code class="descname">P_OVERLAY</code><a class="headerlink" href="#os.P_OVERLAY" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Possible values for the <em>mode</em> parameter to the <a class="reference internal" href="#os.spawnl" title="os.spawnl"><code class="xref py py-func docutils literal notranslate"><span class="pre">spawn*</span></code></a> family of
|
||
functions. These are less portable than those listed above. <a class="reference internal" href="#os.P_DETACH" title="os.P_DETACH"><code class="xref py py-const docutils literal notranslate"><span class="pre">P_DETACH</span></code></a>
|
||
is similar to <a class="reference internal" href="#os.P_NOWAIT" title="os.P_NOWAIT"><code class="xref py py-const docutils literal notranslate"><span class="pre">P_NOWAIT</span></code></a>, but the new process is detached from the
|
||
console of the calling process. If <a class="reference internal" href="#os.P_OVERLAY" title="os.P_OVERLAY"><code class="xref py py-const docutils literal notranslate"><span class="pre">P_OVERLAY</span></code></a> is used, the current
|
||
process will be replaced; the <a class="reference internal" href="#os.spawnl" title="os.spawnl"><code class="xref py py-func docutils literal notranslate"><span class="pre">spawn*</span></code></a> function will not return.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Windows.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.startfile">
|
||
<code class="descclassname">os.</code><code class="descname">startfile</code><span class="sig-paren">(</span><em>path</em><span class="optional">[</span>, <em>operation</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#os.startfile" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Start a file with its associated application.</p>
|
||
<p>When <em>operation</em> is not specified or <code class="docutils literal notranslate"><span class="pre">'open'</span></code>, this acts like double-clicking
|
||
the file in Windows Explorer, or giving the file name as an argument to the
|
||
<strong class="program">start</strong> command from the interactive command shell: the file is opened
|
||
with whatever application (if any) its extension is associated.</p>
|
||
<p>When another <em>operation</em> is given, it must be a “command verb” that specifies
|
||
what should be done with the file. Common verbs documented by Microsoft are
|
||
<code class="docutils literal notranslate"><span class="pre">'print'</span></code> and <code class="docutils literal notranslate"><span class="pre">'edit'</span></code> (to be used on files) as well as <code class="docutils literal notranslate"><span class="pre">'explore'</span></code> and
|
||
<code class="docutils literal notranslate"><span class="pre">'find'</span></code> (to be used on directories).</p>
|
||
<p><a class="reference internal" href="#os.startfile" title="os.startfile"><code class="xref py py-func docutils literal notranslate"><span class="pre">startfile()</span></code></a> returns as soon as the associated application is launched.
|
||
There is no option to wait for the application to close, and no way to retrieve
|
||
the application’s exit status. The <em>path</em> parameter is relative to the current
|
||
directory. If you want to use an absolute path, make sure the first character
|
||
is not a slash (<code class="docutils literal notranslate"><span class="pre">'/'</span></code>); the underlying Win32 <code class="xref c c-func docutils literal notranslate"><span class="pre">ShellExecute()</span></code> function
|
||
doesn’t work if it is. Use the <a class="reference internal" href="os.path.html#os.path.normpath" title="os.path.normpath"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.path.normpath()</span></code></a> function to ensure that
|
||
the path is properly encoded for Win32.</p>
|
||
<p>To reduce interpreter startup overhead, the Win32 <code class="xref c c-func docutils literal notranslate"><span class="pre">ShellExecute()</span></code>
|
||
function is not resolved until this function is first called. If the function
|
||
cannot be resolved, <a class="reference internal" href="exceptions.html#NotImplementedError" title="NotImplementedError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">NotImplementedError</span></code></a> will be raised.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Windows.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.system">
|
||
<code class="descclassname">os.</code><code class="descname">system</code><span class="sig-paren">(</span><em>command</em><span class="sig-paren">)</span><a class="headerlink" href="#os.system" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Execute the command (a string) in a subshell. This is implemented by calling
|
||
the Standard C function <code class="xref c c-func docutils literal notranslate"><span class="pre">system()</span></code>, and has the same limitations.
|
||
Changes to <a class="reference internal" href="sys.html#sys.stdin" title="sys.stdin"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.stdin</span></code></a>, etc. are not reflected in the environment of
|
||
the executed command. If <em>command</em> generates any output, it will be sent to
|
||
the interpreter standard output stream.</p>
|
||
<p>On Unix, the return value is the exit status of the process encoded in the
|
||
format specified for <a class="reference internal" href="#os.wait" title="os.wait"><code class="xref py py-func docutils literal notranslate"><span class="pre">wait()</span></code></a>. Note that POSIX does not specify the
|
||
meaning of the return value of the C <code class="xref c c-func docutils literal notranslate"><span class="pre">system()</span></code> function, so the return
|
||
value of the Python function is system-dependent.</p>
|
||
<p>On Windows, the return value is that returned by the system shell after
|
||
running <em>command</em>. The shell is given by the Windows environment variable
|
||
<span class="target" id="index-32"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">COMSPEC</span></code>: it is usually <strong class="program">cmd.exe</strong>, which returns the exit
|
||
status of the command run; on systems using a non-native shell, consult your
|
||
shell documentation.</p>
|
||
<p>The <a class="reference internal" href="subprocess.html#module-subprocess" title="subprocess: Subprocess management."><code class="xref py py-mod docutils literal notranslate"><span class="pre">subprocess</span></code></a> module provides more powerful facilities for spawning
|
||
new processes and retrieving their results; using that module is preferable
|
||
to using this function. See the <a class="reference internal" href="subprocess.html#subprocess-replacements"><span class="std std-ref">Replacing Older Functions with the subprocess Module</span></a> section in
|
||
the <a class="reference internal" href="subprocess.html#module-subprocess" title="subprocess: Subprocess management."><code class="xref py py-mod docutils literal notranslate"><span class="pre">subprocess</span></code></a> documentation for some helpful recipes.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix, Windows.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.times">
|
||
<code class="descclassname">os.</code><code class="descname">times</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#os.times" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Returns the current global process times.
|
||
The return value is an object with five attributes:</p>
|
||
<ul class="simple">
|
||
<li><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">user</span></code> - user time</p></li>
|
||
<li><p><a class="reference internal" href="#os.system" title="os.system"><code class="xref py py-attr docutils literal notranslate"><span class="pre">system</span></code></a> - system time</p></li>
|
||
<li><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">children_user</span></code> - user time of all child processes</p></li>
|
||
<li><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">children_system</span></code> - system time of all child processes</p></li>
|
||
<li><p><code class="xref py py-attr docutils literal notranslate"><span class="pre">elapsed</span></code> - elapsed real time since a fixed point in the past</p></li>
|
||
</ul>
|
||
<p>For backwards compatibility, this object also behaves like a five-tuple
|
||
containing <code class="xref py py-attr docutils literal notranslate"><span class="pre">user</span></code>, <a class="reference internal" href="#os.system" title="os.system"><code class="xref py py-attr docutils literal notranslate"><span class="pre">system</span></code></a>, <code class="xref py py-attr docutils literal notranslate"><span class="pre">children_user</span></code>,
|
||
<code class="xref py py-attr docutils literal notranslate"><span class="pre">children_system</span></code>, and <code class="xref py py-attr docutils literal notranslate"><span class="pre">elapsed</span></code> in that order.</p>
|
||
<p>See the Unix manual page
|
||
<em class="manpage">times(2)</em> or the corresponding Windows Platform API documentation.
|
||
On Windows, only <code class="xref py py-attr docutils literal notranslate"><span class="pre">user</span></code> and <a class="reference internal" href="#os.system" title="os.system"><code class="xref py py-attr docutils literal notranslate"><span class="pre">system</span></code></a> are known; the other
|
||
attributes are zero.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix, Windows.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.3: </span>Return type changed from a tuple to a tuple-like object
|
||
with named attributes.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.wait">
|
||
<code class="descclassname">os.</code><code class="descname">wait</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#os.wait" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Wait for completion of a child process, and return a tuple containing its pid
|
||
and exit status indication: a 16-bit number, whose low byte is the signal number
|
||
that killed the process, and whose high byte is the exit status (if the signal
|
||
number is zero); the high bit of the low byte is set if a core file was
|
||
produced.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.waitid">
|
||
<code class="descclassname">os.</code><code class="descname">waitid</code><span class="sig-paren">(</span><em>idtype</em>, <em>id</em>, <em>options</em><span class="sig-paren">)</span><a class="headerlink" href="#os.waitid" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Wait for the completion of one or more child processes.
|
||
<em>idtype</em> can be <a class="reference internal" href="#os.P_PID" title="os.P_PID"><code class="xref py py-data docutils literal notranslate"><span class="pre">P_PID</span></code></a>, <a class="reference internal" href="#os.P_PGID" title="os.P_PGID"><code class="xref py py-data docutils literal notranslate"><span class="pre">P_PGID</span></code></a> or <a class="reference internal" href="#os.P_ALL" title="os.P_ALL"><code class="xref py py-data docutils literal notranslate"><span class="pre">P_ALL</span></code></a>.
|
||
<em>id</em> specifies the pid to wait on.
|
||
<em>options</em> is constructed from the ORing of one or more of <a class="reference internal" href="#os.WEXITED" title="os.WEXITED"><code class="xref py py-data docutils literal notranslate"><span class="pre">WEXITED</span></code></a>,
|
||
<a class="reference internal" href="#os.WSTOPPED" title="os.WSTOPPED"><code class="xref py py-data docutils literal notranslate"><span class="pre">WSTOPPED</span></code></a> or <a class="reference internal" href="#os.WCONTINUED" title="os.WCONTINUED"><code class="xref py py-data docutils literal notranslate"><span class="pre">WCONTINUED</span></code></a> and additionally may be ORed with
|
||
<a class="reference internal" href="#os.WNOHANG" title="os.WNOHANG"><code class="xref py py-data docutils literal notranslate"><span class="pre">WNOHANG</span></code></a> or <a class="reference internal" href="#os.WNOWAIT" title="os.WNOWAIT"><code class="xref py py-data docutils literal notranslate"><span class="pre">WNOWAIT</span></code></a>. The return value is an object
|
||
representing the data contained in the <code class="xref c c-type docutils literal notranslate"><span class="pre">siginfo_t</span></code> structure, namely:
|
||
<code class="xref py py-attr docutils literal notranslate"><span class="pre">si_pid</span></code>, <code class="xref py py-attr docutils literal notranslate"><span class="pre">si_uid</span></code>, <code class="xref py py-attr docutils literal notranslate"><span class="pre">si_signo</span></code>, <code class="xref py py-attr docutils literal notranslate"><span class="pre">si_status</span></code>,
|
||
<code class="xref py py-attr docutils literal notranslate"><span class="pre">si_code</span></code> or <code class="docutils literal notranslate"><span class="pre">None</span></code> if <a class="reference internal" href="#os.WNOHANG" title="os.WNOHANG"><code class="xref py py-data docutils literal notranslate"><span class="pre">WNOHANG</span></code></a> is specified and there are no
|
||
children in a waitable state.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.P_PID">
|
||
<code class="descclassname">os.</code><code class="descname">P_PID</code><a class="headerlink" href="#os.P_PID" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.P_PGID">
|
||
<code class="descclassname">os.</code><code class="descname">P_PGID</code><a class="headerlink" href="#os.P_PGID" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.P_ALL">
|
||
<code class="descclassname">os.</code><code class="descname">P_ALL</code><a class="headerlink" href="#os.P_ALL" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>These are the possible values for <em>idtype</em> in <a class="reference internal" href="#os.waitid" title="os.waitid"><code class="xref py py-func docutils literal notranslate"><span class="pre">waitid()</span></code></a>. They affect
|
||
how <em>id</em> is interpreted.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.WEXITED">
|
||
<code class="descclassname">os.</code><code class="descname">WEXITED</code><a class="headerlink" href="#os.WEXITED" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.WSTOPPED">
|
||
<code class="descclassname">os.</code><code class="descname">WSTOPPED</code><a class="headerlink" href="#os.WSTOPPED" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.WNOWAIT">
|
||
<code class="descclassname">os.</code><code class="descname">WNOWAIT</code><a class="headerlink" href="#os.WNOWAIT" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Flags that can be used in <em>options</em> in <a class="reference internal" href="#os.waitid" title="os.waitid"><code class="xref py py-func docutils literal notranslate"><span class="pre">waitid()</span></code></a> that specify what
|
||
child signal to wait for.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.CLD_EXITED">
|
||
<code class="descclassname">os.</code><code class="descname">CLD_EXITED</code><a class="headerlink" href="#os.CLD_EXITED" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.CLD_DUMPED">
|
||
<code class="descclassname">os.</code><code class="descname">CLD_DUMPED</code><a class="headerlink" href="#os.CLD_DUMPED" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.CLD_TRAPPED">
|
||
<code class="descclassname">os.</code><code class="descname">CLD_TRAPPED</code><a class="headerlink" href="#os.CLD_TRAPPED" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.CLD_CONTINUED">
|
||
<code class="descclassname">os.</code><code class="descname">CLD_CONTINUED</code><a class="headerlink" href="#os.CLD_CONTINUED" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>These are the possible values for <code class="xref py py-attr docutils literal notranslate"><span class="pre">si_code</span></code> in the result returned by
|
||
<a class="reference internal" href="#os.waitid" title="os.waitid"><code class="xref py py-func docutils literal notranslate"><span class="pre">waitid()</span></code></a>.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.waitpid">
|
||
<code class="descclassname">os.</code><code class="descname">waitpid</code><span class="sig-paren">(</span><em>pid</em>, <em>options</em><span class="sig-paren">)</span><a class="headerlink" href="#os.waitpid" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>The details of this function differ on Unix and Windows.</p>
|
||
<p>On Unix: Wait for completion of a child process given by process id <em>pid</em>, and
|
||
return a tuple containing its process id and exit status indication (encoded as
|
||
for <a class="reference internal" href="#os.wait" title="os.wait"><code class="xref py py-func docutils literal notranslate"><span class="pre">wait()</span></code></a>). The semantics of the call are affected by the value of the
|
||
integer <em>options</em>, which should be <code class="docutils literal notranslate"><span class="pre">0</span></code> for normal operation.</p>
|
||
<p>If <em>pid</em> is greater than <code class="docutils literal notranslate"><span class="pre">0</span></code>, <a class="reference internal" href="#os.waitpid" title="os.waitpid"><code class="xref py py-func docutils literal notranslate"><span class="pre">waitpid()</span></code></a> requests status information for
|
||
that specific process. If <em>pid</em> is <code class="docutils literal notranslate"><span class="pre">0</span></code>, the request is for the status of any
|
||
child in the process group of the current process. If <em>pid</em> is <code class="docutils literal notranslate"><span class="pre">-1</span></code>, the
|
||
request pertains to any child of the current process. If <em>pid</em> is less than
|
||
<code class="docutils literal notranslate"><span class="pre">-1</span></code>, status is requested for any process in the process group <code class="docutils literal notranslate"><span class="pre">-pid</span></code> (the
|
||
absolute value of <em>pid</em>).</p>
|
||
<p>An <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a> is raised with the value of errno when the syscall
|
||
returns -1.</p>
|
||
<p>On Windows: Wait for completion of a process given by process handle <em>pid</em>, and
|
||
return a tuple containing <em>pid</em>, and its exit status shifted left by 8 bits
|
||
(shifting makes cross-platform use of the function easier). A <em>pid</em> less than or
|
||
equal to <code class="docutils literal notranslate"><span class="pre">0</span></code> has no special meaning on Windows, and raises an exception. The
|
||
value of integer <em>options</em> has no effect. <em>pid</em> can refer to any process whose
|
||
id is known, not necessarily a child process. The <a class="reference internal" href="#os.spawnl" title="os.spawnl"><code class="xref py py-func docutils literal notranslate"><span class="pre">spawn*</span></code></a>
|
||
functions called with <a class="reference internal" href="#os.P_NOWAIT" title="os.P_NOWAIT"><code class="xref py py-const docutils literal notranslate"><span class="pre">P_NOWAIT</span></code></a> return suitable process handles.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.5: </span>If the system call is interrupted and the signal handler does not raise an
|
||
exception, the function now retries the system call instead of raising an
|
||
<a class="reference internal" href="exceptions.html#InterruptedError" title="InterruptedError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">InterruptedError</span></code></a> exception (see <span class="target" id="index-33"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0475"><strong>PEP 475</strong></a> for the rationale).</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.wait3">
|
||
<code class="descclassname">os.</code><code class="descname">wait3</code><span class="sig-paren">(</span><em>options</em><span class="sig-paren">)</span><a class="headerlink" href="#os.wait3" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Similar to <a class="reference internal" href="#os.waitpid" title="os.waitpid"><code class="xref py py-func docutils literal notranslate"><span class="pre">waitpid()</span></code></a>, except no process id argument is given and a
|
||
3-element tuple containing the child’s process id, exit status indication,
|
||
and resource usage information is returned. Refer to
|
||
<a class="reference internal" href="resource.html#module-resource" title="resource: An interface to provide resource usage information on the current process. (Unix)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">resource</span></code></a>.<a class="reference internal" href="resource.html#resource.getrusage" title="resource.getrusage"><code class="xref py py-func docutils literal notranslate"><span class="pre">getrusage()</span></code></a> for details on resource usage
|
||
information. The option argument is the same as that provided to
|
||
<a class="reference internal" href="#os.waitpid" title="os.waitpid"><code class="xref py py-func docutils literal notranslate"><span class="pre">waitpid()</span></code></a> and <a class="reference internal" href="#os.wait4" title="os.wait4"><code class="xref py py-func docutils literal notranslate"><span class="pre">wait4()</span></code></a>.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.wait4">
|
||
<code class="descclassname">os.</code><code class="descname">wait4</code><span class="sig-paren">(</span><em>pid</em>, <em>options</em><span class="sig-paren">)</span><a class="headerlink" href="#os.wait4" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Similar to <a class="reference internal" href="#os.waitpid" title="os.waitpid"><code class="xref py py-func docutils literal notranslate"><span class="pre">waitpid()</span></code></a>, except a 3-element tuple, containing the child’s
|
||
process id, exit status indication, and resource usage information is returned.
|
||
Refer to <a class="reference internal" href="resource.html#module-resource" title="resource: An interface to provide resource usage information on the current process. (Unix)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">resource</span></code></a>.<a class="reference internal" href="resource.html#resource.getrusage" title="resource.getrusage"><code class="xref py py-func docutils literal notranslate"><span class="pre">getrusage()</span></code></a> for details on
|
||
resource usage information. The arguments to <a class="reference internal" href="#os.wait4" title="os.wait4"><code class="xref py py-func docutils literal notranslate"><span class="pre">wait4()</span></code></a> are the same
|
||
as those provided to <a class="reference internal" href="#os.waitpid" title="os.waitpid"><code class="xref py py-func docutils literal notranslate"><span class="pre">waitpid()</span></code></a>.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.WNOHANG">
|
||
<code class="descclassname">os.</code><code class="descname">WNOHANG</code><a class="headerlink" href="#os.WNOHANG" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>The option for <a class="reference internal" href="#os.waitpid" title="os.waitpid"><code class="xref py py-func docutils literal notranslate"><span class="pre">waitpid()</span></code></a> to return immediately if no child process status
|
||
is available immediately. The function returns <code class="docutils literal notranslate"><span class="pre">(0,</span> <span class="pre">0)</span></code> in this case.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.WCONTINUED">
|
||
<code class="descclassname">os.</code><code class="descname">WCONTINUED</code><a class="headerlink" href="#os.WCONTINUED" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>This option causes child processes to be reported if they have been continued
|
||
from a job control stop since their status was last reported.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: some Unix systems.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.WUNTRACED">
|
||
<code class="descclassname">os.</code><code class="descname">WUNTRACED</code><a class="headerlink" href="#os.WUNTRACED" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>This option causes child processes to be reported if they have been stopped but
|
||
their current state has not been reported since they were stopped.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<p>The following functions take a process status code as returned by
|
||
<a class="reference internal" href="#os.system" title="os.system"><code class="xref py py-func docutils literal notranslate"><span class="pre">system()</span></code></a>, <a class="reference internal" href="#os.wait" title="os.wait"><code class="xref py py-func docutils literal notranslate"><span class="pre">wait()</span></code></a>, or <a class="reference internal" href="#os.waitpid" title="os.waitpid"><code class="xref py py-func docutils literal notranslate"><span class="pre">waitpid()</span></code></a> as a parameter. They may be
|
||
used to determine the disposition of a process.</p>
|
||
<dl class="function">
|
||
<dt id="os.WCOREDUMP">
|
||
<code class="descclassname">os.</code><code class="descname">WCOREDUMP</code><span class="sig-paren">(</span><em>status</em><span class="sig-paren">)</span><a class="headerlink" href="#os.WCOREDUMP" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return <code class="docutils literal notranslate"><span class="pre">True</span></code> if a core dump was generated for the process, otherwise
|
||
return <code class="docutils literal notranslate"><span class="pre">False</span></code>.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.WIFCONTINUED">
|
||
<code class="descclassname">os.</code><code class="descname">WIFCONTINUED</code><span class="sig-paren">(</span><em>status</em><span class="sig-paren">)</span><a class="headerlink" href="#os.WIFCONTINUED" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return <code class="docutils literal notranslate"><span class="pre">True</span></code> if the process has been continued from a job control stop,
|
||
otherwise return <code class="docutils literal notranslate"><span class="pre">False</span></code>.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.WIFSTOPPED">
|
||
<code class="descclassname">os.</code><code class="descname">WIFSTOPPED</code><span class="sig-paren">(</span><em>status</em><span class="sig-paren">)</span><a class="headerlink" href="#os.WIFSTOPPED" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return <code class="docutils literal notranslate"><span class="pre">True</span></code> if the process has been stopped, otherwise return
|
||
<code class="docutils literal notranslate"><span class="pre">False</span></code>.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.WIFSIGNALED">
|
||
<code class="descclassname">os.</code><code class="descname">WIFSIGNALED</code><span class="sig-paren">(</span><em>status</em><span class="sig-paren">)</span><a class="headerlink" href="#os.WIFSIGNALED" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return <code class="docutils literal notranslate"><span class="pre">True</span></code> if the process exited due to a signal, otherwise return
|
||
<code class="docutils literal notranslate"><span class="pre">False</span></code>.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.WIFEXITED">
|
||
<code class="descclassname">os.</code><code class="descname">WIFEXITED</code><span class="sig-paren">(</span><em>status</em><span class="sig-paren">)</span><a class="headerlink" href="#os.WIFEXITED" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return <code class="docutils literal notranslate"><span class="pre">True</span></code> if the process exited using the <em class="manpage">exit(2)</em> system call,
|
||
otherwise return <code class="docutils literal notranslate"><span class="pre">False</span></code>.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.WEXITSTATUS">
|
||
<code class="descclassname">os.</code><code class="descname">WEXITSTATUS</code><span class="sig-paren">(</span><em>status</em><span class="sig-paren">)</span><a class="headerlink" href="#os.WEXITSTATUS" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>If <code class="docutils literal notranslate"><span class="pre">WIFEXITED(status)</span></code> is true, return the integer parameter to the
|
||
<em class="manpage">exit(2)</em> system call. Otherwise, the return value is meaningless.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.WSTOPSIG">
|
||
<code class="descclassname">os.</code><code class="descname">WSTOPSIG</code><span class="sig-paren">(</span><em>status</em><span class="sig-paren">)</span><a class="headerlink" href="#os.WSTOPSIG" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return the signal which caused the process to stop.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.WTERMSIG">
|
||
<code class="descclassname">os.</code><code class="descname">WTERMSIG</code><span class="sig-paren">(</span><em>status</em><span class="sig-paren">)</span><a class="headerlink" href="#os.WTERMSIG" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return the signal which caused the process to exit.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
</div>
|
||
<div class="section" id="interface-to-the-scheduler">
|
||
<h2>Interface to the scheduler<a class="headerlink" href="#interface-to-the-scheduler" title="Permalink to this headline">¶</a></h2>
|
||
<p>These functions control how a process is allocated CPU time by the operating
|
||
system. They are only available on some Unix platforms. For more detailed
|
||
information, consult your Unix manpages.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3.</span></p>
|
||
</div>
|
||
<p>The following scheduling policies are exposed if they are supported by the
|
||
operating system.</p>
|
||
<dl class="data">
|
||
<dt id="os.SCHED_OTHER">
|
||
<code class="descclassname">os.</code><code class="descname">SCHED_OTHER</code><a class="headerlink" href="#os.SCHED_OTHER" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>The default scheduling policy.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.SCHED_BATCH">
|
||
<code class="descclassname">os.</code><code class="descname">SCHED_BATCH</code><a class="headerlink" href="#os.SCHED_BATCH" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Scheduling policy for CPU-intensive processes that tries to preserve
|
||
interactivity on the rest of the computer.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.SCHED_IDLE">
|
||
<code class="descclassname">os.</code><code class="descname">SCHED_IDLE</code><a class="headerlink" href="#os.SCHED_IDLE" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Scheduling policy for extremely low priority background tasks.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.SCHED_SPORADIC">
|
||
<code class="descclassname">os.</code><code class="descname">SCHED_SPORADIC</code><a class="headerlink" href="#os.SCHED_SPORADIC" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Scheduling policy for sporadic server programs.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.SCHED_FIFO">
|
||
<code class="descclassname">os.</code><code class="descname">SCHED_FIFO</code><a class="headerlink" href="#os.SCHED_FIFO" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>A First In First Out scheduling policy.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.SCHED_RR">
|
||
<code class="descclassname">os.</code><code class="descname">SCHED_RR</code><a class="headerlink" href="#os.SCHED_RR" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>A round-robin scheduling policy.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.SCHED_RESET_ON_FORK">
|
||
<code class="descclassname">os.</code><code class="descname">SCHED_RESET_ON_FORK</code><a class="headerlink" href="#os.SCHED_RESET_ON_FORK" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>This flag can be OR’ed with any other scheduling policy. When a process with
|
||
this flag set forks, its child’s scheduling policy and priority are reset to
|
||
the default.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="class">
|
||
<dt id="os.sched_param">
|
||
<em class="property">class </em><code class="descclassname">os.</code><code class="descname">sched_param</code><span class="sig-paren">(</span><em>sched_priority</em><span class="sig-paren">)</span><a class="headerlink" href="#os.sched_param" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>This class represents tunable scheduling parameters used in
|
||
<a class="reference internal" href="#os.sched_setparam" title="os.sched_setparam"><code class="xref py py-func docutils literal notranslate"><span class="pre">sched_setparam()</span></code></a>, <a class="reference internal" href="#os.sched_setscheduler" title="os.sched_setscheduler"><code class="xref py py-func docutils literal notranslate"><span class="pre">sched_setscheduler()</span></code></a>, and
|
||
<a class="reference internal" href="#os.sched_getparam" title="os.sched_getparam"><code class="xref py py-func docutils literal notranslate"><span class="pre">sched_getparam()</span></code></a>. It is immutable.</p>
|
||
<p>At the moment, there is only one possible parameter:</p>
|
||
<dl class="attribute">
|
||
<dt id="os.sched_param.sched_priority">
|
||
<code class="descname">sched_priority</code><a class="headerlink" href="#os.sched_param.sched_priority" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>The scheduling priority for a scheduling policy.</p>
|
||
</dd></dl>
|
||
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.sched_get_priority_min">
|
||
<code class="descclassname">os.</code><code class="descname">sched_get_priority_min</code><span class="sig-paren">(</span><em>policy</em><span class="sig-paren">)</span><a class="headerlink" href="#os.sched_get_priority_min" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Get the minimum priority value for <em>policy</em>. <em>policy</em> is one of the
|
||
scheduling policy constants above.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.sched_get_priority_max">
|
||
<code class="descclassname">os.</code><code class="descname">sched_get_priority_max</code><span class="sig-paren">(</span><em>policy</em><span class="sig-paren">)</span><a class="headerlink" href="#os.sched_get_priority_max" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Get the maximum priority value for <em>policy</em>. <em>policy</em> is one of the
|
||
scheduling policy constants above.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.sched_setscheduler">
|
||
<code class="descclassname">os.</code><code class="descname">sched_setscheduler</code><span class="sig-paren">(</span><em>pid</em>, <em>policy</em>, <em>param</em><span class="sig-paren">)</span><a class="headerlink" href="#os.sched_setscheduler" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Set the scheduling policy for the process with PID <em>pid</em>. A <em>pid</em> of 0 means
|
||
the calling process. <em>policy</em> is one of the scheduling policy constants
|
||
above. <em>param</em> is a <a class="reference internal" href="#os.sched_param" title="os.sched_param"><code class="xref py py-class docutils literal notranslate"><span class="pre">sched_param</span></code></a> instance.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.sched_getscheduler">
|
||
<code class="descclassname">os.</code><code class="descname">sched_getscheduler</code><span class="sig-paren">(</span><em>pid</em><span class="sig-paren">)</span><a class="headerlink" href="#os.sched_getscheduler" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return the scheduling policy for the process with PID <em>pid</em>. A <em>pid</em> of 0
|
||
means the calling process. The result is one of the scheduling policy
|
||
constants above.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.sched_setparam">
|
||
<code class="descclassname">os.</code><code class="descname">sched_setparam</code><span class="sig-paren">(</span><em>pid</em>, <em>param</em><span class="sig-paren">)</span><a class="headerlink" href="#os.sched_setparam" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Set a scheduling parameters for the process with PID <em>pid</em>. A <em>pid</em> of 0 means
|
||
the calling process. <em>param</em> is a <a class="reference internal" href="#os.sched_param" title="os.sched_param"><code class="xref py py-class docutils literal notranslate"><span class="pre">sched_param</span></code></a> instance.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.sched_getparam">
|
||
<code class="descclassname">os.</code><code class="descname">sched_getparam</code><span class="sig-paren">(</span><em>pid</em><span class="sig-paren">)</span><a class="headerlink" href="#os.sched_getparam" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return the scheduling parameters as a <a class="reference internal" href="#os.sched_param" title="os.sched_param"><code class="xref py py-class docutils literal notranslate"><span class="pre">sched_param</span></code></a> instance for the
|
||
process with PID <em>pid</em>. A <em>pid</em> of 0 means the calling process.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.sched_rr_get_interval">
|
||
<code class="descclassname">os.</code><code class="descname">sched_rr_get_interval</code><span class="sig-paren">(</span><em>pid</em><span class="sig-paren">)</span><a class="headerlink" href="#os.sched_rr_get_interval" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return the round-robin quantum in seconds for the process with PID <em>pid</em>. A
|
||
<em>pid</em> of 0 means the calling process.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.sched_yield">
|
||
<code class="descclassname">os.</code><code class="descname">sched_yield</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#os.sched_yield" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Voluntarily relinquish the CPU.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.sched_setaffinity">
|
||
<code class="descclassname">os.</code><code class="descname">sched_setaffinity</code><span class="sig-paren">(</span><em>pid</em>, <em>mask</em><span class="sig-paren">)</span><a class="headerlink" href="#os.sched_setaffinity" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Restrict the process with PID <em>pid</em> (or the current process if zero) to a
|
||
set of CPUs. <em>mask</em> is an iterable of integers representing the set of
|
||
CPUs to which the process should be restricted.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.sched_getaffinity">
|
||
<code class="descclassname">os.</code><code class="descname">sched_getaffinity</code><span class="sig-paren">(</span><em>pid</em><span class="sig-paren">)</span><a class="headerlink" href="#os.sched_getaffinity" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return the set of CPUs the process with PID <em>pid</em> (or the current process
|
||
if zero) is restricted to.</p>
|
||
</dd></dl>
|
||
|
||
</div>
|
||
<div class="section" id="miscellaneous-system-information">
|
||
<span id="os-path"></span><h2>Miscellaneous System Information<a class="headerlink" href="#miscellaneous-system-information" title="Permalink to this headline">¶</a></h2>
|
||
<dl class="function">
|
||
<dt id="os.confstr">
|
||
<code class="descclassname">os.</code><code class="descname">confstr</code><span class="sig-paren">(</span><em>name</em><span class="sig-paren">)</span><a class="headerlink" href="#os.confstr" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return string-valued system configuration values. <em>name</em> specifies the
|
||
configuration value to retrieve; it may be a string which is the name of a
|
||
defined system value; these names are specified in a number of standards (POSIX,
|
||
Unix 95, Unix 98, and others). Some platforms define additional names as well.
|
||
The names known to the host operating system are given as the keys of the
|
||
<code class="docutils literal notranslate"><span class="pre">confstr_names</span></code> dictionary. For configuration variables not included in that
|
||
mapping, passing an integer for <em>name</em> is also accepted.</p>
|
||
<p>If the configuration value specified by <em>name</em> isn’t defined, <code class="docutils literal notranslate"><span class="pre">None</span></code> is
|
||
returned.</p>
|
||
<p>If <em>name</em> is a string and is not known, <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> is raised. If a
|
||
specific value for <em>name</em> is not supported by the host system, even if it is
|
||
included in <code class="docutils literal notranslate"><span class="pre">confstr_names</span></code>, an <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a> is raised with
|
||
<a class="reference internal" href="errno.html#errno.EINVAL" title="errno.EINVAL"><code class="xref py py-const docutils literal notranslate"><span class="pre">errno.EINVAL</span></code></a> for the error number.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.confstr_names">
|
||
<code class="descclassname">os.</code><code class="descname">confstr_names</code><a class="headerlink" href="#os.confstr_names" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Dictionary mapping names accepted by <a class="reference internal" href="#os.confstr" title="os.confstr"><code class="xref py py-func docutils literal notranslate"><span class="pre">confstr()</span></code></a> to the integer values
|
||
defined for those names by the host operating system. This can be used to
|
||
determine the set of names known to the system.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.cpu_count">
|
||
<code class="descclassname">os.</code><code class="descname">cpu_count</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#os.cpu_count" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return the number of CPUs in the system. Returns <code class="docutils literal notranslate"><span class="pre">None</span></code> if undetermined.</p>
|
||
<p>This number is not equivalent to the number of CPUs the current process can
|
||
use. The number of usable CPUs can be obtained with
|
||
<code class="docutils literal notranslate"><span class="pre">len(os.sched_getaffinity(0))</span></code></p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.4.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.getloadavg">
|
||
<code class="descclassname">os.</code><code class="descname">getloadavg</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#os.getloadavg" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return the number of processes in the system run queue averaged over the last
|
||
1, 5, and 15 minutes or raises <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a> if the load average was
|
||
unobtainable.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.sysconf">
|
||
<code class="descclassname">os.</code><code class="descname">sysconf</code><span class="sig-paren">(</span><em>name</em><span class="sig-paren">)</span><a class="headerlink" href="#os.sysconf" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return integer-valued system configuration values. If the configuration value
|
||
specified by <em>name</em> isn’t defined, <code class="docutils literal notranslate"><span class="pre">-1</span></code> is returned. The comments regarding
|
||
the <em>name</em> parameter for <a class="reference internal" href="#os.confstr" title="os.confstr"><code class="xref py py-func docutils literal notranslate"><span class="pre">confstr()</span></code></a> apply here as well; the dictionary that
|
||
provides information on the known names is given by <code class="docutils literal notranslate"><span class="pre">sysconf_names</span></code>.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.sysconf_names">
|
||
<code class="descclassname">os.</code><code class="descname">sysconf_names</code><a class="headerlink" href="#os.sysconf_names" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Dictionary mapping names accepted by <a class="reference internal" href="#os.sysconf" title="os.sysconf"><code class="xref py py-func docutils literal notranslate"><span class="pre">sysconf()</span></code></a> to the integer values
|
||
defined for those names by the host operating system. This can be used to
|
||
determine the set of names known to the system.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<p>The following data values are used to support path manipulation operations. These
|
||
are defined for all platforms.</p>
|
||
<p>Higher-level operations on pathnames are defined in the <a class="reference internal" href="os.path.html#module-os.path" title="os.path: Operations on pathnames."><code class="xref py py-mod docutils literal notranslate"><span class="pre">os.path</span></code></a> module.</p>
|
||
<span class="target" id="index-34"></span><dl class="data">
|
||
<dt id="os.curdir">
|
||
<code class="descclassname">os.</code><code class="descname">curdir</code><a class="headerlink" href="#os.curdir" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>The constant string used by the operating system to refer to the current
|
||
directory. This is <code class="docutils literal notranslate"><span class="pre">'.'</span></code> for Windows and POSIX. Also available via
|
||
<a class="reference internal" href="os.path.html#module-os.path" title="os.path: Operations on pathnames."><code class="xref py py-mod docutils literal notranslate"><span class="pre">os.path</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<span class="target" id="index-35"></span><dl class="data">
|
||
<dt id="os.pardir">
|
||
<code class="descclassname">os.</code><code class="descname">pardir</code><a class="headerlink" href="#os.pardir" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>The constant string used by the operating system to refer to the parent
|
||
directory. This is <code class="docutils literal notranslate"><span class="pre">'..'</span></code> for Windows and POSIX. Also available via
|
||
<a class="reference internal" href="os.path.html#module-os.path" title="os.path: Operations on pathnames."><code class="xref py py-mod docutils literal notranslate"><span class="pre">os.path</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<span class="target" id="index-36"></span><span class="target" id="index-37"></span><dl class="data">
|
||
<dt id="os.sep">
|
||
<code class="descclassname">os.</code><code class="descname">sep</code><a class="headerlink" href="#os.sep" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>The character used by the operating system to separate pathname components.
|
||
This is <code class="docutils literal notranslate"><span class="pre">'/'</span></code> for POSIX and <code class="docutils literal notranslate"><span class="pre">'\\'</span></code> for Windows. Note that knowing this
|
||
is not sufficient to be able to parse or concatenate pathnames — use
|
||
<a class="reference internal" href="os.path.html#os.path.split" title="os.path.split"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.path.split()</span></code></a> and <a class="reference internal" href="os.path.html#os.path.join" title="os.path.join"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.path.join()</span></code></a> — but it is occasionally
|
||
useful. Also available via <a class="reference internal" href="os.path.html#module-os.path" title="os.path: Operations on pathnames."><code class="xref py py-mod docutils literal notranslate"><span class="pre">os.path</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<span class="target" id="index-38"></span><dl class="data">
|
||
<dt id="os.altsep">
|
||
<code class="descclassname">os.</code><code class="descname">altsep</code><a class="headerlink" href="#os.altsep" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>An alternative character used by the operating system to separate pathname
|
||
components, or <code class="docutils literal notranslate"><span class="pre">None</span></code> if only one separator character exists. This is set to
|
||
<code class="docutils literal notranslate"><span class="pre">'/'</span></code> on Windows systems where <code class="docutils literal notranslate"><span class="pre">sep</span></code> is a backslash. Also available via
|
||
<a class="reference internal" href="os.path.html#module-os.path" title="os.path: Operations on pathnames."><code class="xref py py-mod docutils literal notranslate"><span class="pre">os.path</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<span class="target" id="index-39"></span><dl class="data">
|
||
<dt id="os.extsep">
|
||
<code class="descclassname">os.</code><code class="descname">extsep</code><a class="headerlink" href="#os.extsep" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>The character which separates the base filename from the extension; for example,
|
||
the <code class="docutils literal notranslate"><span class="pre">'.'</span></code> in <code class="file docutils literal notranslate"><span class="pre">os.py</span></code>. Also available via <a class="reference internal" href="os.path.html#module-os.path" title="os.path: Operations on pathnames."><code class="xref py py-mod docutils literal notranslate"><span class="pre">os.path</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<span class="target" id="index-40"></span><dl class="data">
|
||
<dt id="os.pathsep">
|
||
<code class="descclassname">os.</code><code class="descname">pathsep</code><a class="headerlink" href="#os.pathsep" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>The character conventionally used by the operating system to separate search
|
||
path components (as in <span class="target" id="index-41"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PATH</span></code>), such as <code class="docutils literal notranslate"><span class="pre">':'</span></code> for POSIX or <code class="docutils literal notranslate"><span class="pre">';'</span></code> for
|
||
Windows. Also available via <a class="reference internal" href="os.path.html#module-os.path" title="os.path: Operations on pathnames."><code class="xref py py-mod docutils literal notranslate"><span class="pre">os.path</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.defpath">
|
||
<code class="descclassname">os.</code><code class="descname">defpath</code><a class="headerlink" href="#os.defpath" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>The default search path used by <a class="reference internal" href="#os.execl" title="os.execl"><code class="xref py py-func docutils literal notranslate"><span class="pre">exec*p*</span></code></a> and
|
||
<a class="reference internal" href="#os.spawnl" title="os.spawnl"><code class="xref py py-func docutils literal notranslate"><span class="pre">spawn*p*</span></code></a> if the environment doesn’t have a <code class="docutils literal notranslate"><span class="pre">'PATH'</span></code>
|
||
key. Also available via <a class="reference internal" href="os.path.html#module-os.path" title="os.path: Operations on pathnames."><code class="xref py py-mod docutils literal notranslate"><span class="pre">os.path</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.linesep">
|
||
<code class="descclassname">os.</code><code class="descname">linesep</code><a class="headerlink" href="#os.linesep" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>The string used to separate (or, rather, terminate) lines on the current
|
||
platform. This may be a single character, such as <code class="docutils literal notranslate"><span class="pre">'\n'</span></code> for POSIX, or
|
||
multiple characters, for example, <code class="docutils literal notranslate"><span class="pre">'\r\n'</span></code> for Windows. Do not use
|
||
<em>os.linesep</em> as a line terminator when writing files opened in text mode (the
|
||
default); use a single <code class="docutils literal notranslate"><span class="pre">'\n'</span></code> instead, on all platforms.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.devnull">
|
||
<code class="descclassname">os.</code><code class="descname">devnull</code><a class="headerlink" href="#os.devnull" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>The file path of the null device. For example: <code class="docutils literal notranslate"><span class="pre">'/dev/null'</span></code> for
|
||
POSIX, <code class="docutils literal notranslate"><span class="pre">'nul'</span></code> for Windows. Also available via <a class="reference internal" href="os.path.html#module-os.path" title="os.path: Operations on pathnames."><code class="xref py py-mod docutils literal notranslate"><span class="pre">os.path</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.RTLD_LAZY">
|
||
<code class="descclassname">os.</code><code class="descname">RTLD_LAZY</code><a class="headerlink" href="#os.RTLD_LAZY" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.RTLD_NOW">
|
||
<code class="descclassname">os.</code><code class="descname">RTLD_NOW</code><a class="headerlink" href="#os.RTLD_NOW" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.RTLD_GLOBAL">
|
||
<code class="descclassname">os.</code><code class="descname">RTLD_GLOBAL</code><a class="headerlink" href="#os.RTLD_GLOBAL" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.RTLD_LOCAL">
|
||
<code class="descclassname">os.</code><code class="descname">RTLD_LOCAL</code><a class="headerlink" href="#os.RTLD_LOCAL" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.RTLD_NODELETE">
|
||
<code class="descclassname">os.</code><code class="descname">RTLD_NODELETE</code><a class="headerlink" href="#os.RTLD_NODELETE" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.RTLD_NOLOAD">
|
||
<code class="descclassname">os.</code><code class="descname">RTLD_NOLOAD</code><a class="headerlink" href="#os.RTLD_NOLOAD" title="Permalink to this definition">¶</a></dt>
|
||
<dt id="os.RTLD_DEEPBIND">
|
||
<code class="descclassname">os.</code><code class="descname">RTLD_DEEPBIND</code><a class="headerlink" href="#os.RTLD_DEEPBIND" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Flags for use with the <a class="reference internal" href="sys.html#sys.setdlopenflags" title="sys.setdlopenflags"><code class="xref py py-func docutils literal notranslate"><span class="pre">setdlopenflags()</span></code></a> and
|
||
<a class="reference internal" href="sys.html#sys.getdlopenflags" title="sys.getdlopenflags"><code class="xref py py-func docutils literal notranslate"><span class="pre">getdlopenflags()</span></code></a> functions. See the Unix manual page
|
||
<em class="manpage">dlopen(3)</em> for what the different flags mean.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
</div>
|
||
<div class="section" id="random-numbers">
|
||
<h2>Random numbers<a class="headerlink" href="#random-numbers" title="Permalink to this headline">¶</a></h2>
|
||
<dl class="function">
|
||
<dt id="os.getrandom">
|
||
<code class="descclassname">os.</code><code class="descname">getrandom</code><span class="sig-paren">(</span><em>size</em>, <em>flags=0</em><span class="sig-paren">)</span><a class="headerlink" href="#os.getrandom" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Get up to <em>size</em> random bytes. The function can return less bytes than
|
||
requested.</p>
|
||
<p>These bytes can be used to seed user-space random number generators or for
|
||
cryptographic purposes.</p>
|
||
<p><code class="docutils literal notranslate"><span class="pre">getrandom()</span></code> relies on entropy gathered from device drivers and other
|
||
sources of environmental noise. Unnecessarily reading large quantities of
|
||
data will have a negative impact on other users of the <code class="docutils literal notranslate"><span class="pre">/dev/random</span></code> and
|
||
<code class="docutils literal notranslate"><span class="pre">/dev/urandom</span></code> devices.</p>
|
||
<p>The flags argument is a bit mask that can contain zero or more of the
|
||
following values ORed together: <a class="reference internal" href="#os.GRND_RANDOM" title="os.GRND_RANDOM"><code class="xref py py-data docutils literal notranslate"><span class="pre">os.GRND_RANDOM</span></code></a> and
|
||
<a class="reference internal" href="#os.GRND_NONBLOCK" title="os.GRND_NONBLOCK"><code class="xref py py-data docutils literal notranslate"><span class="pre">GRND_NONBLOCK</span></code></a>.</p>
|
||
<p>See also the <a class="reference external" href="http://man7.org/linux/man-pages/man2/getrandom.2.html">Linux getrandom() manual page</a>.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Linux 3.17 and newer.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.6.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="os.urandom">
|
||
<code class="descclassname">os.</code><code class="descname">urandom</code><span class="sig-paren">(</span><em>size</em><span class="sig-paren">)</span><a class="headerlink" href="#os.urandom" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return a string of <em>size</em> random bytes suitable for cryptographic use.</p>
|
||
<p>This function returns random bytes from an OS-specific randomness source. The
|
||
returned data should be unpredictable enough for cryptographic applications,
|
||
though its exact quality depends on the OS implementation.</p>
|
||
<p>On Linux, if the <code class="docutils literal notranslate"><span class="pre">getrandom()</span></code> syscall is available, it is used in
|
||
blocking mode: block until the system urandom entropy pool is initialized
|
||
(128 bits of entropy are collected by the kernel). See the <span class="target" id="index-42"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0524"><strong>PEP 524</strong></a> for
|
||
the rationale. On Linux, the <a class="reference internal" href="#os.getrandom" title="os.getrandom"><code class="xref py py-func docutils literal notranslate"><span class="pre">getrandom()</span></code></a> function can be used to get
|
||
random bytes in non-blocking mode (using the <a class="reference internal" href="#os.GRND_NONBLOCK" title="os.GRND_NONBLOCK"><code class="xref py py-data docutils literal notranslate"><span class="pre">GRND_NONBLOCK</span></code></a> flag) or
|
||
to poll until the system urandom entropy pool is initialized.</p>
|
||
<p>On a Unix-like system, random bytes are read from the <code class="docutils literal notranslate"><span class="pre">/dev/urandom</span></code>
|
||
device. If the <code class="docutils literal notranslate"><span class="pre">/dev/urandom</span></code> device is not available or not readable, the
|
||
<a class="reference internal" href="exceptions.html#NotImplementedError" title="NotImplementedError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">NotImplementedError</span></code></a> exception is raised.</p>
|
||
<p>On Windows, it will use <code class="docutils literal notranslate"><span class="pre">CryptGenRandom()</span></code>.</p>
|
||
<div class="admonition seealso">
|
||
<p class="admonition-title">See also</p>
|
||
<p>The <a class="reference internal" href="secrets.html#module-secrets" title="secrets: Generate secure random numbers for managing secrets."><code class="xref py py-mod docutils literal notranslate"><span class="pre">secrets</span></code></a> module provides higher level functions. For an
|
||
easy-to-use interface to the random number generator provided by your
|
||
platform, please see <a class="reference internal" href="random.html#random.SystemRandom" title="random.SystemRandom"><code class="xref py py-class docutils literal notranslate"><span class="pre">random.SystemRandom</span></code></a>.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6.0: </span>On Linux, <code class="docutils literal notranslate"><span class="pre">getrandom()</span></code> is now used in blocking mode to increase the
|
||
security.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.5.2: </span>On Linux, if the <code class="docutils literal notranslate"><span class="pre">getrandom()</span></code> syscall blocks (the urandom entropy pool
|
||
is not initialized yet), fall back on reading <code class="docutils literal notranslate"><span class="pre">/dev/urandom</span></code>.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.5: </span>On Linux 3.17 and newer, the <code class="docutils literal notranslate"><span class="pre">getrandom()</span></code> syscall is now used
|
||
when available. On OpenBSD 5.6 and newer, the C <code class="docutils literal notranslate"><span class="pre">getentropy()</span></code>
|
||
function is now used. These functions avoid the usage of an internal file
|
||
descriptor.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.GRND_NONBLOCK">
|
||
<code class="descclassname">os.</code><code class="descname">GRND_NONBLOCK</code><a class="headerlink" href="#os.GRND_NONBLOCK" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>By default, when reading from <code class="docutils literal notranslate"><span class="pre">/dev/random</span></code>, <a class="reference internal" href="#os.getrandom" title="os.getrandom"><code class="xref py py-func docutils literal notranslate"><span class="pre">getrandom()</span></code></a> blocks if
|
||
no random bytes are available, and when reading from <code class="docutils literal notranslate"><span class="pre">/dev/urandom</span></code>, it blocks
|
||
if the entropy pool has not yet been initialized.</p>
|
||
<p>If the <a class="reference internal" href="#os.GRND_NONBLOCK" title="os.GRND_NONBLOCK"><code class="xref py py-data docutils literal notranslate"><span class="pre">GRND_NONBLOCK</span></code></a> flag is set, then <a class="reference internal" href="#os.getrandom" title="os.getrandom"><code class="xref py py-func docutils literal notranslate"><span class="pre">getrandom()</span></code></a> does not
|
||
block in these cases, but instead immediately raises <a class="reference internal" href="exceptions.html#BlockingIOError" title="BlockingIOError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">BlockingIOError</span></code></a>.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.6.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="os.GRND_RANDOM">
|
||
<code class="descclassname">os.</code><code class="descname">GRND_RANDOM</code><a class="headerlink" href="#os.GRND_RANDOM" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>If this bit is set, then random bytes are drawn from the
|
||
<code class="docutils literal notranslate"><span class="pre">/dev/random</span></code> pool instead of the <code class="docutils literal notranslate"><span class="pre">/dev/urandom</span></code> pool.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.6.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
</div>
|
||
</div>
|
||
|
||
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
||
<div class="sphinxsidebarwrapper">
|
||
<h3><a href="../contents.html">Table of Contents</a></h3>
|
||
<ul>
|
||
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">os</span></code> — Miscellaneous operating system interfaces</a><ul>
|
||
<li><a class="reference internal" href="#file-names-command-line-arguments-and-environment-variables">File Names, Command Line Arguments, and Environment Variables</a></li>
|
||
<li><a class="reference internal" href="#process-parameters">Process Parameters</a></li>
|
||
<li><a class="reference internal" href="#file-object-creation">File Object Creation</a></li>
|
||
<li><a class="reference internal" href="#file-descriptor-operations">File Descriptor Operations</a><ul>
|
||
<li><a class="reference internal" href="#querying-the-size-of-a-terminal">Querying the size of a terminal</a></li>
|
||
<li><a class="reference internal" href="#inheritance-of-file-descriptors">Inheritance of File Descriptors</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#files-and-directories">Files and Directories</a><ul>
|
||
<li><a class="reference internal" href="#linux-extended-attributes">Linux extended attributes</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#process-management">Process Management</a></li>
|
||
<li><a class="reference internal" href="#interface-to-the-scheduler">Interface to the scheduler</a></li>
|
||
<li><a class="reference internal" href="#miscellaneous-system-information">Miscellaneous System Information</a></li>
|
||
<li><a class="reference internal" href="#random-numbers">Random numbers</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
<h4>Previous topic</h4>
|
||
<p class="topless"><a href="allos.html"
|
||
title="previous chapter">Generic Operating System Services</a></p>
|
||
<h4>Next topic</h4>
|
||
<p class="topless"><a href="io.html"
|
||
title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">io</span></code> — Core tools for working with streams</a></p>
|
||
<div role="note" aria-label="source link">
|
||
<h3>This Page</h3>
|
||
<ul class="this-page-menu">
|
||
<li><a href="../bugs.html">Report a Bug</a></li>
|
||
<li>
|
||
<a href="https://github.com/python/cpython/blob/3.7/Doc/library/os.rst"
|
||
rel="nofollow">Show Source
|
||
</a>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="clearer"></div>
|
||
</div>
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<h3>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="General Index"
|
||
>index</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python Module Index"
|
||
>modules</a> |</li>
|
||
<li class="right" >
|
||
<a href="io.html" title="io — Core tools for working with streams"
|
||
>next</a> |</li>
|
||
<li class="right" >
|
||
<a href="allos.html" title="Generic Operating System Services"
|
||
>previous</a> |</li>
|
||
<li><img src="../_static/py.png" alt=""
|
||
style="vertical-align: middle; margin-top: -1px"/></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li>
|
||
<span class="language_switcher_placeholder">en</span>
|
||
<span class="version_switcher_placeholder">3.7.4</span>
|
||
<a href="../index.html">Documentation </a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>
|
||
<li class="nav-item nav-item-2"><a href="allos.html" >Generic Operating System Services</a> »</li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" style="display: none" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="Quick search" type="text" name="q" />
|
||
<input type="submit" value="Go" />
|
||
<input type="hidden" name="check_keywords" value="yes" />
|
||
<input type="hidden" name="area" value="default" />
|
||
</form>
|
||
</div>
|
||
<script type="text/javascript">$('.inline-search').show(0);</script>
|
||
|
|
||
</li>
|
||
|
||
</ul>
|
||
</div>
|
||
<div class="footer">
|
||
© <a href="../copyright.html">Copyright</a> 2001-2019, Python Software Foundation.
|
||
<br />
|
||
The Python Software Foundation is a non-profit corporation.
|
||
<a href="https://www.python.org/psf/donations/">Please donate.</a>
|
||
<br />
|
||
Last updated on Jul 13, 2019.
|
||
<a href="../bugs.html">Found a bug</a>?
|
||
<br />
|
||
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.0.1.
|
||
</div>
|
||
|
||
</body>
|
||
</html> |