:mod:`os` --- Miscellaneous operating system interfaces
=======================================================

.. module:: os
   :synopsis: Miscellaneous operating system interfaces.


This module provides a portable way of using operating system dependent
functionality.  If you just want to read or write a file see :func:`open`, if
you want to manipulate paths, see the :mod:`os.path` module, and if you want to
read all the lines in all the files on the command line see the :mod:`fileinput`
module.  For creating temporary files and directories see the :mod:`tempfile`
module, and for high-level file and directory handling see the :mod:`shutil`
module.

The design of all built-in operating system dependent modules of Python is such
that as long as the same functionality is available, it uses the same interface;
for example, the function ``os.stat(path)`` returns stat information about
*path* in the same format (which happens to have originated with the POSIX
interface).

Extensions peculiar to a particular operating system are also available through
the :mod:`os` module, but using them is of course a threat to portability!

.. note::

   If not separately noted, all functions that claim "Availability: Unix" are
   supported on Mac OS X, which builds on a Unix core.

.. note::

   All functions in this module raise :exc:`OSError` in the case of invalid or
   inaccessible file names and paths, or other arguments that have the correct
   type, but are not accepted by the operating system.


.. exception:: error

   An alias for the built-in :exc:`OSError` exception.


.. data:: name

   The name of the operating system dependent module imported.  The following names
   have currently been registered: ``'posix'``, ``'nt'``, ``'mac'``, ``'os2'``,
   ``'ce'``, ``'java'``, ``'riscos'``.


.. _os-procinfo:

Process Parameters
------------------

These functions and data items provide information and operate on the current
process and user.


.. data:: environ

   A mapping object representing the string environment. For example,
   ``environ['HOME']`` is the pathname of your home directory (on some platforms),
   and is equivalent to ``getenv("HOME")`` in C.

   This mapping is captured the first time the :mod:`os` module is imported,
   typically during Python startup as part of processing :file:`site.py`.  Changes
   to the environment made after this time are not reflected in ``os.environ``,
   except for changes made by modifying ``os.environ`` directly.

   If the platform supports the :func:`putenv` function, this mapping may be used
   to modify the environment as well as query the environment.  :func:`putenv` will
   be called automatically when the mapping is modified.

   .. note::

      Calling :func:`putenv` directly does not change ``os.environ``, so it's better
      to modify ``os.environ``.

   .. note::

      On some platforms, including FreeBSD and Mac OS X, setting ``environ`` may
      cause memory leaks.  Refer to the system documentation for
      :cfunc:`putenv`.

   If :func:`putenv` is not provided, a modified copy of this mapping  may be
   passed to the appropriate process-creation functions to cause  child processes
   to use a modified environment.

   If the platform supports the :func:`unsetenv` function, you can delete items in
   this mapping to unset environment variables. :func:`unsetenv` will be called
   automatically when an item is deleted from ``os.environ``, and when
   one of the :meth:`pop` or :meth:`clear` methods is called.

   .. versionchanged:: 2.6
      Also unset environment variables when calling :meth:`os.environ.clear`
      and :meth:`os.environ.pop`.


.. function:: chdir(path)
              fchdir(fd)
              getcwd()
   :noindex:

   These functions are described in :ref:`os-file-dir`.


.. function:: ctermid()

   Return the filename corresponding to the controlling terminal of the process.
   Availability: Unix.


.. function:: getegid()

   Return the effective group id of the current process.  This corresponds to the
   "set id" bit on the file being executed in the current process. Availability:
   Unix.


.. function:: geteuid()

   .. index:: single: user; effective id

   Return the current process's effective user id. Availability: Unix.


.. function:: getgid()

   .. index:: single: process; group

   Return the real group id of the current process. Availability: Unix.


.. function:: getgroups()

   Return list of supplemental group ids associated with the current process.
   Availability: Unix.


.. function:: getlogin()

   Return the name of the user logged in on the controlling terminal of the
   process.  For most purposes, it is more useful to use the environment variable
   :envvar:`LOGNAME` to find out who the user is, or
   ``pwd.getpwuid(os.getuid())[0]`` to get the login name of the currently
   effective user id. Availability: Unix.


.. function:: getpgid(pid)

   Return the process group id of the process with process id *pid*. If *pid* is 0,
   the process group id of the current process is returned. Availability: Unix.

   .. versionadded:: 2.3


.. function:: getpgrp()

   .. index:: single: process; group

   Return the id of the current process group. Availability: Unix.


.. function:: getpid()

   .. index:: single: process; id

   Return the current process id. Availability: Unix, Windows.


.. function:: getppid()

   .. index:: single: process; id of parent

   Return the parent's process id. Availability: Unix.


.. function:: getuid()

   .. index:: single: user; id

   Return the current process's user id. Availability: Unix.


.. function:: getenv(varname[, value])

   Return the value of the environment variable *varname* if it exists, or *value*
   if it doesn't.  *value* defaults to ``None``. Availability: most flavors of
   Unix, Windows.


.. function:: putenv(varname, value)

   .. index:: single: environment variables; setting

   Set the environment variable named *varname* to the string *value*.  Such
   changes to the environment affect subprocesses started with :func:`os.system`,
   :func:`popen` or :func:`fork` and :func:`execv`. Availability: most flavors of
   Unix, Windows.

   .. note::

      On some platforms, including FreeBSD and Mac OS X, setting ``environ`` may
      cause memory leaks. Refer to the system documentation for putenv.

   When :func:`putenv` is supported, assignments to items in ``os.environ`` are
   automatically translated into corresponding calls to :func:`putenv`; however,
   calls to :func:`putenv` don't update ``os.environ``, so it is actually
   preferable to assign to items of ``os.environ``.


.. function:: setegid(egid)

   Set the current process's effective group id. Availability: Unix.


