\section{\module{msvcrt} --
         Useful routines from the MS V\Cpp\ runtime}

\declaremodule{builtin}{msvcrt}
  \platform{Windows}
\modulesynopsis{Miscellaneous useful routines from the MS V\Cpp\ runtime.}
\sectionauthor{Fred L. Drake, Jr.}{[email protected]}


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 file descriptor \var{fd} from the C
  runtime.  Raises \exception{IOError} on failure.  The locked region
  of the file extends from the current file position for \var{nbytes}
  bytes, and may continue beyond the end of the file.  \var{mode} must
  be one of the \constant{LK_\var{*}} constants listed below.
  Multiple regions in a file may be locked at the same time, but may
  not overlap.  Adjacent regions are not merged; they must be unlocked
  individually.
\end{funcdesc}

\begin{datadesc}{LK_LOCK}
\dataline{LK_RLCK}
  Locks the specified bytes. If the bytes cannot be locked, the
  program immediately tries again after 1 second.  If, after 10
  attempts, the bytes cannot be locked, \exception{IOError} is
  raised.
\end{datadesc}

\begin{datadesc}{LK_NBLCK}
\dataline{LK_NBRLCK}
  Locks the specified bytes. If the bytes cannot be locked,
  \exception{IOError} is raised.
\end{datadesc}

\begin{datadesc}{LK_UNLCK}
  Unlocks the specified bytes, which must have been previously locked. 
\end{datadesc}

\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{os.O_TEXT};
  for binary, it should be \constant{os.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{os.O_APPEND}, \constant{os.O_RDONLY}, and
  \constant{os.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}