Doc/lib/libmsvcrt.tex

   1 \section{\module{msvcrt} --
   2          Useful routines from the MS VC++ runtime}
   3
   4 \declaremodule{builtin}{msvcrt}
   5   \platform{Windows}
   6 \modulesynopsis{Miscellaneous useful routines from the MS VC++ runtime.}
   7 \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
   8
   9
  10 These functions provide access to some useful capabilities on Windows
  11 platforms.  Some higher-level modules use these functions to build the
  12 Windows implementations of their services.  For example, the
  13 \refmodule{getpass} module uses this in the implementation of the
  14 \function{getpass()} function.
  15
  16 Further documentation on these functions can be found in the Platform
  17 API documentation.
  18
  19
  20 \subsection{File Operations \label{msvcrt-files}}
  21
  22 \begin{funcdesc}{locking}{fd, mode, nbytes}
  23   Lock part of a file based on file descriptor \var{fd} from the C
  24   runtime.  Raises \exception{IOError} on failure.  The locked region
  25   of the file extends from the current file position for \var{nbytes}
  26   bytes, and may continue beyond the end of the file.  \var{mode} must
  27   be one of the \constant{LK_\var{*}} constants listed below.
  28   Multiple regions in a file may be locked at the same time, but may
  29   not overlap.  Adjacent regions are not merged; they must be unlocked
  30   individually.
  31 \end{funcdesc}
  32
  33 \begin{datadesc}{LK_LOCK}
  34 \dataline{LK_RLCK}
  35   Locks the specified bytes. If the bytes cannot be locked, the
  36   program immediately tries again after 1 second.  If, after 10
  37   attempts, the bytes cannot be locked, \exception{IOError} is
  38   raised.
  39 \end{datadesc}
  40
  41 \begin{datadesc}{LK_NBLCK}
  42 \dataline{LK_NBRLCK}
  43   Locks the specified bytes. If the bytes cannot be locked,
  44   \exception{IOError} is raised.
  45 \end{datadesc}
  46
  47 \begin{datadesc}{LK_UNLCK}
  48   Unlocks the specified bytes, which must have been previously locked.
  49 \end{datadesc}
  50
  51 \begin{funcdesc}{setmode}{fd, flags}
  52   Set the line-end translation mode for the file descriptor \var{fd}.
  53   To set it to text mode, \var{flags} should be \constant{os.O_TEXT};
  54   for binary, it should be \constant{os.O_BINARY}.
  55 \end{funcdesc}
  56
  57 \begin{funcdesc}{open_osfhandle}{handle, flags}
  58   Create a C runtime file descriptor from the file handle
  59   \var{handle}.  The \var{flags} parameter should be a bit-wise OR of
  60   \constant{os.O_APPEND}, \constant{os.O_RDONLY}, and
  61   \constant{os.O_TEXT}.  The returned file descriptor may be used as a
  62   parameter to \function{os.fdopen()} to create a file object.
  63 \end{funcdesc}
  64
  65 \begin{funcdesc}{get_osfhandle}{fd}
  66   Return the file handle for the file descriptor \var{fd}.  Raises
  67   \exception{IOError} if \var{fd} is not recognized.
  68 \end{funcdesc}
  69
  70
  71 \subsection{Console I/O \label{msvcrt-console}}
  72
  73 \begin{funcdesc}{kbhit}{}
  74   Return true if a keypress is waiting to be read.
  75 \end{funcdesc}
  76
  77 \begin{funcdesc}{getch}{}
  78   Read a keypress and return the resulting character.  Nothing is
  79   echoed to the console.  This call will block if a keypress is not
  80   already available, but will not wait for \kbd{Enter} to be pressed.
  81   If the pressed key was a special function key, this will return
  82   \code{'\e000'} or \code{'\e xe0'}; the next call will return the
  83   keycode.  The \kbd{Control-C} keypress cannot be read with this
  84   function.
  85 \end{funcdesc}
  86
  87 \begin{funcdesc}{getche}{}
  88   Similar to \function{getch()}, but the keypress will be echoed if it
  89   represents a printable character.
  90 \end{funcdesc}
  91
  92 \begin{funcdesc}{putch}{char}
  93   Print the character \var{char} to the console without buffering.
  94 \end{funcdesc}
  95
  96 \begin{funcdesc}{ungetch}{char}
  97   Cause the character \var{char} to be ``pushed back'' into the
  98   console buffer; it will be the next character read by
  99   \function{getch()} or \function{getche()}.
 100 \end{funcdesc}
 101
 102
 103 \subsection{Other Functions \label{msvcrt-other}}
 104
 105 \begin{funcdesc}{heapmin}{}
 106   Force the \cfunction{malloc()} heap to clean itself up and return
 107   unused blocks to the operating system.  This only works on Windows
 108   NT.  On failure, this raises \exception{IOError}.
 109 \end{funcdesc}