Added chapter on Windows modules, including msvcrt and winsound.

Doc/lib/libmsvcrt.tex

@@ -0,0 +1,84 @@
+\section{\module{msvcrt} --
+         Useful routines from the MS VC++ runtime}
+
+\declaremodule{builtin}{msvcrt}
+\modulesynopsis{Miscellaneous useful routines from the MS VC++ runtime.}
+\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
+
+
+These functions provide access to some useful capabilities on Windows
+platforms.  Some higher-level modules use these functions to build the 
+Windows implementations of their services.  For example, the
+\refmodule{getpass} module uses this in the implementation of the
+\function{getpass()} function.
+
+Further documentation on these functions can be found in the Platform
+API documentation.
+
+
+\subsection{File Operations \label{msvcrt-files}}
+
+\begin{funcdesc}{locking}{fd, mode, nbytes}
+  Lock part of a file based on a file descriptor from the C runtime.
+  Raises \exception{IOError} on failure.
+\end{funcdesc}
+
+\begin{funcdesc}{setmode}{fd, flags}
+  Set the line-end translation mode for the file descriptor \var{fd}.
+  To set it to text mode, \var{flags} should be \constant{_O_TEXT};
+  for binary, it should be \constant{_O_BINARY}.
+\end{funcdesc}
+
+\begin{funcdesc}{open_osfhandle}{handle, flags}
+  Create a C runtime file descriptor from the file handle
+  \var{handle}.  The \var{flags} parameter should be a bit-wise OR of
+  \constant{_O_APPEND}, \constant{_O_RDONLY}, and \constant{_O_TEXT}.
+  The returned file descriptor may be used as a parameter to
+  \function{os.fdopen()} to create a file object.
+\end{funcdesc}
+
+\begin{funcdesc}{get_osfhandle}{fd}
+  Return the file handle for the file descriptor \var{fd}.  Raises
+  \exception{IOError} if \var{fd} is not recognized.
+\end{funcdesc}
+
+
+\subsection{Console I/O \label{msvcrt-console}}
+
+\begin{funcdesc}{kbhit}{}
+  Return true if a keypress is waiting to be read.
+\end{funcdesc}
+
+\begin{funcdesc}{getch}{}
+  Read a keypress and return the resulting character.  Nothing is
+  echoed to the console.  This call will block if a keypress is not
+  already available, but will not wait for \kbd{Enter} to be pressed.
+  If the pressed key was a special function key, this will return
+  \code{'\e000'} or \code{'\e xe0'}; the next call will return the
+  keycode.  The \kbd{Control-C} keypress cannot be read with this
+  function.
+\end{funcdesc}
+
+\begin{funcdesc}{getche}{}
+  Similar to \function{getch()}, but the keypress will be echoed if it 
+  represents a printable character.
+\end{funcdesc}
+
+\begin{funcdesc}{putch}{char}
+  Print the character \var{char} to the console without buffering.
+\end{funcdesc}
+
+\begin{funcdesc}{ungetch}{char}
+  Cause the character \var{char} to be ``pushed back'' into the
+  console buffer; it will be the next character read by
+  \function{getch()} or \function{getche()}.
+\end{funcdesc}
+
+
+\subsection{Other Functions \label{msvcrt-other}}
+
+\begin{funcdesc}{heapmin}{}
+  Force the \cfunction{malloc()} heap to clean itself up and return
+  unused blocks to the operating system.  This only works on Windows
+  NT.  On failure, this raises \exception{IOError}.
+\end{funcdesc}