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