msvcrt.rst 4.27 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
:mod:`msvcrt` -- Useful routines from the MS VC++ runtime
=========================================================

.. module:: msvcrt
   :platform: Windows
   :synopsis: 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 :mod:`getpass` module uses
this in the implementation of the :func:`getpass` function.

Further documentation on these functions can be found in the Platform API
documentation.

18 19
The module implements both the normal and wide char variants of the console I/O
api. The normal API deals only with ASCII characters and is of limited use
20
for internationalized applications. The wide char API should be used where
21
ever possible
22

23 24 25 26 27
.. versionchanged:: 3.3
   Operations in this module now raise :exc:`OSError` where :exc:`IOError`
   was raised.


28 29 30 31 32 33 34 35 36
.. _msvcrt-files:

File Operations
---------------


.. function:: locking(fd, mode, nbytes)

   Lock part of a file based on file descriptor *fd* from the C runtime.  Raises
37
   :exc:`OSError` on failure.  The locked region of the file extends from the
38 39 40 41 42 43 44 45 46 47 48
   current file position for *nbytes* bytes, and may continue beyond the end of the
   file.  *mode* must be one of the :const:`LK_\*` 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.


.. data:: LK_LOCK
          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
49
   be locked, :exc:`OSError` is raised.
50 51 52 53 54


.. data:: LK_NBLCK
          LK_NBRLCK

55
   Locks the specified bytes. If the bytes cannot be locked, :exc:`OSError` is
56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73
   raised.


.. data:: LK_UNLCK

   Unlocks the specified bytes, which must have been previously locked.


.. function:: setmode(fd, flags)

   Set the line-end translation mode for the file descriptor *fd*. To set it to
   text mode, *flags* should be :const:`os.O_TEXT`; for binary, it should be
   :const:`os.O_BINARY`.


.. function:: open_osfhandle(handle, flags)

   Create a C runtime file descriptor from the file handle *handle*.  The *flags*
74
   parameter should be a bitwise OR of :const:`os.O_APPEND`, :const:`os.O_RDONLY`,
75 76 77 78 79 80
   and :const:`os.O_TEXT`.  The returned file descriptor may be used as a parameter
   to :func:`os.fdopen` to create a file object.


.. function:: get_osfhandle(fd)

81
   Return the file handle for the file descriptor *fd*.  Raises :exc:`OSError` if
82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97
   *fd* is not recognized.


.. _msvcrt-console:

Console I/O
-----------


.. function:: kbhit()

   Return true if a keypress is waiting to be read.


.. function:: getch()

98 99 100 101 102 103
   Read a keypress and return the resulting character as a byte string.
   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 ``'\000'`` or ``'\xe0'``; the next call will return the keycode.
   The :kbd:`Control-C` keypress cannot be read with this function.
104

105

106 107
.. function:: getwch()

108
   Wide char variant of :func:`getch`, returning a Unicode value.
109

110 111 112 113 114 115 116

.. function:: getche()

   Similar to :func:`getch`, but the keypress will be echoed if it  represents a
   printable character.


117 118
.. function:: getwche()

119
   Wide char variant of :func:`getche`, returning a Unicode value.
120

121

122 123
.. function:: putch(char)

124
   Print the byte string *char* to the console without buffering.
125

126

127 128
.. function:: putwch(unicode_char)

129
   Wide char variant of :func:`putch`, accepting a Unicode value.
130

131 132 133

.. function:: ungetch(char)

134 135
   Cause the byte string *char* to be "pushed back" into the console buffer;
   it will be the next character read by :func:`getch` or :func:`getche`.
136

137

138 139
.. function:: ungetwch(unicode_char)

140
   Wide char variant of :func:`ungetch`, accepting a Unicode value.
141

142 143 144 145 146 147 148 149 150

.. _msvcrt-other:

Other Functions
---------------


.. function:: heapmin()

151
   Force the :c:func:`malloc` heap to clean itself up and return unused blocks to
152
   the operating system.  On failure, this raises :exc:`OSError`.