.. function:: seteuid(euid)

   Set the current process's effective user id. Availability: Unix.


.. function:: setgid(gid)

   Set the current process' group id. Availability: Unix.


.. function:: setgroups(groups)

   Set the list of supplemental group ids associated with the current process to
   *groups*. *groups* must be a sequence, and each element must be an integer
   identifying a group. This operation is typically available only to the superuser.
   Availability: Unix.

   .. versionadded:: 2.2


.. function:: setpgrp()

   Call the system call :cfunc:`setpgrp` or :cfunc:`setpgrp(0, 0)` depending on
   which version is implemented (if any).  See the Unix manual for the semantics.
   Availability: Unix.


.. function:: setpgid(pid, pgrp)

   Call the system call :cfunc:`setpgid` to set the process group id of the
   process with id *pid* to the process group with id *pgrp*.  See the Unix manual
   for the semantics. Availability: Unix.


.. function:: setreuid(ruid, euid)

   Set the current process's real and effective user ids. Availability: Unix.


.. function:: setregid(rgid, egid)

   Set the current process's real and effective group ids. Availability: Unix.


.. function:: getsid(pid)

   Call the system call :cfunc:`getsid`.  See the Unix manual for the semantics.
   Availability: Unix.

   .. versionadded:: 2.4


.. function:: setsid()

   Call the system call :cfunc:`setsid`.  See the Unix manual for the semantics.
   Availability: Unix.


.. function:: setuid(uid)

   .. index:: single: user; id, setting

   Set the current process's user id. Availability: Unix.


.. placed in this section since it relates to errno.... a little weak
.. function:: strerror(code)

   Return the error message corresponding to the error code in *code*.
   On platforms where :cfunc:`strerror` returns ``NULL`` when given an unknown
   error number, :exc:`ValueError` is raised.  Availability: Unix, Windows.


.. function:: umask(mask)

   Set the current numeric umask and return the previous umask. Availability:
   Unix, Windows.


.. function:: uname()

   .. index::
      single: gethostname() (in module socket)
      single: gethostbyaddr() (in module socket)

   Return a 5-tuple containing information identifying the current operating
   system.  The tuple contains 5 strings: ``(sysname, nodename, release, version,
   machine)``.  Some systems truncate the nodename to 8 characters or to the
   leading component; a better way to get the hostname is
   :func:`socket.gethostname`  or even
   ``socket.gethostbyaddr(socket.gethostname())``. Availability: recent flavors of
   Unix.


.. function:: unsetenv(varname)

   .. index:: single: environment variables; deleting

   Unset (delete) the environment variable named *varname*. Such changes to the
   environment affect subprocesses started with :func:`os.system`, :func:`popen` or
   :func:`fork` and :func:`execv`. Availability: most flavors of Unix, Windows.

   When :func:`unsetenv` is supported, deletion of items in ``os.environ`` is
   automatically translated into a corresponding call to :func:`unsetenv`; however,
   calls to :func:`unsetenv` don't update ``os.environ``, so it is actually
   preferable to delete items of ``os.environ``.


.. _os-newstreams:

File Object Creation
--------------------

These functions create new file objects. (See also :func:`open`.)


.. function:: fdopen(fd[, mode[, bufsize]])

   .. index:: single: I/O control; buffering

   Return an open file object connected to the file descriptor *fd*.  The *mode*
   and *bufsize* arguments have the same meaning as the corresponding arguments to
   the built-in :func:`open` function. Availability: Unix, Windows.

   .. versionchanged:: 2.3
      When specified, the *mode* argument must now start with one of the letters
      ``'r'``, ``'w'``, or ``'a'``, otherwise a :exc:`ValueError` is raised.

   .. versionchanged:: 2.5
      On Unix, when the *mode* argument starts with ``'a'``, the *O_APPEND* flag is
      set on the file descriptor (which the :cfunc:`fdopen` implementation already
      does on most platforms).


.. function:: popen(command[, mode[, bufsize]])

   Open a pipe to or from *command*.  The return value is an open file object
   connected to the pipe, which can be read or written depending on whether *mode*
   is ``'r'`` (default) or ``'w'``. The *bufsize* argument has the same meaning as
   the corresponding argument to the built-in :func:`open` function.  The exit
   status of the command (encoded in the format specified for :func:`wait`) is
   available as the return value of the :meth:`~file.close` method of the file object,
   except that when the exit status is zero (termination without errors), ``None``
   is returned. Availability: Unix, Windows.

   .. deprecated:: 2.6
      This function is obsolete.  Use the :mod:`subprocess` module.  Check
      especially the :ref:`subprocess-replacements` section.

   .. versionchanged:: 2.0
      This function worked unreliably under Windows in earlier versions of Python.
      This was due to the use of the :cfunc:`_popen` function from the libraries
      provided with Windows.  Newer versions of Python do not use the broken
      implementation from the Windows libraries.


.. function:: tmpfile()

   Return a new file object opened in update mode (``w+b``).  The file has no
   directory entries associated with it and will be automatically deleted once
   there are no file descriptors for the file. Availability: Unix,
   Windows.

There are a number of different :func:`popen\*` functions that provide slightly
different ways to create subprocesses.

.. deprecated:: 2.6
   All of the :func:`popen\*` functions are obsolete. Use the :mod:`subprocess`
   module.

For each of the :func:`popen\*` variants, if *bufsize* is specified, it
specifies the buffer size for the I/O pipes. *mode*, if provided, should be the
string ``'b'`` or ``'t'``; on Windows this is needed to determine whether the
file objects should be opened in binary or text mode.  The default value for
*mode* is ``'t'``.

Also, for each of these variants, on Unix, *cmd* may be a sequence, in which
case arguments will be passed directly to the program without shell intervention
(as with :func:`os.spawnv`). If *cmd* is a string it will be passed to the shell
(as with :func:`os.system`).

