Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

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.
........
This commit is contained in:
Antoine Pitrou 2010-06-15 17:31:05 +00:00
parent 0dafd71c25
commit 1a3a3b8bb6
1 changed files with 17 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
Doc/c-api/file.rst
View File

@ -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
<http://www.gnu.org/software/libc/manual/html_node/Stream_002fDescriptor-Precautions.html#Stream_002fDescriptor-Precautions>`_.
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)