Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | :mod:`posix` --- The most common POSIX system calls |
| 2 | =================================================== |
| 3 | |
| 4 | .. module:: posix |
| 5 | :platform: Unix |
| 6 | :synopsis: The most common POSIX system calls (normally used via module os). |
| 7 | |
| 8 | |
| 9 | This module provides access to operating system functionality that is |
| 10 | standardized by the C Standard and the POSIX standard (a thinly disguised Unix |
| 11 | interface). |
| 12 | |
| 13 | .. index:: module: os |
| 14 | |
| 15 | **Do not import this module directly.** Instead, import the module :mod:`os`, |
| 16 | which provides a *portable* version of this interface. On Unix, the :mod:`os` |
| 17 | module provides a superset of the :mod:`posix` interface. On non-Unix operating |
| 18 | systems the :mod:`posix` module is not available, but a subset is always |
| 19 | available through the :mod:`os` interface. Once :mod:`os` is imported, there is |
| 20 | *no* performance penalty in using it instead of :mod:`posix`. In addition, |
| 21 | :mod:`os` provides some additional functionality, such as automatically calling |
| 22 | :func:`putenv` when an entry in ``os.environ`` is changed. |
| 23 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 24 | Errors are reported as exceptions; the usual exceptions are given for type |
Christian Heimes | a62da1d | 2008-01-12 19:39:10 +0000 | [diff] [blame] | 25 | errors, while errors reported by the system calls raise :exc:`OSError`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 26 | |
| 27 | |
| 28 | .. _posix-large-files: |
| 29 | |
| 30 | Large File Support |
| 31 | ------------------ |
| 32 | |
| 33 | .. index:: |
| 34 | single: large files |
| 35 | single: file; large files |
| 36 | |
| 37 | .. sectionauthor:: Steve Clift <clift@mail.anacapa.net> |
| 38 | |
Christian Heimes | a62da1d | 2008-01-12 19:39:10 +0000 | [diff] [blame] | 39 | Several operating systems (including AIX, HP-UX, Irix and Solaris) provide |
Serhiy Storchaka | f8def28 | 2013-02-16 17:29:56 +0200 | [diff] [blame] | 40 | support for files that are larger than 2 GiB from a C programming model where |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 41 | :c:type:`int` and :c:type:`long` are 32-bit values. This is typically accomplished |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 42 | by defining the relevant size and offset types as 64-bit values. Such files are |
| 43 | sometimes referred to as :dfn:`large files`. |
| 44 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 45 | Large file support is enabled in Python when the size of an :c:type:`off_t` is |
| 46 | larger than a :c:type:`long` and the :c:type:`long long` type is available and is |
| 47 | at least as large as an :c:type:`off_t`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 48 | It may be necessary to configure and compile Python with certain compiler flags |
| 49 | to enable this mode. For example, it is enabled by default with recent versions |
| 50 | of Irix, but with Solaris 2.6 and 2.7 you need to do something like:: |
| 51 | |
| 52 | CFLAGS="`getconf LFS_CFLAGS`" OPT="-g -O2 $CFLAGS" \ |
| 53 | ./configure |
| 54 | |
Georg Brandl | 81ac1ce | 2007-08-31 17:17:17 +0000 | [diff] [blame] | 55 | On large-file-capable Linux systems, this might work:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 56 | |
| 57 | CFLAGS='-D_LARGEFILE64_SOURCE -D_FILE_OFFSET_BITS=64' OPT="-g -O2 $CFLAGS" \ |
| 58 | ./configure |
| 59 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 60 | |
| 61 | .. _posix-contents: |
| 62 | |
Christian Heimes | a62da1d | 2008-01-12 19:39:10 +0000 | [diff] [blame] | 63 | Notable Module Contents |
| 64 | ----------------------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 65 | |
Christian Heimes | a62da1d | 2008-01-12 19:39:10 +0000 | [diff] [blame] | 66 | In addition to many functions described in the :mod:`os` module documentation, |
| 67 | :mod:`posix` defines the following data item: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 68 | |
| 69 | .. data:: environ |
| 70 | |
Christian Heimes | a62da1d | 2008-01-12 19:39:10 +0000 | [diff] [blame] | 71 | A dictionary representing the string environment at the time the interpreter |
Victor Stinner | 84ae118 | 2010-05-06 22:05:07 +0000 | [diff] [blame] | 72 | was started. Keys and values are bytes on Unix and str on Windows. For |
| 73 | example, ``environ[b'HOME']`` (``environ['HOME']`` on Windows) is the |
| 74 | pathname of your home directory, equivalent to ``getenv("HOME")`` in C. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 75 | |
| 76 | Modifying this dictionary does not affect the string environment passed on by |
| 77 | :func:`execv`, :func:`popen` or :func:`system`; if you need to change the |
| 78 | environment, pass ``environ`` to :func:`execve` or add variable assignments and |
| 79 | export statements to the command string for :func:`system` or :func:`popen`. |
| 80 | |
Victor Stinner | 84ae118 | 2010-05-06 22:05:07 +0000 | [diff] [blame] | 81 | .. versionchanged:: 3.2 |
| 82 | On Unix, keys and values are bytes. |
| 83 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 84 | .. note:: |
| 85 | |
Victor Stinner | 84ae118 | 2010-05-06 22:05:07 +0000 | [diff] [blame] | 86 | The :mod:`os` module provides an alternate implementation of ``environ`` |
| 87 | which updates the environment on modification. Note also that updating |
| 88 | :data:`os.environ` will render this dictionary obsolete. Use of the |
| 89 | :mod:`os` module version of this is recommended over direct access to the |
| 90 | :mod:`posix` module. |