These methods do not make it possible to retrieve the exit status from the child
processes.  The only way to control the input and output streams and also
retrieve the return codes is to use the :mod:`subprocess` module; these are only
available on Unix.

For a discussion of possible deadlock conditions related to the use of these
functions, see :ref:`popen2-flow-control`.


.. function:: popen2(cmd[, mode[, bufsize]])

   Execute *cmd* as a sub-process and return the file objects ``(child_stdin,
   child_stdout)``.

   .. deprecated:: 2.6
      This function is obsolete.  Use the :mod:`subprocess` module.  Check
      especially the :ref:`subprocess-replacements` section.

   Availability: Unix, Windows.

   .. versionadded:: 2.0


.. function:: popen3(cmd[, mode[, bufsize]])

   Execute *cmd* as a sub-process and return the file objects ``(child_stdin,
   child_stdout, child_stderr)``.

   .. deprecated:: 2.6
      This function is obsolete.  Use the :mod:`subprocess` module.  Check
      especially the :ref:`subprocess-replacements` section.

   Availability: Unix, Windows.

   .. versionadded:: 2.0


.. function:: popen4(cmd[, mode[, bufsize]])

   Execute *cmd* as a sub-process and return the file objects ``(child_stdin,
   child_stdout_and_stderr)``.

   .. deprecated:: 2.6
      This function is obsolete.  Use the :mod:`subprocess` module.  Check
      especially the :ref:`subprocess-replacements` section.

   Availability: Unix, Windows.

   .. versionadded:: 2.0

(Note that ``child_stdin, child_stdout, and child_stderr`` are named from the
point of view of the child process, so *child_stdin* is the child's standard
input.)

This functionality is also available in the :mod:`popen2` module using functions
of the same names, but the return values of those functions have a different
order.


.. _os-fd-ops:

File Descriptor Operations
--------------------------

These functions operate on I/O streams referenced using file descriptors.

File descriptors are small integers corresponding to a file that has been opened
by the current process.  For example, standard input is usually file descriptor
0, standard output is 1, and standard error is 2.  Further files opened by a
process will then be assigned 3, 4, 5, and so forth.  The name "file descriptor"
is slightly deceptive; on Unix platforms, sockets and pipes are also referenced
by file descriptors.


.. function:: close(fd)

   Close file descriptor *fd*. Availability: Unix, Windows.

   .. note::

      This function is intended for low-level I/O and must be applied to a file
      descriptor as returned by :func:`os.open` or :func:`pipe`.  To close a "file
      object" returned by the built-in function :func:`open` or by :func:`popen` or
      :func:`fdopen`, use its :meth:`~file.close` method.


.. function:: closerange(fd_low, fd_high)

   Close all file descriptors from *fd_low* (inclusive) to *fd_high* (exclusive),
   ignoring errors. Availability: Unix, Windows. Equivalent to::

      for fd in xrange(fd_low, fd_high):
          try:
              os.close(fd)
          except OSError:
              pass

   .. versionadded:: 2.6


.. function:: dup(fd)

   Return a duplicate of file descriptor *fd*. Availability: Unix,
   Windows.


.. function:: dup2(fd, fd2)

   Duplicate file descriptor *fd* to *fd2*, closing the latter first if necessary.
   Availability: Unix, Windows.


.. function:: fchmod(fd, mode)

   Change the mode of the file given by *fd* to the numeric *mode*.  See the docs
   for :func:`chmod` for possible values of *mode*.  Availability: Unix.

   .. versionadded:: 2.6


.. function:: fchown(fd, uid, gid)

   Change the owner and group id of the file given by *fd* to the numeric *uid*
   and *gid*.  To leave one of the ids unchanged, set it to -1.
   Availability: Unix.

   .. versionadded:: 2.6


.. function:: fdatasync(fd)

   Force write of file with filedescriptor *fd* to disk. Does not force update of
   metadata. Availability: Unix.


.. function:: fpathconf(fd, name)

   Return system configuration information relevant to an open file. *name*
   specifies the configuration value to retrieve; it may be a string which is the
   name of a defined system value; these names are specified in a number of
   standards (POSIX.1, Unix 95, Unix 98, and others).  Some platforms define
   additional names as well.  The names known to the host operating system are
   given in the ``pathconf_names`` dictionary.  For configuration variables not
   included in that mapping, passing an integer for *name* is also accepted.
   Availability: Unix.

   If *name* is a string and is not known, :exc:`ValueError` is raised.  If a
   specific value for *name* is not supported by the host system, even if it is
   included in ``pathconf_names``, an :exc:`OSError` is raised with
   :const:`errno.EINVAL` for the error number.


.. function:: fstat(fd)

   Return status for file descriptor *fd*, like :func:`stat`. Availability:
   Unix, Windows.


.. function:: fstatvfs(fd)

   Return information about the filesystem containing the file associated with file
   descriptor *fd*, like :func:`statvfs`. Availability: Unix.


.. function:: fsync(fd)

   Force write of file with filedescriptor *fd* to disk.  On Unix, this calls the
   native :cfunc:`fsync` function; on Windows, the MS :cfunc:`_commit` function.

   If you're starting with a Python file object *f*, first do ``f.flush()``, and
   then do ``os.fsync(f.fileno())``, to ensure that all internal buffers associated
   with *f* are written to disk. Availability: Unix, and Windows
   starting in 2.2.3.


.. function:: ftruncate(fd, length)

   Truncate the file corresponding to file descriptor *fd*, so that it is at most
   *length* bytes in size. Availability: Unix.


.. function:: isatty(fd)

   Return ``True`` if the file descriptor *fd* is open and connected to a
   tty(-like) device, else ``False``. Availability: Unix.


