2 :mod:`msvcrt` -- Useful routines from the MS VC++ runtime
3 =========================================================
7 :synopsis: Miscellaneous useful routines from the MS VC++ runtime.
8 .. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
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.
16 Further documentation on these functions can be found in the Platform API
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
30 .. function:: locking(fd, mode, nbytes)
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.
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.
51 Locks the specified bytes. If the bytes cannot be locked, :exc:`IOError` is
57 Unlocks the specified bytes, which must have been previously locked.
60 .. function:: setmode(fd, flags)
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
67 .. function:: open_osfhandle(handle, flags)
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.
75 .. function:: get_osfhandle(fd)
77 Return the file handle for the file descriptor *fd*. Raises :exc:`IOError` if
78 *fd* is not recognized.
89 Return true if a keypress is waiting to be read.
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
102 .. function:: getwch()
104 Wide char variant of :func:`getch`, returning a Unicode value.
106 .. versionadded:: 2.6
109 .. function:: getche()
111 Similar to :func:`getch`, but the keypress will be echoed if it represents a
115 .. function:: getwche()
117 Wide char variant of :func:`getche`, returning a Unicode value.
119 .. versionadded:: 2.6
122 .. function:: putch(char)
124 Print the character *char* to the console without buffering.
127 .. function:: putwch(unicode_char)
129 Wide char variant of :func:`putch`, accepting a Unicode value.
131 .. versionadded:: 2.6
134 .. function:: ungetch(char)
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`.
140 .. function:: ungetwch(unicode_char)
142 Wide char variant of :func:`ungetch`, accepting a Unicode value.
144 .. versionadded:: 2.6
153 .. function:: heapmin()
155 Force the :cfunc:`malloc` heap to clean itself up and return unused blocks to
156 the operating system. This only works on Windows NT. On failure, this raises