Merged revisions 84827-84829 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/branches/py3k
........
r84827 | antoine.pitrou | 2010-09-15 11:58:26 +0200 (mer., 15 sept. 2010) | 3 lines
Add a glossary entry for file objects.
........
r84828 | antoine.pitrou | 2010-09-15 12:08:31 +0200 (mer., 15 sept. 2010) | 3 lines
Update file-related information in the FAQ.
........
r84829 | antoine.pitrou | 2010-09-15 13:11:28 +0200 (mer., 15 sept. 2010) | 3 lines
Add cross-references to the glossary entry for file objects.
........
diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index 80955af..2fb8cd6 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -401,7 +401,7 @@
File Object Creation
--------------------
-These functions create new file objects. (See also :func:`open`.)
+These functions create new :term:`file objects <file object>`. (See also :func:`open`.)
.. function:: fdopen(fd[, mode[, bufsize]])
@@ -436,6 +436,10 @@
is slightly deceptive; on Unix platforms, sockets and pipes are also referenced
by file descriptors.
+The :meth:`~file.fileno` method can be used to obtain the file descriptor
+associated with a :term:`file object` when required. Note that using the file
+descriptor directly will bypass the file object methods, ignoring aspects such
+as internal buffering of data.
.. function:: close(fd)
@@ -550,9 +554,9 @@
Force write of file with filedescriptor *fd* to disk. On Unix, this calls the
native :cfunc:`fsync` function; on Windows, the MS :cfunc:`_commit` function.
- If you're starting with a Python file object *f*, first do ``f.flush()``, and
- then do ``os.fsync(f.fileno())``, to ensure that all internal buffers associated
- with *f* are written to disk.
+ If you're starting with a buffered Python :term:`file object` *f*, first do
+ ``f.flush()``, and then do ``os.fsync(f.fileno())``, to ensure that all internal
+ buffers associated with *f* are written to disk.
Availability: Unix, and Windows.
@@ -609,9 +613,9 @@
.. note::
This function is intended for low-level I/O. For normal usage, use the
- built-in function :func:`open`, which returns a "file object" with
+ built-in function :func:`open`, which returns a :term:`file object` with
:meth:`~file.read` and :meth:`~file.wprite` methods (and many more). To
- wrap a file descriptor in a "file object", use :func:`fdopen`.
+ wrap a file descriptor in a file object, use :func:`fdopen`.
.. function:: openpty()