sandbox/morph / Doc / library / os.rst

Full commit

:mod:`os` --- 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.

Notes on the availability of these functions:

  • 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.
  • An "Availability: Unix" note means that this function is commonly found on Unix systems. It does not make any claims about its existence on a specific operating system.
  • If not separately noted, all functions that claim "Availability: Unix" are supported on Mac OS X, which builds on a Unix core.


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.

Process Parameters

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

File Object Creation

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

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

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

(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.

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.

The :meth:`~file.fileno` method can be used to obtain the file descriptor associated with a file object when required. Note that using the file descriptor directly will bypass the file object methods, ignoring aspects such as internal buffering of data.

open() flag constants

The following constants are options for the flags parameter to the :func:`` 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 on Windows.

Files and Directories

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 :c:func:`main`. For example, os.execv('/bin/echo', ['foo', 'bar']) will only print bar on standard output; foo will seem to be ignored.

The following exit codes are defined and can be used with :func:`_exit`, although they are not required. These are typically used for system programs written in Python, such as a mail server's external command delivery program.


Some of these may not be available on all Unix platforms, since there is some variation. These constants are defined where they are defined by the underlying platform.

The following functions take a process status code as returned by :func:`system`, :func:`wait`, or :func:`waitpid` as a parameter. They may be used to determine the disposition of a process.

Miscellaneous System Information

The following data values are used to support path manipulation operations. These are defined for all platforms.

Higher-level operations on pathnames are defined in the :mod:`os.path` module.

Miscellaneous Functions