364 lines
12 KiB
TeX
364 lines
12 KiB
TeX
\section{Built-in Module \sectcode{posix}}
|
|
\bimodindex{posix}
|
|
|
|
This module provides access to operating system functionality that is
|
|
standardized by the C Standard and the POSIX standard (a thinly disguised
|
|
\UNIX{} interface).
|
|
|
|
\strong{Do not import this module directly.} Instead, import the
|
|
module \code{os}, which provides a \emph{portable} version of this
|
|
interface. On \UNIX{}, the \code{os} module provides a superset of
|
|
the \code{posix} interface. On non-\UNIX{} operating systems the
|
|
\code{posix} module is not available, but a subset is always available
|
|
through the \code{os} interface. Once \code{os} is imported, there is
|
|
\emph{no} performance penalty in using it instead of
|
|
\code{posix}.
|
|
\stmodindex{os}
|
|
|
|
The descriptions below are very terse; refer to the
|
|
corresponding \UNIX{} manual entry for more information. Arguments
|
|
called \var{path} refer to a pathname given as a string.
|
|
|
|
Errors are reported as exceptions; the usual exceptions are given
|
|
for type errors, while errors reported by the system calls raise
|
|
\code{posix.error}, described below.
|
|
|
|
Module \code{posix} defines the following data items:
|
|
|
|
\renewcommand{\indexsubitem}{(data in module posix)}
|
|
\begin{datadesc}{environ}
|
|
A dictionary representing the string environment at the time
|
|
the interpreter was started.
|
|
For example,
|
|
\code{posix.environ['HOME']}
|
|
is the pathname of your home directory, equivalent to
|
|
\code{getenv("HOME")}
|
|
in C.
|
|
Modifying this dictionary does not affect the string environment
|
|
passed on by \code{execv()}, \code{popen()} or \code{system()}; if you
|
|
need to change the environment, pass \code{environ} to \code{execve()}
|
|
or add variable assignments and export statements to the command
|
|
string for \code{system()} or \code{popen()}.%
|
|
\footnote{The problem with automatically passing on \code{environ} is
|
|
that there is no portable way of changing the environment.}
|
|
\end{datadesc}
|
|
|
|
\renewcommand{\indexsubitem}{(exception in module posix)}
|
|
\begin{excdesc}{error}
|
|
This exception is raised when a POSIX function returns a
|
|
POSIX-related error (e.g., not for illegal argument types). Its
|
|
string value is \code{'posix.error'}. The accompanying value is a
|
|
pair containing the numeric error code from \code{errno} and the
|
|
corresponding string, as would be printed by the C function
|
|
\code{perror()}.
|
|
\end{excdesc}
|
|
|
|
It defines the following functions and constants:
|
|
|
|
\renewcommand{\indexsubitem}{(in module posix)}
|
|
\begin{funcdesc}{chdir}{path}
|
|
Change the current working directory to \var{path}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{chmod}{path\, mode}
|
|
Change the mode of \var{path} to the numeric \var{mode}.
|
|
\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}.
|
|
(Not on MS-DOS.)
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{close}{fd}
|
|
Close file descriptor \var{fd}.
|
|
|
|
Note: this function is intended for low-level I/O and must be applied
|
|
to a file descriptor as returned by \code{posix.open()} or
|
|
\code{posix.pipe()}. To close a ``file object'' returned by the
|
|
built-in function \code{open} or by \code{posix.popen} or
|
|
\code{posix.fdopen}, use its \code{close()} method.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{dup}{fd}
|
|
Return a duplicate of file descriptor \var{fd}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{dup2}{fd\, fd2}
|
|
Duplicate file descriptor \var{fd} to \var{fd2}, closing the latter
|
|
first if necessary. Return \code{None}.
|
|
\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.
|
|
(Not on MS-DOS.)
|
|
\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.
|
|
(Not on MS-DOS.)
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{_exit}{n}
|
|
Exit to the system with status \var{n}, without calling cleanup
|
|
handlers, flushing stdio buffers, etc.
|
|
(Not on MS-DOS.)
|
|
|
|
Note: the standard way to exit is \code{sys.exit(\var{n})}.
|
|
\code{posix._exit()} should normally only be used in the child process
|
|
after a \code{fork()}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{fdopen}{fd\optional{\, mode\optional{\, bufsize}}}
|
|
Return an open file object connected to the file descriptor \var{fd}.
|
|
The \var{mode} and \var{bufsize} arguments have the same meaning as
|
|
the corresponding arguments to the built-in \code{open()} function.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{fork}{}
|
|
Fork a child process. Return 0 in the child, the child's process id
|
|
in the parent.
|
|
(Not on MS-DOS.)
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{fstat}{fd}
|
|
Return status for file descriptor \var{fd}, like \code{stat()}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{getcwd}{}
|
|
Return a string representing the current working directory.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{getegid}{}
|
|
Return the current process's effective group id.
|
|
(Not on MS-DOS.)
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{geteuid}{}
|
|
Return the current process's effective user id.
|
|
(Not on MS-DOS.)
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{getgid}{}
|
|
Return the current process's group id.
|
|
(Not on MS-DOS.)
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{getpid}{}
|
|
Return the current process id.
|
|
(Not on MS-DOS.)
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{getppid}{}
|
|
Return the parent's process id.
|
|
(Not on MS-DOS.)
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{getuid}{}
|
|
Return the current process's user id.
|
|
(Not on MS-DOS.)
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{kill}{pid\, sig}
|
|
Kill the process \var{pid} with signal \var{sig}.
|
|
(Not on MS-DOS.)
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{link}{src\, dst}
|
|
Create a hard link pointing to \var{src} named \var{dst}.
|
|
(Not on MS-DOS.)
|
|
\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 includes the special entries
|
|
\code{'.'} and \code{'..'} if they are present in the directory.
|
|
\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}: 0 to set the position relative to
|
|
the beginning of the file; 1 to set it relative to the current
|
|
position; 2 to set it relative to the end of the file.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{lstat}{path}
|
|
Like \code{stat()}, but do not follow symbolic links. (On systems
|
|
without symbolic links, this is identical to \code{posix.stat}.)
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{mkdir}{path\, mode}
|
|
Create a directory named \var{path} with numeric mode \var{mode}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{nice}{increment}
|
|
Add \var{incr} to the process' ``niceness''. Return the new niceness.
|
|
(Not on MS-DOS.)
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{open}{file\, flags\, mode}
|
|
Open the file \var{file} and set various flags according to
|
|
\var{flags} and possibly its mode according to \var{mode}.
|
|
Return the file descriptor for the newly opened file.
|
|
|
|
Note: this function is intended for low-level I/O. For normal usage,
|
|
use the built-in function \code{open}, which returns a ``file object''
|
|
with \code{read()} and \code{write()} methods (and many more).
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{pipe}{}
|
|
Create a pipe. Return a pair of file descriptors \code{(r, w)}
|
|
usable for reading and writing, respectively.
|
|
(Not on MS-DOS.)
|
|
\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 \code{open()} function.
|
|
(Not on MS-DOS.)
|
|
\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.
|
|
|
|
Note: this function is intended for low-level I/O and must be applied
|
|
to a file descriptor as returned by \code{posix.open()} or
|
|
\code{posix.pipe()}. To read a ``file object'' returned by the
|
|
built-in function \code{open} or by \code{posix.popen} or
|
|
\code{posix.fdopen}, or \code{sys.stdin}, use its
|
|
\code{read()} or \code{readline()} methods.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{readlink}{path}
|
|
Return a string representing the path to which the symbolic link
|
|
points. (On systems without symbolic links, this always raises
|
|
\code{posix.error}.)
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{rename}{src\, dst}
|
|
Rename the file or directory \var{src} to \var{dst}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{rmdir}{path}
|
|
Remove the directory \var{path}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{setgid}{gid}
|
|
Set the current process's group id.
|
|
(Not on MS-DOS.)
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{setuid}{uid}
|
|
Set the current process's user id.
|
|
(Not on MS-DOS.)
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{stat}{path}
|
|
Perform a {\em 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 {\em 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-DOS, some items are filled with dummy values.)
|
|
|
|
Note: The standard module \code{stat} defines functions and constants
|
|
that are useful for extracting information from a stat structure.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{symlink}{src\, dst}
|
|
Create a symbolic link pointing to \var{src} named \var{dst}. (On
|
|
systems without symbolic links, this always raises
|
|
\code{posix.error}.)
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{system}{command}
|
|
Execute the command (a string) in a subshell. This is implemented by
|
|
calling the Standard C function \code{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 as returned by Standard C
|
|
\code{system()}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{times}{}
|
|
Return a 4-tuple of floating point numbers indicating accumulated CPU
|
|
times, in seconds. The items are: user time, system time, children's
|
|
user time, and children's system time, in that order. See the \UNIX{}
|
|
manual page {\it times}(2). (Not on MS-DOS.)
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{umask}{mask}
|
|
Set the current numeric umask and returns the previous umask.
|
|
(Not on MS-DOS.)
|
|
\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 \code{socket.gethostname()}. (Not on MS-DOS, nor on older
|
|
\UNIX{} systems.)
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{unlink}{path}
|
|
Unlink \var{path}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{utime}{path\, \(atime\, mtime\)}
|
|
Set the access and modified time of the file to the given values.
|
|
(The second argument is a tuple of two items.)
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{wait}{}
|
|
Wait for completion of a child process, and return a tuple containing
|
|
its pid and exit status indication (encoded as by \UNIX{}).
|
|
(Not on MS-DOS.)
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{waitpid}{pid\, options}
|
|
Wait for completion of a child process given by proces id, and return
|
|
a tuple containing its pid and exit status indication (encoded as by
|
|
\UNIX{}). The semantics of the call are affected by the value of
|
|
the integer options, which should be 0 for normal operation. (If the
|
|
system does not support \code{waitpid()}, this always raises
|
|
\code{posix.error}. Not on MS-DOS.)
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{write}{fd\, str}
|
|
Write the string \var{str} to file descriptor \var{fd}.
|
|
Return the number of bytes actually written.
|
|
|
|
Note: this function is intended for low-level I/O and must be applied
|
|
to a file descriptor as returned by \code{posix.open()} or
|
|
\code{posix.pipe()}. To write a ``file object'' returned by the
|
|
built-in function \code{open} or by \code{posix.popen} or
|
|
\code{posix.fdopen}, or \code{sys.stdout} or \code{sys.stderr}, use
|
|
its \code{write()} method.
|
|
\end{funcdesc}
|
|
|
|
\begin{datadesc}{WNOHANG}
|
|
The option for \code{waitpid()} to avoid hanging if no child process
|
|
status is available immediately.
|
|
\end{datadesc}
|