[Python-Dev] Documentation patch for waiting method.

[Eric S. Raymond]

Index: libstdtypes.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libstdtypes.tex,v
retrieving revision 1.50
diff -u -r1.50 libstdtypes.tex
--- libstdtypes.tex	2001/01/17 01:18:00	1.50
+++ libstdtypes.tex	2001/01/25 16:46:40
@@ -1142,6 +1142,24 @@
   \UNIX{} versions support this operation).
 \end{methoddesc}
 
+\begin{methoddesc}[file]{waiting}{}
+  Return the number of bytes waiting to be read from this file object.
+  For regular files, this returns the size of the file in bytes minus
+  the current seek address, as would be returned by \method{tell()}; a
+  zero return can be used to detect EOF.  For streams such as FIFOs,
+  sockets, Unix ttys, and other Unix character devices, this method
+  returns the number of bytes currently buffered up and waiting to be
+  read.  Attempts to call this method on Unix block devices or
+  on directories will raise an error.
+	\footnote{The \method{waiting()} method uses
+  	\cfunction{fstat(2)} and \cfunction{lseek(2)} on plain files;
+  	these should be reliable on all of Unix, Windows, and MacOS.
+  	It uses the FIONREAD ioctl(2) call to query FIFOs, sockets,
+  	Unix ttys, and other POSIX character devices; FIFO and socket
+  	behavior should be consistent across all three platforms, but
+  	the results from querying other character devices may vary.}
+\end{methoddesc}
+
 \begin{methoddesc}[file]{write}{str}
   Write a string to the file.  There is no return value.  Note: Due to
   buffering, the string may not actually show up in the file until

-- 
		<a href="http://www.tuxedo.org/~esr/">Eric S. Raymond</a>

"To disarm the people... was the best and most effectual way to enslave them."
        -- George Mason, speech of June 14, 1788