1046 lines
37 KiB
TeX
1046 lines
37 KiB
TeX
\section{\module{os} ---
|
|
Miscellaneous OS interfaces}
|
|
|
|
\declaremodule{standard}{os}
|
|
\modulesynopsis{Miscellaneous OS interfaces.}
|
|
|
|
|
|
This module provides a more portable way of using operating system
|
|
(OS) dependent functionality than importing an OS dependent built-in
|
|
module like \refmodule{posix} or \module{nt}.
|
|
|
|
This module searches for an OS 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 OS dependent
|
|
modules is such that as long as the same functionality is available,
|
|
it uses the same interface; e.g., 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 OS 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 OS 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 (e.g., not for illegal argument types). 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 (e.g. \function{chdir()} or
|
|
\function{unlink()}), the exception instance will contain a third
|
|
attribute, \member{filename}, which is the file name passed to the
|
|
function.
|
|
|
|
When exceptions are strings, the string for the exception is
|
|
\code{'OSError'}.
|
|
\end{excdesc}
|
|
|
|
\begin{datadesc}{name}
|
|
The name of the OS dependent module imported. The following names
|
|
have currently been registered: \code{'posix'}, \code{'nt'},
|
|
\code{'dos'}, \code{'mac'}, \code{'os2'}, \code{'ce'}, \code{'java'}.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{path}
|
|
The corresponding OS dependent standard module for pathname
|
|
operations, e.g., \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 a valid 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.
|
|
|
|
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.
|
|
|
|
If \function{putenv()} is not provided, this mapping may be passed to
|
|
the appropriate process-creation functions to cause child processes to
|
|
use a modified environment.
|
|
\end{datadesc}
|
|
|
|
\begin{funcdescni}{chdir}{path}
|
|
\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 current process' effective group id.
|
|
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 current process' group id.
|
|
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 actual login name for the current process, even if there
|
|
are multiple login names which map to the same user id.
|
|
Availability: \UNIX{}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{getpgrp}{}
|
|
\index{process!group}
|
|
Return the current process group id.
|
|
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}{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.
|
|
|
|
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}{setgid}{gid}
|
|
Set the current process' group id.
|
|
Availability: \UNIX{}.
|
|
\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()}. See the \UNIX{} manual
|
|
for the semantics.
|
|
Availability: \UNIX{}.
|
|
\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}
|
|
|
|
|
|
|
|
\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.
|
|
\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. \strong{Note:} This function
|
|
behaves unreliably under Windows due to the native implementation of
|
|
\cfunction{popen()}.
|
|
Availability: \UNIX{}, Windows.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{tmpfile}{}
|
|
Return a new file object opened in update mode (\samp{w+}). The file
|
|
has no directory entries associated with it and will be automatically
|
|
deleted once there are no file descriptors for the file.
|
|
Availability: \UNIX{}.
|
|
\end{funcdesc}
|
|
|
|
|
|
\subsection{File Descriptor Operations \label{os-fd-ops}}
|
|
|
|
These functions operate on I/O streams referred to
|
|
using file descriptors.
|
|
|
|
|
|
\begin{funcdesc}{close}{fd}
|
|
Close file descriptor \var{fd}.
|
|
Availability: Macintosh, \UNIX{}, Windows.
|
|
|
|
Note: 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{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: \UNIX{}, Windows.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{fpathconf}{fd, name}
|
|
Return system configration 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, Unix95, Unix98, 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: \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: \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}{ftruncate}{fd, length}
|
|
Truncate the file corresponding to file descriptor \var{fd},
|
|
so that it is at most \var{length} bytes in size.
|
|
Availability: \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).
|
|
|
|
Note: 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{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: \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.
|
|
Availability: Macintosh, \UNIX{}, Windows.
|
|
|
|
Note: 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{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: \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: \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: \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.
|
|
|
|
Note: 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{funcdesc}
|
|
|
|
|
|
The following data items are available for use in constructing the
|
|
\var{flags} parameter to the \function{open()} function.
|
|
|
|
\begin{datadesc}{O_RDONLY}
|
|
\dataline{O_WRONLY}
|
|
\dataline{O_RDWR}
|
|
\dataline{O_NDELAY}
|
|
\dataline{O_NONBLOCK}
|
|
\dataline{O_APPEND}
|
|
\dataline{O_DSYNC}
|
|
\dataline{O_RSYNC}
|
|
\dataline{O_SYNC}
|
|
\dataline{O_NOCTTY}
|
|
\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}
|
|
|
|
|
|
\subsection{Files and Directories \label{os-file-dir}}
|
|
|
|
\begin{funcdesc}{access}{path, mode}
|
|
Check read/write/execute permissions for this process or existence of
|
|
file \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 \code{1} if access is allowed, \code{0} if not.
|
|
See the \UNIX{} man page \manpage{access}{2} for more information.
|
|
Availability: \UNIX{}.
|
|
\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}{getcwd}{}
|
|
Return a string representing the current working directory.
|
|
Availability: Macintosh, \UNIX{}, Windows.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{chmod}{path, mode}
|
|
Change the mode of \var{path} to the numeric \var{mode}.
|
|
Availability: \UNIX{}, Windows.
|
|
\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}.
|
|
Availability: \UNIX{}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{link}{src, dst}
|
|
Create a hard link pointing to \var{src} named \var{dst}.
|
|
Availability: \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.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{lstat}{path}
|
|
Like \function{stat()}, but do not follow symbolic links.
|
|
Availability: \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: \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}{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}}
|
|
\index{directory!creating}
|
|
Recursive directory creation function. 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}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{pathconf}{path, name}
|
|
Return system configration 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, Unix95, Unix98, 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: \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: \UNIX.
|
|
\end{datadesc}
|
|
|
|
\begin{funcdesc}{readlink}{path}
|
|
Return a string representing the path to which the symbolic link
|
|
points.
|
|
Availability: \UNIX{}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{remove}{path}
|
|
Remove the file \var{path}. See \function{rmdir()} below to remove a
|
|
directory. This is identical to the \function{unlink()} function
|
|
documented below.
|
|
Availability: Macintosh, \UNIX{}, Windows.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{removedirs}{path}
|
|
\index{directory!deleting}
|
|
Recursive directory removal function. 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}.
|
|
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()}.
|
|
|
|
Note: this function can fail with the new directory structure made if
|
|
you lack permissions needed to remove the leaf directory or file.
|
|
\versionadded{1.5.2}
|
|
\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 a tuple of at least 10 integers giving the most
|
|
important (and portable) members of the \emph{stat} structure, in the
|
|
order
|
|
\code{st_mode},
|
|
\code{st_ino},
|
|
\code{st_dev},
|
|
\code{st_nlink},
|
|
\code{st_uid},
|
|
\code{st_gid},
|
|
\code{st_size},
|
|
\code{st_atime},
|
|
\code{st_mtime},
|
|
\code{st_ctime}.
|
|
More items may be added at the end by some implementations.
|
|
(On MS Windows, some items are filled with dummy values.)
|
|
Availability: Macintosh, \UNIX{}, Windows.
|
|
|
|
Note: The standard module \refmodule{stat}\refstmodindex{stat} defines
|
|
functions and constants that are useful for extracting information
|
|
from a \ctype{stat} structure.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{statvfs}{path}
|
|
Perform a \cfunction{statvfs()} system call on the given path. The
|
|
return value is a tuple of 10 integers giving the most common
|
|
members of the \ctype{statvfs} structure, in the order
|
|
\code{f_bsize},
|
|
\code{f_frsize},
|
|
\code{f_blocks},
|
|
\code{f_bfree},
|
|
\code{f_bavail},
|
|
\code{f_files},
|
|
\code{f_ffree},
|
|
\code{f_favail},
|
|
\code{f_flag},
|
|
\code{f_namemax}.
|
|
Availability: \UNIX{}.
|
|
|
|
Note: The standard module \module{statvfs}\refstmodindex{statvfs}
|
|
defines constants that are useful for extracting information
|
|
from a \ctype{statvfs} structure.
|
|
\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.
|
|
\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.
|
|
\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.
|
|
\versionchanged[added support for \code{None} for \var{times}]{1.6}
|
|
Availability: Macintosh, \UNIX{}, Windows.
|
|
\end{funcdesc}
|
|
|
|
|
|
\subsection{Process Management \label{os-process}}
|
|
|
|
These functions may be used to create and manage processes.
|
|
|
|
|
|
\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: \UNIX, Windows.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{execl}{path, arg0, arg1, ...}
|
|
This is equivalent to
|
|
\samp{execv(\var{path}, (\var{arg0}, \var{arg1}, ...))}.
|
|
Availability: \UNIX{}, Windows.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{execle}{path, arg0, arg1, ..., env}
|
|
This is equivalent to
|
|
\samp{execve(\var{path}, (\var{arg0}, \var{arg1}, ...), \var{env})}.
|
|
Availability: \UNIX{}, Windows.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{execlp}{path, arg0, arg1, ...}
|
|
This is equivalent to
|
|
\samp{execvp(\var{path}, (\var{arg0}, \var{arg1}, ...))}.
|
|
Availability: \UNIX{}, Windows.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{execv}{path, args}
|
|
Execute the executable \var{path} with argument list \var{args},
|
|
replacing the current process (i.e., the Python interpreter).
|
|
The argument list may be a tuple or list of strings.
|
|
Availability: \UNIX{}, Windows.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{execve}{path, args, env}
|
|
Execute the executable \var{path} with argument list \var{args},
|
|
and environment \var{env},
|
|
replacing the current process (i.e., the Python interpreter).
|
|
The argument list may be a tuple or list of strings.
|
|
The environment must be a dictionary mapping strings to strings.
|
|
Availability: \UNIX{}, Windows.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{execvp}{path, args}
|
|
This is like \samp{execv(\var{path}, \var{args})} but duplicates
|
|
the shell's actions in searching for an executable file in a list of
|
|
directories. The directory list is obtained from
|
|
\code{environ['PATH']}.
|
|
Availability: \UNIX{}, Windows.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{execvpe}{path, args, env}
|
|
This is a cross between \function{execve()} and \function{execvp()}.
|
|
The directory list is obtained from \code{\var{env}['PATH']}.
|
|
Availability: \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: \UNIX{}, Windows.
|
|
|
|
Note: 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{funcdesc}
|
|
|
|
\begin{funcdesc}{fork}{}
|
|
Fork a child process. Return \code{0} in the child, the child's
|
|
process id in the parent.
|
|
Availability: \UNIX{}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{kill}{pid, sig}
|
|
\index{process!killing}
|
|
\index{process!signalling}
|
|
Kill the process \var{pid} with signal \var{sig}.
|
|
Availability: \UNIX{}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{nice}{increment}
|
|
Add \var{increment} to the process's ``niceness''. Return the new
|
|
niceness.
|
|
Availability: \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: \UNIX{}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{spawnv}{mode, path, args}
|
|
Execute the program \var{path} in a new process, passing the arguments
|
|
specified in \var{args} as command-line parameters. \var{args} may be
|
|
a list or a tuple. \var{mode} is a magic operational constant. See
|
|
the Visual \Cpp{} Runtime Library documentation for further
|
|
information; the constants are exposed to the Python programmer as
|
|
listed below.
|
|
Availability: \UNIX{}, Windows.
|
|
\versionadded{1.5.2}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{spawnve}{mode, path, args, env}
|
|
Execute the program \var{path} in a new process, passing the arguments
|
|
specified in \var{args} as command-line parameters and the contents of
|
|
the mapping \var{env} as the environment. \var{args} may be a list or
|
|
a tuple. \var{mode} is a magic operational constant. See the Visual
|
|
\Cpp{} Runtime Library documentation for further information; the
|
|
constants are exposed to the Python programmer as listed below.
|
|
Availability: \UNIX{}, Windows.
|
|
\versionadded{1.5.2}
|
|
\end{funcdesc}
|
|
|
|
\begin{datadesc}{P_WAIT}
|
|
\dataline{P_NOWAIT}
|
|
\dataline{P_NOWAITO}
|
|
Possible values for the \var{mode} parameter to \function{spawnv()}
|
|
and \function{spawnve()}.
|
|
Availability: \UNIX{}, Windows.
|
|
\versionadded{1.5.2}
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{P_OVERLAY}
|
|
\dataline{P_DETACH}
|
|
Possible values for the \var{mode} parameter to \function{spawnv()}
|
|
and \function{spawnve()}. These are less portable than those listed
|
|
above.
|
|
Availability: Windows.
|
|
\versionadded{1.5.2}
|
|
\end{datadesc}
|
|
|
|
\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.
|
|
The return value is the exit status of the process encoded in the
|
|
format specified for \function{wait()}, except on Windows 95 and 98,
|
|
where it is always \code{0}. 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.
|
|
Availability: \UNIX{}, Windows.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{times}{}
|
|
Return a 5-tuple of floating point numbers indicating accumulated (CPU
|
|
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: \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: \UNIX{}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{waitpid}{pid, options}
|
|
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.
|
|
Availability: \UNIX{}.
|
|
|
|
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}).
|
|
\end{funcdesc}
|
|
|
|
\begin{datadesc}{WNOHANG}
|
|
The option for \function{waitpid()} to avoid hanging if no child
|
|
process status is available immediately.
|
|
Availability: \UNIX{}.
|
|
\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}{WIFSTOPPED}{status}
|
|
Return true if the process has been stopped.
|
|
Availability: \UNIX{}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{WIFSIGNALED}{status}
|
|
Return true if the process exited due to a signal.
|
|
Availability: \UNIX{}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{WIFEXITED}{status}
|
|
Return true if the process exited using the \manpage{exit}{2} system
|
|
call.
|
|
Availability: \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: \UNIX{}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{WSTOPSIG}{status}
|
|
Return the signal which caused the process to stop.
|
|
Availability: \UNIX{}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{WTERMSIG}{status}
|
|
Return the signal which caused the process to exit.
|
|
Availability: \UNIX{}.
|
|
\end{funcdesc}
|
|
|
|
|
|
\subsection{Miscellanenous 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, Unix95, Unix98, 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: \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: \UNIX.
|
|
\end{datadesc}
|
|
|
|
\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: \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: \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 OS to refer to the current directory,
|
|
e.g.\ \code{'.'} for \POSIX{} or \code{':'} for the Macintosh.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{pardir}
|
|
The constant string used by the OS to refer to the parent directory,
|
|
e.g.\ \code{'..'} for \POSIX{} or \code{'::'} for the Macintosh.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{sep}
|
|
The character used by the OS to separate pathname components,
|
|
e.g.\ \character{/} for \POSIX{} or \character{:} for the Macintosh.
|
|
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.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{altsep}
|
|
An alternative character used by the OS to separate pathname components,
|
|
or \code{None} if only one separator character exists. This is set to
|
|
\character{/} on DOS and Windows systems where \code{sep} is a backslash.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{pathsep}
|
|
The character conventionally used by the OS to separate search patch
|
|
components (as in \envvar{PATH}), e.g.\ \character{:} for \POSIX{} or
|
|
\character{;} for DOS and Windows.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{defpath}
|
|
The default search path used by \function{exec*p*()} if the environment
|
|
doesn't have a \code{'PATH'} key.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{linesep}
|
|
The string used to separate (or, rather, terminate) lines on the
|
|
current platform. This may be a single character,
|
|
e.g.\ \code{'\e n'} for \POSIX{} or \code{'\e r'} for MacOS, or multiple
|
|
characters, e.g.\ \code{'\e r\e n'} for MS-DOS and MS Windows.
|
|
\end{datadesc}
|