This module provides a more portable way of using operating system dependent
-functionality than importing a operating system dependent built-in module like
+functionality than importing an operating system dependent built-in module like
:mod:`posix` or :mod:`nt`. 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
This module searches for an operating system dependent built-in module like
:mod:`mac` or :mod:`posix` and exports the same functions and data as found
-there. The design of all Python's built-in operating system dependent modules
+there. 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
.. 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:
+ "set id" bit on the file being executed in the current process. Availability:
Unix.
.. index:: single: user; effective id
- Return the current process' effective user id. Availability: Unix.
+ Return the current process's effective user id. Availability: Unix.
.. function:: getgid()
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.
+ effective user id. Availability: Unix.
.. function:: getpgid(pid)
.. index:: single: user; id
- Return the current process' user id. Availability: Unix.
+ Return the current process's user id. Availability: Unix.
.. function:: getenv(varname[, value])
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 typical available only to the superuser.
+ identifying a group. This operation is typically available only to the superuser.
Availability: Unix.
.. versionadded:: 2.2
.. function:: setpgrp()
- Calls the system call :cfunc:`setpgrp` or :cfunc:`setpgrp(0, 0)` depending on
+ 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)
- Calls the system call :cfunc:`setpgid` to set the process group id of the
+ 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:: getsid(pid)
- Calls the system call :cfunc:`getsid`. See the Unix manual for the semantics.
+ Call the system call :cfunc:`getsid`. See the Unix manual for the semantics.
Availability: Unix.
.. versionadded:: 2.4
.. function:: setsid()
- Calls the system call :cfunc:`setsid`. See the Unix manual for the semantics.
+ Call the system call :cfunc:`setsid`. See the Unix manual for the semantics.
Availability: Unix.
.. index:: single: user; id, setting
- Set the current process' user id. Availability: Unix.
+ Set the current process's user id. Availability: Unix.
.. placed in this section since it relates to errno.... a little weak
.. function:: umask(mask)
- Set the current numeric umask and returns the previous umask. Availability:
+ Set the current numeric umask and return the previous umask. Availability:
Unix, Windows.
.. function:: popen2(cmd[, mode[, bufsize]])
- Executes *cmd* as a sub-process. Returns the file objects ``(child_stdin,
+ Execute *cmd* as a sub-process and return the file objects ``(child_stdin,
child_stdout)``.
.. deprecated:: 2.6
.. function:: popen3(cmd[, mode[, bufsize]])
- Executes *cmd* as a sub-process. Returns the file objects ``(child_stdin,
+ Execute *cmd* as a sub-process and return the file objects ``(child_stdin,
child_stdout, child_stderr)``.
.. deprecated:: 2.6
.. function:: popen4(cmd[, mode[, bufsize]])
- Executes *cmd* as a sub-process. Returns the file objects ``(child_stdin,
+ Execute *cmd* as a sub-process and return the file objects ``(child_stdin,
child_stdout_and_stderr)``.
.. deprecated:: 2.6
.. function:: lseek(fd, pos, how)
- Set the current position of file descriptor *fd* to position *pos*, modified by
- *how*: ``0`` to set the position relative to the beginning of the file; ``1`` to
- set it relative to the current position; ``2`` to set it relative to the end of
+ 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: Macintosh, Unix, Windows.
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: Macintosh, Some flavors of
+ approach, use the :mod:`pty` module. Availability: Macintosh, some flavors of
Unix.
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 read a "file object"
returned by the built-in function :func:`open` or by :func:`popen` or
- :func:`fdopen`, or ``sys.stdin``, use its :meth:`read` or :meth:`readline`
+ :func:`fdopen`, or :data:`sys.stdin`, use its :meth:`read` or :meth:`readline`
methods.
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 write a "file
object" returned by the built-in function :func:`open` or by :func:`popen` or
- :func:`fdopen`, or ``sys.stdout`` or ``sys.stderr``, use its :meth:`write`
+ :func:`fdopen`, or :data:`sys.stdout` or :data:`sys.stderr`, use its :meth:`write`
method.
The following data items are available for use in constructing the *flags*
O_TRUNC
Options for the *flag* argument to the :func:`open` function. These can be
- bit-wise OR'd together. Availability: Macintosh, Unix, Windows.
+ combined using the bitwise OR operator ``|``. Availability: Macintosh, Unix, Windows.
.. data:: O_DSYNC
O_TEXT
Options for the *flag* argument to the :func:`open` function. These can be
- bit-wise OR'd together. Availability: Windows.
+ combined using the bitwise OR operator ``|``. Availability: Windows.
.. data:: O_DIRECT
.. 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 or-ed
+ following values (as defined in the :mod:`stat` module) or bitwise ORed
combinations of them:
.. function:: lchown(path, uid, gid)
- Change the owner and group id of *path* to the numeric *uid* and gid. This
+ Change the owner and group id of *path* to the numeric *uid* and *gid*. This
function will not follow symbolic links. Availability: Macintosh, Unix.
.. versionadded:: 2.3
.. function:: major(device)
- Extracts the device major number from a raw device number (usually the
+ 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)
- Extracts the device minor number from a raw device number (usually the
+ 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)
- Composes a raw device number from the major and minor device numbers.
+ Compose a raw device number from the major and minor device numbers.
.. versionadded:: 2.3
.. note::
:func:`makedirs` will become confused if the path elements to create include
- *os.pardir*.
+ :data:`os.pardir`.
.. versionadded:: 1.5.2
.. index:: single: directory; deleting
- Removes directories recursively. Works like :func:`rmdir` except that, if the
+ 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
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 removed silently if the user has permission. The operation may fail on some
+ 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
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_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
>>>
.. versionchanged:: 2.3
- If :func:`stat_float_times` returns true, the time values are floats, measuring
+ 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.
Added access to values as attributes of the returned object.
.. versionchanged:: 2.5
- Added st_gen, st_birthtime.
+ Added :attr:`st_gen` and :attr:`st_birthtime`.
.. function:: stat_float_times([newvalue])
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 the :envvar:`TMP` is used. The specific
+ 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.
single: directory; walking
single: directory; traversal
- :func:`walk` generates 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
+ 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)``.
(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
+ 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
+ (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).
+ (directories are generated bottom-up).
- When *topdown* is true, the caller can modify the *dirnames* list in-place
+ 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
+ :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 ``os.listdir()`` call are ignored. If optional
+ 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
+ directories. Set *followlinks* to ``True`` to visit directories pointed to by
symlinks, on systems that support them.
.. versionadded:: 2.6
.. note::
- Be aware that setting *followlinks* to true can lead to infinite recursion if a
+ 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.
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`
+ 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',
+ # 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.
These functions all execute a new program, replacing the current process; they
do not return. On Unix, the new executable is loaded into the current process,
- and will have the same process ID as the caller. Errors will be reported as
+ and will have the same process id as the caller. Errors will be reported as
:exc:`OSError` exceptions.
- The ``'l'`` and ``'v'`` variants of the :func:`exec\*` functions differ in how
- command-line arguments are passed. The ``'l'`` variants are perhaps the easiest
+ The "l" and "v" variants of the :func:`exec\*` functions differ in how
+ command-line arguments are passed. The "l" variants are perhaps the easiest
to work with if the number of parameters is fixed when the code is written; the
individual parameters simply become additional parameters to the :func:`execl\*`
- functions. The ``'v'`` variants are good when the number of parameters is
+ functions. The "v" variants are good when the number of parameters is
variable, with the arguments being passed in a list or tuple as the *args*
parameter. In either case, the arguments to the child process should start with
the name of the command being run, but this is not enforced.
- The variants which include a ``'p'`` near the end (:func:`execlp`,
+ The variants which include a "p" near the end (:func:`execlp`,
:func:`execlpe`, :func:`execvp`, and :func:`execvpe`) will use the
:envvar:`PATH` environment variable to locate the program *file*. When the
environment is being replaced (using one of the :func:`exec\*e` variants,
path.
For :func:`execle`, :func:`execlpe`, :func:`execve`, and :func:`execvpe` (note
- that these all end in ``'e'``), the *env* parameter must be a mapping which is
+ that these all end in "e"), the *env* parameter must be a mapping which is
used to define the environment variables for the new process; the :func:`execl`,
:func:`execlp`, :func:`execv`, and :func:`execvp` all cause the new process to
inherit the environment of the current process. Availability: Macintosh, Unix,
The standard way to exit is ``sys.exit(n)``. :func:`_exit` should normally only
be used in the child process after a :func:`fork`.
-The following exit codes are a defined, and can be used with :func:`_exit`,
+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.
.. function:: fork()
- Fork a child process. Return ``0`` in the child, the child's process id in the
+ Fork a child process. Return ``0`` in the child and the child's process id in the
parent. Availability: Macintosh, Unix.
terminal. Return a pair of ``(pid, fd)``, where *pid* is ``0`` in the child, the
new child's process id in the parent, and *fd* is the file descriptor of the
master end of the pseudo-terminal. For a more portable approach, use the
- :mod:`pty` module. Availability: Macintosh, Some flavors of Unix.
+ :mod:`pty` module. Availability: Macintosh, some flavors of Unix.
.. function:: kill(pid, sig)
spawning new processes and retrieving their results; using that module is
preferable to using these functions.)
- If *mode* is :const:`P_NOWAIT`, this function returns the process ID of the new
+ If *mode* is :const:`P_NOWAIT`, this function returns the process id of the new
process; if *mode* is :const:`P_WAIT`, returns the process's exit code if it
exits normally, or ``-signal``, where *signal* is the signal that killed the
- process. On Windows, the process ID will actually be the process handle, so can
+ process. On Windows, the process id will actually be the process handle, so can
be used with the :func:`waitpid` function.
- The ``'l'`` and ``'v'`` variants of the :func:`spawn\*` functions differ in how
- command-line arguments are passed. The ``'l'`` variants are perhaps the easiest
+ The "l" and "v" variants of the :func:`spawn\*` functions differ in how
+ command-line arguments are passed. The "l" variants are perhaps the easiest
to work with if the number of parameters is fixed when the code is written; the
individual parameters simply become additional parameters to the
- :func:`spawnl\*` functions. The ``'v'`` variants are good when the number of
+ :func:`spawnl\*` functions. The "v" variants are good when the number of
parameters is variable, with the arguments being passed in a list or tuple as
the *args* parameter. In either case, the arguments to the child process must
start with the name of the command being run.
- The variants which include a second ``'p'`` near the end (:func:`spawnlp`,
+ The variants which include a second "p" near the end (:func:`spawnlp`,
:func:`spawnlpe`, :func:`spawnvp`, and :func:`spawnvpe`) will use the
:envvar:`PATH` environment variable to locate the program *file*. When the
environment is being replaced (using one of the :func:`spawn\*e` variants,
appropriate absolute or relative path.
For :func:`spawnle`, :func:`spawnlpe`, :func:`spawnve`, and :func:`spawnvpe`
- (note that these all end in ``'e'``), the *env* parameter must be a mapping
+ (note that these all end in "e"), the *env* parameter must be a mapping
which is used to define the environment variables for the new process; the
:func:`spawnl`, :func:`spawnlp`, :func:`spawnv`, and :func:`spawnvp` all cause
the new process to inherit the environment of the current process.
Possible values for the *mode* parameter to the :func:`spawn\*` family of
functions. If either of these values is given, the :func:`spawn\*` functions
- will return as soon as the new process has been created, with the process ID as
+ will return as soon as the new process has been created, with the process id as
the return value. Availability: Macintosh, Unix, Windows.
.. versionadded:: 1.6
Execute the command (a string) in a subshell. This is implemented by calling
the Standard C function :cfunc:`system`, and has the same limitations. Changes
- to ``posix.environ``, ``sys.stdin``, etc. are not reflected in the environment
- of the executed command.
+ to :data:`os.environ`, :data:`sys.stdin`, etc. are not reflected in the
+ environment of the executed command.
On Unix, the return value is the exit status of the process encoded in the
format specified for :func:`wait`. Note that POSIX does not specify the meaning
.. function:: WCOREDUMP(status)
- Returns ``True`` if a core dump was generated for the process, otherwise it
- returns ``False``. Availability: Macintosh, Unix.
+ Return ``True`` if a core dump was generated for the process, otherwise
+ return ``False``. Availability: Macintosh, Unix.
.. versionadded:: 2.3
.. function:: WIFCONTINUED(status)
- Returns ``True`` if the process has been continued from a job control stop,
- otherwise it returns ``False``. Availability: Unix.
+ Return ``True`` if the process has been continued from a job control stop,
+ otherwise return ``False``. Availability: Unix.
.. versionadded:: 2.3
.. function:: WIFSTOPPED(status)
- Returns ``True`` if the process has been stopped, otherwise it returns
+ Return ``True`` if the process has been stopped, otherwise return
``False``. Availability: Unix.
.. function:: WIFSIGNALED(status)
- Returns ``True`` if the process exited due to a signal, otherwise it returns
+ Return ``True`` if the process exited due to a signal, otherwise return
``False``. Availability: Macintosh, Unix.
.. function:: WIFEXITED(status)
- Returns ``True`` if the process exited using the :manpage:`exit(2)` system call,
- otherwise it returns ``False``. Availability: Macintosh, Unix.
+ Return ``True`` if the process exited using the :manpage:`exit(2)` system call,
+ otherwise return ``False``. Availability: Macintosh, Unix.
.. function:: WEXITSTATUS(status)
defined for those names by the host operating system. This can be used to
determine the set of names known to the system. Availability: Macintosh, Unix.
-The follow data values are used to support path manipulation operations. These
+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.
projects / python / commitdiff