mirror of https://github.com/python/cpython
1945 lines
73 KiB
TeX
1945 lines
73 KiB
TeX
\section{\module{os} ---
|
|
Miscellaneous operating system interfaces}
|
|
|
|
\declaremodule{standard}{os}
|
|
\modulesynopsis{Miscellaneous operating system interfaces.}
|
|
|
|
|
|
This module provides a more portable way of using operating system
|
|
dependent functionality than importing a operating system dependent
|
|
built-in module like \refmodule{posix} or \module{nt}.
|
|
|
|
This module searches for an operating system dependent built-in module like
|
|
\module{mac} or \refmodule{posix} and exports the same functions and data
|
|
as found there. The design of all Python's built-in operating system dependent
|
|
modules is such that as long as the same functionality is available,
|
|
it uses the same interface; for example, the function
|
|
\code{os.stat(\var{path})} returns stat information about \var{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 \module{os} module, but using them is of course a
|
|
threat to portability!
|
|
|
|
Note that after the first time \module{os} is imported, there is
|
|
\emph{no} performance penalty in using functions from \module{os}
|
|
instead of directly from the operating system dependent built-in module,
|
|
so there should be \emph{no} reason not to use \module{os}!
|
|
|
|
|
|
% Frank Stajano <fstajano@uk.research.att.com> complained that it
|
|
% wasn't clear that the entries described in the subsections were all
|
|
% available at the module level (most uses of subsections are
|
|
% different); I think this is only a problem for the HTML version,
|
|
% where the relationship may not be as clear.
|
|
%
|
|
\ifhtml
|
|
The \module{os} module contains many functions and data values.
|
|
The items below and in the following sub-sections are all available
|
|
directly from the \module{os} module.
|
|
\fi
|
|
|
|
|
|
\begin{excdesc}{error}
|
|
This exception is raised when a function returns a system-related
|
|
error (not for illegal argument types or other incidental errors).
|
|
This is also known as the built-in exception \exception{OSError}. The
|
|
accompanying value is a pair containing the numeric error code from
|
|
\cdata{errno} and the corresponding string, as would be printed by the
|
|
C function \cfunction{perror()}. See the module
|
|
\refmodule{errno}\refbimodindex{errno}, which contains names for the
|
|
error codes defined by the underlying operating system.
|
|
|
|
When exceptions are classes, this exception carries two attributes,
|
|
\member{errno} and \member{strerror}. The first holds the value of
|
|
the C \cdata{errno} variable, and the latter holds the corresponding
|
|
error message from \cfunction{strerror()}. For exceptions that
|
|
involve a file system path (such as \function{chdir()} or
|
|
\function{unlink()}), the exception instance will contain a third
|
|
attribute, \member{filename}, which is the file name passed to the
|
|
function.
|
|
\end{excdesc}
|
|
|
|
\begin{datadesc}{name}
|
|
The name of the operating system dependent module imported. The
|
|
following names have currently been registered: \code{'posix'},
|
|
\code{'nt'}, \code{'mac'}, \code{'os2'}, \code{'ce'},
|
|
\code{'java'}, \code{'riscos'}.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{path}
|
|
The corresponding operating system dependent standard module for pathname
|
|
operations, such as \module{posixpath} or \module{macpath}. Thus,
|
|
given the proper imports, \code{os.path.split(\var{file})} is
|
|
equivalent to but more portable than
|
|
\code{posixpath.split(\var{file})}. Note that this is also an
|
|
importable module: it may be imported directly as
|
|
\refmodule{os.path}.
|
|
\end{datadesc}
|
|
|
|
|
|
|
|
\subsection{Process Parameters \label{os-procinfo}}
|
|
|
|
These functions and data items provide information and operate on the
|
|
current process and user.
|
|
|
|
\begin{datadesc}{environ}
|
|
A mapping object representing the string environment. For example,
|
|
\code{environ['HOME']} is the pathname of your home directory (on some
|
|
platforms), and is equivalent to \code{getenv("HOME")} in C.
|
|
|
|
This mapping is captured the first time the \module{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 \code{os.environ}, except for changes made by modifying
|
|
\code{os.environ} directly.
|
|
|
|
If the platform supports the \function{putenv()} function, this
|
|
mapping may be used to modify the environment as well as query the
|
|
environment. \function{putenv()} will be called automatically when
|
|
the mapping is modified.
|
|
\note{Calling \function{putenv()} directly does not change
|
|
\code{os.environ}, so it's better to modify \code{os.environ}.}
|
|
\note{On some platforms, including FreeBSD and Mac OS X, setting
|
|
\code{environ} may cause memory leaks. Refer to the system documentation
|
|
for \cfunction{putenv()}.}
|
|
|
|
If \function{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 \function{unsetenv()} function, you can
|
|
delete items in this mapping to unset environment variables.
|
|
\function{unsetenv()} will be called automatically when an item is
|
|
deleted from \code{os.environ}.
|
|
|
|
\end{datadesc}
|
|
|
|
\begin{funcdescni}{chdir}{path}
|
|
\funclineni{fchdir}{fd}
|
|
\funclineni{getcwd}{}
|
|
These functions are described in ``Files and Directories'' (section
|
|
\ref{os-file-dir}).
|
|
\end{funcdescni}
|
|
|
|
\begin{funcdesc}{ctermid}{}
|
|
Return the filename corresponding to the controlling terminal of the
|
|
process.
|
|
Availability: \UNIX.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{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.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{geteuid}{}
|
|
\index{user!effective id}
|
|
Return the current process' effective user id.
|
|
Availability: \UNIX.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{getgid}{}
|
|
\index{process!group}
|
|
Return the real group id of the current process.
|
|
Availability: \UNIX.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{getgroups}{}
|
|
Return list of supplemental group ids associated with the current
|
|
process.
|
|
Availability: \UNIX.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{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 \code{pwd.getpwuid(os.getuid())[0]} to get the login name
|
|
of the currently effective user ID.
|
|
Availability: \UNIX.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{getpgid}{pid}
|
|
Return the process group id of the process with process id \var{pid}.
|
|
If \var{pid} is 0, the process group id of the current process is
|
|
returned. Availability: \UNIX.
|
|
\versionadded{2.3}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{getpgrp}{}
|
|
\index{process!group}
|
|
Return the id of the current process group.
|
|
Availability: \UNIX.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{getpid}{}
|
|
\index{process!id}
|
|
Return the current process id.
|
|
Availability: \UNIX, Windows.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{getppid}{}
|
|
\index{process!id of parent}
|
|
Return the parent's process id.
|
|
Availability: \UNIX.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{getuid}{}
|
|
\index{user!id}
|
|
Return the current process' user id.
|
|
Availability: \UNIX.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{getenv}{varname\optional{, value}}
|
|
Return the value of the environment variable \var{varname} if it
|
|
exists, or \var{value} if it doesn't. \var{value} defaults to
|
|
\code{None}.
|
|
Availability: most flavors of \UNIX, Windows.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{putenv}{varname, value}
|
|
\index{environment variables!setting}
|
|
Set the environment variable named \var{varname} to the string
|
|
\var{value}. Such changes to the environment affect subprocesses
|
|
started with \function{os.system()}, \function{popen()} or
|
|
\function{fork()} and \function{execv()}.
|
|
Availability: most flavors of \UNIX, Windows.
|
|
|
|
\note{On some platforms, including FreeBSD and Mac OS X,
|
|
setting \code{environ} may cause memory leaks.
|
|
Refer to the system documentation for putenv.}
|
|
|
|
When \function{putenv()} is
|
|
supported, assignments to items in \code{os.environ} are automatically
|
|
translated into corresponding calls to \function{putenv()}; however,
|
|
calls to \function{putenv()} don't update \code{os.environ}, so it is
|
|
actually preferable to assign to items of \code{os.environ}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{setegid}{egid}
|
|
Set the current process's effective group id.
|
|
Availability: \UNIX.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{seteuid}{euid}
|
|
Set the current process's effective user id.
|
|
Availability: \UNIX.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{setgid}{gid}
|
|
Set the current process' group id.
|
|
Availability: \UNIX.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{setgroups}{groups}
|
|
Set the list of supplemental group ids associated with the current
|
|
process to \var{groups}. \var{groups} must be a sequence, and each
|
|
element must be an integer identifying a group. This operation is
|
|
typical available only to the superuser.
|
|
Availability: \UNIX.
|
|
\versionadded{2.2}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{setpgrp}{}
|
|
Calls the system call \cfunction{setpgrp()} or \cfunction{setpgrp(0,
|
|
0)} depending on which version is implemented (if any). See the
|
|
\UNIX{} manual for the semantics.
|
|
Availability: \UNIX.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{setpgid}{pid, pgrp} Calls the system call
|
|
\cfunction{setpgid()} to set the process group id of the process with
|
|
id \var{pid} to the process group with id \var{pgrp}. See the \UNIX{}
|
|
manual for the semantics.
|
|
Availability: \UNIX.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{setreuid}{ruid, euid}
|
|
Set the current process's real and effective user ids.
|
|
Availability: \UNIX.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{setregid}{rgid, egid}
|
|
Set the current process's real and effective group ids.
|
|
Availability: \UNIX.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{getsid}{pid}
|
|
Calls the system call \cfunction{getsid()}. See the \UNIX{} manual
|
|
for the semantics.
|
|
Availability: \UNIX. \versionadded{2.4}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{setsid}{}
|
|
Calls the system call \cfunction{setsid()}. See the \UNIX{} manual
|
|
for the semantics.
|
|
Availability: \UNIX.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{setuid}{uid}
|
|
\index{user!id, setting}
|
|
Set the current process' user id.
|
|
Availability: \UNIX.
|
|
\end{funcdesc}
|
|
|
|
% placed in this section since it relates to errno.... a little weak
|
|
\begin{funcdesc}{strerror}{code}
|
|
Return the error message corresponding to the error code in
|
|
\var{code}.
|
|
Availability: \UNIX, Windows.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{umask}{mask}
|
|
Set the current numeric umask and returns the previous umask.
|
|
Availability: \UNIX, Windows.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{uname}{}
|
|
Return a 5-tuple containing information identifying the current
|
|
operating system. The tuple contains 5 strings:
|
|
\code{(\var{sysname}, \var{nodename}, \var{release}, \var{version},
|
|
\var{machine})}. Some systems truncate the nodename to 8
|
|
characters or to the leading component; a better way to get the
|
|
hostname is \function{socket.gethostname()}
|
|
\withsubitem{(in module socket)}{\ttindex{gethostname()}}
|
|
or even
|
|
\withsubitem{(in module socket)}{\ttindex{gethostbyaddr()}}
|
|
\code{socket.gethostbyaddr(socket.gethostname())}.
|
|
Availability: recent flavors of \UNIX.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{unsetenv}{varname}
|
|
\index{environment variables!deleting}
|
|
Unset (delete) the environment variable named \var{varname}. Such
|
|
changes to the environment affect subprocesses started with
|
|
\function{os.system()}, \function{popen()} or \function{fork()} and
|
|
\function{execv()}. Availability: most flavors of \UNIX, Windows.
|
|
|
|
When \function{unsetenv()} is
|
|
supported, deletion of items in \code{os.environ} is automatically
|
|
translated into a corresponding call to \function{unsetenv()}; however,
|
|
calls to \function{unsetenv()} don't update \code{os.environ}, so it is
|
|
actually preferable to delete items of \code{os.environ}.
|
|
\end{funcdesc}
|
|
|
|
\subsection{File Object Creation \label{os-newstreams}}
|
|
|
|
These functions create new file objects.
|
|
|
|
|
|
\begin{funcdesc}{fdopen}{fd\optional{, mode\optional{, bufsize}}}
|
|
Return an open file object connected to the file descriptor \var{fd}.
|
|
\index{I/O control!buffering}
|
|
The \var{mode} and \var{bufsize} arguments have the same meaning as
|
|
the corresponding arguments to the built-in \function{open()}
|
|
function.
|
|
Availability: Macintosh, \UNIX, Windows.
|
|
|
|
\versionchanged[When specified, the \var{mode} argument must now start
|
|
with one of the letters \character{r}, \character{w}, or \character{a},
|
|
otherwise a \exception{ValueError} is raised]{2.3}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{popen}{command\optional{, mode\optional{, bufsize}}}
|
|
Open a pipe to or from \var{command}. The return value is an open
|
|
file object connected to the pipe, which can be read or written
|
|
depending on whether \var{mode} is \code{'r'} (default) or \code{'w'}.
|
|
The \var{bufsize} argument has the same meaning as the corresponding
|
|
argument to the built-in \function{open()} function. The exit status of
|
|
the command (encoded in the format specified for \function{wait()}) is
|
|
available as the return value of the \method{close()} method of the file
|
|
object, except that when the exit status is zero (termination without
|
|
errors), \code{None} is returned.
|
|
Availability: Macintosh, \UNIX, Windows.
|
|
|
|
\versionchanged[This function worked unreliably under Windows in
|
|
earlier versions of Python. This was due to the use of the
|
|
\cfunction{_popen()} function from the libraries provided with
|
|
Windows. Newer versions of Python do not use the broken
|
|
implementation from the Windows libraries]{2.0}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{tmpfile}{}
|
|
Return a new file object opened in update mode (\samp{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: Macintosh, \UNIX, Windows.
|
|
\end{funcdesc}
|
|
|
|
|
|
For each of the following \function{popen()} variants, if \var{bufsize} is
|
|
specified, it specifies the buffer size for the I/O pipes.
|
|
\var{mode}, if provided, should be the string \code{'b'} or
|
|
\code{'t'}; on Windows this is needed to determine whether the file
|
|
objects should be opened in binary or text mode. The default value
|
|
for \var{mode} is \code{'t'}.
|
|
|
|
Also, for each of these variants, on \UNIX, \var{cmd} may be a sequence, in
|
|
which case arguments will be passed directly to the program without shell
|
|
intervention (as with \function{os.spawnv()}). If \var{cmd} is a string it will
|
|
be passed to the shell (as with \function{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
|
|
\class{Popen3} and \class{Popen4} classes from the \refmodule{popen2}
|
|
module; these are only available on \UNIX.
|
|
|
|
For a discussion of possible deadlock conditions related to the use
|
|
of these functions, see ``\ulink{Flow Control
|
|
Issues}{popen2-flow-control.html}''
|
|
(section~\ref{popen2-flow-control}).
|
|
|
|
\begin{funcdesc}{popen2}{cmd\optional{, mode\optional{, bufsize}}}
|
|
Executes \var{cmd} as a sub-process. Returns the file objects
|
|
\code{(\var{child_stdin}, \var{child_stdout})}.
|
|
Availability: Macintosh, \UNIX, Windows.
|
|
\versionadded{2.0}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{popen3}{cmd\optional{, mode\optional{, bufsize}}}
|
|
Executes \var{cmd} as a sub-process. Returns the file objects
|
|
\code{(\var{child_stdin}, \var{child_stdout}, \var{child_stderr})}.
|
|
Availability: Macintosh, \UNIX, Windows.
|
|
\versionadded{2.0}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{popen4}{cmd\optional{, mode\optional{, bufsize}}}
|
|
Executes \var{cmd} as a sub-process. Returns the file objects
|
|
\code{(\var{child_stdin}, \var{child_stdout_and_stderr})}.
|
|
Availability: Macintosh, \UNIX, Windows.
|
|
\versionadded{2.0}
|
|
\end{funcdesc}
|
|
|
|
(Note that \code{\var{child_stdin}, \var{child_stdout}, and
|
|
\var{child_stderr}} are named from the point of view of the child
|
|
process, i.e. \var{child_stdin} is the child's standard input.)
|
|
|
|
This functionality is also available in the \refmodule{popen2} module
|
|
using functions of the same names, but the return values of those
|
|
functions have a different order.
|
|
|
|
|
|
\subsection{File Descriptor Operations \label{os-fd-ops}}
|
|
|
|
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.
|
|
|
|
|
|
\begin{funcdesc}{close}{fd}
|
|
Close file descriptor \var{fd}.
|
|
Availability: Macintosh, \UNIX, Windows.
|
|
|
|
\begin{notice}
|
|
This function is intended for low-level I/O and must be applied
|
|
to a file descriptor as returned by \function{open()} or
|
|
\function{pipe()}. To close a ``file object'' returned by the
|
|
built-in function \function{open()} or by \function{popen()} or
|
|
\function{fdopen()}, use its \method{close()} method.
|
|
\end{notice}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{dup}{fd}
|
|
Return a duplicate of file descriptor \var{fd}.
|
|
Availability: Macintosh, \UNIX, Windows.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{dup2}{fd, fd2}
|
|
Duplicate file descriptor \var{fd} to \var{fd2}, closing the latter
|
|
first if necessary.
|
|
Availability: Macintosh, \UNIX, Windows.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{fdatasync}{fd}
|
|
Force write of file with filedescriptor \var{fd} to disk.
|
|
Does not force update of metadata.
|
|
Availability: \UNIX.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{fpathconf}{fd, name}
|
|
Return system configuration information relevant to an open file.
|
|
\var{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
|
|
\code{pathconf_names} dictionary. For configuration variables not
|
|
included in that mapping, passing an integer for \var{name} is also
|
|
accepted.
|
|
Availability: Macintosh, \UNIX.
|
|
|
|
If \var{name} is a string and is not known, \exception{ValueError} is
|
|
raised. If a specific value for \var{name} is not supported by the
|
|
host system, even if it is included in \code{pathconf_names}, an
|
|
\exception{OSError} is raised with \constant{errno.EINVAL} for the
|
|
error number.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{fstat}{fd}
|
|
Return status for file descriptor \var{fd}, like \function{stat()}.
|
|
Availability: Macintosh, \UNIX, Windows.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{fstatvfs}{fd}
|
|
Return information about the filesystem containing the file associated
|
|
with file descriptor \var{fd}, like \function{statvfs()}.
|
|
Availability: \UNIX.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{fsync}{fd}
|
|
Force write of file with filedescriptor \var{fd} to disk. On \UNIX,
|
|
this calls the native \cfunction{fsync()} function; on Windows, the
|
|
MS \cfunction{_commit()} function.
|
|
|
|
If you're starting with a Python file object \var{f}, first do
|
|
\code{\var{f}.flush()}, and then do \code{os.fsync(\var{f}.fileno())},
|
|
to ensure that all internal buffers associated with \var{f} are written
|
|
to disk.
|
|
Availability: Macintosh, \UNIX, and Windows starting in 2.2.3.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{ftruncate}{fd, length}
|
|
Truncate the file corresponding to file descriptor \var{fd},
|
|
so that it is at most \var{length} bytes in size.
|
|
Availability: Macintosh, \UNIX.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{isatty}{fd}
|
|
Return \code{True} if the file descriptor \var{fd} is open and
|
|
connected to a tty(-like) device, else \code{False}.
|
|
Availability: Macintosh, \UNIX.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{lseek}{fd, pos, how}
|
|
Set the current position of file descriptor \var{fd} to position
|
|
\var{pos}, modified by \var{how}: \code{0} to set the position
|
|
relative to the beginning of the file; \code{1} to set it relative to
|
|
the current position; \code{2} to set it relative to the end of the
|
|
file.
|
|
Availability: Macintosh, \UNIX, Windows.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{open}{file, flags\optional{, mode}}
|
|
Open the file \var{file} and set various flags according to
|
|
\var{flags} and possibly its mode according to \var{mode}.
|
|
The default \var{mode} is \code{0777} (octal), and the current umask
|
|
value is first masked out. Return the file descriptor for the newly
|
|
opened file.
|
|
Availability: Macintosh, \UNIX, Windows.
|
|
|
|
For a description of the flag and mode values, see the C run-time
|
|
documentation; flag constants (like \constant{O_RDONLY} and
|
|
\constant{O_WRONLY}) are defined in this module too (see below).
|
|
|
|
\begin{notice}
|
|
This function is intended for low-level I/O. For normal usage,
|
|
use the built-in function \function{open()}, which returns a ``file
|
|
object'' with \method{read()} and \method{write()} methods (and many
|
|
more).
|
|
\end{notice}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{openpty}{}
|
|
Open a new pseudo-terminal pair. Return a pair of file descriptors
|
|
\code{(\var{master}, \var{slave})} for the pty and the tty,
|
|
respectively. For a (slightly) more portable approach, use the
|
|
\refmodule{pty}\refstmodindex{pty} module.
|
|
Availability: Macintosh, Some flavors of \UNIX.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{pipe}{}
|
|
Create a pipe. Return a pair of file descriptors \code{(\var{r},
|
|
\var{w})} usable for reading and writing, respectively.
|
|
Availability: Macintosh, \UNIX, Windows.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{read}{fd, n}
|
|
Read at most \var{n} bytes from file descriptor \var{fd}.
|
|
Return a string containing the bytes read. If the end of the file
|
|
referred to by \var{fd} has been reached, an empty string is
|
|
returned.
|
|
Availability: Macintosh, \UNIX, Windows.
|
|
|
|
\begin{notice}
|
|
This function is intended for low-level I/O and must be applied
|
|
to a file descriptor as returned by \function{open()} or
|
|
\function{pipe()}. To read a ``file object'' returned by the
|
|
built-in function \function{open()} or by \function{popen()} or
|
|
\function{fdopen()}, or \code{sys.stdin}, use its
|
|
\method{read()} or \method{readline()} methods.
|
|
\end{notice}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{tcgetpgrp}{fd}
|
|
Return the process group associated with the terminal given by
|
|
\var{fd} (an open file descriptor as returned by \function{open()}).
|
|
Availability: Macintosh, \UNIX.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{tcsetpgrp}{fd, pg}
|
|
Set the process group associated with the terminal given by
|
|
\var{fd} (an open file descriptor as returned by \function{open()})
|
|
to \var{pg}.
|
|
Availability: Macintosh, \UNIX.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{ttyname}{fd}
|
|
Return a string which specifies the terminal device associated with
|
|
file-descriptor \var{fd}. If \var{fd} is not associated with a terminal
|
|
device, an exception is raised.
|
|
Availability:Macintosh, \UNIX.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{write}{fd, str}
|
|
Write the string \var{str} to file descriptor \var{fd}.
|
|
Return the number of bytes actually written.
|
|
Availability: Macintosh, \UNIX, Windows.
|
|
|
|
\begin{notice}
|
|
This function is intended for low-level I/O and must be applied
|
|
to a file descriptor as returned by \function{open()} or
|
|
\function{pipe()}. To write a ``file object'' returned by the
|
|
built-in function \function{open()} or by \function{popen()} or
|
|
\function{fdopen()}, or \code{sys.stdout} or \code{sys.stderr}, use
|
|
its \method{write()} method.
|
|
\end{notice}
|
|
\end{funcdesc}
|
|
|
|
|
|
The following data items are available for use in constructing the
|
|
\var{flags} parameter to the \function{open()} function. Some items will
|
|
not be available on all platforms. For descriptions of their availability
|
|
and use, consult \manpage{open}{2}.
|
|
|
|
\begin{datadesc}{O_RDONLY}
|
|
\dataline{O_WRONLY}
|
|
\dataline{O_RDWR}
|
|
\dataline{O_APPEND}
|
|
\dataline{O_CREAT}
|
|
\dataline{O_EXCL}
|
|
\dataline{O_TRUNC}
|
|
Options for the \var{flag} argument to the \function{open()} function.
|
|
These can be bit-wise OR'd together.
|
|
Availability: Macintosh, \UNIX, Windows.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{O_DSYNC}
|
|
\dataline{O_RSYNC}
|
|
\dataline{O_SYNC}
|
|
\dataline{O_NDELAY}
|
|
\dataline{O_NONBLOCK}
|
|
\dataline{O_NOCTTY}
|
|
\dataline{O_SHLOCK}
|
|
\dataline{O_EXLOCK}
|
|
More options for the \var{flag} argument to the \function{open()} function.
|
|
Availability: Macintosh, \UNIX.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{O_BINARY}
|
|
Option for the \var{flag} argument to the \function{open()} function.
|
|
This can be bit-wise OR'd together with those listed above.
|
|
Availability: Windows.
|
|
% XXX need to check on the availability of this one.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{O_NOINHERIT}
|
|
\dataline{O_SHORT_LIVED}
|
|
\dataline{O_TEMPORARY}
|
|
\dataline{O_RANDOM}
|
|
\dataline{O_SEQUENTIAL}
|
|
\dataline{O_TEXT}
|
|
Options for the \var{flag} argument to the \function{open()} function.
|
|
These can be bit-wise OR'd together.
|
|
Availability: Windows.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{SEEK_SET}
|
|
\dataline{SEEK_CUR}
|
|
\dataline{SEEK_END}
|
|
Parameters to the \function{lseek()} function.
|
|
Their values are 0, 1, and 2, respectively.
|
|
Availability: Windows, Macintosh, \UNIX.
|
|
\versionadded{2.5}
|
|
\end{datadesc}
|
|
|
|
\subsection{Files and Directories \label{os-file-dir}}
|
|
|
|
\begin{funcdesc}{access}{path, mode}
|
|
Use the real uid/gid to test for access to \var{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 \var{path}. \var{mode} should be \constant{F_OK}
|
|
to test the existence of \var{path}, or it can be the inclusive OR of
|
|
one or more of \constant{R_OK}, \constant{W_OK}, and \constant{X_OK} to
|
|
test permissions. Return \constant{True} if access is allowed,
|
|
\constant{False} if not.
|
|
See the \UNIX{} man page \manpage{access}{2} for more information.
|
|
Availability: Macintosh, \UNIX, Windows.
|
|
|
|
\note{Using \function{access()} to check if a user is authorized to e.g.
|
|
open a file before actually doing so using \function{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 \function{access()}
|
|
indicates that they would succeed, particularly for operations
|
|
on network filesystems which may have permissions semantics
|
|
beyond the usual \POSIX{} permission-bit model.}
|
|
\end{funcdesc}
|
|
|
|
\begin{datadesc}{F_OK}
|
|
Value to pass as the \var{mode} parameter of \function{access()} to
|
|
test the existence of \var{path}.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{R_OK}
|
|
Value to include in the \var{mode} parameter of \function{access()}
|
|
to test the readability of \var{path}.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{W_OK}
|
|
Value to include in the \var{mode} parameter of \function{access()}
|
|
to test the writability of \var{path}.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{X_OK}
|
|
Value to include in the \var{mode} parameter of \function{access()}
|
|
to determine if \var{path} can be executed.
|
|
\end{datadesc}
|
|
|
|
\begin{funcdesc}{chdir}{path}
|
|
\index{directory!changing}
|
|
Change the current working directory to \var{path}.
|
|
Availability: Macintosh, \UNIX, Windows.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{fchdir}{fd}
|
|
Change the current working directory to the directory represented by
|
|
the file descriptor \var{fd}. The descriptor must refer to an opened
|
|
directory, not an open file.
|
|
Availability: \UNIX.
|
|
\versionadded{2.3}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{getcwd}{}
|
|
Return a string representing the current working directory.
|
|
Availability: Macintosh, \UNIX, Windows.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{getcwdu}{}
|
|
Return a Unicode object representing the current working directory.
|
|
Availability: Macintosh, \UNIX, Windows.
|
|
\versionadded{2.3}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{chroot}{path}
|
|
Change the root directory of the current process to \var{path}.
|
|
Availability: Macintosh, \UNIX.
|
|
\versionadded{2.2}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{chmod}{path, mode}
|
|
Change the mode of \var{path} to the numeric \var{mode}.
|
|
\var{mode} may take one of the following values
|
|
(as defined in the \module{stat} module) or bitwise or-ed
|
|
combinations of them:
|
|
\begin{itemize}
|
|
\item \code{S_ISUID}
|
|
\item \code{S_ISGID}
|
|
\item \code{S_ENFMT}
|
|
\item \code{S_ISVTX}
|
|
\item \code{S_IREAD}
|
|
\item \code{S_IWRITE}
|
|
\item \code{S_IEXEC}
|
|
\item \code{S_IRWXU}
|
|
\item \code{S_IRUSR}
|
|
\item \code{S_IWUSR}
|
|
\item \code{S_IXUSR}
|
|
\item \code{S_IRWXG}
|
|
\item \code{S_IRGRP}
|
|
\item \code{S_IWGRP}
|
|
\item \code{S_IXGRP}
|
|
\item \code{S_IRWXO}
|
|
\item \code{S_IROTH}
|
|
\item \code{S_IWOTH}
|
|
\item \code{S_IXOTH}
|
|
\end{itemize}
|
|
Availability: Macintosh, \UNIX, Windows.
|
|
|
|
\note{Although Windows supports \function{chmod()}, you can only
|
|
set the file's read-only flag with it (via the \code{S_IWRITE}
|
|
and \code{S_IREAD} constants or a corresponding integer value).
|
|
All other bits are ignored.}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{chown}{path, uid, gid}
|
|
Change the owner and group id of \var{path} to the numeric \var{uid}
|
|
and \var{gid}. To leave one of the ids unchanged, set it to -1.
|
|
Availability: Macintosh, \UNIX.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{lchown}{path, uid, gid}
|
|
Change the owner and group id of \var{path} to the numeric \var{uid}
|
|
and gid. This function will not follow symbolic links.
|
|
Availability: Macintosh, \UNIX.
|
|
\versionadded{2.3}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{link}{src, dst}
|
|
Create a hard link pointing to \var{src} named \var{dst}.
|
|
Availability: Macintosh, \UNIX.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{listdir}{path}
|
|
Return a list containing the names of the entries in the directory.
|
|
The list is in arbitrary order. It does not include the special
|
|
entries \code{'.'} and \code{'..'} even if they are present in the
|
|
directory.
|
|
Availability: Macintosh, \UNIX, Windows.
|
|
|
|
\versionchanged[On Windows NT/2k/XP and \UNIX, if \var{path} is a Unicode
|
|
object, the result will be a list of Unicode objects.]{2.3}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{lstat}{path}
|
|
Like \function{stat()}, but do not follow symbolic links.
|
|
Availability: Macintosh, \UNIX.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{mkfifo}{path\optional{, mode}}
|
|
Create a FIFO (a named pipe) named \var{path} with numeric mode
|
|
\var{mode}. The default \var{mode} is \code{0666} (octal). The current
|
|
umask value is first masked out from the mode.
|
|
Availability: Macintosh, \UNIX.
|
|
|
|
FIFOs are pipes that can be accessed like regular files. FIFOs exist
|
|
until they are deleted (for example with \function{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 \function{mkfifo()}
|
|
doesn't open the FIFO --- it just creates the rendezvous point.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{mknod}{path\optional{, mode=0600, device}}
|
|
Create a filesystem node (file, device special file or named pipe)
|
|
named filename. \var{mode} specifies both the permissions to use and
|
|
the type of node to be created, being combined (bitwise OR) with one
|
|
of S_IFREG, S_IFCHR, S_IFBLK, and S_IFIFO (those constants are
|
|
available in \module{stat}). For S_IFCHR and S_IFBLK, \var{device}
|
|
defines the newly created device special file (probably using
|
|
\function{os.makedev()}), otherwise it is ignored.
|
|
\versionadded{2.3}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{major}{device}
|
|
Extracts the device major number from a raw device number (usually
|
|
the \member{st_dev} or \member{st_rdev} field from \ctype{stat}).
|
|
\versionadded{2.3}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{minor}{device}
|
|
Extracts the device minor number from a raw device number (usually
|
|
the \member{st_dev} or \member{st_rdev} field from \ctype{stat}).
|
|
\versionadded{2.3}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{makedev}{major, minor}
|
|
Composes a raw device number from the major and minor device numbers.
|
|
\versionadded{2.3}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{mkdir}{path\optional{, mode}}
|
|
Create a directory named \var{path} with numeric mode \var{mode}.
|
|
The default \var{mode} is \code{0777} (octal). On some systems,
|
|
\var{mode} is ignored. Where it is used, the current umask value is
|
|
first masked out.
|
|
Availability: Macintosh, \UNIX, Windows.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{makedirs}{path\optional{, mode}}
|
|
Recursive directory creation function.\index{directory!creating}
|
|
\index{UNC paths!and \function{os.makedirs()}}
|
|
Like \function{mkdir()},
|
|
but makes all intermediate-level directories needed to contain the
|
|
leaf directory. Throws an \exception{error} exception if the leaf
|
|
directory already exists or cannot be created. The default \var{mode}
|
|
is \code{0777} (octal).
|
|
\versionadded{1.5.2}
|
|
\versionchanged[This function now handles UNC paths correctly]{2.3}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{pathconf}{path, name}
|
|
Return system configuration information relevant to a named file.
|
|
\var{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
|
|
\code{pathconf_names} dictionary. For configuration variables not
|
|
included in that mapping, passing an integer for \var{name} is also
|
|
accepted.
|
|
Availability: Macintosh, \UNIX.
|
|
|
|
If \var{name} is a string and is not known, \exception{ValueError} is
|
|
raised. If a specific value for \var{name} is not supported by the
|
|
host system, even if it is included in \code{pathconf_names}, an
|
|
\exception{OSError} is raised with \constant{errno.EINVAL} for the
|
|
error number.
|
|
\end{funcdesc}
|
|
|
|
\begin{datadesc}{pathconf_names}
|
|
Dictionary mapping names accepted by \function{pathconf()} and
|
|
\function{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: Macintosh, \UNIX.
|
|
\end{datadesc}
|
|
|
|
\begin{funcdesc}{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
|
|
\code{os.path.join(os.path.dirname(\var{path}), \var{result})}.
|
|
Availability: Macintosh, \UNIX.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{remove}{path}
|
|
Remove the file \var{path}. If \var{path} is a directory,
|
|
\exception{OSError} is raised; see \function{rmdir()} below to remove
|
|
a directory. This is identical to the \function{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: Macintosh, \UNIX, Windows.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{removedirs}{path}
|
|
\index{directory!deleting}
|
|
Removes directories recursively. Works like
|
|
\function{rmdir()} except that, if the leaf directory is
|
|
successfully removed, directories corresponding to rightmost path
|
|
segments will be pruned way until either the whole path is consumed or
|
|
an error is raised (which is ignored, because it generally means that
|
|
a parent directory is not empty). Throws an \exception{error}
|
|
exception if the leaf directory could not be successfully removed.
|
|
\versionadded{1.5.2}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{rename}{src, dst}
|
|
Rename the file or directory \var{src} to \var{dst}. If \var{dst} is
|
|
a directory, \exception{OSError} will be raised. On \UNIX, if
|
|
\var{dst} exists and is a file, it will be removed silently if the
|
|
user has permission. The operation may fail on some \UNIX{} flavors
|
|
if \var{src} and \var{dst} are on different filesystems. If
|
|
successful, the renaming will be an atomic operation (this is a
|
|
\POSIX{} requirement). On Windows, if \var{dst} already exists,
|
|
\exception{OSError} will be raised even if it is a file; there may be
|
|
no way to implement an atomic rename when \var{dst} names an existing
|
|
file.
|
|
Availability: Macintosh, \UNIX, Windows.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{renames}{old, new}
|
|
Recursive directory or file renaming function.
|
|
Works like \function{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 \function{removedirs()}.
|
|
\versionadded{1.5.2}
|
|
|
|
\begin{notice}
|
|
This function can fail with the new directory structure made if
|
|
you lack permissions needed to remove the leaf directory or file.
|
|
\end{notice}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{rmdir}{path}
|
|
Remove the directory \var{path}.
|
|
Availability: Macintosh, \UNIX, Windows.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{stat}{path}
|
|
Perform a \cfunction{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:
|
|
\member{st_mode} (protection bits),
|
|
\member{st_ino} (inode number),
|
|
\member{st_dev} (device),
|
|
\member{st_nlink} (number of hard links),
|
|
\member{st_uid} (user ID of owner),
|
|
\member{st_gid} (group ID of owner),
|
|
\member{st_size} (size of file, in bytes),
|
|
\member{st_atime} (time of most recent access),
|
|
\member{st_mtime} (time of most recent content modification),
|
|
\member{st_ctime}
|
|
(platform dependent; time of most recent metadata change on \UNIX, or
|
|
the time of creation on Windows):
|
|
|
|
\begin{verbatim}
|
|
>>> import os
|
|
>>> statinfo = os.stat('somefile.txt')
|
|
>>> statinfo
|
|
(33188, 422511L, 769L, 1, 1032, 100, 926L, 1105022698,1105022732, 1105022732)
|
|
>>> statinfo.st_size
|
|
926L
|
|
>>>
|
|
\end{verbatim}
|
|
|
|
\versionchanged [If \function{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 \function{stat_float_times} for further discussion. ]{2.3}
|
|
|
|
On some \UNIX{} systems (such as Linux), the following attributes may
|
|
also be available:
|
|
\member{st_blocks} (number of blocks allocated for file),
|
|
\member{st_blksize} (filesystem blocksize),
|
|
\member{st_rdev} (type of device if an inode device).
|
|
\member{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 of root tries to
|
|
use them:
|
|
\member{st_gen} (file generation number),
|
|
\member{st_birthtime} (time of file creation).
|
|
|
|
On Mac OS systems, the following attributes may also be available:
|
|
\member{st_rsize},
|
|
\member{st_creator},
|
|
\member{st_type}.
|
|
|
|
On RISCOS systems, the following attributes are also available:
|
|
\member{st_ftype} (file type),
|
|
\member{st_attrs} (attributes),
|
|
\member{st_obtype} (object type).
|
|
|
|
For backward compatibility, the return value of \function{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
|
|
\member{st_mode},
|
|
\member{st_ino},
|
|
\member{st_dev},
|
|
\member{st_nlink},
|
|
\member{st_uid},
|
|
\member{st_gid},
|
|
\member{st_size},
|
|
\member{st_atime},
|
|
\member{st_mtime},
|
|
\member{st_ctime}.
|
|
More items may be added at the end by some implementations.
|
|
The standard module \refmodule{stat}\refstmodindex{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 \member{st_atime},
|
|
\member{st_mtime}, and \member{st_ctime} members depends on the
|
|
operating system and the file system. For example, on Windows systems
|
|
using the FAT or FAT32 file systems, \member{st_mtime} has 2-second
|
|
resolution, and \member{st_atime} has only 1-day resolution. See
|
|
your operating system documentation for details.}
|
|
|
|
Availability: Macintosh, \UNIX, Windows.
|
|
|
|
\versionchanged
|
|
[Added access to values as attributes of the returned object]{2.2}
|
|
\versionchanged[Added st_gen, st_birthtime]{2.5}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{stat_float_times}{\optional{newvalue}}
|
|
Determine whether \class{stat_result} represents time stamps as float
|
|
objects. If newval is True, future calls to stat() return floats, if
|
|
it is False, future calls return ints. If newval is omitted, return
|
|
the current setting.
|
|
|
|
For compatibility with older Python versions, accessing
|
|
\class{stat_result} as a tuple always returns integers.
|
|
|
|
\versionchanged[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]{2.5}
|
|
|
|
The resolution of the timestamps (i.e. 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 \var{__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.
|
|
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{statvfs}{path}
|
|
Perform a \cfunction{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:
|
|
\member{f_frsize},
|
|
\member{f_blocks},
|
|
\member{f_bfree},
|
|
\member{f_bavail},
|
|
\member{f_files},
|
|
\member{f_ffree},
|
|
\member{f_favail},
|
|
\member{f_flag},
|
|
\member{f_namemax}.
|
|
Availability: \UNIX.
|
|
|
|
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 \refmodule{statvfs}\refstmodindex{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
|
|
[Added access to values as attributes of the returned object]{2.2}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{symlink}{src, dst}
|
|
Create a symbolic link pointing to \var{src} named \var{dst}.
|
|
Availability: \UNIX.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{tempnam}{\optional{dir\optional{, 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 \var{dir} or a common location for temporary
|
|
files if \var{dir} is omitted or \code{None}. If given and not
|
|
\code{None}, \var{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 \function{tempnam()};
|
|
no automatic cleanup is provided.
|
|
On \UNIX, the environment variable \envvar{TMPDIR} overrides
|
|
\var{dir}, while on Windows the \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 \function{tempnam()} is vulnerable to symlink attacks;
|
|
consider using \function{tmpfile()} (section \ref{os-newstreams})
|
|
instead.} Availability: Macintosh, \UNIX, Windows.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{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 \function{tmpnam()}; no automatic cleanup is
|
|
provided.
|
|
\warning{Use of \function{tmpnam()} is vulnerable to symlink attacks;
|
|
consider using \function{tmpfile()} (section \ref{os-newstreams})
|
|
instead.} Availability: \UNIX, Windows. This function probably
|
|
shouldn't be used on Windows, though: Microsoft's implementation of
|
|
\function{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).
|
|
\end{funcdesc}
|
|
|
|
\begin{datadesc}{TMP_MAX}
|
|
The maximum number of unique names that \function{tmpnam()} will
|
|
generate before reusing names.
|
|
\end{datadesc}
|
|
|
|
\begin{funcdesc}{unlink}{path}
|
|
Remove the file \var{path}. This is the same function as
|
|
\function{remove()}; the \function{unlink()} name is its traditional
|
|
\UNIX{} name.
|
|
Availability: Macintosh, \UNIX, Windows.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{utime}{path, times}
|
|
Set the access and modified times of the file specified by \var{path}.
|
|
If \var{times} is \code{None}, then the file's access and modified
|
|
times are set to the current time. Otherwise, \var{times} must be a
|
|
2-tuple of numbers, of the form \code{(\var{atime}, \var{mtime})}
|
|
which is used to set the access and modified times, respectively.
|
|
Whether a directory can be given for \var{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 \function{stat()} call, depending on the resolution
|
|
with which your operating system records access and modification times;
|
|
see \function{stat()}.
|
|
\versionchanged[Added support for \code{None} for \var{times}]{2.0}
|
|
Availability: Macintosh, \UNIX, Windows.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{walk}{top\optional{, topdown\code{=True}
|
|
\optional{, onerror\code{=None}}}}
|
|
\index{directory!walking}
|
|
\index{directory!traversal}
|
|
\function{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 \var{top} (including
|
|
\var{top} itself), it yields a 3-tuple
|
|
\code{(\var{dirpath}, \var{dirnames}, \var{filenames})}.
|
|
|
|
\var{dirpath} is a string, the path to the directory. \var{dirnames} is
|
|
a list of the names of the subdirectories in \var{dirpath}
|
|
(excluding \code{'.'} and \code{'..'}). \var{filenames} is a list of
|
|
the names of the non-directory files in \var{dirpath}. Note that the
|
|
names in the lists contain no path components. To get a full
|
|
path (which begins with \var{top}) to a file or directory in
|
|
\var{dirpath}, do \code{os.path.join(\var{dirpath}, \var{name})}.
|
|
|
|
If optional argument \var{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 \var{topdown} is
|
|
false, the triple for a directory is generated after the triples for all
|
|
of its subdirectories (directories are generated bottom up).
|
|
|
|
When \var{topdown} is true, the caller can modify the \var{dirnames} list
|
|
in-place (perhaps using \keyword{del} or slice assignment), and
|
|
\function{walk()} will only recurse into the subdirectories whose names
|
|
remain in \var{dirnames}; this can be used to prune the search,
|
|
impose a specific order of visiting, or even to inform \function{walk()}
|
|
about directories the caller creates or renames before it resumes
|
|
\function{walk()} again. Modifying \var{dirnames} when \var{topdown} is
|
|
false is ineffective, because in bottom-up mode the directories in
|
|
\var{dirnames} are generated before \var{dirnames} itself is generated.
|
|
|
|
By default errors from the \code{os.listdir()} call are ignored. If
|
|
optional argument \var{onerror} is specified, it should be a function;
|
|
it will be called with one argument, an os.error 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
|
|
\code{filename} attribute of the exception object.
|
|
|
|
\begin{notice}
|
|
If you pass a relative pathname, don't change the current working
|
|
directory between resumptions of \function{walk()}. \function{walk()}
|
|
never changes the current directory, and assumes that its caller
|
|
doesn't either.
|
|
\end{notice}
|
|
|
|
\begin{notice}
|
|
On systems that support symbolic links, links to subdirectories appear
|
|
in \var{dirnames} lists, but \function{walk()} will not visit them
|
|
(infinite loops are hard to avoid when following symbolic links).
|
|
To visit linked directories, you can identify them with
|
|
\code{os.path.islink(\var{path})}, and invoke \code{walk(\var{path})}
|
|
on each directly.
|
|
\end{notice}
|
|
|
|
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:
|
|
|
|
\begin{verbatim}
|
|
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
|
|
\end{verbatim}
|
|
|
|
In the next example, walking the tree bottom up is essential:
|
|
\function{rmdir()} doesn't allow deleting a directory before the
|
|
directory is empty:
|
|
|
|
\begin{verbatim}
|
|
# 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))
|
|
\end{verbatim}
|
|
|
|
\versionadded{2.3}
|
|
\end{funcdesc}
|
|
|
|
\subsection{Process Management \label{os-process}}
|
|
|
|
These functions may be used to create and manage processes.
|
|
|
|
The various \function{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 \code{argv[0]} passed to a program's
|
|
\cfunction{main()}. For example, \samp{os.execv('/bin/echo', ['foo',
|
|
'bar'])} will only print \samp{bar} on standard output; \samp{foo}
|
|
will seem to be ignored.
|
|
|
|
|
|
\begin{funcdesc}{abort}{}
|
|
Generate a \constant{SIGABRT} signal to the current process. On
|
|
\UNIX, the default behavior is to produce a core dump; on Windows, the
|
|
process immediately returns an exit code of \code{3}. Be aware that
|
|
programs which use \function{signal.signal()} to register a handler
|
|
for \constant{SIGABRT} will behave differently.
|
|
Availability: Macintosh, \UNIX, Windows.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{execl}{path, arg0, arg1, \moreargs}
|
|
\funcline{execle}{path, arg0, arg1, \moreargs, env}
|
|
\funcline{execlp}{file, arg0, arg1, \moreargs}
|
|
\funcline{execlpe}{file, arg0, arg1, \moreargs, env}
|
|
\funcline{execv}{path, args}
|
|
\funcline{execve}{path, args, env}
|
|
\funcline{execvp}{file, args}
|
|
\funcline{execvpe}{file, args, env}
|
|
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 \exception{OSError} exceptions.
|
|
|
|
The \character{l} and \character{v} variants of the
|
|
\function{exec*()} functions differ in how command-line arguments are
|
|
passed. The \character{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
|
|
\function{execl*()} functions. The \character{v} variants are good
|
|
when the number of parameters is variable, with the arguments being
|
|
passed in a list or tuple as the \var{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 \character{p} near the end
|
|
(\function{execlp()}, \function{execlpe()}, \function{execvp()},
|
|
and \function{execvpe()}) will use the \envvar{PATH} environment
|
|
variable to locate the program \var{file}. When the environment is
|
|
being replaced (using one of the \function{exec*e()} variants,
|
|
discussed in the next paragraph), the
|
|
new environment is used as the source of the \envvar{PATH} variable.
|
|
The other variants, \function{execl()}, \function{execle()},
|
|
\function{execv()}, and \function{execve()}, will not use the
|
|
\envvar{PATH} variable to locate the executable; \var{path} must
|
|
contain an appropriate absolute or relative path.
|
|
|
|
For \function{execle()}, \function{execlpe()}, \function{execve()},
|
|
and \function{execvpe()} (note that these all end in \character{e}),
|
|
the \var{env} parameter must be a mapping which is used to define the
|
|
environment variables for the new process; the \function{execl()},
|
|
\function{execlp()}, \function{execv()}, and \function{execvp()}
|
|
all cause the new process to inherit the environment of the current
|
|
process.
|
|
Availability: Macintosh, \UNIX, Windows.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{_exit}{n}
|
|
Exit to the system with status \var{n}, without calling cleanup
|
|
handlers, flushing stdio buffers, etc.
|
|
Availability: Macintosh, \UNIX, Windows.
|
|
|
|
\begin{notice}
|
|
The standard way to exit is \code{sys.exit(\var{n})}.
|
|
\function{_exit()} should normally only be used in the child process
|
|
after a \function{fork()}.
|
|
\end{notice}
|
|
\end{funcdesc}
|
|
|
|
The following exit codes are a defined, and can be used with
|
|
\function{_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.
|
|
\note{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.}
|
|
|
|
\begin{datadesc}{EX_OK}
|
|
Exit code that means no error occurred.
|
|
Availability: Macintosh, \UNIX.
|
|
\versionadded{2.3}
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{EX_USAGE}
|
|
Exit code that means the command was used incorrectly, such as when
|
|
the wrong number of arguments are given.
|
|
Availability: Macintosh, \UNIX.
|
|
\versionadded{2.3}
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{EX_DATAERR}
|
|
Exit code that means the input data was incorrect.
|
|
Availability: Macintosh, \UNIX.
|
|
\versionadded{2.3}
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{EX_NOINPUT}
|
|
Exit code that means an input file did not exist or was not readable.
|
|
Availability: Macintosh, \UNIX.
|
|
\versionadded{2.3}
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{EX_NOUSER}
|
|
Exit code that means a specified user did not exist.
|
|
Availability: Macintosh, \UNIX.
|
|
\versionadded{2.3}
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{EX_NOHOST}
|
|
Exit code that means a specified host did not exist.
|
|
Availability: Macintosh, \UNIX.
|
|
\versionadded{2.3}
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{EX_UNAVAILABLE}
|
|
Exit code that means that a required service is unavailable.
|
|
Availability: Macintosh, \UNIX.
|
|
\versionadded{2.3}
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{EX_SOFTWARE}
|
|
Exit code that means an internal software error was detected.
|
|
Availability: Macintosh, \UNIX.
|
|
\versionadded{2.3}
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{EX_OSERR}
|
|
Exit code that means an operating system error was detected, such as
|
|
the inability to fork or create a pipe.
|
|
Availability: Macintosh, \UNIX.
|
|
\versionadded{2.3}
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{EX_OSFILE}
|
|
Exit code that means some system file did not exist, could not be
|
|
opened, or had some other kind of error.
|
|
Availability: Macintosh, \UNIX.
|
|
\versionadded{2.3}
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{EX_CANTCREAT}
|
|
Exit code that means a user specified output file could not be created.
|
|
Availability: Macintosh, \UNIX.
|
|
\versionadded{2.3}
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{EX_IOERR}
|
|
Exit code that means that an error occurred while doing I/O on some file.
|
|
Availability: Macintosh, \UNIX.
|
|
\versionadded{2.3}
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{EX_TEMPFAIL}
|
|
Exit code that means a temporary failure occurred. This indicates
|
|
something that may not really be an error, such as a network
|
|
connection that couldn't be made during a retryable operation.
|
|
Availability: Macintosh, \UNIX.
|
|
\versionadded{2.3}
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{EX_PROTOCOL}
|
|
Exit code that means that a protocol exchange was illegal, invalid, or
|
|
not understood.
|
|
Availability: Macintosh, \UNIX.
|
|
\versionadded{2.3}
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{EX_NOPERM}
|
|
Exit code that means that there were insufficient permissions to
|
|
perform the operation (but not intended for file system problems).
|
|
Availability: Macintosh, \UNIX.
|
|
\versionadded{2.3}
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{EX_CONFIG}
|
|
Exit code that means that some kind of configuration error occurred.
|
|
Availability: Macintosh, \UNIX.
|
|
\versionadded{2.3}
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{EX_NOTFOUND}
|
|
Exit code that means something like ``an entry was not found''.
|
|
Availability: Macintosh, \UNIX.
|
|
\versionadded{2.3}
|
|
\end{datadesc}
|
|
|
|
\begin{funcdesc}{fork}{}
|
|
Fork a child process. Return \code{0} in the child, the child's
|
|
process id in the parent.
|
|
Availability: Macintosh, \UNIX.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{forkpty}{}
|
|
Fork a child process, using a new pseudo-terminal as the child's
|
|
controlling terminal. Return a pair of \code{(\var{pid}, \var{fd})},
|
|
where \var{pid} is \code{0} in the child, the new child's process id
|
|
in the parent, and \var{fd} is the file descriptor of the master end
|
|
of the pseudo-terminal. For a more portable approach, use the
|
|
\refmodule{pty} module.
|
|
Availability: Macintosh, Some flavors of \UNIX.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{kill}{pid, sig}
|
|
\index{process!killing}
|
|
\index{process!signalling}
|
|
Send signal \var{sig} to the process \var{pid}. Constants for the
|
|
specific signals available on the host platform are defined in the
|
|
\refmodule{signal} module.
|
|
Availability: Macintosh, \UNIX.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{killpg}{pgid, sig}
|
|
\index{process!killing}
|
|
\index{process!signalling}
|
|
Send the signal \var{sig} to the process group \var{pgid}.
|
|
Availability: Macintosh, \UNIX.
|
|
\versionadded{2.3}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{nice}{increment}
|
|
Add \var{increment} to the process's ``niceness''. Return the new
|
|
niceness.
|
|
Availability: Macintosh, \UNIX.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{plock}{op}
|
|
Lock program segments into memory. The value of \var{op}
|
|
(defined in \code{<sys/lock.h>}) determines which segments are locked.
|
|
Availability: Macintosh, \UNIX.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdescni}{popen}{\unspecified}
|
|
\funclineni{popen2}{\unspecified}
|
|
\funclineni{popen3}{\unspecified}
|
|
\funclineni{popen4}{\unspecified}
|
|
Run child processes, returning opened pipes for communications. These
|
|
functions are described in section \ref{os-newstreams}.
|
|
\end{funcdescni}
|
|
|
|
\begin{funcdesc}{spawnl}{mode, path, \moreargs}
|
|
\funcline{spawnle}{mode, path, \moreargs, env}
|
|
\funcline{spawnlp}{mode, file, \moreargs}
|
|
\funcline{spawnlpe}{mode, file, \moreargs, env}
|
|
\funcline{spawnv}{mode, path, args}
|
|
\funcline{spawnve}{mode, path, args, env}
|
|
\funcline{spawnvp}{mode, file, args}
|
|
\funcline{spawnvpe}{mode, file, args, env}
|
|
Execute the program \var{path} in a new process. If \var{mode} is
|
|
\constant{P_NOWAIT}, this function returns the process ID of the new
|
|
process; if \var{mode} is \constant{P_WAIT}, returns the process's
|
|
exit code if it exits normally, or \code{-\var{signal}}, where
|
|
\var{signal} is the signal that killed the process. On Windows, the
|
|
process ID will actually be the process handle, so can be used with
|
|
the \function{waitpid()} function.
|
|
|
|
The \character{l} and \character{v} variants of the
|
|
\function{spawn*()} functions differ in how command-line arguments are
|
|
passed. The \character{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
|
|
\function{spawnl*()} functions. The \character{v} variants are good
|
|
when the number of parameters is variable, with the arguments being
|
|
passed in a list or tuple as the \var{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 \character{p} near the end
|
|
(\function{spawnlp()}, \function{spawnlpe()}, \function{spawnvp()},
|
|
and \function{spawnvpe()}) will use the \envvar{PATH} environment
|
|
variable to locate the program \var{file}. When the environment is
|
|
being replaced (using one of the \function{spawn*e()} variants,
|
|
discussed in the next paragraph), the new environment is used as the
|
|
source of the \envvar{PATH} variable. The other variants,
|
|
\function{spawnl()}, \function{spawnle()}, \function{spawnv()}, and
|
|
\function{spawnve()}, will not use the \envvar{PATH} variable to
|
|
locate the executable; \var{path} must contain an appropriate absolute
|
|
or relative path.
|
|
|
|
For \function{spawnle()}, \function{spawnlpe()}, \function{spawnve()},
|
|
and \function{spawnvpe()} (note that these all end in \character{e}),
|
|
the \var{env} parameter must be a mapping which is used to define the
|
|
environment variables for the new process; the \function{spawnl()},
|
|
\function{spawnlp()}, \function{spawnv()}, and \function{spawnvp()}
|
|
all cause the new process to inherit the environment of the current
|
|
process.
|
|
|
|
As an example, the following calls to \function{spawnlp()} and
|
|
\function{spawnvpe()} are equivalent:
|
|
|
|
\begin{verbatim}
|
|
import os
|
|
os.spawnlp(os.P_WAIT, 'cp', 'cp', 'index.html', '/dev/null')
|
|
|
|
L = ['cp', 'index.html', '/dev/null']
|
|
os.spawnvpe(os.P_WAIT, 'cp', L, os.environ)
|
|
\end{verbatim}
|
|
|
|
Availability: \UNIX, Windows. \function{spawnlp()},
|
|
\function{spawnlpe()}, \function{spawnvp()} and \function{spawnvpe()}
|
|
are not available on Windows.
|
|
\versionadded{1.6}
|
|
\end{funcdesc}
|
|
|
|
\begin{datadesc}{P_NOWAIT}
|
|
\dataline{P_NOWAITO}
|
|
Possible values for the \var{mode} parameter to the \function{spawn*()}
|
|
family of functions. If either of these values is given, the
|
|
\function{spawn*()} functions 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}
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{P_WAIT}
|
|
Possible value for the \var{mode} parameter to the \function{spawn*()}
|
|
family of functions. If this is given as \var{mode}, the
|
|
\function{spawn*()} functions will not return until the new process
|
|
has run to completion and will return the exit code of the process the
|
|
run is successful, or \code{-\var{signal}} if a signal kills the
|
|
process.
|
|
Availability: Macintosh, \UNIX, Windows.
|
|
\versionadded{1.6}
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{P_DETACH}
|
|
\dataline{P_OVERLAY}
|
|
Possible values for the \var{mode} parameter to the
|
|
\function{spawn*()} family of functions. These are less portable than
|
|
those listed above.
|
|
\constant{P_DETACH} is similar to \constant{P_NOWAIT}, but the new
|
|
process is detached from the console of the calling process.
|
|
If \constant{P_OVERLAY} is used, the current process will be replaced;
|
|
the \function{spawn*()} function will not return.
|
|
Availability: Windows.
|
|
\versionadded{1.6}
|
|
\end{datadesc}
|
|
|
|
\begin{funcdesc}{startfile}{path}
|
|
Start a file with its associated application. This acts like
|
|
double-clicking the file in Windows Explorer, or giving the file name
|
|
as an argument to the \program{start} command from the interactive
|
|
command shell: the file is opened with whatever application (if any)
|
|
its extension is associated.
|
|
|
|
\function{startfile()} returns as soon as the associated application
|
|
is launched. There is no option to wait for the application to close,
|
|
and no way to retrieve the application's exit status. The \var{path}
|
|
parameter is relative to the current directory. If you want to use an
|
|
absolute path, make sure the first character is not a slash
|
|
(\character{/}); the underlying Win32 \cfunction{ShellExecute()}
|
|
function doesn't work if it is. Use the \function{os.path.normpath()}
|
|
function to ensure that the path is properly encoded for Win32.
|
|
Availability: Windows.
|
|
\versionadded{2.0}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{system}{command}
|
|
Execute the command (a string) in a subshell. This is implemented by
|
|
calling the Standard C function \cfunction{system()}, and has the
|
|
same limitations. Changes to \code{posix.environ}, \code{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 \function{wait()}. Note that \POSIX{} does not
|
|
specify the meaning of the return value of the C \cfunction{system()}
|
|
function, so the return value of the Python function is system-dependent.
|
|
|
|
On Windows, the return value is that returned by the system shell after
|
|
running \var{command}, given by the Windows environment variable
|
|
\envvar{COMSPEC}: on \program{command.com} systems (Windows 95, 98 and ME)
|
|
this is always \code{0}; on \program{cmd.exe} systems (Windows NT, 2000
|
|
and XP) this is the exit status of the command run; on systems using
|
|
a non-native shell, consult your shell documentation.
|
|
|
|
Availability: Macintosh, \UNIX, Windows.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{times}{}
|
|
Return a 5-tuple of floating point numbers indicating accumulated
|
|
(processor or other)
|
|
times, in seconds. The items are: user time, system time, children's
|
|
user time, children's system time, and elapsed real time since a fixed
|
|
point in the past, in that order. See the \UNIX{} manual page
|
|
\manpage{times}{2} or the corresponding Windows Platform API
|
|
documentation.
|
|
Availability: Macintosh, \UNIX, Windows.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{wait}{}
|
|
Wait for completion of a child process, and return a tuple containing
|
|
its pid and exit status indication: a 16-bit number, whose low byte is
|
|
the signal number that killed the process, and whose high byte is the
|
|
exit status (if the signal number is zero); the high bit of the low
|
|
byte is set if a core file was produced.
|
|
Availability: Macintosh, \UNIX.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{waitpid}{pid, options}
|
|
The details of this function differ on \UNIX{} and Windows.
|
|
|
|
On \UNIX:
|
|
Wait for completion of a child process given by process id \var{pid},
|
|
and return a tuple containing its process id and exit status
|
|
indication (encoded as for \function{wait()}). The semantics of the
|
|
call are affected by the value of the integer \var{options}, which
|
|
should be \code{0} for normal operation.
|
|
|
|
If \var{pid} is greater than \code{0}, \function{waitpid()} requests
|
|
status information for that specific process. If \var{pid} is
|
|
\code{0}, the request is for the status of any child in the process
|
|
group of the current process. If \var{pid} is \code{-1}, the request
|
|
pertains to any child of the current process. If \var{pid} is less
|
|
than \code{-1}, status is requested for any process in the process
|
|
group \code{-\var{pid}} (the absolute value of \var{pid}).
|
|
|
|
On Windows:
|
|
Wait for completion of a process given by process handle \var{pid},
|
|
and return a tuple containing \var{pid},
|
|
and its exit status shifted left by 8 bits (shifting makes cross-platform
|
|
use of the function easier).
|
|
A \var{pid} less than or equal to \code{0} has no special meaning on
|
|
Windows, and raises an exception.
|
|
The value of integer \var{options} has no effect.
|
|
\var{pid} can refer to any process whose id is known, not necessarily a
|
|
child process.
|
|
The \function{spawn()} functions called with \constant{P_NOWAIT}
|
|
return suitable process handles.
|
|
\end{funcdesc}
|
|
|
|
\begin{datadesc}{WNOHANG}
|
|
The option for \function{waitpid()} to return immediately if no child
|
|
process status is available immediately. The function returns
|
|
\code{(0, 0)} in this case.
|
|
Availability: Macintosh, \UNIX.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{WCONTINUED}
|
|
This option causes child processes to be reported if they have been
|
|
continued from a job control stop since their status was last
|
|
reported.
|
|
Availability: Some \UNIX{} systems.
|
|
\versionadded{2.3}
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{WUNTRACED}
|
|
This option causes child processes to be reported if they have been
|
|
stopped but their current state has not been reported since they were
|
|
stopped.
|
|
Availability: Macintosh, \UNIX.
|
|
\versionadded{2.3}
|
|
\end{datadesc}
|
|
|
|
The following functions take a process status code as returned by
|
|
\function{system()}, \function{wait()}, or \function{waitpid()} as a
|
|
parameter. They may be used to determine the disposition of a
|
|
process.
|
|
|
|
\begin{funcdesc}{WCOREDUMP}{status}
|
|
Returns \code{True} if a core dump was generated for the process,
|
|
otherwise it returns \code{False}.
|
|
Availability: Macintosh, \UNIX.
|
|
\versionadded{2.3}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{WIFCONTINUED}{status}
|
|
Returns \code{True} if the process has been continued from a job
|
|
control stop, otherwise it returns \code{False}.
|
|
Availability: \UNIX.
|
|
\versionadded{2.3}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{WIFSTOPPED}{status}
|
|
Returns \code{True} if the process has been stopped, otherwise it
|
|
returns \code{False}.
|
|
Availability: \UNIX.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{WIFSIGNALED}{status}
|
|
Returns \code{True} if the process exited due to a signal, otherwise
|
|
it returns \code{False}.
|
|
Availability: Macintosh, \UNIX.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{WIFEXITED}{status}
|
|
Returns \code{True} if the process exited using the \manpage{exit}{2}
|
|
system call, otherwise it returns \code{False}.
|
|
Availability: Macintosh, \UNIX.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{WEXITSTATUS}{status}
|
|
If \code{WIFEXITED(\var{status})} is true, return the integer
|
|
parameter to the \manpage{exit}{2} system call. Otherwise, the return
|
|
value is meaningless.
|
|
Availability: Macintosh, \UNIX.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{WSTOPSIG}{status}
|
|
Return the signal which caused the process to stop.
|
|
Availability: Macintosh, \UNIX.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{WTERMSIG}{status}
|
|
Return the signal which caused the process to exit.
|
|
Availability: Macintosh, \UNIX.
|
|
\end{funcdesc}
|
|
|
|
|
|
\subsection{Miscellaneous System Information \label{os-path}}
|
|
|
|
|
|
\begin{funcdesc}{confstr}{name}
|
|
Return string-valued system configuration values.
|
|
\var{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, \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
|
|
\code{confstr_names} dictionary. For configuration variables not
|
|
included in that mapping, passing an integer for \var{name} is also
|
|
accepted.
|
|
Availability: Macintosh, \UNIX.
|
|
|
|
If the configuration value specified by \var{name} isn't defined, the
|
|
empty string is returned.
|
|
|
|
If \var{name} is a string and is not known, \exception{ValueError} is
|
|
raised. If a specific value for \var{name} is not supported by the
|
|
host system, even if it is included in \code{confstr_names}, an
|
|
\exception{OSError} is raised with \constant{errno.EINVAL} for the
|
|
error number.
|
|
\end{funcdesc}
|
|
|
|
\begin{datadesc}{confstr_names}
|
|
Dictionary mapping names accepted by \function{confstr()} 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: Macintosh, \UNIX.
|
|
\end{datadesc}
|
|
|
|
\begin{funcdesc}{getloadavg}{}
|
|
Return the number of processes in the system run queue averaged over
|
|
the last 1, 5, and 15 minutes or raises OSError if the load average
|
|
was unobtainable.
|
|
|
|
\versionadded{2.3}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{sysconf}{name}
|
|
Return integer-valued system configuration values.
|
|
If the configuration value specified by \var{name} isn't defined,
|
|
\code{-1} is returned. The comments regarding the \var{name}
|
|
parameter for \function{confstr()} apply here as well; the dictionary
|
|
that provides information on the known names is given by
|
|
\code{sysconf_names}.
|
|
Availability: Macintosh, \UNIX.
|
|
\end{funcdesc}
|
|
|
|
\begin{datadesc}{sysconf_names}
|
|
Dictionary mapping names accepted by \function{sysconf()} 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: Macintosh, \UNIX.
|
|
\end{datadesc}
|
|
|
|
|
|
The follow data values are used to support path manipulation
|
|
operations. These are defined for all platforms.
|
|
|
|
Higher-level operations on pathnames are defined in the
|
|
\refmodule{os.path} module.
|
|
|
|
|
|
\begin{datadesc}{curdir}
|
|
The constant string used by the operating system to refer to the current
|
|
directory.
|
|
For example: \code{'.'} for \POSIX{} or \code{':'} for Mac OS 9.
|
|
Also available via \module{os.path}.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{pardir}
|
|
The constant string used by the operating system to refer to the parent
|
|
directory.
|
|
For example: \code{'..'} for \POSIX{} or \code{'::'} for Mac OS 9.
|
|
Also available via \module{os.path}.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{sep}
|
|
The character used by the operating system to separate pathname components,
|
|
for example, \character{/} for \POSIX{} or \character{:} for
|
|
Mac OS 9. Note that knowing this is not sufficient to be able to
|
|
parse or concatenate pathnames --- use \function{os.path.split()} and
|
|
\function{os.path.join()} --- but it is occasionally useful.
|
|
Also available via \module{os.path}.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{altsep}
|
|
An alternative character used by the operating system to separate pathname
|
|
components, or \code{None} if only one separator character exists. This is
|
|
set to \character{/} on Windows systems where \code{sep} is a
|
|
backslash.
|
|
Also available via \module{os.path}.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{extsep}
|
|
The character which separates the base filename from the extension;
|
|
for example, the \character{.} in \file{os.py}.
|
|
Also available via \module{os.path}.
|
|
\versionadded{2.2}
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{pathsep}
|
|
The character conventionally used by the operating system to separate
|
|
search path components (as in \envvar{PATH}), such as \character{:} for
|
|
\POSIX{} or \character{;} for Windows.
|
|
Also available via \module{os.path}.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{defpath}
|
|
The default search path used by \function{exec*p*()} and
|
|
\function{spawn*p*()} if the environment doesn't have a \code{'PATH'}
|
|
key.
|
|
Also available via \module{os.path}.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{linesep}
|
|
The string used to separate (or, rather, terminate) lines on the
|
|
current platform. This may be a single character, such as \code{'\e
|
|
n'} for \POSIX{} or \code{'\e r'} for Mac OS, or multiple characters,
|
|
for example, \code{'\e r\e n'} for Windows.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{devnull}
|
|
The file path of the null device.
|
|
For example: \code{'/dev/null'} for \POSIX{} or \code{'Dev:Nul'} for
|
|
Mac OS 9.
|
|
Also available via \module{os.path}.
|
|
\versionadded{2.4}
|
|
\end{datadesc}
|
|
|
|
|
|
\subsection{Miscellaneous Functions \label{os-miscfunc}}
|
|
|
|
\begin{funcdesc}{urandom}{n}
|
|
Return a string of \var{n} random bytes suitable for cryptographic use.
|
|
|
|
This function returns random bytes from an OS-specific
|
|
randomness source. The returned data should be unpredictable enough for
|
|
cryptographic applications, though its exact quality depends on the OS
|
|
implementation. On a UNIX-like system this will query /dev/urandom, and
|
|
on Windows it will use CryptGenRandom. If a randomness source is not
|
|
found, \exception{NotImplementedError} will be raised.
|
|
\versionadded{2.4}
|
|
\end{funcdesc}
|
|
|
|
|
|
|
|
|