From 1a3a3b8bb61de22e39de524c930560f0e376e1eb Mon Sep 17 00:00:00 2001 From: Antoine Pitrou Date: Tue, 15 Jun 2010 17:31:05 +0000 Subject: Merged revisions 82000-82001 via svnmerge from svn+ssh://pythondev@svn.python.org/python/branches/py3k ........ r82000 | antoine.pitrou | 2010-06-15 19:00:21 +0200 (mar., 15 juin 2010) | 3 lines Fixes to the PyFile_FromFd() doc, by Renato Cunha. ........ r82001 | antoine.pitrou | 2010-06-15 19:30:16 +0200 (mar., 15 juin 2010) | 3 lines Further refinements to the C file API. ........ --- Doc/c-api/file.rst | 29 +++++++++++++++++------------ 1 file changed, 17 insertions(+), 12 deletions(-) diff --git a/Doc/c-api/file.rst b/Doc/c-api/file.rst index 599717b..cc851e6 100644 --- a/Doc/c-api/file.rst +++ b/Doc/c-api/file.rst @@ -7,24 +7,29 @@ File Objects .. index:: object: file -Python's built-in file objects are implemented entirely on the :ctype:`FILE\*` -support from the C standard library. This is an implementation detail and may -change in future releases of Python. The ``PyFile_`` APIs are a wrapper over -the :mod:`io` module. +These APIs are a minimal emulation of the Python 2 C API for built-in file +objects, which used to rely on the buffered I/O (:ctype:`FILE\*`) support +from the C standard library. In Python 3, files and streams use the new +:mod:`io` module, which defines several layers over the low-level unbuffered +I/O of the operating system. The functions described below are +convenience C wrappers over these new APIs, and meant mostly for internal +error reporting in the interpreter; third-party code is advised to access +the :mod:`io` APIs instead. -.. cfunction:: PyFile_FromFd(int fd, char *name, char *mode, int buffering, char *encoding, char *newline, int closefd) +.. cfunction:: PyFile_FromFd(int fd, char *name, char *mode, int buffering, char *encoding, char *errors, char *newline, int closefd) - Create a new :ctype:`PyFileObject` from the file descriptor of an already - opened file *fd*. The arguments *name*, *encoding* and *newline* can be - *NULL* to use the defaults; *buffering* can be *-1* to use the default. - Return *NULL* on failure. + Create a Python file object from the file descriptor of an already + opened file *fd*. The arguments *name*, *encoding*, *errors* and *newline* + can be *NULL* to use the defaults; *buffering* can be *-1* to use the + default. Return *NULL* on failure. For a more comprehensive description of + the arguments, please refer to the :func:`io.open` function documentation. .. warning:: - Take care when you are mixing streams and descriptors! For more - information, see `the GNU C Library docs - `_. + Since Python streams have their own buffering layer, mixing them with + OS-level file descriptors can produce various issues (such as unexpected + ordering of data). .. cfunction:: int PyObject_AsFileDescriptor(PyObject *p) -- cgit v0.12