blob: 540767badfe4ecde08014d01542729449f8b7975 [file] [log] [blame]
Fred Drake295da241998-08-10 19:42:37 +00001\section{\module{posix} ---
Fred Drakef6863c11999-03-02 16:37:17 +00002 The most common \POSIX{} system calls}
Fred Drakeb91e9341998-07-23 17:59:49 +00003
Fred Drakef6863c11999-03-02 16:37:17 +00004\declaremodule{builtin}{posix}
Fred Drakea54a8871999-03-02 17:03:42 +00005 \platform{Unix}
Fred Drakebb3b0021999-01-11 18:36:23 +00006\modulesynopsis{The most common \POSIX{} system calls (normally used
Fred Drakeb2160601999-07-01 13:53:32 +00007 via module \refmodule{os}).}
Fred Drakeb91e9341998-07-23 17:59:49 +00008
Guido van Rossum5fdeeea1994-01-02 01:22:07 +00009
10This module provides access to operating system functionality that is
Fred Drake68a8c691999-02-01 20:23:02 +000011standardized by the C Standard and the \POSIX{} standard (a thinly
Fred Drake75aae9a1998-03-11 05:29:58 +000012disguised \UNIX{} interface).
Guido van Rossum470be141995-03-17 16:07:09 +000013
14\strong{Do not import this module directly.} Instead, import the
Fred Drake215fe2f1999-02-02 19:02:35 +000015module \refmodule{os}, which provides a \emph{portable} version of this
Fred Drake2799f9d1999-04-21 18:33:47 +000016interface. On \UNIX{}, the \refmodule{os} module provides a superset of
Fred Drake75aae9a1998-03-11 05:29:58 +000017the \module{posix} interface. On non-\UNIX{} operating systems the
18\module{posix} module is not available, but a subset is always
Fred Drake2799f9d1999-04-21 18:33:47 +000019available through the \refmodule{os} interface. Once \refmodule{os} is
Fred Drake75aae9a1998-03-11 05:29:58 +000020imported, there is \emph{no} performance penalty in using it instead
Fred Drake2799f9d1999-04-21 18:33:47 +000021of \module{posix}. In addition, \refmodule{os}\refstmodindex{os}
Fred Drakebb3b0021999-01-11 18:36:23 +000022provides some additional functionality, such as automatically calling
23\function{putenv()} when an entry in \code{os.environ} is changed.
Guido van Rossum470be141995-03-17 16:07:09 +000024
Guido van Rossum282290f1997-08-27 14:54:25 +000025The descriptions below are very terse; refer to the corresponding
Fred Drake65b32f71998-02-09 20:27:12 +000026\UNIX{} manual (or \POSIX{} documentation) entry for more information.
Guido van Rossum282290f1997-08-27 14:54:25 +000027Arguments called \var{path} refer to a pathname given as a string.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000028
Barry Warsaweef2cd11998-07-23 19:50:09 +000029Errors are reported as exceptions; the usual exceptions are given for
30type errors, while errors reported by the system calls raise
31\exception{error} (a synonym for the standard exception
Fred Drakebb3b0021999-01-11 18:36:23 +000032\exception{OSError}), described below.
33
Fred Drake215fe2f1999-02-02 19:02:35 +000034
Fred Drakebb3b0021999-01-11 18:36:23 +000035\subsection{Large File Support \label{posix-large-files}}
Fred Drake215fe2f1999-02-02 19:02:35 +000036\sectionauthor{Steve Clift}{clift@mail.anacapa.net}
Fred Drakebb3b0021999-01-11 18:36:23 +000037\index{large files}
38\index{file!large files}
39
Fred Drakebb3b0021999-01-11 18:36:23 +000040
41Several operating systems (including AIX, HPUX, Irix and Solaris)
Fred Drake68a8c691999-02-01 20:23:02 +000042provide support for files that are larger than 2 Gb from a C
Fred Drakebb3b0021999-01-11 18:36:23 +000043programming model where \ctype{int} and \ctype{long} are 32-bit
44values. This is typically accomplished by defining the relevant size
45and offset types as 64-bit values. Such files are sometimes referred
46to as \dfn{large files}.
47
48Large file support is enabled in Python when the size of an
49\ctype{off_t} is larger than a \ctype{long} and the \ctype{long long}
50type is available and is at least as large as an \ctype{off_t}. Python
51longs are then used to represent file sizes, offsets and other values
52that can exceed the range of a Python int. It may be necessary to
53configure and compile Python with certain compiler flags to enable
54this mode. For example, it is enabled by default with recent versions
55of Irix, but with Solaris 2.6 and 2.7 you need to do something like:
56
57\begin{verbatim}
Fred Drake82f355a1999-05-26 13:03:34 +000058CFLAGS="`getconf LFS_CFLAGS`" OPT="-g -O2 $CFLAGS" \
Fred Drakebb3b0021999-01-11 18:36:23 +000059 configure
60\end{verbatim} % $ <-- bow to font-lock
61
62
Fred Drake215fe2f1999-02-02 19:02:35 +000063\subsection{Module Contents \label{posix-contents}}
64
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000065
Fred Drake68a8c691999-02-01 20:23:02 +000066Module \module{posix} defines the following data item:
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000067
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000068\begin{datadesc}{environ}
Fred Drake68a8c691999-02-01 20:23:02 +000069A dictionary representing the string environment at the time the
70interpreter was started. For example, \code{environ['HOME']} is the
Fred Drake2799f9d1999-04-21 18:33:47 +000071pathname of your home directory, equivalent to
72\code{getenv("HOME")} in C.
Guido van Rossum9c43c591997-08-08 21:05:09 +000073
Guido van Rossum470be141995-03-17 16:07:09 +000074Modifying this dictionary does not affect the string environment
Fred Drake75aae9a1998-03-11 05:29:58 +000075passed on by \function{execv()}, \function{popen()} or
76\function{system()}; if you need to change the environment, pass
77\code{environ} to \function{execve()} or add variable assignments and
78export statements to the command string for \function{system()} or
79\function{popen()}.
Guido van Rossum9c43c591997-08-08 21:05:09 +000080
Fred Drake215fe2f1999-02-02 19:02:35 +000081\strong{Note:} The \refmodule{os} module provides an alternate
Fred Drake68a8c691999-02-01 20:23:02 +000082implementation of \code{environ} which updates the environment on
83modification. Note also that updating \code{os.environ} will render
Fred Drake215fe2f1999-02-02 19:02:35 +000084this dictionary obsolete. Use of the \refmodule{os} for this is
Fred Drake68a8c691999-02-01 20:23:02 +000085recommended over direct access to the \module{posix} module.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000086\end{datadesc}
87
Fred Drake68a8c691999-02-01 20:23:02 +000088Additional contents of this module should only be accessed via the
Fred Drake215fe2f1999-02-02 19:02:35 +000089\refmodule{os} module; refer to the documentation for that module for
Fred Drake68a8c691999-02-01 20:23:02 +000090further information.