libmsvcrt.tex 3.86 KB
Newer Older
1
\section{\module{msvcrt} --
Fred Drake's avatar
Fred Drake committed
2
         Useful routines from the MS V\Cpp\ runtime}
3 4

\declaremodule{builtin}{msvcrt}
5
  \platform{Windows}
Fred Drake's avatar
Fred Drake committed
6
\modulesynopsis{Miscellaneous useful routines from the MS V\Cpp\ runtime.}
7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22
\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}
23 24 25 26 27 28 29 30
  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.
31 32
\end{funcdesc}

33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50
\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}

51 52
\begin{funcdesc}{setmode}{fd, flags}
  Set the line-end translation mode for the file descriptor \var{fd}.
53 54
  To set it to text mode, \var{flags} should be \constant{os.O_TEXT};
  for binary, it should be \constant{os.O_BINARY}.
55 56 57 58 59
\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
60 61 62
  \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.
63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109
\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}