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. <[email protected]>
9
10
11These functions provide access to some useful capabilities on Windows platforms.
12Some higher-level modules use these functions to build the  Windows
13implementations of their services.  For example, the :mod:`getpass` module uses
14this in the implementation of the :func:`getpass` function.
15
16Further documentation on these functions can be found in the Platform API
17documentation.
18
19The module implements both the normal and wide char variants of the console I/O
20api. The normal API deals only with ASCII characters and is of limited use
21for internationalized applications. The wide char API should be used where
22ever possible.
23
24.. _msvcrt-files:
25
26File 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
83Console 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
149Other Functions
150---------------
151
152
153.. function:: heapmin()
154
155   Force the :c:func:`malloc` heap to clean itself up and return unused blocks to
156   the operating system.  On failure, this raises :exc:`IOError`.
157