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.
........

1 files changed, 10 insertions, 6 deletions

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 @@ process and user.
 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 @@ process will then be assigned 3, 4, 5, and so forth.  The name "file descriptor"
 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 @@ by file descriptors.
    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 @@ by file descriptors.
    .. 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()