.. function:: lseek(fd, pos, how)

   Set the current position of file descriptor *fd* to position *pos*, modified
   by *how*: :const:`SEEK_SET` or ``0`` to set the position relative to the
   beginning of the file; :const:`SEEK_CUR` or ``1`` to set it relative to the
   current position; :const:`os.SEEK_END` or ``2`` to set it relative to the end of
   the file. Availability: Unix, Windows.


.. function:: open(file, flags[, mode])

   Open the file *file* and set various flags according to *flags* and possibly its
   mode according to *mode*. The default *mode* is ``0777`` (octal), and the
   current umask value is first masked out.  Return the file descriptor for the
   newly opened file. Availability: Unix, Windows.

   For a description of the flag and mode values, see the C run-time documentation;
   flag constants (like :const:`O_RDONLY` and :const:`O_WRONLY`) are defined in
   this module too (see below).

   .. note::

      This function is intended for low-level I/O.  For normal usage, use the built-in
      function :func:`open`, which returns a "file object" with :meth:`~file.read` and
      :meth:`~file.write` methods (and many more).  To wrap a file descriptor in a "file
      object", use :func:`fdopen`.


.. function:: openpty()

   .. index:: module: pty

   Open a new pseudo-terminal pair. Return a pair of file descriptors ``(master,
   slave)`` for the pty and the tty, respectively. For a (slightly) more portable
   approach, use the :mod:`pty` module. Availability: some flavors of
   Unix.


.. function:: pipe()

   Create a pipe.  Return a pair of file descriptors ``(r, w)`` usable for reading
   and writing, respectively. Availability: Unix, Windows.


.. function:: read(fd, n)

   Read at most *n* bytes from file descriptor *fd*. Return a string containing the
   bytes read.  If the end of the file referred to by *fd* has been reached, an
   empty string is returned. Availability: Unix, Windows.

   .. note::

      This function is intended for low-level I/O and must be applied to a file
      descriptor as returned by :func:`os.open` or :func:`pipe`.  To read a "file object"
      returned by the built-in function :func:`open` or by :func:`popen` or
      :func:`fdopen`, or :data:`sys.stdin`, use its :meth:`~file.read` or
      :meth:`~file.readline` methods.


.. function:: tcgetpgrp(fd)

   Return the process group associated with the terminal given by *fd* (an open
   file descriptor as returned by :func:`os.open`). Availability: Unix.


.. function:: tcsetpgrp(fd, pg)

   Set the process group associated with the terminal given by *fd* (an open file
   descriptor as returned by :func:`os.open`) to *pg*. Availability: Unix.


.. function:: ttyname(fd)

   Return a string which specifies the terminal device associated with
   file descriptor *fd*.  If *fd* is not associated with a terminal device, an
   exception is raised. Availability: Unix.


.. function:: write(fd, str)

   Write the string *str* to file descriptor *fd*. Return the number of bytes
   actually written. Availability: Unix, Windows.

   .. note::

      This function is intended for low-level I/O and must be applied to a file
      descriptor as returned by :func:`os.open` or :func:`pipe`.  To write a "file
      object" returned by the built-in function :func:`open` or by :func:`popen` or
      :func:`fdopen`, or :data:`sys.stdout` or :data:`sys.stderr`, use its
      :meth:`~file.write` method.

