Home | History | Annotate | Download | only in library
      1 :mod:`os` --- Miscellaneous operating system interfaces
      2 =======================================================
      3 
      4 .. module:: os
      5    :synopsis: Miscellaneous operating system interfaces.
      6 
      7 **Source code:** :source:`Lib/os.py`
      8 
      9 --------------
     10 
     11 This module provides a portable way of using operating system dependent
     12 functionality.  If you just want to read or write a file see :func:`open`, if
     13 you want to manipulate paths, see the :mod:`os.path` module, and if you want to
     14 read all the lines in all the files on the command line see the :mod:`fileinput`
     15 module.  For creating temporary files and directories see the :mod:`tempfile`
     16 module, and for high-level file and directory handling see the :mod:`shutil`
     17 module.
     18 
     19 Notes on the availability of these functions:
     20 
     21 * The design of all built-in operating system dependent modules of Python is
     22   such that as long as the same functionality is available, it uses the same
     23   interface; for example, the function ``os.stat(path)`` returns stat
     24   information about *path* in the same format (which happens to have originated
     25   with the POSIX interface).
     26 
     27 * Extensions peculiar to a particular operating system are also available
     28   through the :mod:`os` module, but using them is of course a threat to
     29   portability.
     30 
     31 * All functions accepting path or file names accept both bytes and string
     32   objects, and result in an object of the same type, if a path or file name is
     33   returned.
     34 
     35 * An "Availability: Unix" note means that this function is commonly found on
     36   Unix systems.  It does not make any claims about its existence on a specific
     37   operating system.
     38 
     39 * If not separately noted, all functions that claim "Availability: Unix" are
     40   supported on Mac OS X, which builds on a Unix core.
     41 
     42 .. Availability notes get their own line and occur at the end of the function
     43 .. documentation.
     44 
     45 .. note::
     46 
     47    All functions in this module raise :exc:`OSError` in the case of invalid or
     48    inaccessible file names and paths, or other arguments that have the correct
     49    type, but are not accepted by the operating system.
     50 
     51 .. exception:: error
     52 
     53    An alias for the built-in :exc:`OSError` exception.
     54 
     55 
     56 .. data:: name
     57 
     58    The name of the operating system dependent module imported.  The following
     59    names have currently been registered: ``'posix'``, ``'nt'``,
     60    ``'java'``.
     61 
     62    .. seealso::
     63       :attr:`sys.platform` has a finer granularity.  :func:`os.uname` gives
     64       system-dependent version information.
     65 
     66       The :mod:`platform` module provides detailed checks for the
     67       system's identity.
     68 
     69 
     70 .. _os-filenames:
     71 .. _filesystem-encoding:
     72 
     73 File Names, Command Line Arguments, and Environment Variables
     74 -------------------------------------------------------------
     75 
     76 In Python, file names, command line arguments, and environment variables are
     77 represented using the string type. On some systems, decoding these strings to
     78 and from bytes is necessary before passing them to the operating system. Python
     79 uses the file system encoding to perform this conversion (see
     80 :func:`sys.getfilesystemencoding`).
     81 
     82 .. versionchanged:: 3.1
     83    On some systems, conversion using the file system encoding may fail. In this
     84    case, Python uses the :ref:`surrogateescape encoding error handler
     85    <surrogateescape>`, which means that undecodable bytes are replaced by a
     86    Unicode character U+DCxx on decoding, and these are again translated to the
     87    original byte on encoding.
     88 
     89 
     90 The file system encoding must guarantee to successfully decode all bytes
     91 below 128. If the file system encoding fails to provide this guarantee, API
     92 functions may raise UnicodeErrors.
     93 
     94 
     95 .. _os-procinfo:
     96 
     97 Process Parameters
     98 ------------------
     99 
    100 These functions and data items provide information and operate on the current
    101 process and user.
    102 
    103 
    104 .. function:: ctermid()
    105 
    106    Return the filename corresponding to the controlling terminal of the process.
    107 
    108    Availability: Unix.
    109 
    110 
    111 .. data:: environ
    112 
    113    A :term:`mapping` object representing the string environment. For example,
    114    ``environ['HOME']`` is the pathname of your home directory (on some platforms),
    115    and is equivalent to ``getenv("HOME")`` in C.
    116 
    117    This mapping is captured the first time the :mod:`os` module is imported,
    118    typically during Python startup as part of processing :file:`site.py`.  Changes
    119    to the environment made after this time are not reflected in ``os.environ``,
    120    except for changes made by modifying ``os.environ`` directly.
    121 
    122    If the platform supports the :func:`putenv` function, this mapping may be used
    123    to modify the environment as well as query the environment.  :func:`putenv` will
    124    be called automatically when the mapping is modified.
    125 
    126    On Unix, keys and values use :func:`sys.getfilesystemencoding` and
    127    ``'surrogateescape'`` error handler. Use :data:`environb` if you would like
    128    to use a different encoding.
    129 
    130    .. note::
    131 
    132       Calling :func:`putenv` directly does not change ``os.environ``, so it's better
    133       to modify ``os.environ``.
    134 
    135    .. note::
    136 
    137       On some platforms, including FreeBSD and Mac OS X, setting ``environ`` may
    138       cause memory leaks.  Refer to the system documentation for
    139       :c:func:`putenv`.
    140 
    141    If :func:`putenv` is not provided, a modified copy of this mapping  may be
    142    passed to the appropriate process-creation functions to cause  child processes
    143    to use a modified environment.
    144 
    145    If the platform supports the :func:`unsetenv` function, you can delete items in
    146    this mapping to unset environment variables. :func:`unsetenv` will be called
    147    automatically when an item is deleted from ``os.environ``, and when
    148    one of the :meth:`pop` or :meth:`clear` methods is called.
    149 
    150 
    151 .. data:: environb
    152 
    153    Bytes version of :data:`environ`: a :term:`mapping` object representing the
    154    environment as byte strings. :data:`environ` and :data:`environb` are
    155    synchronized (modify :data:`environb` updates :data:`environ`, and vice
    156    versa).
    157 
    158    :data:`environb` is only available if :data:`supports_bytes_environ` is
    159    True.
    160 
    161    .. versionadded:: 3.2
    162 
    163 
    164 .. function:: chdir(path)
    165               fchdir(fd)
    166               getcwd()
    167    :noindex:
    168 
    169    These functions are described in :ref:`os-file-dir`.
    170 
    171 
    172 .. function:: fsencode(filename)
    173 
    174    Encode :term:`path-like <path-like object>` *filename* to the filesystem
    175    encoding with ``'surrogateescape'`` error handler, or ``'strict'`` on
    176    Windows; return :class:`bytes` unchanged.
    177 
    178    :func:`fsdecode` is the reverse function.
    179 
    180    .. versionadded:: 3.2
    181 
    182    .. versionchanged:: 3.6
    183       Support added to accept objects implementing the :class:`os.PathLike`
    184       interface.
    185 
    186 
    187 .. function:: fsdecode(filename)
    188 
    189    Decode the :term:`path-like <path-like object>` *filename* from the
    190    filesystem encoding with ``'surrogateescape'`` error handler, or ``'strict'``
    191    on Windows; return :class:`str` unchanged.
    192 
    193    :func:`fsencode` is the reverse function.
    194 
    195    .. versionadded:: 3.2
    196 
    197    .. versionchanged:: 3.6
    198       Support added to accept objects implementing the :class:`os.PathLike`
    199       interface.
    200 
    201 
    202 .. function:: fspath(path)
    203 
    204    Return the file system representation of the path.
    205 
    206    If :class:`str` or :class:`bytes` is passed in, it is returned unchanged.
    207    Otherwise :meth:`~os.PathLike.__fspath__` is called and its value is
    208    returned as long as it is a :class:`str` or :class:`bytes` object.
    209    In all other cases, :exc:`TypeError` is raised.
    210 
    211    .. versionadded:: 3.6
    212 
    213 
    214 .. class:: PathLike
    215 
    216    An :term:`abstract base class` for objects representing a file system path,
    217    e.g. :class:`pathlib.PurePath`.
    218 
    219    .. versionadded:: 3.6
    220 
    221    .. abstractmethod:: __fspath__()
    222 
    223       Return the file system path representation of the object.
    224 
    225       The method should only return a :class:`str` or :class:`bytes` object,
    226       with the preference being for :class:`str`.
    227 
    228 
    229 .. function:: getenv(key, default=None)
    230 
    231    Return the value of the environment variable *key* if it exists, or
    232    *default* if it doesn't. *key*, *default* and the result are str.
    233 
    234    On Unix, keys and values are decoded with :func:`sys.getfilesystemencoding`
    235    and ``'surrogateescape'`` error handler. Use :func:`os.getenvb` if you
    236    would like to use a different encoding.
    237 
    238    Availability: most flavors of Unix, Windows.
    239 
    240 
    241 .. function:: getenvb(key, default=None)
    242 
    243    Return the value of the environment variable *key* if it exists, or
    244    *default* if it doesn't. *key*, *default* and the result are bytes.
    245 
    246    :func:`getenvb` is only available if :data:`supports_bytes_environ`
    247    is True.
    248 
    249    Availability: most flavors of Unix.
    250 
    251    .. versionadded:: 3.2
    252 
    253 
    254 .. function:: get_exec_path(env=None)
    255 
    256    Returns the list of directories that will be searched for a named
    257    executable, similar to a shell, when launching a process.
    258    *env*, when specified, should be an environment variable dictionary
    259    to lookup the PATH in.
    260    By default, when *env* is ``None``, :data:`environ` is used.
    261 
    262    .. versionadded:: 3.2
    263 
    264 
    265 .. function:: getegid()
    266 
    267    Return the effective group id of the current process.  This corresponds to the
    268    "set id" bit on the file being executed in the current process.
    269 
    270    Availability: Unix.
    271 
    272 
    273 .. function:: geteuid()
    274 
    275    .. index:: single: user; effective id
    276 
    277    Return the current process's effective user id.
    278 
    279    Availability: Unix.
    280 
    281 
    282 .. function:: getgid()
    283 
    284    .. index:: single: process; group
    285 
    286    Return the real group id of the current process.
    287 
    288    Availability: Unix.
    289 
    290 
    291 .. function:: getgrouplist(user, group)
    292 
    293    Return list of group ids that *user* belongs to. If *group* is not in the
    294    list, it is included; typically, *group* is specified as the group ID
    295    field from the password record for *user*.
    296 
    297    Availability: Unix.
    298 
    299    .. versionadded:: 3.3
    300 
    301 
    302 .. function:: getgroups()
    303 
    304    Return list of supplemental group ids associated with the current process.
    305 
    306    Availability: Unix.
    307 
    308    .. note::
    309 
    310       On Mac OS X, :func:`getgroups` behavior differs somewhat from
    311       other Unix platforms. If the Python interpreter was built with a
    312       deployment target of :const:`10.5` or earlier, :func:`getgroups` returns
    313       the list of effective group ids associated with the current user process;
    314       this list is limited to a system-defined number of entries, typically 16,
    315       and may be modified by calls to :func:`setgroups` if suitably privileged.
    316       If built with a deployment target greater than :const:`10.5`,
    317       :func:`getgroups` returns the current group access list for the user
    318       associated with the effective user id of the process; the group access
    319       list may change over the lifetime of the process, it is not affected by
    320       calls to :func:`setgroups`, and its length is not limited to 16.  The
    321       deployment target value, :const:`MACOSX_DEPLOYMENT_TARGET`, can be
    322       obtained with :func:`sysconfig.get_config_var`.
    323 
    324 
    325 .. function:: getlogin()
    326 
    327    Return the name of the user logged in on the controlling terminal of the
    328    process.  For most purposes, it is more useful to use the environment
    329    variables :envvar:`LOGNAME` or :envvar:`USERNAME` to find out who the user
    330    is, or ``pwd.getpwuid(os.getuid())[0]`` to get the login name of the current
    331    real user id.
    332 
    333    Availability: Unix, Windows.
    334 
    335 
    336 .. function:: getpgid(pid)
    337 
    338    Return the process group id of the process with process id *pid*. If *pid* is 0,
    339    the process group id of the current process is returned.
    340 
    341    Availability: Unix.
    342 
    343 .. function:: getpgrp()
    344 
    345    .. index:: single: process; group
    346 
    347    Return the id of the current process group.
    348 
    349    Availability: Unix.
    350 
    351 
    352 .. function:: getpid()
    353 
    354    .. index:: single: process; id
    355 
    356    Return the current process id.
    357 
    358 
    359 .. function:: getppid()
    360 
    361    .. index:: single: process; id of parent
    362 
    363    Return the parent's process id.  When the parent process has exited, on Unix
    364    the id returned is the one of the init process (1), on Windows it is still
    365    the same id, which may be already reused by another process.
    366 
    367    Availability: Unix, Windows.
    368 
    369    .. versionchanged:: 3.2
    370       Added support for Windows.
    371 
    372 
    373 .. function:: getpriority(which, who)
    374 
    375    .. index:: single: process; scheduling priority
    376 
    377    Get program scheduling priority.  The value *which* is one of
    378    :const:`PRIO_PROCESS`, :const:`PRIO_PGRP`, or :const:`PRIO_USER`, and *who*
    379    is interpreted relative to *which* (a process identifier for
    380    :const:`PRIO_PROCESS`, process group identifier for :const:`PRIO_PGRP`, and a
    381    user ID for :const:`PRIO_USER`).  A zero value for *who* denotes
    382    (respectively) the calling process, the process group of the calling process,
    383    or the real user ID of the calling process.
    384 
    385    Availability: Unix.
    386 
    387    .. versionadded:: 3.3
    388 
    389 
    390 .. data:: PRIO_PROCESS
    391           PRIO_PGRP
    392           PRIO_USER
    393 
    394    Parameters for the :func:`getpriority` and :func:`setpriority` functions.
    395 
    396    Availability: Unix.
    397 
    398    .. versionadded:: 3.3
    399 
    400 
    401 .. function:: getresuid()
    402 
    403    Return a tuple (ruid, euid, suid) denoting the current process's
    404    real, effective, and saved user ids.
    405 
    406    Availability: Unix.
    407 
    408    .. versionadded:: 3.2
    409 
    410 
    411 .. function:: getresgid()
    412 
    413    Return a tuple (rgid, egid, sgid) denoting the current process's
    414    real, effective, and saved group ids.
    415 
    416    Availability: Unix.
    417 
    418    .. versionadded:: 3.2
    419 
    420 
    421 .. function:: getuid()
    422 
    423    .. index:: single: user; id
    424 
    425    Return the current process's real user id.
    426 
    427    Availability: Unix.
    428 
    429 
    430 .. function:: initgroups(username, gid)
    431 
    432    Call the system initgroups() to initialize the group access list with all of
    433    the groups of which the specified username is a member, plus the specified
    434    group id.
    435 
    436    Availability: Unix.
    437 
    438    .. versionadded:: 3.2
    439 
    440 
    441 .. function:: putenv(key, value)
    442 
    443    .. index:: single: environment variables; setting
    444 
    445    Set the environment variable named *key* to the string *value*.  Such
    446    changes to the environment affect subprocesses started with :func:`os.system`,
    447    :func:`popen` or :func:`fork` and :func:`execv`.
    448 
    449    Availability: most flavors of Unix, Windows.
    450 
    451    .. note::
    452 
    453       On some platforms, including FreeBSD and Mac OS X, setting ``environ`` may
    454       cause memory leaks. Refer to the system documentation for putenv.
    455 
    456    When :func:`putenv` is supported, assignments to items in ``os.environ`` are
    457    automatically translated into corresponding calls to :func:`putenv`; however,
    458    calls to :func:`putenv` don't update ``os.environ``, so it is actually
    459    preferable to assign to items of ``os.environ``.
    460 
    461 
    462 .. function:: setegid(egid)
    463 
    464    Set the current process's effective group id.
    465 
    466    Availability: Unix.
    467 
    468 
    469 .. function:: seteuid(euid)
    470 
    471    Set the current process's effective user id.
    472 
    473    Availability: Unix.
    474 
    475 
    476 .. function:: setgid(gid)
    477 
    478    Set the current process' group id.
    479 
    480    Availability: Unix.
    481 
    482 
    483 .. function:: setgroups(groups)
    484 
    485    Set the list of supplemental group ids associated with the current process to
    486    *groups*. *groups* must be a sequence, and each element must be an integer
    487    identifying a group. This operation is typically available only to the superuser.
    488 
    489    Availability: Unix.
    490 
    491    .. note:: On Mac OS X, the length of *groups* may not exceed the
    492       system-defined maximum number of effective group ids, typically 16.
    493       See the documentation for :func:`getgroups` for cases where it may not
    494       return the same group list set by calling setgroups().
    495 
    496 .. function:: setpgrp()
    497 
    498    Call the system call :c:func:`setpgrp` or ``setpgrp(0, 0)`` depending on
    499    which version is implemented (if any).  See the Unix manual for the semantics.
    500 
    501    Availability: Unix.
    502 
    503 
    504 .. function:: setpgid(pid, pgrp)
    505 
    506    Call the system call :c:func:`setpgid` to set the process group id of the
    507    process with id *pid* to the process group with id *pgrp*.  See the Unix manual
    508    for the semantics.
    509 
    510    Availability: Unix.
    511 
    512 
    513 .. function:: setpriority(which, who, priority)
    514 
    515    .. index:: single: process; scheduling priority
    516 
    517    Set program scheduling priority. The value *which* is one of
    518    :const:`PRIO_PROCESS`, :const:`PRIO_PGRP`, or :const:`PRIO_USER`, and *who*
    519    is interpreted relative to *which* (a process identifier for
    520    :const:`PRIO_PROCESS`, process group identifier for :const:`PRIO_PGRP`, and a
    521    user ID for :const:`PRIO_USER`). A zero value for *who* denotes
    522    (respectively) the calling process, the process group of the calling process,
    523    or the real user ID of the calling process.
    524    *priority* is a value in the range -20 to 19. The default priority is 0;
    525    lower priorities cause more favorable scheduling.
    526 
    527    Availability: Unix
    528 
    529    .. versionadded:: 3.3
    530 
    531 
    532 .. function:: setregid(rgid, egid)
    533 
    534    Set the current process's real and effective group ids.
    535 
    536    Availability: Unix.
    537 
    538 
    539 .. function:: setresgid(rgid, egid, sgid)
    540 
    541    Set the current process's real, effective, and saved group ids.
    542 
    543    Availability: Unix.
    544 
    545    .. versionadded:: 3.2
    546 
    547 
    548 .. function:: setresuid(ruid, euid, suid)
    549 
    550    Set the current process's real, effective, and saved user ids.
    551 
    552    Availability: Unix.
    553 
    554    .. versionadded:: 3.2
    555 
    556 
    557 .. function:: setreuid(ruid, euid)
    558 
    559    Set the current process's real and effective user ids.
    560 
    561    Availability: Unix.
    562 
    563 
    564 .. function:: getsid(pid)
    565 
    566    Call the system call :c:func:`getsid`.  See the Unix manual for the semantics.
    567 
    568    Availability: Unix.
    569 
    570 
    571 .. function:: setsid()
    572 
    573    Call the system call :c:func:`setsid`.  See the Unix manual for the semantics.
    574 
    575    Availability: Unix.
    576 
    577 
    578 .. function:: setuid(uid)
    579 
    580    .. index:: single: user; id, setting
    581 
    582    Set the current process's user id.
    583 
    584    Availability: Unix.
    585 
    586 
    587 .. placed in this section since it relates to errno.... a little weak
    588 .. function:: strerror(code)
    589 
    590    Return the error message corresponding to the error code in *code*.
    591    On platforms where :c:func:`strerror` returns ``NULL`` when given an unknown
    592    error number, :exc:`ValueError` is raised.
    593 
    594 
    595 .. data:: supports_bytes_environ
    596 
    597    ``True`` if the native OS type of the environment is bytes (eg. ``False`` on
    598    Windows).
    599 
    600    .. versionadded:: 3.2
    601 
    602 
    603 .. function:: umask(mask)
    604 
    605    Set the current numeric umask and return the previous umask.
    606 
    607 
    608 .. function:: uname()
    609 
    610    .. index::
    611       single: gethostname() (in module socket)
    612       single: gethostbyaddr() (in module socket)
    613 
    614    Returns information identifying the current operating system.
    615    The return value is an object with five attributes:
    616 
    617    * :attr:`sysname` - operating system name
    618    * :attr:`nodename` - name of machine on network (implementation-defined)
    619    * :attr:`release` - operating system release
    620    * :attr:`version` - operating system version
    621    * :attr:`machine` - hardware identifier
    622 
    623    For backwards compatibility, this object is also iterable, behaving
    624    like a five-tuple containing :attr:`sysname`, :attr:`nodename`,
    625    :attr:`release`, :attr:`version`, and :attr:`machine`
    626    in that order.
    627 
    628    Some systems truncate :attr:`nodename` to 8 characters or to the
    629    leading component; a better way to get the hostname is
    630    :func:`socket.gethostname`  or even
    631    ``socket.gethostbyaddr(socket.gethostname())``.
    632 
    633    Availability: recent flavors of Unix.
    634 
    635    .. versionchanged:: 3.3
    636       Return type changed from a tuple to a tuple-like object
    637       with named attributes.
    638 
    639 
    640 .. function:: unsetenv(key)
    641 
    642    .. index:: single: environment variables; deleting
    643 
    644    Unset (delete) the environment variable named *key*. Such changes to the
    645    environment affect subprocesses started with :func:`os.system`, :func:`popen` or
    646    :func:`fork` and :func:`execv`.
    647 
    648    When :func:`unsetenv` is supported, deletion of items in ``os.environ`` is
    649    automatically translated into a corresponding call to :func:`unsetenv`; however,
    650    calls to :func:`unsetenv` don't update ``os.environ``, so it is actually
    651    preferable to delete items of ``os.environ``.
    652 
    653    Availability: most flavors of Unix, Windows.
    654 
    655 
    656 .. _os-newstreams:
    657 
    658 File Object Creation
    659 --------------------
    660 
    661 This function creates new :term:`file objects <file object>`.  (See also
    662 :func:`~os.open` for opening file descriptors.)
    663 
    664 
    665 .. function:: fdopen(fd, *args, **kwargs)
    666 
    667    Return an open file object connected to the file descriptor *fd*.  This is an
    668    alias of the :func:`open` built-in function and accepts the same arguments.
    669    The only difference is that the first argument of :func:`fdopen` must always
    670    be an integer.
    671 
    672 
    673 .. _os-fd-ops:
    674 
    675 File Descriptor Operations
    676 --------------------------
    677 
    678 These functions operate on I/O streams referenced using file descriptors.
    679 
    680 File descriptors are small integers corresponding to a file that has been opened
    681 by the current process.  For example, standard input is usually file descriptor
    682 0, standard output is 1, and standard error is 2.  Further files opened by a
    683 process will then be assigned 3, 4, 5, and so forth.  The name "file descriptor"
    684 is slightly deceptive; on Unix platforms, sockets and pipes are also referenced
    685 by file descriptors.
    686 
    687 The :meth:`~io.IOBase.fileno` method can be used to obtain the file descriptor
    688 associated with a :term:`file object` when required.  Note that using the file
    689 descriptor directly will bypass the file object methods, ignoring aspects such
    690 as internal buffering of data.
    691 
    692 
    693 .. function:: close(fd)
    694 
    695    Close file descriptor *fd*.
    696 
    697    .. note::
    698 
    699       This function is intended for low-level I/O and must be applied to a file
    700       descriptor as returned by :func:`os.open` or :func:`pipe`.  To close a "file
    701       object" returned by the built-in function :func:`open` or by :func:`popen` or
    702       :func:`fdopen`, use its :meth:`~io.IOBase.close` method.
    703 
    704 
    705 .. function:: closerange(fd_low, fd_high)
    706 
    707    Close all file descriptors from *fd_low* (inclusive) to *fd_high* (exclusive),
    708    ignoring errors. Equivalent to (but much faster than)::
    709 
    710       for fd in range(fd_low, fd_high):
    711           try:
    712               os.close(fd)
    713           except OSError:
    714               pass
    715 
    716 
    717 .. function:: device_encoding(fd)
    718 
    719    Return a string describing the encoding of the device associated with *fd*
    720    if it is connected to a terminal; else return :const:`None`.
    721 
    722 
    723 .. function:: dup(fd)
    724 
    725    Return a duplicate of file descriptor *fd*. The new file descriptor is
    726    :ref:`non-inheritable <fd_inheritance>`.
    727 
    728    On Windows, when duplicating a standard stream (0: stdin, 1: stdout,
    729    2: stderr), the new file descriptor is :ref:`inheritable
    730    <fd_inheritance>`.
    731 
    732    .. versionchanged:: 3.4
    733       The new file descriptor is now non-inheritable.
    734 
    735 
    736 .. function:: dup2(fd, fd2, inheritable=True)
    737 
    738    Duplicate file descriptor *fd* to *fd2*, closing the latter first if necessary.
    739    The file descriptor *fd2* is :ref:`inheritable <fd_inheritance>` by default,
    740    or non-inheritable if *inheritable* is ``False``.
    741 
    742    .. versionchanged:: 3.4
    743       Add the optional *inheritable* parameter.
    744 
    745 
    746 .. function:: fchmod(fd, mode)
    747 
    748    Change the mode of the file given by *fd* to the numeric *mode*.  See the
    749    docs for :func:`chmod` for possible values of *mode*.  As of Python 3.3, this
    750    is equivalent to ``os.chmod(fd, mode)``.
    751 
    752    Availability: Unix.
    753 
    754 
    755 .. function:: fchown(fd, uid, gid)
    756 
    757    Change the owner and group id of the file given by *fd* to the numeric *uid*
    758    and *gid*.  To leave one of the ids unchanged, set it to -1.  See
    759    :func:`chown`.  As of Python 3.3, this is equivalent to ``os.chown(fd, uid,
    760    gid)``.
    761 
    762    Availability: Unix.
    763 
    764 
    765 .. function:: fdatasync(fd)
    766 
    767    Force write of file with filedescriptor *fd* to disk. Does not force update of
    768    metadata.
    769 
    770    Availability: Unix.
    771 
    772    .. note::
    773       This function is not available on MacOS.
    774 
    775 
    776 .. function:: fpathconf(fd, name)
    777 
    778    Return system configuration information relevant to an open file. *name*
    779    specifies the configuration value to retrieve; it may be a string which is the
    780    name of a defined system value; these names are specified in a number of
    781    standards (POSIX.1, Unix 95, Unix 98, and others).  Some platforms define
    782    additional names as well.  The names known to the host operating system are
    783    given in the ``pathconf_names`` dictionary.  For configuration variables not
    784    included in that mapping, passing an integer for *name* is also accepted.
    785 
    786    If *name* is a string and is not known, :exc:`ValueError` is raised.  If a
    787    specific value for *name* is not supported by the host system, even if it is
    788    included in ``pathconf_names``, an :exc:`OSError` is raised with
    789    :const:`errno.EINVAL` for the error number.
    790 
    791    As of Python 3.3, this is equivalent to ``os.pathconf(fd, name)``.
    792 
    793    Availability: Unix.
    794 
    795 
    796 .. function:: fstat(fd)
    797 
    798    Get the status of the file descriptor *fd*. Return a :class:`stat_result`
    799    object.
    800 
    801    As of Python 3.3, this is equivalent to ``os.stat(fd)``.
    802 
    803    .. seealso::
    804 
    805       The :func:`.stat` function.
    806 
    807 
    808 .. function:: fstatvfs(fd)
    809 
    810    Return information about the filesystem containing the file associated with
    811    file descriptor *fd*, like :func:`statvfs`.  As of Python 3.3, this is
    812    equivalent to ``os.statvfs(fd)``.
    813 
    814    Availability: Unix.
    815 
    816 
    817 .. function:: fsync(fd)
    818 
    819    Force write of file with filedescriptor *fd* to disk.  On Unix, this calls the
    820    native :c:func:`fsync` function; on Windows, the MS :c:func:`_commit` function.
    821 
    822    If you're starting with a buffered Python :term:`file object` *f*, first do
    823    ``f.flush()``, and then do ``os.fsync(f.fileno())``, to ensure that all internal
    824    buffers associated with *f* are written to disk.
    825 
    826    Availability: Unix, Windows.
    827 
    828 
    829 .. function:: ftruncate(fd, length)
    830 
    831    Truncate the file corresponding to file descriptor *fd*, so that it is at
    832    most *length* bytes in size.  As of Python 3.3, this is equivalent to
    833    ``os.truncate(fd, length)``.
    834 
    835    Availability: Unix, Windows.
    836 
    837    .. versionchanged:: 3.5
    838       Added support for Windows
    839 
    840 .. function:: get_blocking(fd)
    841 
    842    Get the blocking mode of the file descriptor: ``False`` if the
    843    :data:`O_NONBLOCK` flag is set, ``True`` if the flag is cleared.
    844 
    845    See also :func:`set_blocking` and :meth:`socket.socket.setblocking`.
    846 
    847    Availability: Unix.
    848 
    849    .. versionadded:: 3.5
    850 
    851 .. function:: isatty(fd)
    852 
    853    Return ``True`` if the file descriptor *fd* is open and connected to a
    854    tty(-like) device, else ``False``.
    855 
    856 
    857 .. function:: lockf(fd, cmd, len)
    858 
    859    Apply, test or remove a POSIX lock on an open file descriptor.
    860    *fd* is an open file descriptor.
    861    *cmd* specifies the command to use - one of :data:`F_LOCK`, :data:`F_TLOCK`,
    862    :data:`F_ULOCK` or :data:`F_TEST`.
    863    *len* specifies the section of the file to lock.
    864 
    865    Availability: Unix.
    866 
    867    .. versionadded:: 3.3
    868 
    869 
    870 .. data:: F_LOCK
    871           F_TLOCK
    872           F_ULOCK
    873           F_TEST
    874 
    875    Flags that specify what action :func:`lockf` will take.
    876 
    877    Availability: Unix.
    878 
    879    .. versionadded:: 3.3
    880 
    881 
    882 .. function:: lseek(fd, pos, how)
    883 
    884    Set the current position of file descriptor *fd* to position *pos*, modified
    885    by *how*: :const:`SEEK_SET` or ``0`` to set the position relative to the
    886    beginning of the file; :const:`SEEK_CUR` or ``1`` to set it relative to the
    887    current position; :const:`SEEK_END` or ``2`` to set it relative to the end of
    888    the file. Return the new cursor position in bytes, starting from the beginning.
    889 
    890 
    891 .. data:: SEEK_SET
    892           SEEK_CUR
    893           SEEK_END
    894 
    895    Parameters to the :func:`lseek` function. Their values are 0, 1, and 2,
    896    respectively.
    897 
    898    .. versionadded:: 3.3
    899       Some operating systems could support additional values, like
    900       :data:`os.SEEK_HOLE` or :data:`os.SEEK_DATA`.
    901 
    902 
    903 .. function:: open(path, flags, mode=0o777, *, dir_fd=None)
    904 
    905    Open the file *path* and set various flags according to *flags* and possibly
    906    its mode according to *mode*.  When computing *mode*, the current umask value
    907    is first masked out.  Return the file descriptor for the newly opened file.
    908    The new file descriptor is :ref:`non-inheritable <fd_inheritance>`.
    909 
    910    For a description of the flag and mode values, see the C run-time documentation;
    911    flag constants (like :const:`O_RDONLY` and :const:`O_WRONLY`) are defined in
    912    the :mod:`os` module.  In particular, on Windows adding
    913    :const:`O_BINARY` is needed to open files in binary mode.
    914 
    915    This function can support :ref:`paths relative to directory descriptors
    916    <dir_fd>` with the *dir_fd* parameter.
    917 
    918    .. versionchanged:: 3.4
    919       The new file descriptor is now non-inheritable.
    920 
    921    .. note::
    922 
    923       This function is intended for low-level I/O.  For normal usage, use the
    924       built-in function :func:`open`, which returns a :term:`file object` with
    925       :meth:`~file.read` and :meth:`~file.write` methods (and many more).  To
    926       wrap a file descriptor in a file object, use :func:`fdopen`.
    927 
    928    .. versionadded:: 3.3
    929       The *dir_fd* argument.
    930 
    931    .. versionchanged:: 3.5
    932       If the system call is interrupted and the signal handler does not raise an
    933       exception, the function now retries the system call instead of raising an
    934       :exc:`InterruptedError` exception (see :pep:`475` for the rationale).
    935 
    936    .. versionchanged:: 3.6
    937       Accepts a :term:`path-like object`.
    938 
    939 The following constants are options for the *flags* parameter to the
    940 :func:`~os.open` function.  They can be combined using the bitwise OR operator
    941 ``|``.  Some of them are not available on all platforms.  For descriptions of
    942 their availability and use, consult the :manpage:`open(2)` manual page on Unix
    943 or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windows.
    944 
    945 
    946 .. data:: O_RDONLY
    947           O_WRONLY
    948           O_RDWR
    949           O_APPEND
    950           O_CREAT
    951           O_EXCL
    952           O_TRUNC
    953 
    954    The above constants are available on Unix and Windows.
    955 
    956 
    957 .. data:: O_DSYNC
    958           O_RSYNC
    959           O_SYNC
    960           O_NDELAY
    961           O_NONBLOCK
    962           O_NOCTTY
    963           O_CLOEXEC
    964 
    965    The above constants are only available on Unix.
    966 
    967    .. versionchanged:: 3.3
    968       Add :data:`O_CLOEXEC` constant.
    969 
    970 .. data:: O_BINARY
    971           O_NOINHERIT
    972           O_SHORT_LIVED
    973           O_TEMPORARY
    974           O_RANDOM
    975           O_SEQUENTIAL
    976           O_TEXT
    977 
    978    The above constants are only available on Windows.
    979 
    980 
    981 .. data:: O_ASYNC
    982           O_DIRECT
    983           O_DIRECTORY
    984           O_NOFOLLOW
    985           O_NOATIME
    986           O_PATH
    987           O_TMPFILE
    988           O_SHLOCK
    989           O_EXLOCK
    990 
    991    The above constants are extensions and not present if they are not defined by
    992    the C library.
    993 
    994    .. versionchanged:: 3.4
    995       Add :data:`O_PATH` on systems that support it.
    996       Add :data:`O_TMPFILE`, only available on Linux Kernel 3.11
    997         or newer.
    998 
    999 
   1000 .. function:: openpty()
   1001 
   1002    .. index:: module: pty
   1003 
   1004    Open a new pseudo-terminal pair. Return a pair of file descriptors
   1005    ``(master, slave)`` for the pty and the tty, respectively. The new file
   1006    descriptors are :ref:`non-inheritable <fd_inheritance>`. For a (slightly) more
   1007    portable approach, use the :mod:`pty` module.
   1008 
   1009    Availability: some flavors of Unix.
   1010 
   1011    .. versionchanged:: 3.4
   1012       The new file descriptors are now non-inheritable.
   1013 
   1014 
   1015 .. function:: pipe()
   1016 
   1017    Create a pipe.  Return a pair of file descriptors ``(r, w)`` usable for
   1018    reading and writing, respectively. The new file descriptor is
   1019    :ref:`non-inheritable <fd_inheritance>`.
   1020 
   1021    Availability: Unix, Windows.
   1022 
   1023    .. versionchanged:: 3.4
   1024       The new file descriptors are now non-inheritable.
   1025 
   1026 
   1027 .. function:: pipe2(flags)
   1028 
   1029    Create a pipe with *flags* set atomically.
   1030    *flags* can be constructed by ORing together one or more of these values:
   1031    :data:`O_NONBLOCK`, :data:`O_CLOEXEC`.
   1032    Return a pair of file descriptors ``(r, w)`` usable for reading and writing,
   1033    respectively.
   1034 
   1035    Availability: some flavors of Unix.
   1036 
   1037    .. versionadded:: 3.3
   1038 
   1039 
   1040 .. function:: posix_fallocate(fd, offset, len)
   1041 
   1042    Ensures that enough disk space is allocated for the file specified by *fd*
   1043    starting from *offset* and continuing for *len* bytes.
   1044 
   1045    Availability: Unix.
   1046 
   1047    .. versionadded:: 3.3
   1048 
   1049 
   1050 .. function:: posix_fadvise(fd, offset, len, advice)
   1051 
   1052    Announces an intention to access data in a specific pattern thus allowing
   1053    the kernel to make optimizations.
   1054    The advice applies to the region of the file specified by *fd* starting at
   1055    *offset* and continuing for *len* bytes.
   1056    *advice* is one of :data:`POSIX_FADV_NORMAL`, :data:`POSIX_FADV_SEQUENTIAL`,
   1057    :data:`POSIX_FADV_RANDOM`, :data:`POSIX_FADV_NOREUSE`,
   1058    :data:`POSIX_FADV_WILLNEED` or :data:`POSIX_FADV_DONTNEED`.
   1059 
   1060    Availability: Unix.
   1061 
   1062    .. versionadded:: 3.3
   1063 
   1064 
   1065 .. data:: POSIX_FADV_NORMAL
   1066           POSIX_FADV_SEQUENTIAL
   1067           POSIX_FADV_RANDOM
   1068           POSIX_FADV_NOREUSE
   1069           POSIX_FADV_WILLNEED
   1070           POSIX_FADV_DONTNEED
   1071 
   1072    Flags that can be used in *advice* in :func:`posix_fadvise` that specify
   1073    the access pattern that is likely to be used.
   1074 
   1075    Availability: Unix.
   1076 
   1077    .. versionadded:: 3.3
   1078 
   1079 
   1080 .. function:: pread(fd, buffersize, offset)
   1081 
   1082    Read from a file descriptor, *fd*, at a position of *offset*. It will read up
   1083    to *buffersize* number of bytes. The file offset remains unchanged.
   1084 
   1085    Availability: Unix.
   1086 
   1087    .. versionadded:: 3.3
   1088 
   1089 
   1090 .. function:: pwrite(fd, str, offset)
   1091 
   1092    Write *bytestring* to a file descriptor, *fd*, from *offset*,
   1093    leaving the file offset unchanged.
   1094 
   1095    Availability: Unix.
   1096 
   1097    .. versionadded:: 3.3
   1098 
   1099 
   1100 .. function:: read(fd, n)
   1101 
   1102    Read at most *n* bytes from file descriptor *fd*. Return a bytestring containing the
   1103    bytes read.  If the end of the file referred to by *fd* has been reached, an
   1104    empty bytes object is returned.
   1105 
   1106    .. note::
   1107 
   1108       This function is intended for low-level I/O and must be applied to a file
   1109       descriptor as returned by :func:`os.open` or :func:`pipe`.  To read a
   1110       "file object" returned by the built-in function :func:`open` or by
   1111       :func:`popen` or :func:`fdopen`, or :data:`sys.stdin`, use its
   1112       :meth:`~file.read` or :meth:`~file.readline` methods.
   1113 
   1114    .. versionchanged:: 3.5
   1115       If the system call is interrupted and the signal handler does not raise an
   1116       exception, the function now retries the system call instead of raising an
   1117       :exc:`InterruptedError` exception (see :pep:`475` for the rationale).
   1118 
   1119 
   1120 .. function:: sendfile(out, in, offset, count)
   1121               sendfile(out, in, offset, count, [headers], [trailers], flags=0)
   1122 
   1123    Copy *count* bytes from file descriptor *in* to file descriptor *out*
   1124    starting at *offset*.
   1125    Return the number of bytes sent. When EOF is reached return 0.
   1126 
   1127    The first function notation is supported by all platforms that define
   1128    :func:`sendfile`.
   1129 
   1130    On Linux, if *offset* is given as ``None``, the bytes are read from the
   1131    current position of *in* and the position of *in* is updated.
   1132 
   1133    The second case may be used on Mac OS X and FreeBSD where *headers* and
   1134    *trailers* are arbitrary sequences of buffers that are written before and
   1135    after the data from *in* is written. It returns the same as the first case.
   1136 
   1137    On Mac OS X and FreeBSD, a value of 0 for *count* specifies to send until
   1138    the end of *in* is reached.
   1139 
   1140    All platforms support sockets as *out* file descriptor, and some platforms
   1141    allow other types (e.g. regular file, pipe) as well.
   1142 
   1143    Cross-platform applications should not use *headers*, *trailers* and *flags*
   1144    arguments.
   1145 
   1146    Availability: Unix.
   1147 
   1148    .. note::
   1149 
   1150       For a higher-level wrapper of :func:`sendfile`, see
   1151       :meth:`socket.socket.sendfile`.
   1152 
   1153    .. versionadded:: 3.3
   1154 
   1155 
   1156 .. function:: set_blocking(fd, blocking)
   1157 
   1158    Set the blocking mode of the specified file descriptor. Set the
   1159    :data:`O_NONBLOCK` flag if blocking is ``False``, clear the flag otherwise.
   1160 
   1161    See also :func:`get_blocking` and :meth:`socket.socket.setblocking`.
   1162 
   1163    Availability: Unix.
   1164 
   1165    .. versionadded:: 3.5
   1166 
   1167 
   1168 .. data:: SF_NODISKIO
   1169           SF_MNOWAIT
   1170           SF_SYNC
   1171 
   1172    Parameters to the :func:`sendfile` function, if the implementation supports
   1173    them.
   1174 
   1175    Availability: Unix.
   1176 
   1177    .. versionadded:: 3.3
   1178 
   1179 
   1180 .. function:: readv(fd, buffers)
   1181 
   1182    Read from a file descriptor *fd* into a number of mutable :term:`bytes-like
   1183    objects <bytes-like object>` *buffers*. :func:`~os.readv` will transfer data
   1184    into each buffer until it is full and then move on to the next buffer in the
   1185    sequence to hold the rest of the data. :func:`~os.readv` returns the total
   1186    number of bytes read (which may be less than the total capacity of all the
   1187    objects).
   1188 
   1189    Availability: Unix.
   1190 
   1191    .. versionadded:: 3.3
   1192 
   1193 
   1194 .. function:: tcgetpgrp(fd)
   1195 
   1196    Return the process group associated with the terminal given by *fd* (an open
   1197    file descriptor as returned by :func:`os.open`).
   1198 
   1199    Availability: Unix.
   1200 
   1201 
   1202 .. function:: tcsetpgrp(fd, pg)
   1203 
   1204    Set the process group associated with the terminal given by *fd* (an open file
   1205    descriptor as returned by :func:`os.open`) to *pg*.
   1206 
   1207    Availability: Unix.
   1208 
   1209 
   1210 .. function:: ttyname(fd)
   1211 
   1212    Return a string which specifies the terminal device associated with
   1213    file descriptor *fd*.  If *fd* is not associated with a terminal device, an
   1214    exception is raised.
   1215 
   1216    Availability: Unix.
   1217 
   1218 
   1219 .. function:: write(fd, str)
   1220 
   1221    Write the bytestring in *str* to file descriptor *fd*. Return the number of
   1222    bytes actually written.
   1223 
   1224    .. note::
   1225 
   1226       This function is intended for low-level I/O and must be applied to a file
   1227       descriptor as returned by :func:`os.open` or :func:`pipe`.  To write a "file
   1228       object" returned by the built-in function :func:`open` or by :func:`popen` or
   1229       :func:`fdopen`, or :data:`sys.stdout` or :data:`sys.stderr`, use its
   1230       :meth:`~file.write` method.
   1231 
   1232    .. versionchanged:: 3.5
   1233       If the system call is interrupted and the signal handler does not raise an
   1234       exception, the function now retries the system call instead of raising an
   1235       :exc:`InterruptedError` exception (see :pep:`475` for the rationale).
   1236 
   1237 
   1238 .. function:: writev(fd, buffers)
   1239 
   1240    Write the contents of *buffers* to file descriptor *fd*. *buffers* must be a
   1241    sequence of :term:`bytes-like objects <bytes-like object>`. Buffers are
   1242    processed in array order. Entire contents of first buffer is written before
   1243    proceeding to second, and so on. The operating system may set a limit
   1244    (sysconf() value SC_IOV_MAX) on the number of buffers that can be used.
   1245 
   1246    :func:`~os.writev` writes the contents of each object to the file descriptor
   1247    and returns the total number of bytes written.
   1248 
   1249    Availability: Unix.
   1250 
   1251    .. versionadded:: 3.3
   1252 
   1253 
   1254 .. _terminal-size:
   1255 
   1256 Querying the size of a terminal
   1257 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   1258 
   1259 .. versionadded:: 3.3
   1260 
   1261 .. function:: get_terminal_size(fd=STDOUT_FILENO)
   1262 
   1263    Return the size of the terminal window as ``(columns, lines)``,
   1264    tuple of type :class:`terminal_size`.
   1265 
   1266    The optional argument ``fd`` (default ``STDOUT_FILENO``, or standard
   1267    output) specifies which file descriptor should be queried.
   1268 
   1269    If the file descriptor is not connected to a terminal, an :exc:`OSError`
   1270    is raised.
   1271 
   1272    :func:`shutil.get_terminal_size` is the high-level function which
   1273    should normally be used, ``os.get_terminal_size`` is the low-level
   1274    implementation.
   1275 
   1276    Availability: Unix, Windows.
   1277 
   1278 .. class:: terminal_size
   1279 
   1280    A subclass of tuple, holding ``(columns, lines)`` of the terminal window size.
   1281 
   1282    .. attribute:: columns
   1283 
   1284       Width of the terminal window in characters.
   1285 
   1286    .. attribute:: lines
   1287 
   1288       Height of the terminal window in characters.
   1289 
   1290 
   1291 .. _fd_inheritance:
   1292 
   1293 Inheritance of File Descriptors
   1294 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   1295 
   1296 .. versionadded:: 3.4
   1297 
   1298 A file descriptor has an "inheritable" flag which indicates if the file descriptor
   1299 can be inherited by child processes.  Since Python 3.4, file descriptors
   1300 created by Python are non-inheritable by default.
   1301 
   1302 On UNIX, non-inheritable file descriptors are closed in child processes at the
   1303 execution of a new program, other file descriptors are inherited.
   1304 
   1305 On Windows, non-inheritable handles and file descriptors are closed in child
   1306 processes, except for standard streams (file descriptors 0, 1 and 2: stdin, stdout
   1307 and stderr), which are always inherited.  Using :func:`spawn\* <spawnl>` functions,
   1308 all inheritable handles and all inheritable file descriptors are inherited.
   1309 Using the :mod:`subprocess` module, all file descriptors except standard
   1310 streams are closed, and inheritable handles are only inherited if the
   1311 *close_fds* parameter is ``False``.
   1312 
   1313 .. function:: get_inheritable(fd)
   1314 
   1315    Get the "inheritable" flag of the specified file descriptor (a boolean).
   1316 
   1317 .. function:: set_inheritable(fd, inheritable)
   1318 
   1319    Set the "inheritable" flag of the specified file descriptor.
   1320 
   1321 .. function:: get_handle_inheritable(handle)
   1322 
   1323    Get the "inheritable" flag of the specified handle (a boolean).
   1324 
   1325    Availability: Windows.
   1326 
   1327 .. function:: set_handle_inheritable(handle, inheritable)
   1328 
   1329    Set the "inheritable" flag of the specified handle.
   1330 
   1331    Availability: Windows.
   1332 
   1333 
   1334 .. _os-file-dir:
   1335 
   1336 Files and Directories
   1337 ---------------------
   1338 
   1339 On some Unix platforms, many of these functions support one or more of these
   1340 features:
   1341 
   1342 .. _path_fd:
   1343 
   1344 * **specifying a file descriptor:**
   1345   For some functions, the *path* argument can be not only a string giving a path
   1346   name, but also a file descriptor.  The function will then operate on the file
   1347   referred to by the descriptor.  (For POSIX systems, Python will call the
   1348   ``f...`` version of the function.)
   1349 
   1350   You can check whether or not *path* can be specified as a file descriptor on
   1351   your platform using :data:`os.supports_fd`.  If it is unavailable, using it
   1352   will raise a :exc:`NotImplementedError`.
   1353 
   1354   If the function also supports *dir_fd* or *follow_symlinks* arguments, it is
   1355   an error to specify one of those when supplying *path* as a file descriptor.
   1356 
   1357 .. _dir_fd:
   1358 
   1359 * **paths relative to directory descriptors:** If *dir_fd* is not ``None``, it
   1360   should be a file descriptor referring to a directory, and the path to operate
   1361   on should be relative; path will then be relative to that directory.  If the
   1362   path is absolute, *dir_fd* is ignored.  (For POSIX systems, Python will call
   1363   the ``...at`` or ``f...at`` version of the function.)
   1364 
   1365   You can check whether or not *dir_fd* is supported on your platform using
   1366   :data:`os.supports_dir_fd`.  If it is unavailable, using it will raise a
   1367   :exc:`NotImplementedError`.
   1368 
   1369 .. _follow_symlinks:
   1370 
   1371 * **not following symlinks:** If *follow_symlinks* is
   1372   ``False``, and the last element of the path to operate on is a symbolic link,
   1373   the function will operate on the symbolic link itself instead of the file the
   1374   link points to.  (For POSIX systems, Python will call the ``l...`` version of
   1375   the function.)
   1376 
   1377   You can check whether or not *follow_symlinks* is supported on your platform
   1378   using :data:`os.supports_follow_symlinks`.  If it is unavailable, using it
   1379   will raise a :exc:`NotImplementedError`.
   1380 
   1381 
   1382 
   1383 .. function:: access(path, mode, *, dir_fd=None, effective_ids=False, follow_symlinks=True)
   1384 
   1385    Use the real uid/gid to test for access to *path*.  Note that most operations
   1386    will use the effective uid/gid, therefore this routine can be used in a
   1387    suid/sgid environment to test if the invoking user has the specified access to
   1388    *path*.  *mode* should be :const:`F_OK` to test the existence of *path*, or it
   1389    can be the inclusive OR of one or more of :const:`R_OK`, :const:`W_OK`, and
   1390    :const:`X_OK` to test permissions.  Return :const:`True` if access is allowed,
   1391    :const:`False` if not. See the Unix man page :manpage:`access(2)` for more
   1392    information.
   1393 
   1394    This function can support specifying :ref:`paths relative to directory
   1395    descriptors <dir_fd>` and :ref:`not following symlinks <follow_symlinks>`.
   1396 
   1397    If *effective_ids* is ``True``, :func:`access` will perform its access
   1398    checks using the effective uid/gid instead of the real uid/gid.
   1399    *effective_ids* may not be supported on your platform; you can check whether
   1400    or not it is available using :data:`os.supports_effective_ids`.  If it is
   1401    unavailable, using it will raise a :exc:`NotImplementedError`.
   1402 
   1403    .. note::
   1404 
   1405       Using :func:`access` to check if a user is authorized to e.g. open a file
   1406       before actually doing so using :func:`open` creates a security hole,
   1407       because the user might exploit the short time interval between checking
   1408       and opening the file to manipulate it. It's preferable to use :term:`EAFP`
   1409       techniques. For example::
   1410 
   1411          if os.access("myfile", os.R_OK):
   1412              with open("myfile") as fp:
   1413                  return fp.read()
   1414          return "some default data"
   1415 
   1416       is better written as::
   1417 
   1418          try:
   1419              fp = open("myfile")
   1420          except PermissionError:
   1421              return "some default data"
   1422          else:
   1423              with fp:
   1424                  return fp.read()
   1425 
   1426    .. note::
   1427 
   1428       I/O operations may fail even when :func:`access` indicates that they would
   1429       succeed, particularly for operations on network filesystems which may have
   1430       permissions semantics beyond the usual POSIX permission-bit model.
   1431 
   1432    .. versionchanged:: 3.3
   1433       Added the *dir_fd*, *effective_ids*, and *follow_symlinks* parameters.
   1434 
   1435    .. versionchanged:: 3.6
   1436       Accepts a :term:`path-like object`.
   1437 
   1438 
   1439 .. data:: F_OK
   1440           R_OK
   1441           W_OK
   1442           X_OK
   1443 
   1444    Values to pass as the *mode* parameter of :func:`access` to test the
   1445    existence, readability, writability and executability of *path*,
   1446    respectively.
   1447 
   1448 
   1449 .. function:: chdir(path)
   1450 
   1451    .. index:: single: directory; changing
   1452 
   1453    Change the current working directory to *path*.
   1454 
   1455    This function can support :ref:`specifying a file descriptor <path_fd>`.  The
   1456    descriptor must refer to an opened directory, not an open file.
   1457 
   1458    .. versionadded:: 3.3
   1459       Added support for specifying *path* as a file descriptor
   1460       on some platforms.
   1461 
   1462    .. versionchanged:: 3.6
   1463       Accepts a :term:`path-like object`.
   1464 
   1465 
   1466 .. function:: chflags(path, flags, *, follow_symlinks=True)
   1467 
   1468    Set the flags of *path* to the numeric *flags*. *flags* may take a combination
   1469    (bitwise OR) of the following values (as defined in the :mod:`stat` module):
   1470 
   1471    * :data:`stat.UF_NODUMP`
   1472    * :data:`stat.UF_IMMUTABLE`
   1473    * :data:`stat.UF_APPEND`
   1474    * :data:`stat.UF_OPAQUE`
   1475    * :data:`stat.UF_NOUNLINK`
   1476    * :data:`stat.UF_COMPRESSED`
   1477    * :data:`stat.UF_HIDDEN`
   1478    * :data:`stat.SF_ARCHIVED`
   1479    * :data:`stat.SF_IMMUTABLE`
   1480    * :data:`stat.SF_APPEND`
   1481    * :data:`stat.SF_NOUNLINK`
   1482    * :data:`stat.SF_SNAPSHOT`
   1483 
   1484    This function can support :ref:`not following symlinks <follow_symlinks>`.
   1485 
   1486    Availability: Unix.
   1487 
   1488    .. versionadded:: 3.3
   1489       The *follow_symlinks* argument.
   1490 
   1491    .. versionchanged:: 3.6
   1492       Accepts a :term:`path-like object`.
   1493 
   1494 
   1495 .. function:: chmod(path, mode, *, dir_fd=None, follow_symlinks=True)
   1496 
   1497    Change the mode of *path* to the numeric *mode*. *mode* may take one of the
   1498    following values (as defined in the :mod:`stat` module) or bitwise ORed
   1499    combinations of them:
   1500 
   1501    * :data:`stat.S_ISUID`
   1502    * :data:`stat.S_ISGID`
   1503    * :data:`stat.S_ENFMT`
   1504    * :data:`stat.S_ISVTX`
   1505    * :data:`stat.S_IREAD`
   1506    * :data:`stat.S_IWRITE`
   1507    * :data:`stat.S_IEXEC`
   1508    * :data:`stat.S_IRWXU`
   1509    * :data:`stat.S_IRUSR`
   1510    * :data:`stat.S_IWUSR`
   1511    * :data:`stat.S_IXUSR`
   1512    * :data:`stat.S_IRWXG`
   1513    * :data:`stat.S_IRGRP`
   1514    * :data:`stat.S_IWGRP`
   1515    * :data:`stat.S_IXGRP`
   1516    * :data:`stat.S_IRWXO`
   1517    * :data:`stat.S_IROTH`
   1518    * :data:`stat.S_IWOTH`
   1519    * :data:`stat.S_IXOTH`
   1520 
   1521    This function can support :ref:`specifying a file descriptor <path_fd>`,
   1522    :ref:`paths relative to directory descriptors <dir_fd>` and :ref:`not
   1523    following symlinks <follow_symlinks>`.
   1524 
   1525    .. note::
   1526 
   1527       Although Windows supports :func:`chmod`, you can only set the file's
   1528       read-only flag with it (via the ``stat.S_IWRITE`` and ``stat.S_IREAD``
   1529       constants or a corresponding integer value).  All other bits are ignored.
   1530 
   1531    .. versionadded:: 3.3
   1532       Added support for specifying *path* as an open file descriptor,
   1533       and the *dir_fd* and *follow_symlinks* arguments.
   1534 
   1535    .. versionchanged:: 3.6
   1536       Accepts a :term:`path-like object`.
   1537 
   1538 
   1539 .. function:: chown(path, uid, gid, *, dir_fd=None, follow_symlinks=True)
   1540 
   1541    Change the owner and group id of *path* to the numeric *uid* and *gid*.  To
   1542    leave one of the ids unchanged, set it to -1.
   1543 
   1544    This function can support :ref:`specifying a file descriptor <path_fd>`,
   1545    :ref:`paths relative to directory descriptors <dir_fd>` and :ref:`not
   1546    following symlinks <follow_symlinks>`.
   1547 
   1548    See :func:`shutil.chown` for a higher-level function that accepts names in
   1549    addition to numeric ids.
   1550 
   1551    Availability: Unix.
   1552 
   1553    .. versionadded:: 3.3
   1554       Added support for specifying an open file descriptor for *path*,
   1555       and the *dir_fd* and *follow_symlinks* arguments.
   1556 
   1557    .. versionchanged:: 3.6
   1558       Supports a :term:`path-like object`.
   1559 
   1560 
   1561 .. function:: chroot(path)
   1562 
   1563    Change the root directory of the current process to *path*.
   1564 
   1565    Availability: Unix.
   1566 
   1567    .. versionchanged:: 3.6
   1568       Accepts a :term:`path-like object`.
   1569 
   1570 
   1571 .. function:: fchdir(fd)
   1572 
   1573    Change the current working directory to the directory represented by the file
   1574    descriptor *fd*.  The descriptor must refer to an opened directory, not an
   1575    open file.  As of Python 3.3, this is equivalent to ``os.chdir(fd)``.
   1576 
   1577    Availability: Unix.
   1578 
   1579 
   1580 .. function:: getcwd()
   1581 
   1582    Return a string representing the current working directory.
   1583 
   1584 
   1585 .. function:: getcwdb()
   1586 
   1587    Return a bytestring representing the current working directory.
   1588 
   1589 
   1590 .. function:: lchflags(path, flags)
   1591 
   1592    Set the flags of *path* to the numeric *flags*, like :func:`chflags`, but do
   1593    not follow symbolic links.  As of Python 3.3, this is equivalent to
   1594    ``os.chflags(path, flags, follow_symlinks=False)``.
   1595 
   1596    Availability: Unix.
   1597 
   1598    .. versionchanged:: 3.6
   1599       Accepts a :term:`path-like object`.
   1600 
   1601 
   1602 .. function:: lchmod(path, mode)
   1603 
   1604    Change the mode of *path* to the numeric *mode*. If path is a symlink, this
   1605    affects the symlink rather than the target.  See the docs for :func:`chmod`
   1606    for possible values of *mode*.  As of Python 3.3, this is equivalent to
   1607    ``os.chmod(path, mode, follow_symlinks=False)``.
   1608 
   1609    Availability: Unix.
   1610 
   1611    .. versionchanged:: 3.6
   1612       Accepts a :term:`path-like object`.
   1613 
   1614 .. function:: lchown(path, uid, gid)
   1615 
   1616    Change the owner and group id of *path* to the numeric *uid* and *gid*.  This
   1617    function will not follow symbolic links.  As of Python 3.3, this is equivalent
   1618    to ``os.chown(path, uid, gid, follow_symlinks=False)``.
   1619 
   1620    Availability: Unix.
   1621 
   1622    .. versionchanged:: 3.6
   1623       Accepts a :term:`path-like object`.
   1624 
   1625 
   1626 .. function:: link(src, dst, *, src_dir_fd=None, dst_dir_fd=None, follow_symlinks=True)
   1627 
   1628    Create a hard link pointing to *src* named *dst*.
   1629 
   1630    This function can support specifying *src_dir_fd* and/or *dst_dir_fd* to
   1631    supply :ref:`paths relative to directory descriptors <dir_fd>`, and :ref:`not
   1632    following symlinks <follow_symlinks>`.
   1633 
   1634    Availability: Unix, Windows.
   1635 
   1636    .. versionchanged:: 3.2
   1637       Added Windows support.
   1638 
   1639    .. versionadded:: 3.3
   1640       Added the *src_dir_fd*, *dst_dir_fd*, and *follow_symlinks* arguments.
   1641 
   1642    .. versionchanged:: 3.6
   1643       Accepts a :term:`path-like object` for *src* and *dst*.
   1644 
   1645 
   1646 .. function:: listdir(path='.')
   1647 
   1648    Return a list containing the names of the entries in the directory given by
   1649    *path*.  The list is in arbitrary order, and does not include the special
   1650    entries ``'.'`` and ``'..'`` even if they are present in the directory.
   1651 
   1652    *path* may be a :term:`path-like object`.  If *path* is of type ``bytes``
   1653    (directly or indirectly through the :class:`PathLike` interface),
   1654    the filenames returned will also be of type ``bytes``;
   1655    in all other circumstances, they will be of type ``str``.
   1656 
   1657    This function can also support :ref:`specifying a file descriptor
   1658    <path_fd>`; the file descriptor must refer to a directory.
   1659 
   1660    .. note::
   1661       To encode ``str`` filenames to ``bytes``, use :func:`~os.fsencode`.
   1662 
   1663    .. seealso::
   1664 
   1665       The :func:`scandir` function returns directory entries along with
   1666       file attribute information, giving better performance for many
   1667       common use cases.
   1668 
   1669    .. versionchanged:: 3.2
   1670       The *path* parameter became optional.
   1671 
   1672    .. versionadded:: 3.3
   1673       Added support for specifying an open file descriptor for *path*.
   1674 
   1675    .. versionchanged:: 3.6
   1676       Accepts a :term:`path-like object`.
   1677 
   1678 
   1679 .. function:: lstat(path, \*, dir_fd=None)
   1680 
   1681    Perform the equivalent of an :c:func:`lstat` system call on the given path.
   1682    Similar to :func:`~os.stat`, but does not follow symbolic links. Return a
   1683    :class:`stat_result` object.
   1684 
   1685    On platforms that do not support symbolic links, this is an alias for
   1686    :func:`~os.stat`.
   1687 
   1688    As of Python 3.3, this is equivalent to ``os.stat(path, dir_fd=dir_fd,
   1689    follow_symlinks=False)``.
   1690 
   1691    This function can also support :ref:`paths relative to directory descriptors
   1692    <dir_fd>`.
   1693 
   1694    .. seealso::
   1695 
   1696       The :func:`.stat` function.
   1697 
   1698    .. versionchanged:: 3.2
   1699       Added support for Windows 6.0 (Vista) symbolic links.
   1700 
   1701    .. versionchanged:: 3.3
   1702       Added the *dir_fd* parameter.
   1703 
   1704    .. versionchanged:: 3.6
   1705       Accepts a :term:`path-like object` for *src* and *dst*.
   1706 
   1707 
   1708 .. function:: mkdir(path, mode=0o777, *, dir_fd=None)
   1709 
   1710    Create a directory named *path* with numeric mode *mode*.
   1711 
   1712    If the directory already exists, :exc:`FileExistsError` is raised.
   1713 
   1714    .. _mkdir_modebits:
   1715 
   1716    On some systems, *mode* is ignored.  Where it is used, the current umask
   1717    value is first masked out.  If bits other than the last 9 (i.e. the last 3
   1718    digits of the octal representation of the *mode*) are set, their meaning is
   1719    platform-dependent.  On some platforms, they are ignored and you should call
   1720    :func:`chmod` explicitly to set them.
   1721 
   1722    This function can also support :ref:`paths relative to directory descriptors
   1723    <dir_fd>`.
   1724 
   1725    It is also possible to create temporary directories; see the
   1726    :mod:`tempfile` module's :func:`tempfile.mkdtemp` function.
   1727 
   1728    .. versionadded:: 3.3
   1729       The *dir_fd* argument.
   1730 
   1731    .. versionchanged:: 3.6
   1732       Accepts a :term:`path-like object`.
   1733 
   1734 
   1735 .. function:: makedirs(name, mode=0o777, exist_ok=False)
   1736 
   1737    .. index::
   1738       single: directory; creating
   1739       single: UNC paths; and os.makedirs()
   1740 
   1741    Recursive directory creation function.  Like :func:`mkdir`, but makes all
   1742    intermediate-level directories needed to contain the leaf directory.
   1743 
   1744    The *mode* parameter is passed to :func:`mkdir`; see :ref:`the mkdir()
   1745    description <mkdir_modebits>` for how it is interpreted.
   1746 
   1747    If *exist_ok* is ``False`` (the default), an :exc:`OSError` is raised if the
   1748    target directory already exists.
   1749 
   1750    .. note::
   1751 
   1752       :func:`makedirs` will become confused if the path elements to create
   1753       include :data:`pardir` (eg. ".." on UNIX systems).
   1754 
   1755    This function handles UNC paths correctly.
   1756 
   1757    .. versionadded:: 3.2
   1758       The *exist_ok* parameter.
   1759 
   1760    .. versionchanged:: 3.4.1
   1761 
   1762       Before Python 3.4.1, if *exist_ok* was ``True`` and the directory existed,
   1763       :func:`makedirs` would still raise an error if *mode* did not match the
   1764       mode of the existing directory. Since this behavior was impossible to
   1765       implement safely, it was removed in Python 3.4.1. See :issue:`21082`.
   1766 
   1767    .. versionchanged:: 3.6
   1768       Accepts a :term:`path-like object`.
   1769 
   1770 
   1771 .. function:: mkfifo(path, mode=0o666, *, dir_fd=None)
   1772 
   1773    Create a FIFO (a named pipe) named *path* with numeric mode *mode*.
   1774    The current umask value is first masked out from the mode.
   1775 
   1776    This function can also support :ref:`paths relative to directory descriptors
   1777    <dir_fd>`.
   1778 
   1779    FIFOs are pipes that can be accessed like regular files.  FIFOs exist until they
   1780    are deleted (for example with :func:`os.unlink`). Generally, FIFOs are used as
   1781    rendezvous between "client" and "server" type processes: the server opens the
   1782    FIFO for reading, and the client opens it for writing.  Note that :func:`mkfifo`
   1783    doesn't open the FIFO --- it just creates the rendezvous point.
   1784 
   1785    Availability: Unix.
   1786 
   1787    .. versionadded:: 3.3
   1788       The *dir_fd* argument.
   1789 
   1790    .. versionchanged:: 3.6
   1791       Accepts a :term:`path-like object`.
   1792 
   1793 
   1794 .. function:: mknod(path, mode=0o600, device=0, *, dir_fd=None)
   1795 
   1796    Create a filesystem node (file, device special file or named pipe) named
   1797    *path*. *mode* specifies both the permissions to use and the type of node
   1798    to be created, being combined (bitwise OR) with one of ``stat.S_IFREG``,
   1799    ``stat.S_IFCHR``, ``stat.S_IFBLK``, and ``stat.S_IFIFO`` (those constants are
   1800    available in :mod:`stat`).  For ``stat.S_IFCHR`` and ``stat.S_IFBLK``,
   1801    *device* defines the newly created device special file (probably using
   1802    :func:`os.makedev`), otherwise it is ignored.
   1803 
   1804    This function can also support :ref:`paths relative to directory descriptors
   1805    <dir_fd>`.
   1806 
   1807    Availability: Unix.
   1808 
   1809    .. versionadded:: 3.3
   1810       The *dir_fd* argument.
   1811 
   1812    .. versionchanged:: 3.6
   1813       Accepts a :term:`path-like object`.
   1814 
   1815 
   1816 .. function:: major(device)
   1817 
   1818    Extract the device major number from a raw device number (usually the
   1819    :attr:`st_dev` or :attr:`st_rdev` field from :c:type:`stat`).
   1820 
   1821 
   1822 .. function:: minor(device)
   1823 
   1824    Extract the device minor number from a raw device number (usually the
   1825    :attr:`st_dev` or :attr:`st_rdev` field from :c:type:`stat`).
   1826 
   1827 
   1828 .. function:: makedev(major, minor)
   1829 
   1830    Compose a raw device number from the major and minor device numbers.
   1831 
   1832 
   1833 .. function:: pathconf(path, name)
   1834 
   1835    Return system configuration information relevant to a named file. *name*
   1836    specifies the configuration value to retrieve; it may be a string which is the
   1837    name of a defined system value; these names are specified in a number of
   1838    standards (POSIX.1, Unix 95, Unix 98, and others).  Some platforms define
   1839    additional names as well.  The names known to the host operating system are
   1840    given in the ``pathconf_names`` dictionary.  For configuration variables not
   1841    included in that mapping, passing an integer for *name* is also accepted.
   1842 
   1843    If *name* is a string and is not known, :exc:`ValueError` is raised.  If a
   1844    specific value for *name* is not supported by the host system, even if it is
   1845    included in ``pathconf_names``, an :exc:`OSError` is raised with
   1846    :const:`errno.EINVAL` for the error number.
   1847 
   1848    This function can support :ref:`specifying a file descriptor
   1849    <path_fd>`.
   1850 
   1851    Availability: Unix.
   1852 
   1853    .. versionchanged:: 3.6
   1854       Accepts a :term:`path-like object`.
   1855 
   1856 
   1857 .. data:: pathconf_names
   1858 
   1859    Dictionary mapping names accepted by :func:`pathconf` and :func:`fpathconf` to
   1860    the integer values defined for those names by the host operating system.  This
   1861    can be used to determine the set of names known to the system.
   1862 
   1863    Availability: Unix.
   1864 
   1865 
   1866 .. function:: readlink(path, *, dir_fd=None)
   1867 
   1868    Return a string representing the path to which the symbolic link points.  The
   1869    result may be either an absolute or relative pathname; if it is relative, it
   1870    may be converted to an absolute pathname using
   1871    ``os.path.join(os.path.dirname(path), result)``.
   1872 
   1873    If the *path* is a string object (directly or indirectly through a
   1874    :class:`PathLike` interface), the result will also be a string object,
   1875    and the call may raise a UnicodeDecodeError. If the *path* is a bytes
   1876    object (direct or indirectly), the result will be a bytes object.
   1877 
   1878    This function can also support :ref:`paths relative to directory descriptors
   1879    <dir_fd>`.
   1880 
   1881    Availability: Unix, Windows
   1882 
   1883    .. versionchanged:: 3.2
   1884       Added support for Windows 6.0 (Vista) symbolic links.
   1885 
   1886    .. versionadded:: 3.3
   1887       The *dir_fd* argument.
   1888 
   1889    .. versionchanged:: 3.6
   1890       Accepts a :term:`path-like object`.
   1891 
   1892 
   1893 .. function:: remove(path, *, dir_fd=None)
   1894 
   1895    Remove (delete) the file *path*.  If *path* is a directory, :exc:`OSError` is
   1896    raised.  Use :func:`rmdir` to remove directories.
   1897 
   1898    This function can support :ref:`paths relative to directory descriptors
   1899    <dir_fd>`.
   1900 
   1901    On Windows, attempting to remove a file that is in use causes an exception to
   1902    be raised; on Unix, the directory entry is removed but the storage allocated
   1903    to the file is not made available until the original file is no longer in use.
   1904 
   1905    This function is semantically identical to :func:`unlink`.
   1906 
   1907    .. versionadded:: 3.3
   1908       The *dir_fd* argument.
   1909 
   1910    .. versionchanged:: 3.6
   1911       Accepts a :term:`path-like object`.
   1912 
   1913 
   1914 .. function:: removedirs(name)
   1915 
   1916    .. index:: single: directory; deleting
   1917 
   1918    Remove directories recursively.  Works like :func:`rmdir` except that, if the
   1919    leaf directory is successfully removed, :func:`removedirs`  tries to
   1920    successively remove every parent directory mentioned in  *path* until an error
   1921    is raised (which is ignored, because it generally means that a parent directory
   1922    is not empty). For example, ``os.removedirs('foo/bar/baz')`` will first remove
   1923    the directory ``'foo/bar/baz'``, and then remove ``'foo/bar'`` and ``'foo'`` if
   1924    they are empty. Raises :exc:`OSError` if the leaf directory could not be
   1925    successfully removed.
   1926 
   1927    .. versionchanged:: 3.6
   1928       Accepts a :term:`path-like object`.
   1929 
   1930 
   1931 .. function:: rename(src, dst, *, src_dir_fd=None, dst_dir_fd=None)
   1932 
   1933    Rename the file or directory *src* to *dst*.  If *dst* is a directory,
   1934    :exc:`OSError` will be raised.  On Unix, if *dst* exists and is a file, it will
   1935    be replaced silently if the user has permission.  The operation may fail on some
   1936    Unix flavors if *src* and *dst* are on different filesystems.  If successful,
   1937    the renaming will be an atomic operation (this is a POSIX requirement).  On
   1938    Windows, if *dst* already exists, :exc:`OSError` will be raised even if it is a
   1939    file.
   1940 
   1941    This function can support specifying *src_dir_fd* and/or *dst_dir_fd* to
   1942    supply :ref:`paths relative to directory descriptors <dir_fd>`.
   1943 
   1944    If you want cross-platform overwriting of the destination, use :func:`replace`.
   1945 
   1946    .. versionadded:: 3.3
   1947       The *src_dir_fd* and *dst_dir_fd* arguments.
   1948 
   1949    .. versionchanged:: 3.6
   1950       Accepts a :term:`path-like object` for *src* and *dst*.
   1951 
   1952 
   1953 .. function:: renames(old, new)
   1954 
   1955    Recursive directory or file renaming function. Works like :func:`rename`, except
   1956    creation of any intermediate directories needed to make the new pathname good is
   1957    attempted first. After the rename, directories corresponding to rightmost path
   1958    segments of the old name will be pruned away using :func:`removedirs`.
   1959 
   1960    .. note::
   1961 
   1962       This function can fail with the new directory structure made if you lack
   1963       permissions needed to remove the leaf directory or file.
   1964 
   1965    .. versionchanged:: 3.6
   1966       Accepts a :term:`path-like object` for *old* and *new*.
   1967 
   1968 
   1969 .. function:: replace(src, dst, *, src_dir_fd=None, dst_dir_fd=None)
   1970 
   1971    Rename the file or directory *src* to *dst*.  If *dst* is a directory,
   1972    :exc:`OSError` will be raised.  If *dst* exists and is a file, it will
   1973    be replaced silently if the user has permission.  The operation may fail
   1974    if *src* and *dst* are on different filesystems.  If successful,
   1975    the renaming will be an atomic operation (this is a POSIX requirement).
   1976 
   1977    This function can support specifying *src_dir_fd* and/or *dst_dir_fd* to
   1978    supply :ref:`paths relative to directory descriptors <dir_fd>`.
   1979 
   1980    .. versionadded:: 3.3
   1981 
   1982    .. versionchanged:: 3.6
   1983       Accepts a :term:`path-like object` for *src* and *dst*.
   1984 
   1985 
   1986 .. function:: rmdir(path, *, dir_fd=None)
   1987 
   1988    Remove (delete) the directory *path*.  Only works when the directory is
   1989    empty, otherwise, :exc:`OSError` is raised.  In order to remove whole
   1990    directory trees, :func:`shutil.rmtree` can be used.
   1991 
   1992    This function can support :ref:`paths relative to directory descriptors
   1993    <dir_fd>`.
   1994 
   1995    .. versionadded:: 3.3
   1996       The *dir_fd* parameter.
   1997 
   1998    .. versionchanged:: 3.6
   1999       Accepts a :term:`path-like object`.
   2000 
   2001 
   2002 .. function:: scandir(path='.')
   2003 
   2004    Return an iterator of :class:`os.DirEntry` objects corresponding to the
   2005    entries in the directory given by *path*. The entries are yielded in
   2006    arbitrary order, and the special entries ``'.'`` and ``'..'`` are not
   2007    included.
   2008 
   2009    Using :func:`scandir` instead of :func:`listdir` can significantly
   2010    increase the performance of code that also needs file type or file
   2011    attribute information, because :class:`os.DirEntry` objects expose this
   2012    information if the operating system provides it when scanning a directory.
   2013    All :class:`os.DirEntry` methods may perform a system call, but
   2014    :func:`~os.DirEntry.is_dir` and :func:`~os.DirEntry.is_file` usually only
   2015    require a system call for symbolic links; :func:`os.DirEntry.stat`
   2016    always requires a system call on Unix but only requires one for
   2017    symbolic links on Windows.
   2018 
   2019    *path* may be a :term:`path-like object`.  If *path* is of type ``bytes``
   2020    (directly or indirectly through the :class:`PathLike` interface),
   2021    the type of the :attr:`~os.DirEntry.name` and :attr:`~os.DirEntry.path`
   2022    attributes of each :class:`os.DirEntry` will be ``bytes``; in all other
   2023    circumstances, they will be of type ``str``.
   2024 
   2025    The :func:`scandir` iterator supports the :term:`context manager` protocol
   2026    and has the following method:
   2027 
   2028    .. method:: scandir.close()
   2029 
   2030       Close the iterator and free acquired resources.
   2031 
   2032       This is called automatically when the iterator is exhausted or garbage
   2033       collected, or when an error happens during iterating.  However it
   2034       is advisable to call it explicitly or use the :keyword:`with`
   2035       statement.
   2036 
   2037       .. versionadded:: 3.6
   2038 
   2039    The following example shows a simple use of :func:`scandir` to display all
   2040    the files (excluding directories) in the given *path* that don't start with
   2041    ``'.'``. The ``entry.is_file()`` call will generally not make an additional
   2042    system call::
   2043 
   2044       with os.scandir(path) as it:
   2045           for entry in it:
   2046               if not entry.name.startswith('.') and entry.is_file():
   2047                   print(entry.name)
   2048 
   2049    .. note::
   2050 
   2051       On Unix-based systems, :func:`scandir` uses the system's
   2052       `opendir() <http://pubs.opengroup.org/onlinepubs/009695399/functions/opendir.html>`_
   2053       and
   2054       `readdir() <http://pubs.opengroup.org/onlinepubs/009695399/functions/readdir_r.html>`_
   2055       functions. On Windows, it uses the Win32
   2056       `FindFirstFileW <https://msdn.microsoft.com/en-us/library/windows/desktop/aa364418(v=vs.85).aspx>`_
   2057       and
   2058       `FindNextFileW <https://msdn.microsoft.com/en-us/library/windows/desktop/aa364428(v=vs.85).aspx>`_
   2059       functions.
   2060 
   2061    .. versionadded:: 3.5
   2062 
   2063    .. versionadded:: 3.6
   2064       Added support for the :term:`context manager` protocol and the
   2065       :func:`~scandir.close()` method.  If a :func:`scandir` iterator is neither
   2066       exhausted nor explicitly closed a :exc:`ResourceWarning` will be emitted
   2067       in its destructor.
   2068 
   2069       The function accepts a :term:`path-like object`.
   2070 
   2071 
   2072 .. class:: DirEntry
   2073 
   2074    Object yielded by :func:`scandir` to expose the file path and other file
   2075    attributes of a directory entry.
   2076 
   2077    :func:`scandir` will provide as much of this information as possible without
   2078    making additional system calls. When a ``stat()`` or ``lstat()`` system call
   2079    is made, the ``os.DirEntry`` object will cache the result.
   2080 
   2081    ``os.DirEntry`` instances are not intended to be stored in long-lived data
   2082    structures; if you know the file metadata has changed or if a long time has
   2083    elapsed since calling :func:`scandir`, call ``os.stat(entry.path)`` to fetch
   2084    up-to-date information.
   2085 
   2086    Because the ``os.DirEntry`` methods can make operating system calls, they may
   2087    also raise :exc:`OSError`. If you need very fine-grained
   2088    control over errors, you can catch :exc:`OSError` when calling one of the
   2089    ``os.DirEntry`` methods and handle as appropriate.
   2090 
   2091    To be directly usable as a :term:`path-like object`, ``os.DirEntry``
   2092    implements the :class:`PathLike` interface.
   2093 
   2094    Attributes and methods on a ``os.DirEntry`` instance are as follows:
   2095 
   2096    .. attribute:: name
   2097 
   2098       The entry's base filename, relative to the :func:`scandir` *path*
   2099       argument.
   2100 
   2101       The :attr:`name` attribute will be ``bytes`` if the :func:`scandir`
   2102       *path* argument is of type ``bytes`` and ``str`` otherwise.  Use
   2103       :func:`~os.fsdecode` to decode byte filenames.
   2104 
   2105    .. attribute:: path
   2106 
   2107       The entry's full path name: equivalent to ``os.path.join(scandir_path,
   2108       entry.name)`` where *scandir_path* is the :func:`scandir` *path*
   2109       argument.  The path is only absolute if the :func:`scandir` *path*
   2110       argument was absolute.
   2111 
   2112       The :attr:`path` attribute will be ``bytes`` if the :func:`scandir`
   2113       *path* argument is of type ``bytes`` and ``str`` otherwise.  Use
   2114       :func:`~os.fsdecode` to decode byte filenames.
   2115 
   2116    .. method:: inode()
   2117 
   2118       Return the inode number of the entry.
   2119 
   2120       The result is cached on the ``os.DirEntry`` object. Use
   2121       ``os.stat(entry.path, follow_symlinks=False).st_ino`` to fetch up-to-date
   2122       information.
   2123 
   2124       On the first, uncached call, a system call is required on Windows but
   2125       not on Unix.
   2126 
   2127    .. method:: is_dir(\*, follow_symlinks=True)
   2128 
   2129       Return ``True`` if this entry is a directory or a symbolic link pointing
   2130       to a directory; return ``False`` if the entry is or points to any other
   2131       kind of file, or if it doesn't exist anymore.
   2132 
   2133       If *follow_symlinks* is ``False``, return ``True`` only if this entry
   2134       is a directory (without following symlinks); return ``False`` if the
   2135       entry is any other kind of file or if it doesn't exist anymore.
   2136 
   2137       The result is cached on the ``os.DirEntry`` object, with a separate cache
   2138       for *follow_symlinks* ``True`` and ``False``. Call :func:`os.stat` along
   2139       with :func:`stat.S_ISDIR` to fetch up-to-date information.
   2140 
   2141       On the first, uncached call, no system call is required in most cases.
   2142       Specifically, for non-symlinks, neither Windows or Unix require a system
   2143       call, except on certain Unix file systems, such as network file systems,
   2144       that return ``dirent.d_type == DT_UNKNOWN``. If the entry is a symlink,
   2145       a system call will be required to follow the symlink unless
   2146       *follow_symlinks* is ``False``.
   2147 
   2148       This method can raise :exc:`OSError`, such as :exc:`PermissionError`,
   2149       but :exc:`FileNotFoundError` is caught and not raised.
   2150 
   2151    .. method:: is_file(\*, follow_symlinks=True)
   2152 
   2153       Return ``True`` if this entry is a file or a symbolic link pointing to a
   2154       file; return ``False`` if the entry is or points to a directory or other
   2155       non-file entry, or if it doesn't exist anymore.
   2156 
   2157       If *follow_symlinks* is ``False``, return ``True`` only if this entry
   2158       is a file (without following symlinks); return ``False`` if the entry is
   2159       a directory or other non-file entry, or if it doesn't exist anymore.
   2160 
   2161       The result is cached on the ``os.DirEntry`` object. Caching, system calls
   2162       made, and exceptions raised are as per :func:`~os.DirEntry.is_dir`.
   2163 
   2164    .. method:: is_symlink()
   2165 
   2166       Return ``True`` if this entry is a symbolic link (even if broken);
   2167       return ``False`` if the entry points to a directory or any kind of file,
   2168       or if it doesn't exist anymore.
   2169 
   2170       The result is cached on the ``os.DirEntry`` object. Call
   2171       :func:`os.path.islink` to fetch up-to-date information.
   2172 
   2173       On the first, uncached call, no system call is required in most cases.
   2174       Specifically, neither Windows or Unix require a system call, except on
   2175       certain Unix file systems, such as network file systems, that return
   2176       ``dirent.d_type == DT_UNKNOWN``.
   2177 
   2178       This method can raise :exc:`OSError`, such as :exc:`PermissionError`,
   2179       but :exc:`FileNotFoundError` is caught and not raised.
   2180 
   2181    .. method:: stat(\*, follow_symlinks=True)
   2182 
   2183       Return a :class:`stat_result` object for this entry. This method
   2184       follows symbolic links by default; to stat a symbolic link add the
   2185       ``follow_symlinks=False`` argument.
   2186 
   2187       On Unix, this method always requires a system call. On Windows, it
   2188       only requires a system call if *follow_symlinks* is ``True`` and the
   2189       entry is a symbolic link.
   2190 
   2191       On Windows, the ``st_ino``, ``st_dev`` and ``st_nlink`` attributes of the
   2192       :class:`stat_result` are always set to zero. Call :func:`os.stat` to
   2193       get these attributes.
   2194 
   2195       The result is cached on the ``os.DirEntry`` object, with a separate cache
   2196       for *follow_symlinks* ``True`` and ``False``. Call :func:`os.stat` to
   2197       fetch up-to-date information.
   2198 
   2199    Note that there is a nice correspondence between several attributes
   2200    and methods of ``os.DirEntry`` and of :class:`pathlib.Path`.  In
   2201    particular, the ``name`` attribute has the same
   2202    meaning, as do the ``is_dir()``, ``is_file()``, ``is_symlink()``
   2203    and ``stat()`` methods.
   2204 
   2205    .. versionadded:: 3.5
   2206 
   2207    .. versionchanged:: 3.6
   2208       Added support for the :class:`~os.PathLike` interface.  Added support
   2209       for :class:`bytes` paths on Windows.
   2210 
   2211 
   2212 .. function:: stat(path, \*, dir_fd=None, follow_symlinks=True)
   2213 
   2214    Get the status of a file or a file descriptor. Perform the equivalent of a
   2215    :c:func:`stat` system call on the given path. *path* may be specified as
   2216    either a string or bytes -- directly or indirectly through the :class:`PathLike`
   2217    interface -- or as an open file descriptor. Return a :class:`stat_result`
   2218    object.
   2219 
   2220    This function normally follows symlinks; to stat a symlink add the argument
   2221    ``follow_symlinks=False``, or use :func:`lstat`.
   2222 
   2223    This function can support :ref:`specifying a file descriptor <path_fd>` and
   2224    :ref:`not following symlinks <follow_symlinks>`.
   2225 
   2226    .. index:: module: stat
   2227 
   2228    Example::
   2229 
   2230       >>> import os
   2231       >>> statinfo = os.stat('somefile.txt')
   2232       >>> statinfo
   2233       os.stat_result(st_mode=33188, st_ino=7876932, st_dev=234881026,
   2234       st_nlink=1, st_uid=501, st_gid=501, st_size=264, st_atime=1297230295,
   2235       st_mtime=1297230027, st_ctime=1297230027)
   2236       >>> statinfo.st_size
   2237       264
   2238 
   2239    .. seealso::
   2240 
   2241       :func:`fstat` and :func:`lstat` functions.
   2242 
   2243    .. versionadded:: 3.3
   2244       Added the *dir_fd* and *follow_symlinks* arguments, specifying a file
   2245       descriptor instead of a path.
   2246 
   2247    .. versionchanged:: 3.6
   2248       Accepts a :term:`path-like object`.
   2249 
   2250 
   2251 .. class:: stat_result
   2252 
   2253    Object whose attributes correspond roughly to the members of the
   2254    :c:type:`stat` structure. It is used for the result of :func:`os.stat`,
   2255    :func:`os.fstat` and :func:`os.lstat`.
   2256 
   2257    Attributes:
   2258 
   2259    .. attribute:: st_mode
   2260 
   2261       File mode: file type and file mode bits (permissions).
   2262 
   2263    .. attribute:: st_ino
   2264 
   2265       Inode number.
   2266 
   2267    .. attribute:: st_dev
   2268 
   2269       Identifier of the device on which this file resides.
   2270 
   2271    .. attribute:: st_nlink
   2272 
   2273       Number of hard links.
   2274 
   2275    .. attribute:: st_uid
   2276 
   2277       User identifier of the file owner.
   2278 
   2279    .. attribute:: st_gid
   2280 
   2281       Group identifier of the file owner.
   2282 
   2283    .. attribute:: st_size
   2284 
   2285       Size of the file in bytes, if it is a regular file or a symbolic link.
   2286       The size of a symbolic link is the length of the pathname it contains,
   2287       without a terminating null byte.
   2288 
   2289    Timestamps:
   2290 
   2291    .. attribute:: st_atime
   2292 
   2293       Time of most recent access expressed in seconds.
   2294 
   2295    .. attribute:: st_mtime
   2296 
   2297       Time of most recent content modification expressed in seconds.
   2298 
   2299    .. attribute:: st_ctime
   2300 
   2301       Platform dependent:
   2302 
   2303       * the time of most recent metadata change on Unix,
   2304       * the time of creation on Windows, expressed in seconds.
   2305 
   2306    .. attribute:: st_atime_ns
   2307 
   2308       Time of most recent access expressed in nanoseconds as an integer.
   2309 
   2310    .. attribute:: st_mtime_ns
   2311 
   2312       Time of most recent content modification expressed in nanoseconds as an
   2313       integer.
   2314 
   2315    .. attribute:: st_ctime_ns
   2316 
   2317       Platform dependent:
   2318 
   2319       * the time of most recent metadata change on Unix,
   2320       * the time of creation on Windows, expressed in nanoseconds as an
   2321         integer.
   2322 
   2323    See also the :func:`stat_float_times` function.
   2324 
   2325    .. note::
   2326 
   2327       The exact meaning and resolution of the :attr:`st_atime`,
   2328       :attr:`st_mtime`, and :attr:`st_ctime` attributes depend on the operating
   2329       system and the file system. For example, on Windows systems using the FAT
   2330       or FAT32 file systems, :attr:`st_mtime` has 2-second resolution, and
   2331       :attr:`st_atime` has only 1-day resolution.  See your operating system
   2332       documentation for details.
   2333 
   2334       Similarly, although :attr:`st_atime_ns`, :attr:`st_mtime_ns`,
   2335       and :attr:`st_ctime_ns` are always expressed in nanoseconds, many
   2336       systems do not provide nanosecond precision.  On systems that do
   2337       provide nanosecond precision, the floating-point object used to
   2338       store :attr:`st_atime`, :attr:`st_mtime`, and :attr:`st_ctime`
   2339       cannot preserve all of it, and as such will be slightly inexact.
   2340       If you need the exact timestamps you should always use
   2341       :attr:`st_atime_ns`, :attr:`st_mtime_ns`, and :attr:`st_ctime_ns`.
   2342 
   2343    On some Unix systems (such as Linux), the following attributes may also be
   2344    available:
   2345 
   2346    .. attribute:: st_blocks
   2347 
   2348       Number of 512-byte blocks allocated for file.
   2349       This may be smaller than :attr:`st_size`/512 when the file has holes.
   2350 
   2351    .. attribute:: st_blksize
   2352 
   2353       "Preferred" blocksize for efficient file system I/O. Writing to a file in
   2354       smaller chunks may cause an inefficient read-modify-rewrite.
   2355 
   2356    .. attribute:: st_rdev
   2357 
   2358       Type of device if an inode device.
   2359 
   2360    .. attribute:: st_flags
   2361 
   2362       User defined flags for file.
   2363 
   2364    On other Unix systems (such as FreeBSD), the following attributes may be
   2365    available (but may be only filled out if root tries to use them):
   2366 
   2367    .. attribute:: st_gen
   2368 
   2369       File generation number.
   2370 
   2371    .. attribute:: st_birthtime
   2372 
   2373       Time of file creation.
   2374 
   2375    On Mac OS systems, the following attributes may also be available:
   2376 
   2377    .. attribute:: st_rsize
   2378 
   2379       Real size of the file.
   2380 
   2381    .. attribute:: st_creator
   2382 
   2383       Creator of the file.
   2384 
   2385    .. attribute:: st_type
   2386 
   2387       File type.
   2388 
   2389    On Windows systems, the following attribute is also available:
   2390 
   2391    .. attribute:: st_file_attributes
   2392 
   2393       Windows file attributes: ``dwFileAttributes`` member of the
   2394       ``BY_HANDLE_FILE_INFORMATION`` structure returned by
   2395       :c:func:`GetFileInformationByHandle`. See the ``FILE_ATTRIBUTE_*``
   2396       constants in the :mod:`stat` module.
   2397 
   2398    The standard module :mod:`stat` defines functions and constants that are
   2399    useful for extracting information from a :c:type:`stat` structure. (On
   2400    Windows, some items are filled with dummy values.)
   2401 
   2402    For backward compatibility, a :class:`stat_result` instance is also
   2403    accessible as a tuple of at least 10 integers giving the most important (and
   2404    portable) members of the :c:type:`stat` structure, in the order
   2405    :attr:`st_mode`, :attr:`st_ino`, :attr:`st_dev`, :attr:`st_nlink`,
   2406    :attr:`st_uid`, :attr:`st_gid`, :attr:`st_size`, :attr:`st_atime`,
   2407    :attr:`st_mtime`, :attr:`st_ctime`. More items may be added at the end by
   2408    some implementations. For compatibility with older Python versions,
   2409    accessing :class:`stat_result` as a tuple always returns integers.
   2410 
   2411    .. versionadded:: 3.3
   2412       Added the :attr:`st_atime_ns`, :attr:`st_mtime_ns`, and
   2413       :attr:`st_ctime_ns` members.
   2414 
   2415    .. versionadded:: 3.5
   2416       Added the :attr:`st_file_attributes` member on Windows.
   2417 
   2418 
   2419 .. function:: stat_float_times([newvalue])
   2420 
   2421    Determine whether :class:`stat_result` represents time stamps as float objects.
   2422    If *newvalue* is ``True``, future calls to :func:`~os.stat` return floats, if it is
   2423    ``False``, future calls return ints. If *newvalue* is omitted, return the
   2424    current setting.
   2425 
   2426    For compatibility with older Python versions, accessing :class:`stat_result` as
   2427    a tuple always returns integers.
   2428 
   2429    Python now returns float values by default. Applications which do not work
   2430    correctly with floating point time stamps can use this function to restore the
   2431    old behaviour.
   2432 
   2433    The resolution of the timestamps (that is the smallest possible fraction)
   2434    depends on the system. Some systems only support second resolution; on these
   2435    systems, the fraction will always be zero.
   2436 
   2437    It is recommended that this setting is only changed at program startup time in
   2438    the *__main__* module; libraries should never change this setting. If an
   2439    application uses a library that works incorrectly if floating point time stamps
   2440    are processed, this application should turn the feature off until the library
   2441    has been corrected.
   2442 
   2443    .. deprecated:: 3.3
   2444 
   2445 
   2446 .. function:: statvfs(path)
   2447 
   2448    Perform a :c:func:`statvfs` system call on the given path.  The return value is
   2449    an object whose attributes describe the filesystem on the given path, and
   2450    correspond to the members of the :c:type:`statvfs` structure, namely:
   2451    :attr:`f_bsize`, :attr:`f_frsize`, :attr:`f_blocks`, :attr:`f_bfree`,
   2452    :attr:`f_bavail`, :attr:`f_files`, :attr:`f_ffree`, :attr:`f_favail`,
   2453    :attr:`f_flag`, :attr:`f_namemax`.
   2454 
   2455    Two module-level constants are defined for the :attr:`f_flag` attribute's
   2456    bit-flags: if :const:`ST_RDONLY` is set, the filesystem is mounted
   2457    read-only, and if :const:`ST_NOSUID` is set, the semantics of
   2458    setuid/setgid bits are disabled or not supported.
   2459 
   2460    Additional module-level constants are defined for GNU/glibc based systems.
   2461    These are :const:`ST_NODEV` (disallow access to device special files),
   2462    :const:`ST_NOEXEC` (disallow program execution), :const:`ST_SYNCHRONOUS`
   2463    (writes are synced at once), :const:`ST_MANDLOCK` (allow mandatory locks on an FS),
   2464    :const:`ST_WRITE` (write on file/directory/symlink), :const:`ST_APPEND`
   2465    (append-only file), :const:`ST_IMMUTABLE` (immutable file), :const:`ST_NOATIME`
   2466    (do not update access times), :const:`ST_NODIRATIME` (do not update directory access
   2467    times), :const:`ST_RELATIME` (update atime relative to mtime/ctime).
   2468 
   2469    This function can support :ref:`specifying a file descriptor <path_fd>`.
   2470 
   2471    Availability: Unix.
   2472 
   2473    .. versionchanged:: 3.2
   2474       The :const:`ST_RDONLY` and :const:`ST_NOSUID` constants were added.
   2475 
   2476    .. versionadded:: 3.3
   2477       Added support for specifying an open file descriptor for *path*.
   2478 
   2479    .. versionchanged:: 3.4
   2480       The :const:`ST_NODEV`, :const:`ST_NOEXEC`, :const:`ST_SYNCHRONOUS`,
   2481       :const:`ST_MANDLOCK`, :const:`ST_WRITE`, :const:`ST_APPEND`,
   2482       :const:`ST_IMMUTABLE`, :const:`ST_NOATIME`, :const:`ST_NODIRATIME`,
   2483       and :const:`ST_RELATIME` constants were added.
   2484 
   2485    .. versionchanged:: 3.6
   2486       Accepts a :term:`path-like object`.
   2487 
   2488 
   2489 .. data:: supports_dir_fd
   2490 
   2491    A :class:`~collections.abc.Set` object indicating which functions in the
   2492    :mod:`os` module permit use of their *dir_fd* parameter.  Different platforms
   2493    provide different functionality, and an option that might work on one might
   2494    be unsupported on another.  For consistency's sakes, functions that support
   2495    *dir_fd* always allow specifying the parameter, but will raise an exception
   2496    if the functionality is not actually available.
   2497 
   2498    To check whether a particular function permits use of its *dir_fd*
   2499    parameter, use the ``in`` operator on ``supports_dir_fd``.  As an example,
   2500    this expression determines whether the *dir_fd* parameter of :func:`os.stat`
   2501    is locally available::
   2502 
   2503        os.stat in os.supports_dir_fd
   2504 
   2505    Currently *dir_fd* parameters only work on Unix platforms; none of them work
   2506    on Windows.
   2507 
   2508    .. versionadded:: 3.3
   2509 
   2510 
   2511 .. data:: supports_effective_ids
   2512 
   2513    A :class:`~collections.abc.Set` object indicating which functions in the
   2514    :mod:`os` module permit use of the *effective_ids* parameter for
   2515    :func:`os.access`.  If the local platform supports it, the collection will
   2516    contain :func:`os.access`, otherwise it will be empty.
   2517 
   2518    To check whether you can use the *effective_ids* parameter for
   2519    :func:`os.access`, use the ``in`` operator on ``supports_effective_ids``,
   2520    like so::
   2521 
   2522        os.access in os.supports_effective_ids
   2523 
   2524    Currently *effective_ids* only works on Unix platforms; it does not work on
   2525    Windows.
   2526 
   2527    .. versionadded:: 3.3
   2528 
   2529 
   2530 .. data:: supports_fd
   2531 
   2532    A :class:`~collections.abc.Set` object indicating which functions in the
   2533    :mod:`os` module permit specifying their *path* parameter as an open file
   2534    descriptor.  Different platforms provide different functionality, and an
   2535    option that might work on one might be unsupported on another.  For
   2536    consistency's sakes, functions that support *fd* always allow specifying
   2537    the parameter, but will raise an exception if the functionality is not
   2538    actually available.
   2539 
   2540    To check whether a particular function permits specifying an open file
   2541    descriptor for its *path* parameter, use the ``in`` operator on
   2542    ``supports_fd``. As an example, this expression determines whether
   2543    :func:`os.chdir` accepts open file descriptors when called on your local
   2544    platform::
   2545 
   2546        os.chdir in os.supports_fd
   2547 
   2548    .. versionadded:: 3.3
   2549 
   2550 
   2551 .. data:: supports_follow_symlinks
   2552 
   2553    A :class:`~collections.abc.Set` object indicating which functions in the
   2554    :mod:`os` module permit use of their *follow_symlinks* parameter.  Different
   2555    platforms provide different functionality, and an option that might work on
   2556    one might be unsupported on another.  For consistency's sakes, functions that
   2557    support *follow_symlinks* always allow specifying the parameter, but will
   2558    raise an exception if the functionality is not actually available.
   2559 
   2560    To check whether a particular function permits use of its *follow_symlinks*
   2561    parameter, use the ``in`` operator on ``supports_follow_symlinks``.  As an
   2562    example, this expression determines whether the *follow_symlinks* parameter
   2563    of :func:`os.stat` is locally available::
   2564 
   2565        os.stat in os.supports_follow_symlinks
   2566 
   2567    .. versionadded:: 3.3
   2568 
   2569 
   2570 .. function:: symlink(src, dst, target_is_directory=False, *, dir_fd=None)
   2571 
   2572    Create a symbolic link pointing to *src* named *dst*.
   2573 
   2574    On Windows, a symlink represents either a file or a directory, and does not
   2575    morph to the target dynamically.  If the target is present, the type of the
   2576    symlink will be created to match. Otherwise, the symlink will be created
   2577    as a directory if *target_is_directory* is ``True`` or a file symlink (the
   2578    default) otherwise.  On non-Window platforms, *target_is_directory* is ignored.
   2579 
   2580    Symbolic link support was introduced in Windows 6.0 (Vista).  :func:`symlink`
   2581    will raise a :exc:`NotImplementedError` on Windows versions earlier than 6.0.
   2582 
   2583    This function can support :ref:`paths relative to directory descriptors
   2584    <dir_fd>`.
   2585 
   2586    .. note::
   2587 
   2588       On Windows, the *SeCreateSymbolicLinkPrivilege* is required in order to
   2589       successfully create symlinks. This privilege is not typically granted to
   2590       regular users but is available to accounts which can escalate privileges
   2591       to the administrator level. Either obtaining the privilege or running your
   2592       application as an administrator are ways to successfully create symlinks.
   2593 
   2594 
   2595       :exc:`OSError` is raised when the function is called by an unprivileged
   2596       user.
   2597 
   2598    Availability: Unix, Windows.
   2599 
   2600    .. versionchanged:: 3.2
   2601       Added support for Windows 6.0 (Vista) symbolic links.
   2602 
   2603    .. versionadded:: 3.3
   2604       Added the *dir_fd* argument, and now allow *target_is_directory*
   2605       on non-Windows platforms.
   2606 
   2607    .. versionchanged:: 3.6
   2608       Accepts a :term:`path-like object` for *src* and *dst*.
   2609 
   2610 
   2611 .. function:: sync()
   2612 
   2613    Force write of everything to disk.
   2614 
   2615    Availability: Unix.
   2616 
   2617    .. versionadded:: 3.3
   2618 
   2619 
   2620 .. function:: truncate(path, length)
   2621 
   2622    Truncate the file corresponding to *path*, so that it is at most
   2623    *length* bytes in size.
   2624 
   2625    This function can support :ref:`specifying a file descriptor <path_fd>`.
   2626 
   2627    Availability: Unix, Windows.
   2628 
   2629    .. versionadded:: 3.3
   2630 
   2631    .. versionchanged:: 3.5
   2632       Added support for Windows
   2633 
   2634    .. versionchanged:: 3.6
   2635       Accepts a :term:`path-like object`.
   2636 
   2637 
   2638 .. function:: unlink(path, *, dir_fd=None)
   2639 
   2640    Remove (delete) the file *path*.  This function is semantically
   2641    identical to :func:`remove`; the ``unlink`` name is its
   2642    traditional Unix name.  Please see the documentation for
   2643    :func:`remove` for further information.
   2644 
   2645    .. versionadded:: 3.3
   2646       The *dir_fd* parameter.
   2647 
   2648    .. versionchanged:: 3.6
   2649       Accepts a :term:`path-like object`.
   2650 
   2651 
   2652 .. function:: utime(path, times=None, *[, ns], dir_fd=None, follow_symlinks=True)
   2653 
   2654    Set the access and modified times of the file specified by *path*.
   2655 
   2656    :func:`utime` takes two optional parameters, *times* and *ns*.
   2657    These specify the times set on *path* and are used as follows:
   2658 
   2659    - If *ns* is specified,
   2660      it must be a 2-tuple of the form ``(atime_ns, mtime_ns)``
   2661      where each member is an int expressing nanoseconds.
   2662    - If *times* is not ``None``,
   2663      it must be a 2-tuple of the form ``(atime, mtime)``
   2664      where each member is an int or float expressing seconds.
   2665    - If *times* is ``None`` and *ns* is unspecified,
   2666      this is equivalent to specifying ``ns=(atime_ns, mtime_ns)``
   2667      where both times are the current time.
   2668 
   2669    It is an error to specify tuples for both *times* and *ns*.
   2670 
   2671    Whether a directory can be given for *path*
   2672    depends on whether the operating system implements directories as files
   2673    (for example, Windows does not).  Note that the exact times you set here may
   2674    not be returned by a subsequent :func:`~os.stat` call, depending on the
   2675    resolution with which your operating system records access and modification
   2676    times; see :func:`~os.stat`.  The best way to preserve exact times is to
   2677    use the *st_atime_ns* and *st_mtime_ns* fields from the :func:`os.stat`
   2678    result object with the *ns* parameter to `utime`.
   2679 
   2680    This function can support :ref:`specifying a file descriptor <path_fd>`,
   2681    :ref:`paths relative to directory descriptors <dir_fd>` and :ref:`not
   2682    following symlinks <follow_symlinks>`.
   2683 
   2684    .. versionadded:: 3.3
   2685       Added support for specifying an open file descriptor for *path*,
   2686       and the *dir_fd*, *follow_symlinks*, and *ns* parameters.
   2687 
   2688    .. versionchanged:: 3.6
   2689       Accepts a :term:`path-like object`.
   2690 
   2691 
   2692 .. function:: walk(top, topdown=True, onerror=None, followlinks=False)
   2693 
   2694    .. index::
   2695       single: directory; walking
   2696       single: directory; traversal
   2697 
   2698    Generate the file names in a directory tree by walking the tree
   2699    either top-down or bottom-up. For each directory in the tree rooted at directory
   2700    *top* (including *top* itself), it yields a 3-tuple ``(dirpath, dirnames,
   2701    filenames)``.
   2702 
   2703    *dirpath* is a string, the path to the directory.  *dirnames* is a list of the
   2704    names of the subdirectories in *dirpath* (excluding ``'.'`` and ``'..'``).
   2705    *filenames* is a list of the names of the non-directory files in *dirpath*.
   2706    Note that the names in the lists contain no path components.  To get a full path
   2707    (which begins with *top*) to a file or directory in *dirpath*, do
   2708    ``os.path.join(dirpath, name)``.
   2709 
   2710    If optional argument *topdown* is ``True`` or not specified, the triple for a
   2711    directory is generated before the triples for any of its subdirectories
   2712    (directories are generated top-down).  If *topdown* is ``False``, the triple
   2713    for a directory is generated after the triples for all of its subdirectories
   2714    (directories are generated bottom-up). No matter the value of *topdown*, the
   2715    list of subdirectories is retrieved before the tuples for the directory and
   2716    its subdirectories are generated.
   2717 
   2718    When *topdown* is ``True``, the caller can modify the *dirnames* list in-place
   2719    (perhaps using :keyword:`del` or slice assignment), and :func:`walk` will only
   2720    recurse into the subdirectories whose names remain in *dirnames*; this can be
   2721    used to prune the search, impose a specific order of visiting, or even to inform
   2722    :func:`walk` about directories the caller creates or renames before it resumes
   2723    :func:`walk` again.  Modifying *dirnames* when *topdown* is ``False`` has
   2724    no effect on the behavior of the walk, because in bottom-up mode the directories
   2725    in *dirnames* are generated before *dirpath* itself is generated.
   2726 
   2727    By default, errors from the :func:`listdir` call are ignored.  If optional
   2728    argument *onerror* is specified, it should be a function; it will be called with
   2729    one argument, an :exc:`OSError` instance.  It can report the error to continue
   2730    with the walk, or raise the exception to abort the walk.  Note that the filename
   2731    is available as the ``filename`` attribute of the exception object.
   2732 
   2733    By default, :func:`walk` will not walk down into symbolic links that resolve to
   2734    directories. Set *followlinks* to ``True`` to visit directories pointed to by
   2735    symlinks, on systems that support them.
   2736 
   2737    .. note::
   2738 
   2739       Be aware that setting *followlinks* to ``True`` can lead to infinite
   2740       recursion if a link points to a parent directory of itself. :func:`walk`
   2741       does not keep track of the directories it visited already.
   2742 
   2743    .. note::
   2744 
   2745       If you pass a relative pathname, don't change the current working directory
   2746       between resumptions of :func:`walk`.  :func:`walk` never changes the current
   2747       directory, and assumes that its caller doesn't either.
   2748 
   2749    This example displays the number of bytes taken by non-directory files in each
   2750    directory under the starting directory, except that it doesn't look under any
   2751    CVS subdirectory::
   2752 
   2753       import os
   2754       from os.path import join, getsize
   2755       for root, dirs, files in os.walk('python/Lib/email'):
   2756           print(root, "consumes", end=" ")
   2757           print(sum(getsize(join(root, name)) for name in files), end=" ")
   2758           print("bytes in", len(files), "non-directory files")
   2759           if 'CVS' in dirs:
   2760               dirs.remove('CVS')  # don't visit CVS directories
   2761 
   2762    In the next example (simple implementation of :func:`shutil.rmtree`),
   2763    walking the tree bottom-up is essential, :func:`rmdir` doesn't allow
   2764    deleting a directory before the directory is empty::
   2765 
   2766       # Delete everything reachable from the directory named in "top",
   2767       # assuming there are no symbolic links.
   2768       # CAUTION:  This is dangerous!  For example, if top == '/', it
   2769       # could delete all your disk files.
   2770       import os
   2771       for root, dirs, files in os.walk(top, topdown=False):
   2772           for name in files:
   2773               os.remove(os.path.join(root, name))
   2774           for name in dirs:
   2775               os.rmdir(os.path.join(root, name))
   2776 
   2777    .. versionchanged:: 3.5
   2778       This function now calls :func:`os.scandir` instead of :func:`os.listdir`,
   2779       making it faster by reducing the number of calls to :func:`os.stat`.
   2780 
   2781    .. versionchanged:: 3.6
   2782       Accepts a :term:`path-like object`.
   2783 
   2784 
   2785 .. function:: fwalk(top='.', topdown=True, onerror=None, *, follow_symlinks=False, dir_fd=None)
   2786 
   2787    .. index::
   2788       single: directory; walking
   2789       single: directory; traversal
   2790 
   2791    This behaves exactly like :func:`walk`, except that it yields a 4-tuple
   2792    ``(dirpath, dirnames, filenames, dirfd)``, and it supports ``dir_fd``.
   2793 
   2794    *dirpath*, *dirnames* and *filenames* are identical to :func:`walk` output,
   2795    and *dirfd* is a file descriptor referring to the directory *dirpath*.
   2796 
   2797    This function always supports :ref:`paths relative to directory descriptors
   2798    <dir_fd>` and :ref:`not following symlinks <follow_symlinks>`.  Note however
   2799    that, unlike other functions, the :func:`fwalk` default value for
   2800    *follow_symlinks* is ``False``.
   2801 
   2802    .. note::
   2803 
   2804       Since :func:`fwalk` yields file descriptors, those are only valid until
   2805       the next iteration step, so you should duplicate them (e.g. with
   2806       :func:`dup`) if you want to keep them longer.
   2807 
   2808    This example displays the number of bytes taken by non-directory files in each
   2809    directory under the starting directory, except that it doesn't look under any
   2810    CVS subdirectory::
   2811 
   2812       import os
   2813       for root, dirs, files, rootfd in os.fwalk('python/Lib/email'):
   2814           print(root, "consumes", end="")
   2815           print(sum([os.stat(name, dir_fd=rootfd).st_size for name in files]),
   2816                 end="")
   2817           print("bytes in", len(files), "non-directory files")
   2818           if 'CVS' in dirs:
   2819               dirs.remove('CVS')  # don't visit CVS directories
   2820 
   2821    In the next example, walking the tree bottom-up is essential:
   2822    :func:`rmdir` doesn't allow deleting a directory before the directory is
   2823    empty::
   2824 
   2825       # Delete everything reachable from the directory named in "top",
   2826       # assuming there are no symbolic links.
   2827       # CAUTION:  This is dangerous!  For example, if top == '/', it
   2828       # could delete all your disk files.
   2829       import os
   2830       for root, dirs, files, rootfd in os.fwalk(top, topdown=False):
   2831           for name in files:
   2832               os.unlink(name, dir_fd=rootfd)
   2833           for name in dirs:
   2834               os.rmdir(name, dir_fd=rootfd)
   2835 
   2836    Availability: Unix.
   2837 
   2838    .. versionadded:: 3.3
   2839 
   2840    .. versionchanged:: 3.6
   2841       Accepts a :term:`path-like object`.
   2842 
   2843 
   2844 Linux extended attributes
   2845 ~~~~~~~~~~~~~~~~~~~~~~~~~
   2846 
   2847 .. versionadded:: 3.3
   2848 
   2849 These functions are all available on Linux only.
   2850 
   2851 .. function:: getxattr(path, attribute, *, follow_symlinks=True)
   2852 
   2853    Return the value of the extended filesystem attribute *attribute* for
   2854    *path*. *attribute* can be bytes or str (directly or indirectly through the
   2855    :class:`PathLike` interface). If it is str, it is encoded with the filesystem
   2856    encoding.
   2857 
   2858    This function can support :ref:`specifying a file descriptor <path_fd>` and
   2859    :ref:`not following symlinks <follow_symlinks>`.
   2860 
   2861    .. versionchanged:: 3.6
   2862       Accepts a :term:`path-like object` for *path* and *attribute*.
   2863 
   2864 
   2865 .. function:: listxattr(path=None, *, follow_symlinks=True)
   2866 
   2867    Return a list of the extended filesystem attributes on *path*.  The
   2868    attributes in the list are represented as strings decoded with the filesystem
   2869    encoding.  If *path* is ``None``, :func:`listxattr` will examine the current
   2870    directory.
   2871 
   2872    This function can support :ref:`specifying a file descriptor <path_fd>` and
   2873    :ref:`not following symlinks <follow_symlinks>`.
   2874 
   2875    .. versionchanged:: 3.6
   2876       Accepts a :term:`path-like object`.
   2877 
   2878 
   2879 .. function:: removexattr(path, attribute, *, follow_symlinks=True)
   2880 
   2881    Removes the extended filesystem attribute *attribute* from *path*.
   2882    *attribute* should be bytes or str (directly or indirectly through the
   2883    :class:`PathLike` interface). If it is a string, it is encoded
   2884    with the filesystem encoding.
   2885 
   2886    This function can support :ref:`specifying a file descriptor <path_fd>` and
   2887    :ref:`not following symlinks <follow_symlinks>`.
   2888 
   2889    .. versionchanged:: 3.6
   2890       Accepts a :term:`path-like object` for *path* and *attribute*.
   2891 
   2892 
   2893 .. function:: setxattr(path, attribute, value, flags=0, *, follow_symlinks=True)
   2894 
   2895    Set the extended filesystem attribute *attribute* on *path* to *value*.
   2896    *attribute* must be a bytes or str with no embedded NULs (directly or
   2897    indirectly through the :class:`PathLike` interface). If it is a str,
   2898    it is encoded with the filesystem encoding.  *flags* may be
   2899    :data:`XATTR_REPLACE` or :data:`XATTR_CREATE`. If :data:`XATTR_REPLACE` is
   2900    given and the attribute does not exist, ``EEXISTS`` will be raised.
   2901    If :data:`XATTR_CREATE` is given and the attribute already exists, the
   2902    attribute will not be created and ``ENODATA`` will be raised.
   2903 
   2904    This function can support :ref:`specifying a file descriptor <path_fd>` and
   2905    :ref:`not following symlinks <follow_symlinks>`.
   2906 
   2907    .. note::
   2908 
   2909       A bug in Linux kernel versions less than 2.6.39 caused the flags argument
   2910       to be ignored on some filesystems.
   2911 
   2912    .. versionchanged:: 3.6
   2913       Accepts a :term:`path-like object` for *path* and *attribute*.
   2914 
   2915 
   2916 .. data:: XATTR_SIZE_MAX
   2917 
   2918    The maximum size the value of an extended attribute can be. Currently, this
   2919    is 64 KiB on Linux.
   2920 
   2921 
   2922 .. data:: XATTR_CREATE
   2923 
   2924    This is a possible value for the flags argument in :func:`setxattr`. It
   2925    indicates the operation must create an attribute.
   2926 
   2927 
   2928 .. data:: XATTR_REPLACE
   2929 
   2930    This is a possible value for the flags argument in :func:`setxattr`. It
   2931    indicates the operation must replace an existing attribute.
   2932 
   2933 
   2934 .. _os-process:
   2935 
   2936 Process Management
   2937 ------------------
   2938 
   2939 These functions may be used to create and manage processes.
   2940 
   2941 The various :func:`exec\* <execl>` functions take a list of arguments for the new
   2942 program loaded into the process.  In each case, the first of these arguments is
   2943 passed to the new program as its own name rather than as an argument a user may
   2944 have typed on a command line.  For the C programmer, this is the ``argv[0]``
   2945 passed to a program's :c:func:`main`.  For example, ``os.execv('/bin/echo',
   2946 ['foo', 'bar'])`` will only print ``bar`` on standard output; ``foo`` will seem
   2947 to be ignored.
   2948 
   2949 
   2950 .. function:: abort()
   2951 
   2952    Generate a :const:`SIGABRT` signal to the current process.  On Unix, the default
   2953    behavior is to produce a core dump; on Windows, the process immediately returns
   2954    an exit code of ``3``.  Be aware that calling this function will not call the
   2955    Python signal handler registered for :const:`SIGABRT` with
   2956    :func:`signal.signal`.
   2957 
   2958 
   2959 .. function:: execl(path, arg0, arg1, ...)
   2960               execle(path, arg0, arg1, ..., env)
   2961               execlp(file, arg0, arg1, ...)
   2962               execlpe(file, arg0, arg1, ..., env)
   2963               execv(path, args)
   2964               execve(path, args, env)
   2965               execvp(file, args)
   2966               execvpe(file, args, env)
   2967 
   2968    These functions all execute a new program, replacing the current process; they
   2969    do not return.  On Unix, the new executable is loaded into the current process,
   2970    and will have the same process id as the caller.  Errors will be reported as
   2971    :exc:`OSError` exceptions.
   2972 
   2973    The current process is replaced immediately. Open file objects and
   2974    descriptors are not flushed, so if there may be data buffered
   2975    on these open files, you should flush them using
   2976    :func:`sys.stdout.flush` or :func:`os.fsync` before calling an
   2977    :func:`exec\* <execl>` function.
   2978 
   2979    The "l" and "v" variants of the :func:`exec\* <execl>` functions differ in how
   2980    command-line arguments are passed.  The "l" variants are perhaps the easiest
   2981    to work with if the number of parameters is fixed when the code is written; the
   2982    individual parameters simply become additional parameters to the :func:`execl\*`
   2983    functions.  The "v" variants are good when the number of parameters is
   2984    variable, with the arguments being passed in a list or tuple as the *args*
   2985    parameter.  In either case, the arguments to the child process should start with
   2986    the name of the command being run, but this is not enforced.
   2987 
   2988    The variants which include a "p" near the end (:func:`execlp`,
   2989    :func:`execlpe`, :func:`execvp`, and :func:`execvpe`) will use the
   2990    :envvar:`PATH` environment variable to locate the program *file*.  When the
   2991    environment is being replaced (using one of the :func:`exec\*e <execl>` variants,
   2992    discussed in the next paragraph), the new environment is used as the source of
   2993    the :envvar:`PATH` variable. The other variants, :func:`execl`, :func:`execle`,
   2994    :func:`execv`, and :func:`execve`, will not use the :envvar:`PATH` variable to
   2995    locate the executable; *path* must contain an appropriate absolute or relative
   2996    path.
   2997 
   2998    For :func:`execle`, :func:`execlpe`, :func:`execve`, and :func:`execvpe` (note
   2999    that these all end in "e"), the *env* parameter must be a mapping which is
   3000    used to define the environment variables for the new process (these are used
   3001    instead of the current process' environment); the functions :func:`execl`,
   3002    :func:`execlp`, :func:`execv`, and :func:`execvp` all cause the new process to
   3003    inherit the environment of the current process.
   3004 
   3005    For :func:`execve` on some platforms, *path* may also be specified as an open
   3006    file descriptor.  This functionality may not be supported on your platform;
   3007    you can check whether or not it is available using :data:`os.supports_fd`.
   3008    If it is unavailable, using it will raise a :exc:`NotImplementedError`.
   3009 
   3010    Availability: Unix, Windows.
   3011 
   3012    .. versionadded:: 3.3
   3013       Added support for specifying an open file descriptor for *path*
   3014       for :func:`execve`.
   3015 
   3016    .. versionchanged:: 3.6
   3017       Accepts a :term:`path-like object`.
   3018 
   3019 .. function:: _exit(n)
   3020 
   3021    Exit the process with status *n*, without calling cleanup handlers, flushing
   3022    stdio buffers, etc.
   3023 
   3024    .. note::
   3025 
   3026       The standard way to exit is ``sys.exit(n)``.  :func:`_exit` should
   3027       normally only be used in the child process after a :func:`fork`.
   3028 
   3029 The following exit codes are defined and can be used with :func:`_exit`,
   3030 although they are not required.  These are typically used for system programs
   3031 written in Python, such as a mail server's external command delivery program.
   3032 
   3033 .. note::
   3034 
   3035    Some of these may not be available on all Unix platforms, since there is some
   3036    variation.  These constants are defined where they are defined by the underlying
   3037    platform.
   3038 
   3039 
   3040 .. data:: EX_OK
   3041 
   3042    Exit code that means no error occurred.
   3043 
   3044    Availability: Unix.
   3045 
   3046 
   3047 .. data:: EX_USAGE
   3048 
   3049    Exit code that means the command was used incorrectly, such as when the wrong
   3050    number of arguments are given.
   3051 
   3052    Availability: Unix.
   3053 
   3054 
   3055 .. data:: EX_DATAERR
   3056 
   3057    Exit code that means the input data was incorrect.
   3058 
   3059    Availability: Unix.
   3060 
   3061 
   3062 .. data:: EX_NOINPUT
   3063 
   3064    Exit code that means an input file did not exist or was not readable.
   3065 
   3066    Availability: Unix.
   3067 
   3068 
   3069 .. data:: EX_NOUSER
   3070 
   3071    Exit code that means a specified user did not exist.
   3072 
   3073    Availability: Unix.
   3074 
   3075 
   3076 .. data:: EX_NOHOST
   3077 
   3078    Exit code that means a specified host did not exist.
   3079 
   3080    Availability: Unix.
   3081 
   3082 
   3083 .. data:: EX_UNAVAILABLE
   3084 
   3085    Exit code that means that a required service is unavailable.
   3086 
   3087    Availability: Unix.
   3088 
   3089 
   3090 .. data:: EX_SOFTWARE
   3091 
   3092    Exit code that means an internal software error was detected.
   3093 
   3094    Availability: Unix.
   3095 
   3096 
   3097 .. data:: EX_OSERR
   3098 
   3099    Exit code that means an operating system error was detected, such as the
   3100    inability to fork or create a pipe.
   3101 
   3102    Availability: Unix.
   3103 
   3104 
   3105 .. data:: EX_OSFILE
   3106 
   3107    Exit code that means some system file did not exist, could not be opened, or had
   3108    some other kind of error.
   3109 
   3110    Availability: Unix.
   3111 
   3112 
   3113 .. data:: EX_CANTCREAT
   3114 
   3115    Exit code that means a user specified output file could not be created.
   3116 
   3117    Availability: Unix.
   3118 
   3119 
   3120 .. data:: EX_IOERR
   3121 
   3122    Exit code that means that an error occurred while doing I/O on some file.
   3123 
   3124    Availability: Unix.
   3125 
   3126 
   3127 .. data:: EX_TEMPFAIL
   3128 
   3129    Exit code that means a temporary failure occurred.  This indicates something
   3130    that may not really be an error, such as a network connection that couldn't be
   3131    made during a retryable operation.
   3132 
   3133    Availability: Unix.
   3134 
   3135 
   3136 .. data:: EX_PROTOCOL
   3137 
   3138    Exit code that means that a protocol exchange was illegal, invalid, or not
   3139    understood.
   3140 
   3141    Availability: Unix.
   3142 
   3143 
   3144 .. data:: EX_NOPERM
   3145 
   3146    Exit code that means that there were insufficient permissions to perform the
   3147    operation (but not intended for file system problems).
   3148 
   3149    Availability: Unix.
   3150 
   3151 
   3152 .. data:: EX_CONFIG
   3153 
   3154    Exit code that means that some kind of configuration error occurred.
   3155 
   3156    Availability: Unix.
   3157 
   3158 
   3159 .. data:: EX_NOTFOUND
   3160 
   3161    Exit code that means something like "an entry was not found".
   3162 
   3163    Availability: Unix.
   3164 
   3165 
   3166 .. function:: fork()
   3167 
   3168    Fork a child process.  Return ``0`` in the child and the child's process id in the
   3169    parent.  If an error occurs :exc:`OSError` is raised.
   3170 
   3171    Note that some platforms including FreeBSD <= 6.3 and Cygwin have
   3172    known issues when using fork() from a thread.
   3173 
   3174    .. warning::
   3175 
   3176       See :mod:`ssl` for applications that use the SSL module with fork().
   3177 
   3178    Availability: Unix.
   3179 
   3180 
   3181 .. function:: forkpty()
   3182 
   3183    Fork a child process, using a new pseudo-terminal as the child's controlling
   3184    terminal. Return a pair of ``(pid, fd)``, where *pid* is ``0`` in the child, the
   3185    new child's process id in the parent, and *fd* is the file descriptor of the
   3186    master end of the pseudo-terminal.  For a more portable approach, use the
   3187    :mod:`pty` module.  If an error occurs :exc:`OSError` is raised.
   3188 
   3189    Availability: some flavors of Unix.
   3190 
   3191 
   3192 .. function:: kill(pid, sig)
   3193 
   3194    .. index::
   3195       single: process; killing
   3196       single: process; signalling
   3197 
   3198    Send signal *sig* to the process *pid*.  Constants for the specific signals
   3199    available on the host platform are defined in the :mod:`signal` module.
   3200 
   3201    Windows: The :data:`signal.CTRL_C_EVENT` and
   3202    :data:`signal.CTRL_BREAK_EVENT` signals are special signals which can
   3203    only be sent to console processes which share a common console window,
   3204    e.g., some subprocesses. Any other value for *sig* will cause the process
   3205    to be unconditionally killed by the TerminateProcess API, and the exit code
   3206    will be set to *sig*. The Windows version of :func:`kill` additionally takes
   3207    process handles to be killed.
   3208 
   3209    See also :func:`signal.pthread_kill`.
   3210 
   3211    .. versionadded:: 3.2
   3212       Windows support.
   3213 
   3214 
   3215 .. function:: killpg(pgid, sig)
   3216 
   3217    .. index::
   3218       single: process; killing
   3219       single: process; signalling
   3220 
   3221    Send the signal *sig* to the process group *pgid*.
   3222 
   3223    Availability: Unix.
   3224 
   3225 
   3226 .. function:: nice(increment)
   3227 
   3228    Add *increment* to the process's "niceness".  Return the new niceness.
   3229 
   3230    Availability: Unix.
   3231 
   3232 
   3233 .. function:: plock(op)
   3234 
   3235    Lock program segments into memory.  The value of *op* (defined in
   3236    ``<sys/lock.h>``) determines which segments are locked.
   3237 
   3238    Availability: Unix.
   3239 
   3240 
   3241 .. function:: popen(cmd, mode='r', buffering=-1)
   3242 
   3243    Open a pipe to or from command *cmd*.
   3244    The return value is an open file object
   3245    connected to the pipe, which can be read or written depending on whether *mode*
   3246    is ``'r'`` (default) or ``'w'``. The *buffering* argument has the same meaning as
   3247    the corresponding argument to the built-in :func:`open` function. The
   3248    returned file object reads or writes text strings rather than bytes.
   3249 
   3250    The ``close`` method returns :const:`None` if the subprocess exited
   3251    successfully, or the subprocess's return code if there was an
   3252    error. On POSIX systems, if the return code is positive it
   3253    represents the return value of the process left-shifted by one
   3254    byte.  If the return code is negative, the process was terminated
   3255    by the signal given by the negated value of the return code.  (For
   3256    example, the return value might be ``- signal.SIGKILL`` if the
   3257    subprocess was killed.)  On Windows systems, the return value
   3258    contains the signed integer return code from the child process.
   3259 
   3260    This is implemented using :class:`subprocess.Popen`; see that class's
   3261    documentation for more powerful ways to manage and communicate with
   3262    subprocesses.
   3263 
   3264 
   3265 .. function:: spawnl(mode, path, ...)
   3266               spawnle(mode, path, ..., env)
   3267               spawnlp(mode, file, ...)
   3268               spawnlpe(mode, file, ..., env)
   3269               spawnv(mode, path, args)
   3270               spawnve(mode, path, args, env)
   3271               spawnvp(mode, file, args)
   3272               spawnvpe(mode, file, args, env)
   3273 
   3274    Execute the program *path* in a new process.
   3275 
   3276    (Note that the :mod:`subprocess` module provides more powerful facilities for
   3277    spawning new processes and retrieving their results; using that module is
   3278    preferable to using these functions.  Check especially the
   3279    :ref:`subprocess-replacements` section.)
   3280 
   3281    If *mode* is :const:`P_NOWAIT`, this function returns the process id of the new
   3282    process; if *mode* is :const:`P_WAIT`, returns the process's exit code if it
   3283    exits normally, or ``-signal``, where *signal* is the signal that killed the
   3284    process.  On Windows, the process id will actually be the process handle, so can
   3285    be used with the :func:`waitpid` function.
   3286 
   3287    The "l" and "v" variants of the :func:`spawn\* <spawnl>` functions differ in how
   3288    command-line arguments are passed.  The "l" variants are perhaps the easiest
   3289    to work with if the number of parameters is fixed when the code is written; the
   3290    individual parameters simply become additional parameters to the
   3291    :func:`spawnl\*` functions.  The "v" variants are good when the number of
   3292    parameters is variable, with the arguments being passed in a list or tuple as
   3293    the *args* parameter.  In either case, the arguments to the child process must
   3294    start with the name of the command being run.
   3295 
   3296    The variants which include a second "p" near the end (:func:`spawnlp`,
   3297    :func:`spawnlpe`, :func:`spawnvp`, and :func:`spawnvpe`) will use the
   3298    :envvar:`PATH` environment variable to locate the program *file*.  When the
   3299    environment is being replaced (using one of the :func:`spawn\*e <spawnl>` variants,
   3300    discussed in the next paragraph), the new environment is used as the source of
   3301    the :envvar:`PATH` variable.  The other variants, :func:`spawnl`,
   3302    :func:`spawnle`, :func:`spawnv`, and :func:`spawnve`, will not use the
   3303    :envvar:`PATH` variable to locate the executable; *path* must contain an
   3304    appropriate absolute or relative path.
   3305 
   3306    For :func:`spawnle`, :func:`spawnlpe`, :func:`spawnve`, and :func:`spawnvpe`
   3307    (note that these all end in "e"), the *env* parameter must be a mapping
   3308    which is used to define the environment variables for the new process (they are
   3309    used instead of the current process' environment); the functions
   3310    :func:`spawnl`, :func:`spawnlp`, :func:`spawnv`, and :func:`spawnvp` all cause
   3311    the new process to inherit the environment of the current process.  Note that
   3312    keys and values in the *env* dictionary must be strings; invalid keys or
   3313    values will cause the function to fail, with a return value of ``127``.
   3314 
   3315    As an example, the following calls to :func:`spawnlp` and :func:`spawnvpe` are
   3316    equivalent::
   3317 
   3318       import os
   3319       os.spawnlp(os.P_WAIT, 'cp', 'cp', 'index.html', '/dev/null')
   3320 
   3321       L = ['cp', 'index.html', '/dev/null']
   3322       os.spawnvpe(os.P_WAIT, 'cp', L, os.environ)
   3323 
   3324    Availability: Unix, Windows.  :func:`spawnlp`, :func:`spawnlpe`, :func:`spawnvp`
   3325    and :func:`spawnvpe` are not available on Windows.  :func:`spawnle` and
   3326    :func:`spawnve` are not thread-safe on Windows; we advise you to use the
   3327    :mod:`subprocess` module instead.
   3328 
   3329    .. versionchanged:: 3.6
   3330       Accepts a :term:`path-like object`.
   3331 
   3332 
   3333 .. data:: P_NOWAIT
   3334           P_NOWAITO
   3335 
   3336    Possible values for the *mode* parameter to the :func:`spawn\* <spawnl>` family of
   3337    functions.  If either of these values is given, the :func:`spawn\*` functions
   3338    will return as soon as the new process has been created, with the process id as
   3339    the return value.
   3340 
   3341    Availability: Unix, Windows.
   3342 
   3343 
   3344 .. data:: P_WAIT
   3345 
   3346    Possible value for the *mode* parameter to the :func:`spawn\* <spawnl>` family of
   3347    functions.  If this is given as *mode*, the :func:`spawn\*` functions will not
   3348    return until the new process has run to completion and will return the exit code
   3349    of the process the run is successful, or ``-signal`` if a signal kills the
   3350    process.
   3351 
   3352    Availability: Unix, Windows.
   3353 
   3354 
   3355 .. data:: P_DETACH
   3356           P_OVERLAY
   3357 
   3358    Possible values for the *mode* parameter to the :func:`spawn\* <spawnl>` family of
   3359    functions.  These are less portable than those listed above. :const:`P_DETACH`
   3360    is similar to :const:`P_NOWAIT`, but the new process is detached from the
   3361    console of the calling process. If :const:`P_OVERLAY` is used, the current
   3362    process will be replaced; the :func:`spawn\* <spawnl>` function will not return.
   3363 
   3364    Availability: Windows.
   3365 
   3366 
   3367 .. function:: startfile(path[, operation])
   3368 
   3369    Start a file with its associated application.
   3370 
   3371    When *operation* is not specified or ``'open'``, this acts like double-clicking
   3372    the file in Windows Explorer, or giving the file name as an argument to the
   3373    :program:`start` command from the interactive command shell: the file is opened
   3374    with whatever application (if any) its extension is associated.
   3375 
   3376    When another *operation* is given, it must be a "command verb" that specifies
   3377    what should be done with the file. Common verbs documented by Microsoft are
   3378    ``'print'`` and  ``'edit'`` (to be used on files) as well as ``'explore'`` and
   3379    ``'find'`` (to be used on directories).
   3380 
   3381    :func:`startfile` returns as soon as the associated application is launched.
   3382    There is no option to wait for the application to close, and no way to retrieve
   3383    the application's exit status.  The *path* parameter is relative to the current
   3384    directory.  If you want to use an absolute path, make sure the first character
   3385    is not a slash (``'/'``); the underlying Win32 :c:func:`ShellExecute` function
   3386    doesn't work if it is.  Use the :func:`os.path.normpath` function to ensure that
   3387    the path is properly encoded for Win32.
   3388 
   3389    To reduce interpreter startup overhead, the Win32 :c:func:`ShellExecute`
   3390    function is not resolved until this function is first called.  If the function
   3391    cannot be resolved, :exc:`NotImplementedError` will be raised.
   3392 
   3393    Availability: Windows.
   3394 
   3395 
   3396 .. function:: system(command)
   3397 
   3398    Execute the command (a string) in a subshell.  This is implemented by calling
   3399    the Standard C function :c:func:`system`, and has the same limitations.
   3400    Changes to :data:`sys.stdin`, etc. are not reflected in the environment of
   3401    the executed command. If *command* generates any output, it will be sent to
   3402    the interpreter standard output stream.
   3403 
   3404    On Unix, the return value is the exit status of the process encoded in the
   3405    format specified for :func:`wait`.  Note that POSIX does not specify the
   3406    meaning of the return value of the C :c:func:`system` function, so the return
   3407    value of the Python function is system-dependent.
   3408 
   3409    On Windows, the return value is that returned by the system shell after
   3410    running *command*.  The shell is given by the Windows environment variable
   3411    :envvar:`COMSPEC`: it is usually :program:`cmd.exe`, which returns the exit
   3412    status of the command run; on systems using a non-native shell, consult your
   3413    shell documentation.
   3414 
   3415    The :mod:`subprocess` module provides more powerful facilities for spawning
   3416    new processes and retrieving their results; using that module is preferable
   3417    to using this function.  See the :ref:`subprocess-replacements` section in
   3418    the :mod:`subprocess` documentation for some helpful recipes.
   3419 
   3420    Availability: Unix, Windows.
   3421 
   3422 
   3423 .. function:: times()
   3424 
   3425    Returns the current global process times.
   3426    The return value is an object with five attributes:
   3427 
   3428    * :attr:`user` - user time
   3429    * :attr:`system` - system time
   3430    * :attr:`children_user` - user time of all child processes
   3431    * :attr:`children_system` - system time of all child processes
   3432    * :attr:`elapsed` - elapsed real time since a fixed point in the past
   3433 
   3434    For backwards compatibility, this object also behaves like a five-tuple
   3435    containing :attr:`user`, :attr:`system`, :attr:`children_user`,
   3436    :attr:`children_system`, and :attr:`elapsed` in that order.
   3437 
   3438    See the Unix manual page
   3439    :manpage:`times(2)` or the corresponding Windows Platform API documentation.
   3440    On Windows, only :attr:`user` and :attr:`system` are known; the other
   3441    attributes are zero.
   3442 
   3443    Availability: Unix, Windows.
   3444 
   3445    .. versionchanged:: 3.3
   3446       Return type changed from a tuple to a tuple-like object
   3447       with named attributes.
   3448 
   3449 
   3450 .. function:: wait()
   3451 
   3452    Wait for completion of a child process, and return a tuple containing its pid
   3453    and exit status indication: a 16-bit number, whose low byte is the signal number
   3454    that killed the process, and whose high byte is the exit status (if the signal
   3455    number is zero); the high bit of the low byte is set if a core file was
   3456    produced.
   3457 
   3458    Availability: Unix.
   3459 
   3460 .. function:: waitid(idtype, id, options)
   3461 
   3462    Wait for the completion of one or more child processes.
   3463    *idtype* can be :data:`P_PID`, :data:`P_PGID` or :data:`P_ALL`.
   3464    *id* specifies the pid to wait on.
   3465    *options* is constructed from the ORing of one or more of :data:`WEXITED`,
   3466    :data:`WSTOPPED` or :data:`WCONTINUED` and additionally may be ORed with
   3467    :data:`WNOHANG` or :data:`WNOWAIT`. The return value is an object
   3468    representing the data contained in the :c:type:`siginfo_t` structure, namely:
   3469    :attr:`si_pid`, :attr:`si_uid`, :attr:`si_signo`, :attr:`si_status`,
   3470    :attr:`si_code` or ``None`` if :data:`WNOHANG` is specified and there are no
   3471    children in a waitable state.
   3472 
   3473    Availability: Unix.
   3474 
   3475    .. versionadded:: 3.3
   3476 
   3477 .. data:: P_PID
   3478           P_PGID
   3479           P_ALL
   3480 
   3481    These are the possible values for *idtype* in :func:`waitid`. They affect
   3482    how *id* is interpreted.
   3483 
   3484    Availability: Unix.
   3485 
   3486    .. versionadded:: 3.3
   3487 
   3488 .. data:: WEXITED
   3489           WSTOPPED
   3490           WNOWAIT
   3491 
   3492    Flags that can be used in *options* in :func:`waitid` that specify what
   3493    child signal to wait for.
   3494 
   3495    Availability: Unix.
   3496 
   3497    .. versionadded:: 3.3
   3498 
   3499 
   3500 .. data:: CLD_EXITED
   3501           CLD_DUMPED
   3502           CLD_TRAPPED
   3503           CLD_CONTINUED
   3504 
   3505    These are the possible values for :attr:`si_code` in the result returned by
   3506    :func:`waitid`.
   3507 
   3508    Availability: Unix.
   3509 
   3510    .. versionadded:: 3.3
   3511 
   3512 
   3513 .. function:: waitpid(pid, options)
   3514 
   3515    The details of this function differ on Unix and Windows.
   3516 
   3517    On Unix: Wait for completion of a child process given by process id *pid*, and
   3518    return a tuple containing its process id and exit status indication (encoded as
   3519    for :func:`wait`).  The semantics of the call are affected by the value of the
   3520    integer *options*, which should be ``0`` for normal operation.
   3521 
   3522    If *pid* is greater than ``0``, :func:`waitpid` requests status information for
   3523    that specific process.  If *pid* is ``0``, the request is for the status of any
   3524    child in the process group of the current process.  If *pid* is ``-1``, the
   3525    request pertains to any child of the current process.  If *pid* is less than
   3526    ``-1``, status is requested for any process in the process group ``-pid`` (the
   3527    absolute value of *pid*).
   3528 
   3529    An :exc:`OSError` is raised with the value of errno when the syscall
   3530    returns -1.
   3531 
   3532    On Windows: Wait for completion of a process given by process handle *pid*, and
   3533    return a tuple containing *pid*, and its exit status shifted left by 8 bits
   3534    (shifting makes cross-platform use of the function easier). A *pid* less than or
   3535    equal to ``0`` has no special meaning on Windows, and raises an exception. The
   3536    value of integer *options* has no effect. *pid* can refer to any process whose
   3537    id is known, not necessarily a child process. The :func:`spawn\* <spawnl>`
   3538    functions called with :const:`P_NOWAIT` return suitable process handles.
   3539 
   3540    .. versionchanged:: 3.5
   3541       If the system call is interrupted and the signal handler does not raise an
   3542       exception, the function now retries the system call instead of raising an
   3543       :exc:`InterruptedError` exception (see :pep:`475` for the rationale).
   3544 
   3545 
   3546 .. function:: wait3(options)
   3547 
   3548    Similar to :func:`waitpid`, except no process id argument is given and a
   3549    3-element tuple containing the child's process id, exit status indication, and
   3550    resource usage information is returned.  Refer to :mod:`resource`.\
   3551    :func:`~resource.getrusage` for details on resource usage information.  The
   3552    option argument is the same as that provided to :func:`waitpid` and
   3553    :func:`wait4`.
   3554 
   3555    Availability: Unix.
   3556 
   3557 
   3558 .. function:: wait4(pid, options)
   3559 
   3560    Similar to :func:`waitpid`, except a 3-element tuple, containing the child's
   3561    process id, exit status indication, and resource usage information is returned.
   3562    Refer to :mod:`resource`.\ :func:`~resource.getrusage` for details on
   3563    resource usage information.  The arguments to :func:`wait4` are the same
   3564    as those provided to :func:`waitpid`.
   3565 
   3566    Availability: Unix.
   3567 
   3568 
   3569 .. data:: WNOHANG
   3570 
   3571    The option for :func:`waitpid` to return immediately if no child process status
   3572    is available immediately. The function returns ``(0, 0)`` in this case.
   3573 
   3574    Availability: Unix.
   3575 
   3576 
   3577 .. data:: WCONTINUED
   3578 
   3579    This option causes child processes to be reported if they have been continued
   3580    from a job control stop since their status was last reported.
   3581 
   3582    Availability: some Unix systems.
   3583 
   3584 
   3585 .. data:: WUNTRACED
   3586 
   3587    This option causes child processes to be reported if they have been stopped but
   3588    their current state has not been reported since they were stopped.
   3589 
   3590    Availability: Unix.
   3591 
   3592 
   3593 The following functions take a process status code as returned by
   3594 :func:`system`, :func:`wait`, or :func:`waitpid` as a parameter.  They may be
   3595 used to determine the disposition of a process.
   3596 
   3597 .. function:: WCOREDUMP(status)
   3598 
   3599    Return ``True`` if a core dump was generated for the process, otherwise
   3600    return ``False``.
   3601 
   3602    Availability: Unix.
   3603 
   3604 
   3605 .. function:: WIFCONTINUED(status)
   3606 
   3607    Return ``True`` if the process has been continued from a job control stop,
   3608    otherwise return ``False``.
   3609 
   3610    Availability: Unix.
   3611 
   3612 
   3613 .. function:: WIFSTOPPED(status)
   3614 
   3615    Return ``True`` if the process has been stopped, otherwise return
   3616    ``False``.
   3617 
   3618    Availability: Unix.
   3619 
   3620 
   3621 .. function:: WIFSIGNALED(status)
   3622 
   3623    Return ``True`` if the process exited due to a signal, otherwise return
   3624    ``False``.
   3625 
   3626    Availability: Unix.
   3627 
   3628 
   3629 .. function:: WIFEXITED(status)
   3630 
   3631    Return ``True`` if the process exited using the :manpage:`exit(2)` system call,
   3632    otherwise return ``False``.
   3633 
   3634    Availability: Unix.
   3635 
   3636 
   3637 .. function:: WEXITSTATUS(status)
   3638 
   3639    If ``WIFEXITED(status)`` is true, return the integer parameter to the
   3640    :manpage:`exit(2)` system call.  Otherwise, the return value is meaningless.
   3641 
   3642    Availability: Unix.
   3643 
   3644 
   3645 .. function:: WSTOPSIG(status)
   3646 
   3647    Return the signal which caused the process to stop.
   3648 
   3649    Availability: Unix.
   3650 
   3651 
   3652 .. function:: WTERMSIG(status)
   3653 
   3654    Return the signal which caused the process to exit.
   3655 
   3656    Availability: Unix.
   3657 
   3658 
   3659 Interface to the scheduler
   3660 --------------------------
   3661 
   3662 These functions control how a process is allocated CPU time by the operating
   3663 system. They are only available on some Unix platforms. For more detailed
   3664 information, consult your Unix manpages.
   3665 
   3666 .. versionadded:: 3.3
   3667 
   3668 The following scheduling policies are exposed if they are supported by the
   3669 operating system.
   3670 
   3671 .. data:: SCHED_OTHER
   3672 
   3673    The default scheduling policy.
   3674 
   3675 .. data:: SCHED_BATCH
   3676 
   3677    Scheduling policy for CPU-intensive processes that tries to preserve
   3678    interactivity on the rest of the computer.
   3679 
   3680 .. data:: SCHED_IDLE
   3681 
   3682    Scheduling policy for extremely low priority background tasks.
   3683 
   3684 .. data:: SCHED_SPORADIC
   3685 
   3686    Scheduling policy for sporadic server programs.
   3687 
   3688 .. data:: SCHED_FIFO
   3689 
   3690    A First In First Out scheduling policy.
   3691 
   3692 .. data:: SCHED_RR
   3693 
   3694    A round-robin scheduling policy.
   3695 
   3696 .. data:: SCHED_RESET_ON_FORK
   3697 
   3698    This flag can be OR'ed with any other scheduling policy. When a process with
   3699    this flag set forks, its child's scheduling policy and priority are reset to
   3700    the default.
   3701 
   3702 
   3703 .. class:: sched_param(sched_priority)
   3704 
   3705    This class represents tunable scheduling parameters used in
   3706    :func:`sched_setparam`, :func:`sched_setscheduler`, and
   3707    :func:`sched_getparam`. It is immutable.
   3708 
   3709    At the moment, there is only one possible parameter:
   3710 
   3711    .. attribute:: sched_priority
   3712 
   3713       The scheduling priority for a scheduling policy.
   3714 
   3715 
   3716 .. function:: sched_get_priority_min(policy)
   3717 
   3718    Get the minimum priority value for *policy*. *policy* is one of the
   3719    scheduling policy constants above.
   3720 
   3721 
   3722 .. function:: sched_get_priority_max(policy)
   3723 
   3724    Get the maximum priority value for *policy*. *policy* is one of the
   3725    scheduling policy constants above.
   3726 
   3727 
   3728 .. function:: sched_setscheduler(pid, policy, param)
   3729 
   3730    Set the scheduling policy for the process with PID *pid*. A *pid* of 0 means
   3731    the calling process. *policy* is one of the scheduling policy constants
   3732    above. *param* is a :class:`sched_param` instance.
   3733 
   3734 
   3735 .. function:: sched_getscheduler(pid)
   3736 
   3737    Return the scheduling policy for the process with PID *pid*. A *pid* of 0
   3738    means the calling process. The result is one of the scheduling policy
   3739    constants above.
   3740 
   3741 
   3742 .. function:: sched_setparam(pid, param)
   3743 
   3744    Set a scheduling parameters for the process with PID *pid*. A *pid* of 0 means
   3745    the calling process. *param* is a :class:`sched_param` instance.
   3746 
   3747 
   3748 .. function:: sched_getparam(pid)
   3749 
   3750    Return the scheduling parameters as a :class:`sched_param` instance for the
   3751    process with PID *pid*. A *pid* of 0 means the calling process.
   3752 
   3753 
   3754 .. function:: sched_rr_get_interval(pid)
   3755 
   3756    Return the round-robin quantum in seconds for the process with PID *pid*. A
   3757    *pid* of 0 means the calling process.
   3758 
   3759 
   3760 .. function:: sched_yield()
   3761 
   3762    Voluntarily relinquish the CPU.
   3763 
   3764 
   3765 .. function:: sched_setaffinity(pid, mask)
   3766 
   3767    Restrict the process with PID *pid* (or the current process if zero) to a
   3768    set of CPUs.  *mask* is an iterable of integers representing the set of
   3769    CPUs to which the process should be restricted.
   3770 
   3771 
   3772 .. function:: sched_getaffinity(pid)
   3773 
   3774    Return the set of CPUs the process with PID *pid* (or the current process
   3775    if zero) is restricted to.
   3776 
   3777 
   3778 .. _os-path:
   3779 
   3780 Miscellaneous System Information
   3781 --------------------------------
   3782 
   3783 
   3784 .. function:: confstr(name)
   3785 
   3786    Return string-valued system configuration values. *name* specifies the
   3787    configuration value to retrieve; it may be a string which is the name of a
   3788    defined system value; these names are specified in a number of standards (POSIX,
   3789    Unix 95, Unix 98, and others).  Some platforms define additional names as well.
   3790    The names known to the host operating system are given as the keys of the
   3791    ``confstr_names`` dictionary.  For configuration variables not included in that
   3792    mapping, passing an integer for *name* is also accepted.
   3793 
   3794    If the configuration value specified by *name* isn't defined, ``None`` is
   3795    returned.
   3796 
   3797    If *name* is a string and is not known, :exc:`ValueError` is raised.  If a
   3798    specific value for *name* is not supported by the host system, even if it is
   3799    included in ``confstr_names``, an :exc:`OSError` is raised with
   3800    :const:`errno.EINVAL` for the error number.
   3801 
   3802    Availability: Unix.
   3803 
   3804 
   3805 .. data:: confstr_names
   3806 
   3807    Dictionary mapping names accepted by :func:`confstr` to the integer values
   3808    defined for those names by the host operating system. This can be used to
   3809    determine the set of names known to the system.
   3810 
   3811    Availability: Unix.
   3812 
   3813 
   3814 .. function:: cpu_count()
   3815 
   3816    Return the number of CPUs in the system. Returns ``None`` if undetermined.
   3817 
   3818    This number is not equivalent to the number of CPUs the current process can
   3819    use.  The number of usable CPUs can be obtained with
   3820    ``len(os.sched_getaffinity(0))``
   3821 
   3822 
   3823    .. versionadded:: 3.4
   3824 
   3825 
   3826 .. function:: getloadavg()
   3827 
   3828    Return the number of processes in the system run queue averaged over the last
   3829    1, 5, and 15 minutes or raises :exc:`OSError` if the load average was
   3830    unobtainable.
   3831 
   3832    Availability: Unix.
   3833 
   3834 
   3835 .. function:: sysconf(name)
   3836 
   3837    Return integer-valued system configuration values. If the configuration value
   3838    specified by *name* isn't defined, ``-1`` is returned.  The comments regarding
   3839    the *name* parameter for :func:`confstr` apply here as well; the dictionary that
   3840    provides information on the known names is given by ``sysconf_names``.
   3841 
   3842    Availability: Unix.
   3843 
   3844 
   3845 .. data:: sysconf_names
   3846 
   3847    Dictionary mapping names accepted by :func:`sysconf` to the integer values
   3848    defined for those names by the host operating system. This can be used to
   3849    determine the set of names known to the system.
   3850 
   3851    Availability: Unix.
   3852 
   3853 The following data values are used to support path manipulation operations.  These
   3854 are defined for all platforms.
   3855 
   3856 Higher-level operations on pathnames are defined in the :mod:`os.path` module.
   3857 
   3858 
   3859 .. data:: curdir
   3860 
   3861    The constant string used by the operating system to refer to the current
   3862    directory. This is ``'.'`` for Windows and POSIX. Also available via
   3863    :mod:`os.path`.
   3864 
   3865 
   3866 .. data:: pardir
   3867 
   3868    The constant string used by the operating system to refer to the parent
   3869    directory. This is ``'..'`` for Windows and POSIX. Also available via
   3870    :mod:`os.path`.
   3871 
   3872 
   3873 .. data:: sep
   3874 
   3875    The character used by the operating system to separate pathname components.
   3876    This is ``'/'`` for POSIX and ``'\\'`` for Windows.  Note that knowing this
   3877    is not sufficient to be able to parse or concatenate pathnames --- use
   3878    :func:`os.path.split` and :func:`os.path.join` --- but it is occasionally
   3879    useful. Also available via :mod:`os.path`.
   3880 
   3881 
   3882 .. data:: altsep
   3883 
   3884    An alternative character used by the operating system to separate pathname
   3885    components, or ``None`` if only one separator character exists.  This is set to
   3886    ``'/'`` on Windows systems where ``sep`` is a backslash. Also available via
   3887    :mod:`os.path`.
   3888 
   3889 
   3890 .. data:: extsep
   3891 
   3892    The character which separates the base filename from the extension; for example,
   3893    the ``'.'`` in :file:`os.py`. Also available via :mod:`os.path`.
   3894 
   3895 
   3896 .. data:: pathsep
   3897 
   3898    The character conventionally used by the operating system to separate search
   3899    path components (as in :envvar:`PATH`), such as ``':'`` for POSIX or ``';'`` for
   3900    Windows. Also available via :mod:`os.path`.
   3901 
   3902 
   3903 .. data:: defpath
   3904 
   3905    The default search path used by :func:`exec\*p\* <execl>` and
   3906    :func:`spawn\*p\* <spawnl>` if the environment doesn't have a ``'PATH'``
   3907    key. Also available via :mod:`os.path`.
   3908 
   3909 
   3910 .. data:: linesep
   3911 
   3912    The string used to separate (or, rather, terminate) lines on the current
   3913    platform.  This may be a single character, such as ``'\n'`` for POSIX, or
   3914    multiple characters, for example, ``'\r\n'`` for Windows. Do not use
   3915    *os.linesep* as a line terminator when writing files opened in text mode (the
   3916    default); use a single ``'\n'`` instead, on all platforms.
   3917 
   3918 
   3919 .. data:: devnull
   3920 
   3921    The file path of the null device. For example: ``'/dev/null'`` for
   3922    POSIX, ``'nul'`` for Windows.  Also available via :mod:`os.path`.
   3923 
   3924 .. data:: RTLD_LAZY
   3925           RTLD_NOW
   3926           RTLD_GLOBAL
   3927           RTLD_LOCAL
   3928           RTLD_NODELETE
   3929           RTLD_NOLOAD
   3930           RTLD_DEEPBIND
   3931 
   3932    Flags for use with the :func:`~sys.setdlopenflags` and
   3933    :func:`~sys.getdlopenflags` functions.  See the Unix manual page
   3934    :manpage:`dlopen(3)` for what the different flags mean.
   3935 
   3936    .. versionadded:: 3.3
   3937 
   3938 
   3939 Random numbers
   3940 --------------
   3941 
   3942 
   3943 .. function:: getrandom(size, flags=0)
   3944 
   3945    Get up to *size* random bytes. The function can return less bytes than
   3946    requested.
   3947 
   3948    These bytes can be used to seed user-space random number generators or for
   3949    cryptographic purposes.
   3950 
   3951    ``getrandom()`` relies on entropy gathered from device drivers and other
   3952    sources of environmental noise. Unnecessarily reading large quantities of
   3953    data will have a negative impact on  other users  of the ``/dev/random`` and
   3954    ``/dev/urandom`` devices.
   3955 
   3956    The flags argument is a bit mask that can contain zero or more of the
   3957    following values ORed together: :py:data:`os.GRND_RANDOM` and
   3958    :py:data:`GRND_NONBLOCK`.
   3959 
   3960    See also the `Linux getrandom() manual page
   3961    <http://man7.org/linux/man-pages/man2/getrandom.2.html>`_.
   3962 
   3963    Availability: Linux 3.17 and newer.
   3964 
   3965    .. versionadded:: 3.6
   3966 
   3967 .. function:: urandom(size)
   3968 
   3969    Return a string of *size* random bytes suitable for cryptographic use.
   3970 
   3971    This function returns random bytes from an OS-specific randomness source.  The
   3972    returned data should be unpredictable enough for cryptographic applications,
   3973    though its exact quality depends on the OS implementation.
   3974 
   3975    On Linux, if the ``getrandom()`` syscall is available, it is used in
   3976    blocking mode: block until the system urandom entropy pool is initialized
   3977    (128 bits of entropy are collected by the kernel). See the :pep:`524` for
   3978    the rationale. On Linux, the :func:`getrandom` function can be used to get
   3979    random bytes in non-blocking mode (using the :data:`GRND_NONBLOCK` flag) or
   3980    to poll until the system urandom entropy pool is initialized.
   3981 
   3982    On a Unix-like system, random bytes are read from the ``/dev/urandom``
   3983    device. If the ``/dev/urandom`` device is not available or not readable, the
   3984    :exc:`NotImplementedError` exception is raised.
   3985 
   3986    On Windows, it will use ``CryptGenRandom()``.
   3987 
   3988    .. seealso::
   3989       The :mod:`secrets` module provides higher level functions. For an
   3990       easy-to-use interface to the random number generator provided by your
   3991       platform, please see :class:`random.SystemRandom`.
   3992 
   3993    .. versionchanged:: 3.6.0
   3994       On Linux, ``getrandom()`` is now used in blocking mode to increase the
   3995       security.
   3996 
   3997    .. versionchanged:: 3.5.2
   3998       On Linux, if the ``getrandom()`` syscall blocks (the urandom entropy pool
   3999       is not initialized yet), fall back on reading ``/dev/urandom``.
   4000 
   4001    .. versionchanged:: 3.5
   4002       On Linux 3.17 and newer, the ``getrandom()`` syscall is now used
   4003       when available.  On OpenBSD 5.6 and newer, the C ``getentropy()``
   4004       function is now used. These functions avoid the usage of an internal file
   4005       descriptor.
   4006 
   4007 .. data:: GRND_NONBLOCK
   4008 
   4009    By  default, when reading from ``/dev/random``, :func:`getrandom` blocks if
   4010    no random bytes are available, and when reading from ``/dev/urandom``, it blocks
   4011    if the entropy pool has not yet been initialized.
   4012 
   4013    If the :py:data:`GRND_NONBLOCK` flag is set, then :func:`getrandom` does not
   4014    block in these cases, but instead immediately raises :exc:`BlockingIOError`.
   4015 
   4016    .. versionadded:: 3.6
   4017 
   4018 .. data:: GRND_RANDOM
   4019 
   4020    If  this  bit  is  set,  then  random bytes are drawn from the
   4021    ``/dev/random`` pool instead of the ``/dev/urandom`` pool.
   4022 
   4023    .. versionadded:: 3.6
   4024