Doc/library/msvcrt.rst

   1
   2 :mod:`msvcrt` -- Useful routines from the MS VC++ runtime
   3 =========================================================
   4
   5 .. module:: msvcrt
   6    :platform: Windows
   7    :synopsis: Miscellaneous useful routines from the MS VC++ runtime.
   8 .. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
   9
  10
  11 These functions provide access to some useful capabilities on Windows platforms.
  12 Some higher-level modules use these functions to build the  Windows
  13 implementations of their services.  For example, the :mod:`getpass` module uses
  14 this in the implementation of the :func:`getpass` function.
  15
  16 Further documentation on these functions can be found in the Platform API
  17 documentation.
  18
  19 The module implements both the normal and wide char variants of the console I/O
  20 api. The normal API deals only with ASCII characters and is of limited use
  21 for internationalized applications. The wide char API should be used where
  22 ever possible
  23
  24 .. _msvcrt-files:
  25
  26 File Operations
  27 ---------------
  28
  29
  30 .. function:: locking(fd, mode, nbytes)
  31
  32    Lock part of a file based on file descriptor *fd* from the C runtime.  Raises
  33    :exc:`IOError` on failure.  The locked region of the file extends from the
  34    current file position for *nbytes* bytes, and may continue beyond the end of the
  35    file.  *mode* must be one of the :const:`LK_\*` constants listed below. Multiple
  36    regions in a file may be locked at the same time, but may not overlap.  Adjacent
  37    regions are not merged; they must be unlocked individually.
  38
  39
  40 .. data:: LK_LOCK
  41           LK_RLCK
  42
  43    Locks the specified bytes. If the bytes cannot be locked, the program
  44    immediately tries again after 1 second.  If, after 10 attempts, the bytes cannot
  45    be locked, :exc:`IOError` is raised.
  46
  47
  48 .. data:: LK_NBLCK
  49           LK_NBRLCK
  50
  51    Locks the specified bytes. If the bytes cannot be locked, :exc:`IOError` is
  52    raised.
  53
  54
  55 .. data:: LK_UNLCK
  56
  57    Unlocks the specified bytes, which must have been previously locked.
  58
  59
  60 .. function:: setmode(fd, flags)
  61
  62    Set the line-end translation mode for the file descriptor *fd*. To set it to
  63    text mode, *flags* should be :const:`os.O_TEXT`; for binary, it should be
  64    :const:`os.O_BINARY`.
  65
  66
  67 .. function:: open_osfhandle(handle, flags)
  68
  69    Create a C runtime file descriptor from the file handle *handle*.  The *flags*
  70    parameter should be a bitwise OR of :const:`os.O_APPEND`, :const:`os.O_RDONLY`,
  71    and :const:`os.O_TEXT`.  The returned file descriptor may be used as a parameter
  72    to :func:`os.fdopen` to create a file object.
  73
  74
  75 .. function:: get_osfhandle(fd)
  76
  77    Return the file handle for the file descriptor *fd*.  Raises :exc:`IOError` if
  78    *fd* is not recognized.
  79
  80
  81 .. _msvcrt-console:
  82
  83 Console I/O
  84 -----------
  85
  86
  87 .. function:: kbhit()
  88
  89    Return true if a keypress is waiting to be read.
  90
  91
  92 .. function:: getch()
  93
  94    Read a keypress and return the resulting character.  Nothing is echoed to the
  95    console.  This call will block if a keypress is not already available, but will
  96    not wait for :kbd:`Enter` to be pressed. If the pressed key was a special
  97    function key, this will return ``'\000'`` or ``'\xe0'``; the next call will
  98    return the keycode.  The :kbd:`Control-C` keypress cannot be read with this
  99    function.
 100
 101
 102 .. function:: getwch()
 103
 104    Wide char variant of :func:`getch`, returning a Unicode value.
 105
 106    .. versionadded:: 2.6
 107
 108
 109 .. function:: getche()
 110
 111    Similar to :func:`getch`, but the keypress will be echoed if it  represents a
 112    printable character.
 113
 114
 115 .. function:: getwche()
 116
 117    Wide char variant of :func:`getche`, returning a Unicode value.
 118
 119    .. versionadded:: 2.6
 120
 121
 122 .. function:: putch(char)
 123
 124    Print the character *char* to the console without buffering.
 125
 126
 127 .. function:: putwch(unicode_char)
 128
 129    Wide char variant of :func:`putch`, accepting a Unicode value.
 130
 131    .. versionadded:: 2.6
 132
 133
 134 .. function:: ungetch(char)
 135
 136    Cause the character *char* to be "pushed back" into the console buffer; it will
 137    be the next character read by :func:`getch` or :func:`getche`.
 138
 139
 140 .. function:: ungetwch(unicode_char)
 141
 142    Wide char variant of :func:`ungetch`, accepting a Unicode value.
 143
 144    .. versionadded:: 2.6
 145
 146
 147 .. _msvcrt-other:
 148
 149 Other Functions
 150 ---------------
 151
 152
 153 .. function:: heapmin()
 154
 155    Force the :cfunc:`malloc` heap to clean itself up and return unused blocks to
 156    the operating system.  On failure, this raises :exc:`IOError`.