The following constants are options for the *flags* parameter to the
:func:`~os.open` function.  They can be combined using the bitwise OR operator
``|``.  Some of them are not available on all platforms.  For descriptions of
their availability and use, consult the :manpage:`open(2)` manual page on Unix
or `the MSDN <http://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windows.


.. data:: O_RDONLY
          O_WRONLY
          O_RDWR
          O_APPEND
          O_CREAT
          O_EXCL
          O_TRUNC

   These constants are available on Unix and Windows.


.. data:: O_DSYNC
          O_RSYNC
          O_SYNC
          O_NDELAY
          O_NONBLOCK
          O_NOCTTY
          O_SHLOCK
          O_EXLOCK

   These constants are only available on Unix.


.. data:: O_BINARY
          O_NOINHERIT
          O_SHORT_LIVED
          O_TEMPORARY
          O_RANDOM
          O_SEQUENTIAL
          O_TEXT

   These constants are only available on Windows.


.. data:: O_ASYNC
          O_DIRECT
          O_DIRECTORY
          O_NOFOLLOW
          O_NOATIME

   These constants are GNU extensions and not present if they are not defined by
   the C library.


.. data:: SEEK_SET
          SEEK_CUR
          SEEK_END

   Parameters to the :func:`lseek` function. Their values are 0, 1, and 2,
   respectively. Availability: Windows, Unix.

   .. versionadded:: 2.5


.. _os-file-dir:

Files and Directories
---------------------

.. function:: access(path, mode)

   Use the real uid/gid to test for access to *path*.  Note that most operations
   will use the effective uid/gid, therefore this routine can be used in a
   suid/sgid environment to test if the invoking user has the specified access to
   *path*.  *mode* should be :const:`F_OK` to test the existence of *path*, or it
   can be the inclusive OR of one or more of :const:`R_OK`, :const:`W_OK`, and
   :const:`X_OK` to test permissions.  Return :const:`True` if access is allowed,
   :const:`False` if not. See the Unix man page :manpage:`access(2)` for more
   information. Availability: Unix, Windows.

   .. note::

      Using :func:`access` to check if a user is authorized to e.g. open a file before
      actually doing so using :func:`open` creates a security hole, because the user
      might exploit the short time interval  between checking and opening the file to
      manipulate it.

   .. note::

      I/O operations may fail even when :func:`access` indicates that they would
      succeed, particularly for operations on network filesystems which may have
      permissions semantics beyond the usual POSIX permission-bit model.


.. data:: F_OK

   Value to pass as the *mode* parameter of :func:`access` to test the existence of
   *path*.


.. data:: R_OK

   Value to include in the *mode* parameter of :func:`access` to test the
   readability of *path*.


.. data:: W_OK

   Value to include in the *mode* parameter of :func:`access` to test the
   writability of *path*.


.. data:: X_OK

   Value to include in the *mode* parameter of :func:`access` to determine if
   *path* can be executed.


.. function:: chdir(path)

   .. index:: single: directory; changing

   Change the current working directory to *path*. Availability: Unix,
   Windows.


.. function:: fchdir(fd)

   Change the current working directory to the directory represented by the file
   descriptor *fd*.  The descriptor must refer to an opened directory, not an open
   file. Availability: Unix.

   .. versionadded:: 2.3


.. function:: getcwd()

   Return a string representing the current working directory. Availability:
   Unix, Windows.


.. function:: getcwdu()

   Return a Unicode object representing the current working directory.
   Availability: Unix, Windows.

   .. versionadded:: 2.3


.. function:: chflags(path, flags)

   Set the flags of *path* to the numeric *flags*. *flags* may take a combination
   (bitwise OR) of the following values (as defined in the :mod:`stat` module):

   * ``UF_NODUMP``
   * ``UF_IMMUTABLE``
   * ``UF_APPEND``
   * ``UF_OPAQUE``
   * ``UF_NOUNLINK``
   * ``SF_ARCHIVED``
   * ``SF_IMMUTABLE``
   * ``SF_APPEND``
   * ``SF_NOUNLINK``
   * ``SF_SNAPSHOT``

   Availability: Unix.

   .. versionadded:: 2.6


.. function:: chroot(path)

   Change the root directory of the current process to *path*. Availability:
   Unix.

   .. versionadded:: 2.2


.. function:: chmod(path, mode)

   Change the mode of *path* to the numeric *mode*. *mode* may take one of the
   following values (as defined in the :mod:`stat` module) or bitwise ORed
   combinations of them:


   * :data:`stat.S_ISUID`
   * :data:`stat.S_ISGID`
   * :data:`stat.S_ENFMT`
   * :data:`stat.S_ISVTX`
   * :data:`stat.S_IREAD`
   * :data:`stat.S_IWRITE`
   * :data:`stat.S_IEXEC`
   * :data:`stat.S_IRWXU`
   * :data:`stat.S_IRUSR`
   * :data:`stat.S_IWUSR`
   * :data:`stat.S_IXUSR`
   * :data:`stat.S_IRWXG`
   * :data:`stat.S_IRGRP`
   * :data:`stat.S_IWGRP`
   * :data:`stat.S_IXGRP`
   * :data:`stat.S_IRWXO`
   * :data:`stat.S_IROTH`
   * :data:`stat.S_IWOTH`
   * :data:`stat.S_IXOTH`

   Availability: Unix, Windows.

   .. note::

      Although Windows supports :func:`chmod`, you can only  set the file's read-only
      flag with it (via the ``stat.S_IWRITE``  and ``stat.S_IREAD``
      constants or a corresponding integer value).  All other bits are
      ignored.


.. function:: chown(path, uid, gid)

   Change the owner and group id of *path* to the numeric *uid* and *gid*. To leave
   one of the ids unchanged, set it to -1. Availability: Unix.


.. function:: lchflags(path, flags)

   Set the flags of *path* to the numeric *flags*, like :func:`chflags`, but do not
   follow symbolic links. Availability: Unix.

   .. versionadded:: 2.6


.. function:: lchmod(path, mode)

   Change the mode of *path* to the numeric *mode*. If path is a symlink, this
   affects the symlink rather than the target. See the docs for :func:`chmod`
   for possible values of *mode*.  Availability: Unix.

   .. versionadded:: 2.6


.. function:: lchown(path, uid, gid)

   Change the owner and group id of *path* to the numeric *uid* and *gid*. This
   function will not follow symbolic links. Availability: Unix.

   .. versionadded:: 2.3


.. function:: link(src, dst)

   Create a hard link pointing to *src* named *dst*. Availability: Unix.


.. function:: listdir(path)

   Return a list containing the names of the entries in the directory given by
   *path*.  The list is in arbitrary order.  It does not include the special
   entries ``'.'`` and ``'..'`` even if they are present in the
   directory.  Availability: Unix, Windows.

   .. versionchanged:: 2.3
      On Windows NT/2k/XP and Unix, if *path* is a Unicode object, the result will be
      a list of Unicode objects. Undecodable filenames will still be returned as
      string objects.


.. function:: lstat(path)

   Like :func:`stat`, but do not follow symbolic links.  This is an alias for
   :func:`stat` on platforms that do not support symbolic links, such as
   Windows.


.. function:: mkfifo(path[, mode])

   Create a FIFO (a named pipe) named *path* with numeric mode *mode*.  The default
   *mode* is ``0666`` (octal).  The current umask value is first masked out from
   the mode. Availability: Unix.

   FIFOs are pipes that can be accessed like regular files.  FIFOs exist until they
   are deleted (for example with :func:`os.unlink`). Generally, FIFOs are used as
   rendezvous between "client" and "server" type processes: the server opens the
   FIFO for reading, and the client opens it for writing.  Note that :func:`mkfifo`
   doesn't open the FIFO --- it just creates the rendezvous point.


.. function:: mknod(filename[, mode=0600, device])

   Create a filesystem node (file, device special file or named pipe) named
   *filename*. *mode* specifies both the permissions to use and the type of node to
   be created, being combined (bitwise OR) with one of ``stat.S_IFREG``,
   ``stat.S_IFCHR``, ``stat.S_IFBLK``,
   and ``stat.S_IFIFO`` (those constants are available in :mod:`stat`).
   For ``stat.S_IFCHR`` and
   ``stat.S_IFBLK``, *device* defines the newly created device special file (probably using
   :func:`os.makedev`), otherwise it is ignored.

   .. versionadded:: 2.3


.. function:: major(device)

   Extract the device major number from a raw device number (usually the
   :attr:`st_dev` or :attr:`st_rdev` field from :ctype:`stat`).

   .. versionadded:: 2.3


.. function:: minor(device)

   Extract the device minor number from a raw device number (usually the
   :attr:`st_dev` or :attr:`st_rdev` field from :ctype:`stat`).

   .. versionadded:: 2.3


.. function:: makedev(major, minor)

   Compose a raw device number from the major and minor device numbers.

   .. versionadded:: 2.3


.. function:: mkdir(path[, mode])

   Create a directory named *path* with numeric mode *mode*. The default *mode* is
   ``0777`` (octal).  On some systems, *mode* is ignored.  Where it is used, the
   current umask value is first masked out. Availability: Unix, Windows.

   It is also possible to create temporary directories; see the
   :mod:`tempfile` module's :func:`tempfile.mkdtemp` function.


.. function:: makedirs(path[, mode])

   .. index::
      single: directory; creating
      single: UNC paths; and os.makedirs()

   Recursive directory creation function.  Like :func:`mkdir`, but makes all
   intermediate-level directories needed to contain the leaf directory.  Throws an
   :exc:`error` exception if the leaf directory already exists or cannot be
   created.  The default *mode* is ``0777`` (octal).  On some systems, *mode* is
   ignored. Where it is used, the current umask value is first masked out.

   .. note::

      :func:`makedirs` will become confused if the path elements to create include
      :data:`os.pardir`.

   .. versionadded:: 1.5.2

   .. versionchanged:: 2.3
      This function now handles UNC paths correctly.


.. function:: pathconf(path, name)

   Return system configuration information relevant to a named file. *name*
   specifies the configuration value to retrieve; it may be a string which is the
   name of a defined system value; these names are specified in a number of
   standards (POSIX.1, Unix 95, Unix 98, and others).  Some platforms define
   additional names as well.  The names known to the host operating system are
   given in the ``pathconf_names`` dictionary.  For configuration variables not
   included in that mapping, passing an integer for *name* is also accepted.
   Availability: Unix.

   If *name* is a string and is not known, :exc:`ValueError` is raised.  If a
   specific value for *name* is not supported by the host system, even if it is
   included in ``pathconf_names``, an :exc:`OSError` is raised with
   :const:`errno.EINVAL` for the error number.


.. data:: pathconf_names

   Dictionary mapping names accepted by :func:`pathconf` and :func:`fpathconf` to
   the integer values defined for those names by the host operating system.  This
   can be used to determine the set of names known to the system. Availability:
   Unix.


.. function:: readlink(path)

   Return a string representing the path to which the symbolic link points.  The
   result may be either an absolute or relative pathname; if it is relative, it may
   be converted to an absolute pathname using ``os.path.join(os.path.dirname(path),
   result)``.

   .. versionchanged:: 2.6
      If the *path* is a Unicode object the result will also be a Unicode object.

   Availability: Unix.


.. function:: remove(path)

   Remove the file *path*.  If *path* is a directory, :exc:`OSError` is raised; see
   :func:`rmdir` below to remove a directory.  This is identical to the
   :func:`unlink` function documented below.  On Windows, attempting to remove a
   file that is in use causes an exception to be raised; on Unix, the directory
   entry is removed but the storage allocated to the file is not made available
   until the original file is no longer in use. Availability: Unix,
   Windows.


.. function:: removedirs(path)

   .. index:: single: directory; deleting

   Remove directories recursively.  Works like :func:`rmdir` except that, if the
   leaf directory is successfully removed, :func:`removedirs`  tries to
   successively remove every parent directory mentioned in  *path* until an error
   is raised (which is ignored, because it generally means that a parent directory
   is not empty). For example, ``os.removedirs('foo/bar/baz')`` will first remove
   the directory ``'foo/bar/baz'``, and then remove ``'foo/bar'`` and ``'foo'`` if
   they are empty. Raises :exc:`OSError` if the leaf directory could not be
   successfully removed.

   .. versionadded:: 1.5.2


.. function:: rename(src, dst)

   Rename the file or directory *src* to *dst*.  If *dst* is a directory,
   :exc:`OSError` will be raised.  On Unix, if *dst* exists and is a file, it will
   be replaced silently if the user has permission.  The operation may fail on some
   Unix flavors if *src* and *dst* are on different filesystems.  If successful,
   the renaming will be an atomic operation (this is a POSIX requirement).  On
   Windows, if *dst* already exists, :exc:`OSError` will be raised even if it is a
   file; there may be no way to implement an atomic rename when *dst* names an
   existing file. Availability: Unix, Windows.


.. function:: renames(old, new)

   Recursive directory or file renaming function. Works like :func:`rename`, except
   creation of any intermediate directories needed to make the new pathname good is
   attempted first. After the rename, directories corresponding to rightmost path
   segments of the old name will be pruned away using :func:`removedirs`.

   .. versionadded:: 1.5.2

   .. note::

      This function can fail with the new directory structure made if you lack
      permissions needed to remove the leaf directory or file.


.. function:: rmdir(path)

   Remove the directory *path*. Availability: Unix, Windows.


.. function:: stat(path)

   Perform a :cfunc:`stat` system call on the given path.  The return value is an
   object whose attributes correspond to the members of the :ctype:`stat`
   structure, namely: :attr:`st_mode` (protection bits), :attr:`st_ino` (inode
   number), :attr:`st_dev` (device), :attr:`st_nlink` (number of hard links),
   :attr:`st_uid` (user id of owner), :attr:`st_gid` (group id of owner),
   :attr:`st_size` (size of file, in bytes), :attr:`st_atime` (time of most recent
   access), :attr:`st_mtime` (time of most recent content modification),
   :attr:`st_ctime` (platform dependent; time of most recent metadata change on
   Unix, or the time of creation on Windows)::

      >>> import os
      >>> statinfo = os.stat('somefile.txt')
      >>> statinfo
      (33188, 422511L, 769L, 1, 1032, 100, 926L, 1105022698,1105022732, 1105022732)
      >>> statinfo.st_size
      926L
      >>>

   .. versionchanged:: 2.3
      If :func:`stat_float_times` returns ``True``, the time values are floats, measuring
      seconds. Fractions of a second may be reported if the system supports that. On
      Mac OS, the times are always floats. See :func:`stat_float_times` for further
      discussion.

   On some Unix systems (such as Linux), the following attributes may also be
   available: :attr:`st_blocks` (number of blocks allocated for file),
   :attr:`st_blksize` (filesystem blocksize), :attr:`st_rdev` (type of device if an
   inode device). :attr:`st_flags` (user defined flags for file).

   On other Unix systems (such as FreeBSD), the following attributes may be
   available (but may be only filled out if root tries to use them): :attr:`st_gen`
   (file generation number), :attr:`st_birthtime` (time of file creation).

   On Mac OS systems, the following attributes may also be available:
   :attr:`st_rsize`, :attr:`st_creator`, :attr:`st_type`.

   On RISCOS systems, the following attributes are also available: :attr:`st_ftype`
   (file type), :attr:`st_attrs` (attributes), :attr:`st_obtype` (object type).

   .. index:: module: stat

   For backward compatibility, the return value of :func:`stat` is also accessible
   as a tuple of at least 10 integers giving the most important (and portable)
   members of the :ctype:`stat` structure, in the order :attr:`st_mode`,
   :attr:`st_ino`, :attr:`st_dev`, :attr:`st_nlink`, :attr:`st_uid`,
   :attr:`st_gid`, :attr:`st_size`, :attr:`st_atime`, :attr:`st_mtime`,
   :attr:`st_ctime`. More items may be added at the end by some implementations.
   The standard module :mod:`stat` defines functions and constants that are useful
   for extracting information from a :ctype:`stat` structure. (On Windows, some
   items are filled with dummy values.)

   .. note::

      The exact meaning and resolution of the :attr:`st_atime`, :attr:`st_mtime`, and
      :attr:`st_ctime` members depends on the operating system and the file system.
      For example, on Windows systems using the FAT or FAT32 file systems,
      :attr:`st_mtime` has 2-second resolution, and :attr:`st_atime` has only 1-day
      resolution.  See your operating system documentation for details.

   Availability: Unix, Windows.

   .. versionchanged:: 2.2
      Added access to values as attributes of the returned object.

   .. versionchanged:: 2.5
      Added :attr:`st_gen` and :attr:`st_birthtime`.


.. function:: stat_float_times([newvalue])

   Determine whether :class:`stat_result` represents time stamps as float objects.
   If *newvalue* is ``True``, future calls to :func:`stat` return floats, if it is
   ``False``, future calls return ints. If *newvalue* is omitted, return the
   current setting.

   For compatibility with older Python versions, accessing :class:`stat_result` as
   a tuple always returns integers.

   .. versionchanged:: 2.5
      Python now returns float values by default. Applications which do not work
      correctly with floating point time stamps can use this function to restore the
      old behaviour.

   The resolution of the timestamps (that is the smallest possible fraction)
   depends on the system. Some systems only support second resolution; on these
   systems, the fraction will always be zero.

   It is recommended that this setting is only changed at program startup time in
   the *__main__* module; libraries should never change this setting. If an
   application uses a library that works incorrectly if floating point time stamps
   are processed, this application should turn the feature off until the library
   has been corrected.


.. function:: statvfs(path)

   Perform a :cfunc:`statvfs` system call on the given path.  The return value is
   an object whose attributes describe the filesystem on the given path, and
   correspond to the members of the :ctype:`statvfs` structure, namely:
   :attr:`f_bsize`, :attr:`f_frsize`, :attr:`f_blocks`, :attr:`f_bfree`,
   :attr:`f_bavail`, :attr:`f_files`, :attr:`f_ffree`, :attr:`f_favail`,
   :attr:`f_flag`, :attr:`f_namemax`. Availability: Unix.

   .. index:: module: statvfs

   For backward compatibility, the return value is also accessible as a tuple whose
   values correspond to the attributes, in the order given above. The standard
   module :mod:`statvfs` defines constants that are useful for extracting
   information from a :ctype:`statvfs` structure when accessing it as a sequence;
   this remains useful when writing code that needs to work with versions of Python
   that don't support accessing the fields as attributes.

   .. versionchanged:: 2.2
      Added access to values as attributes of the returned object.


.. function:: symlink(src, dst)

   Create a symbolic link pointing to *src* named *dst*. Availability: Unix.


.. function:: tempnam([dir[, prefix]])

   Return a unique path name that is reasonable for creating a temporary file.
   This will be an absolute path that names a potential directory entry in the
   directory *dir* or a common location for temporary files if *dir* is omitted or
   ``None``.  If given and not ``None``, *prefix* is used to provide a short prefix
   to the filename.  Applications are responsible for properly creating and
   managing files created using paths returned by :func:`tempnam`; no automatic
   cleanup is provided. On Unix, the environment variable :envvar:`TMPDIR`
   overrides *dir*, while on Windows :envvar:`TMP` is used.  The specific
   behavior of this function depends on the C library implementation; some aspects
   are underspecified in system documentation.

   .. warning::

      Use of :func:`tempnam` is vulnerable to symlink attacks; consider using
      :func:`tmpfile` (section :ref:`os-newstreams`) instead.

   Availability: Unix, Windows.


.. function:: tmpnam()

   Return a unique path name that is reasonable for creating a temporary file.
   This will be an absolute path that names a potential directory entry in a common
   location for temporary files.  Applications are responsible for properly
   creating and managing files created using paths returned by :func:`tmpnam`; no
   automatic cleanup is provided.

   .. warning::

      Use of :func:`tmpnam` is vulnerable to symlink attacks; consider using
      :func:`tmpfile` (section :ref:`os-newstreams`) instead.

   Availability: Unix, Windows.  This function probably shouldn't be used on
   Windows, though: Microsoft's implementation of :func:`tmpnam` always creates a
   name in the root directory of the current drive, and that's generally a poor
   location for a temp file (depending on privileges, you may not even be able to
   open a file using this name).


.. data:: TMP_MAX

   The maximum number of unique names that :func:`tmpnam` will generate before
   reusing names.


.. function:: unlink(path)

   Remove the file *path*.  This is the same function as :func:`remove`; the
   :func:`unlink` name is its traditional Unix name. Availability: Unix,
   Windows.


.. function:: utime(path, times)

   Set the access and modified times of the file specified by *path*. If *times*
   is ``None``, then the file's access and modified times are set to the current
   time. (The effect is similar to running the Unix program :program:`touch` on
   the path.)  Otherwise, *times* must be a 2-tuple of numbers, of the form
   ``(atime, mtime)`` which is used to set the access and modified times,
   respectively. Whether a directory can be given for *path* depends on whether
   the operating system implements directories as files (for example, Windows
   does not).  Note that the exact times you set here may not be returned by a
   subsequent :func:`stat` call, depending on the resolution with which your
   operating system records access and modification times; see :func:`stat`.

   .. versionchanged:: 2.0
      Added support for ``None`` for *times*.

   Availability: Unix, Windows.


.. function:: walk(top[, topdown=True [, onerror=None[, followlinks=False]]])

   .. index::
      single: directory; walking
      single: directory; traversal

   Generate the file names in a directory tree by walking the tree
   either top-down or bottom-up. For each directory in the tree rooted at directory
   *top* (including *top* itself), it yields a 3-tuple ``(dirpath, dirnames,
   filenames)``.

   *dirpath* is a string, the path to the directory.  *dirnames* is a list of the
   names of the subdirectories in *dirpath* (excluding ``'.'`` and ``'..'``).
   *filenames* is a list of the names of the non-directory files in *dirpath*.
   Note that the names in the lists contain no path components.  To get a full path
   (which begins with *top*) to a file or directory in *dirpath*, do
   ``os.path.join(dirpath, name)``.

   If optional argument *topdown* is ``True`` or not specified, the triple for a
   directory is generated before the triples for any of its subdirectories
   (directories are generated top-down).  If *topdown* is ``False``, the triple for a
   directory is generated after the triples for all of its subdirectories
   (directories are generated bottom-up).

   When *topdown* is ``True``, the caller can modify the *dirnames* list in-place
   (perhaps using :keyword:`del` or slice assignment), and :func:`walk` will only
   recurse into the subdirectories whose names remain in *dirnames*; this can be
   used to prune the search, impose a specific order of visiting, or even to inform
   :func:`walk` about directories the caller creates or renames before it resumes
   :func:`walk` again.  Modifying *dirnames* when *topdown* is ``False`` is
   ineffective, because in bottom-up mode the directories in *dirnames* are
   generated before *dirpath* itself is generated.

   By default errors from the :func:`listdir` call are ignored.  If optional
   argument *onerror* is specified, it should be a function; it will be called with
   one argument, an :exc:`OSError` instance.  It can report the error to continue
   with the walk, or raise the exception to abort the walk.  Note that the filename
   is available as the ``filename`` attribute of the exception object.

   By default, :func:`walk` will not walk down into symbolic links that resolve to
   directories. Set *followlinks* to ``True`` to visit directories pointed to by
   symlinks, on systems that support them.

   .. versionadded:: 2.6
      The *followlinks* parameter.

   .. note::

      Be aware that setting *followlinks* to ``True`` can lead to infinite recursion if a
      link points to a parent directory of itself. :func:`walk` does not keep track of
      the directories it visited already.

   .. note::

      If you pass a relative pathname, don't change the current working directory
      between resumptions of :func:`walk`.  :func:`walk` never changes the current
      directory, and assumes that its caller doesn't either.

   This example displays the number of bytes taken by non-directory files in each
   directory under the starting directory, except that it doesn't look under any
   CVS subdirectory::

      import os
      from os.path import join, getsize
      for root, dirs, files in os.walk('python/Lib/email'):
          print root, "consumes",
          print sum(getsize(join(root, name)) for name in files),
          print "bytes in", len(files), "non-directory files"
          if 'CVS' in dirs:
              dirs.remove('CVS')  # don't visit CVS directories

   In the next example, walking the tree bottom-up is essential: :func:`rmdir`
   doesn't allow deleting a directory before the directory is empty::

      # Delete everything reachable from the directory named in "top",
      # assuming there are no symbolic links.
      # CAUTION:  This is dangerous!  For example, if top == '/', it
      # could delete all your disk files.
      import os
      for root, dirs, files in os.walk(top, topdown=False):
          for name in files:
              os.remove(os.path.join(root, name))
          for name in dirs:
              os.rmdir(os.path.join(root, name))

   .. versionadded:: 2.3


.. _os-process:

Process Management
------------------

These functions may be used to create and manage processes.

The various :func:`exec\*` functions take a list of arguments for the new
program loaded into the process.  In each case, the first of these arguments is
passed to the new program as its own name rather than as an argument a user may
have typed on a command line.  For the C programmer, this is the ``argv[0]``
passed to a program's :cfunc:`main`.  Fo…