cpython/Doc/library/posix.rst

93 lines
3.5 KiB
ReStructuredText
Raw Normal View History

2007-08-15 11:28:22 -03:00
:mod:`posix` --- The most common POSIX system calls
===================================================
.. module:: posix
:platform: Unix
:synopsis: The most common POSIX system calls (normally used via module os).
--------------
2007-08-15 11:28:22 -03:00
This module provides access to operating system functionality that is
standardized by the C Standard and the POSIX standard (a thinly disguised Unix
interface).
.. index:: pair: module; os
2007-08-15 11:28:22 -03:00
**Do not import this module directly.** Instead, import the module :mod:`os`,
which provides a *portable* version of this interface. On Unix, the :mod:`os`
module provides a superset of the :mod:`posix` interface. On non-Unix operating
systems the :mod:`posix` module is not available, but a subset is always
available through the :mod:`os` interface. Once :mod:`os` is imported, there is
*no* performance penalty in using it instead of :mod:`posix`. In addition,
:mod:`os` provides some additional functionality, such as automatically calling
:func:`~os.putenv` when an entry in ``os.environ`` is changed.
2007-08-15 11:28:22 -03:00
Errors are reported as exceptions; the usual exceptions are given for type
Merged revisions 59921-59932 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r59923 | raymond.hettinger | 2008-01-11 19:04:55 +0100 (Fri, 11 Jan 2008) | 1 line Speed-up and simplify code urlparse's result objects. ........ r59924 | andrew.kuchling | 2008-01-11 20:33:24 +0100 (Fri, 11 Jan 2008) | 1 line Bug #1790: update link; remove outdated paragraph ........ r59925 | thomas.heller | 2008-01-11 20:34:06 +0100 (Fri, 11 Jan 2008) | 5 lines Raise an error instead of crashing with a segfault when a NULL function pointer is called. Will backport to release25-maint. ........ r59927 | thomas.heller | 2008-01-11 21:29:19 +0100 (Fri, 11 Jan 2008) | 4 lines Fix a potential 'SystemError: NULL result without error'. NULL may be a valid return value from PyLong_AsVoidPtr. Will backport to release25-maint. ........ r59928 | raymond.hettinger | 2008-01-12 00:25:18 +0100 (Sat, 12 Jan 2008) | 1 line Update the opcode docs for STORE_MAP and BUILD_MAP ........ r59929 | mark.dickinson | 2008-01-12 02:56:00 +0100 (Sat, 12 Jan 2008) | 4 lines Issue 1780: Allow leading and trailing whitespace in Decimal constructor, when constructing from a string. Disallow trailing newlines in Context.create_decimal. ........ r59930 | georg.brandl | 2008-01-12 11:53:29 +0100 (Sat, 12 Jan 2008) | 3 lines Move OSError docs to exceptions doc, remove obsolete descriptions from os docs, rework posix docs. ........ r59931 | georg.brandl | 2008-01-12 14:47:57 +0100 (Sat, 12 Jan 2008) | 3 lines Patch #1700288: Method cache optimization, by Armin Rigo, ported to 2.6 by Kevin Jacobs. ........ r59932 | georg.brandl | 2008-01-12 17:11:09 +0100 (Sat, 12 Jan 2008) | 2 lines Fix editing glitch. ........
2008-01-12 15:39:10 -04:00
errors, while errors reported by the system calls raise :exc:`OSError`.
2007-08-15 11:28:22 -03:00
.. _posix-large-files:
Large File Support
------------------
.. index::
single: large files
single: file; large files
.. sectionauthor:: Steve Clift <clift@mail.anacapa.net>
Several operating systems (including AIX and Solaris) provide
support for files that are larger than 2 GiB from a C programming model where
:c:expr:`int` and :c:expr:`long` are 32-bit values. This is typically accomplished
2007-08-15 11:28:22 -03:00
by defining the relevant size and offset types as 64-bit values. Such files are
sometimes referred to as :dfn:`large files`.
Large file support is enabled in Python when the size of an :c:type:`off_t` is
larger than a :c:expr:`long` and the :c:expr:`long long` is at least as large
as an :c:type:`off_t`.
2007-08-15 11:28:22 -03:00
It may be necessary to configure and compile Python with certain compiler flags
to enable this mode. For example, with Solaris 2.6 and 2.7 you need to do
something like::
2007-08-15 11:28:22 -03:00
CFLAGS="`getconf LFS_CFLAGS`" OPT="-g -O2 $CFLAGS" \
./configure
On large-file-capable Linux systems, this might work::
2007-08-15 11:28:22 -03:00
CFLAGS='-D_LARGEFILE64_SOURCE -D_FILE_OFFSET_BITS=64' OPT="-g -O2 $CFLAGS" \
./configure
.. _posix-contents:
Merged revisions 59921-59932 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r59923 | raymond.hettinger | 2008-01-11 19:04:55 +0100 (Fri, 11 Jan 2008) | 1 line Speed-up and simplify code urlparse's result objects. ........ r59924 | andrew.kuchling | 2008-01-11 20:33:24 +0100 (Fri, 11 Jan 2008) | 1 line Bug #1790: update link; remove outdated paragraph ........ r59925 | thomas.heller | 2008-01-11 20:34:06 +0100 (Fri, 11 Jan 2008) | 5 lines Raise an error instead of crashing with a segfault when a NULL function pointer is called. Will backport to release25-maint. ........ r59927 | thomas.heller | 2008-01-11 21:29:19 +0100 (Fri, 11 Jan 2008) | 4 lines Fix a potential 'SystemError: NULL result without error'. NULL may be a valid return value from PyLong_AsVoidPtr. Will backport to release25-maint. ........ r59928 | raymond.hettinger | 2008-01-12 00:25:18 +0100 (Sat, 12 Jan 2008) | 1 line Update the opcode docs for STORE_MAP and BUILD_MAP ........ r59929 | mark.dickinson | 2008-01-12 02:56:00 +0100 (Sat, 12 Jan 2008) | 4 lines Issue 1780: Allow leading and trailing whitespace in Decimal constructor, when constructing from a string. Disallow trailing newlines in Context.create_decimal. ........ r59930 | georg.brandl | 2008-01-12 11:53:29 +0100 (Sat, 12 Jan 2008) | 3 lines Move OSError docs to exceptions doc, remove obsolete descriptions from os docs, rework posix docs. ........ r59931 | georg.brandl | 2008-01-12 14:47:57 +0100 (Sat, 12 Jan 2008) | 3 lines Patch #1700288: Method cache optimization, by Armin Rigo, ported to 2.6 by Kevin Jacobs. ........ r59932 | georg.brandl | 2008-01-12 17:11:09 +0100 (Sat, 12 Jan 2008) | 2 lines Fix editing glitch. ........
2008-01-12 15:39:10 -04:00
Notable Module Contents
-----------------------
2007-08-15 11:28:22 -03:00
Merged revisions 59921-59932 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r59923 | raymond.hettinger | 2008-01-11 19:04:55 +0100 (Fri, 11 Jan 2008) | 1 line Speed-up and simplify code urlparse's result objects. ........ r59924 | andrew.kuchling | 2008-01-11 20:33:24 +0100 (Fri, 11 Jan 2008) | 1 line Bug #1790: update link; remove outdated paragraph ........ r59925 | thomas.heller | 2008-01-11 20:34:06 +0100 (Fri, 11 Jan 2008) | 5 lines Raise an error instead of crashing with a segfault when a NULL function pointer is called. Will backport to release25-maint. ........ r59927 | thomas.heller | 2008-01-11 21:29:19 +0100 (Fri, 11 Jan 2008) | 4 lines Fix a potential 'SystemError: NULL result without error'. NULL may be a valid return value from PyLong_AsVoidPtr. Will backport to release25-maint. ........ r59928 | raymond.hettinger | 2008-01-12 00:25:18 +0100 (Sat, 12 Jan 2008) | 1 line Update the opcode docs for STORE_MAP and BUILD_MAP ........ r59929 | mark.dickinson | 2008-01-12 02:56:00 +0100 (Sat, 12 Jan 2008) | 4 lines Issue 1780: Allow leading and trailing whitespace in Decimal constructor, when constructing from a string. Disallow trailing newlines in Context.create_decimal. ........ r59930 | georg.brandl | 2008-01-12 11:53:29 +0100 (Sat, 12 Jan 2008) | 3 lines Move OSError docs to exceptions doc, remove obsolete descriptions from os docs, rework posix docs. ........ r59931 | georg.brandl | 2008-01-12 14:47:57 +0100 (Sat, 12 Jan 2008) | 3 lines Patch #1700288: Method cache optimization, by Armin Rigo, ported to 2.6 by Kevin Jacobs. ........ r59932 | georg.brandl | 2008-01-12 17:11:09 +0100 (Sat, 12 Jan 2008) | 2 lines Fix editing glitch. ........
2008-01-12 15:39:10 -04:00
In addition to many functions described in the :mod:`os` module documentation,
:mod:`posix` defines the following data item:
2007-08-15 11:28:22 -03:00
.. data:: environ
Merged revisions 59921-59932 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r59923 | raymond.hettinger | 2008-01-11 19:04:55 +0100 (Fri, 11 Jan 2008) | 1 line Speed-up and simplify code urlparse's result objects. ........ r59924 | andrew.kuchling | 2008-01-11 20:33:24 +0100 (Fri, 11 Jan 2008) | 1 line Bug #1790: update link; remove outdated paragraph ........ r59925 | thomas.heller | 2008-01-11 20:34:06 +0100 (Fri, 11 Jan 2008) | 5 lines Raise an error instead of crashing with a segfault when a NULL function pointer is called. Will backport to release25-maint. ........ r59927 | thomas.heller | 2008-01-11 21:29:19 +0100 (Fri, 11 Jan 2008) | 4 lines Fix a potential 'SystemError: NULL result without error'. NULL may be a valid return value from PyLong_AsVoidPtr. Will backport to release25-maint. ........ r59928 | raymond.hettinger | 2008-01-12 00:25:18 +0100 (Sat, 12 Jan 2008) | 1 line Update the opcode docs for STORE_MAP and BUILD_MAP ........ r59929 | mark.dickinson | 2008-01-12 02:56:00 +0100 (Sat, 12 Jan 2008) | 4 lines Issue 1780: Allow leading and trailing whitespace in Decimal constructor, when constructing from a string. Disallow trailing newlines in Context.create_decimal. ........ r59930 | georg.brandl | 2008-01-12 11:53:29 +0100 (Sat, 12 Jan 2008) | 3 lines Move OSError docs to exceptions doc, remove obsolete descriptions from os docs, rework posix docs. ........ r59931 | georg.brandl | 2008-01-12 14:47:57 +0100 (Sat, 12 Jan 2008) | 3 lines Patch #1700288: Method cache optimization, by Armin Rigo, ported to 2.6 by Kevin Jacobs. ........ r59932 | georg.brandl | 2008-01-12 17:11:09 +0100 (Sat, 12 Jan 2008) | 2 lines Fix editing glitch. ........
2008-01-12 15:39:10 -04:00
A dictionary representing the string environment at the time the interpreter
was started. Keys and values are bytes on Unix and str on Windows. For
example, ``environ[b'HOME']`` (``environ['HOME']`` on Windows) is the
pathname of your home directory, equivalent to ``getenv("HOME")`` in C.
2007-08-15 11:28:22 -03:00
Modifying this dictionary does not affect the string environment passed on by
:func:`~os.execv`, :func:`~os.popen` or :func:`~os.system`; if you need to
change the environment, pass ``environ`` to :func:`~os.execve` or add
variable assignments and export statements to the command string for
:func:`~os.system` or :func:`~os.popen`.
2007-08-15 11:28:22 -03:00
.. versionchanged:: 3.2
On Unix, keys and values are bytes.
2007-08-15 11:28:22 -03:00
.. note::
The :mod:`os` module provides an alternate implementation of ``environ``
which updates the environment on modification. Note also that updating
:data:`os.environ` will render this dictionary obsolete. Use of the
:mod:`os` module version of this is recommended over direct access to the
:mod:`posix` module.