: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'``.

.. data:: path

   The corresponding operating system dependent standard module for pathname

   operations, such as :mod:`posixpath` or :mod:`ntpath`.  Thus, given the proper

   imports, ``os.path.split(file)`` is equivalent to but more portable than

   ``posixpath.split(file)``.  Note that this is also an importable module: it may

   be imported directly as :mod:`os.path`.

.. _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:`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:`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:`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.