Debian Codegraph @

Doc/library/msvcrt.rst

raw
1 :mod:`!msvcrt` --- Useful routines from the MS VC++ runtime
2 ===========================================================
3
4 .. module:: msvcrt
5 :synopsis: Miscellaneous useful routines from the MS VC++ runtime.
6
7 .. sectionauthor:: Fred L. Drake, Jr. <[email protected]>
8
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 .. availability:: Windows.
25
26 .. versionchanged:: 3.3
27 Operations in this module now raise :exc:`OSError` where :exc:`IOError`
28 was raised.
29
30
31 .. _msvcrt-files:
32
33 File Operations
34 ---------------
35
36
37 .. function:: locking(fd, mode, nbytes)
38
39 Lock part of a file based on file descriptor *fd* from the C runtime. Raises
40 :exc:`OSError` on failure. The locked region of the file extends from the
41 current file position for *nbytes* bytes, and may continue beyond the end of the
42 file. *mode* must be one of the :const:`!LK_\*` constants listed below. Multiple
43 regions in a file may be locked at the same time, but may not overlap. Adjacent
44 regions are not merged; they must be unlocked individually.
45
46 .. audit-event:: msvcrt.locking fd,mode,nbytes msvcrt.locking
47
48
49 .. data:: LK_LOCK
50 LK_RLCK
51
52 Locks the specified bytes. If the bytes cannot be locked, the program
53 immediately tries again after 1 second. If, after 10 attempts, the bytes cannot
54 be locked, :exc:`OSError` is raised.
55
56
57 .. data:: LK_NBLCK
58 LK_NBRLCK
59
60 Locks the specified bytes. If the bytes cannot be locked, :exc:`OSError` is
61 raised.
62
63
64 .. data:: LK_UNLCK
65
66 Unlocks the specified bytes, which must have been previously locked.
67
68
69 .. function:: setmode(fd, flags)
70
71 Set the line-end translation mode for the file descriptor *fd*. To set it to
72 text mode, *flags* should be :const:`os.O_TEXT`; for binary, it should be
73 :const:`os.O_BINARY`.
74
75
76 .. function:: open_osfhandle(handle, flags)
77
78 Create a C runtime file descriptor from the file handle *handle*. The *flags*
79 parameter should be a bitwise OR of :const:`os.O_APPEND`,
80 :const:`os.O_RDONLY`, :const:`os.O_TEXT` and :const:`os.O_NOINHERIT`.
81 The returned file descriptor may be used as a parameter
82 to :func:`os.fdopen` to create a file object.
83
84 The file descriptor is inheritable by default. Pass :const:`os.O_NOINHERIT`
85 flag to make it non inheritable.
86
87 .. audit-event:: msvcrt.open_osfhandle handle,flags msvcrt.open_osfhandle
88
89
90 .. function:: get_osfhandle(fd)
91
92 Return the file handle for the file descriptor *fd*. Raises :exc:`OSError` if
93 *fd* is not recognized.
94
95 .. audit-event:: msvcrt.get_osfhandle fd msvcrt.get_osfhandle
96
97
98 .. _msvcrt-console:
99
100 Console I/O
101 -----------
102
103
104 .. function:: kbhit()
105
106 Returns a nonzero value if a keypress is waiting to be read. Otherwise,
107 return 0.
108
109
110 .. function:: getch()
111
112 Read a keypress and return the resulting character as a byte string.
113 Nothing is echoed to the console. This call will block if a keypress
114 is not already available, but will not wait for :kbd:`Enter` to be
115 pressed. If the pressed key was a special function key, this will
116 return ``'\000'`` or ``'\xe0'``; the next call will return the keycode.
117 The :kbd:`Control-C` keypress cannot be read with this function.
118
119
120 .. function:: getwch()
121
122 Wide char variant of :func:`getch`, returning a Unicode value.
123
124
125 .. function:: getche()
126
127 Similar to :func:`getch`, but the keypress will be echoed if it represents a
128 printable character.
129
130
131 .. function:: getwche()
132
133 Wide char variant of :func:`getche`, returning a Unicode value.
134
135
136 .. function:: putch(char)
137
138 Print the byte string *char* to the console without buffering.
139
140
141 .. function:: putwch(unicode_char)
142
143 Wide char variant of :func:`putch`, accepting a Unicode value.
144
145
146 .. function:: ungetch(char)
147
148 Cause the byte string *char* to be "pushed back" into the console buffer;
149 it will be the next character read by :func:`getch` or :func:`getche`.
150
151
152 .. function:: ungetwch(unicode_char)
153
154 Wide char variant of :func:`ungetch`, accepting a Unicode value.
155
156
157 .. _msvcrt-other:
158
159 Other Functions
160 ---------------
161
162
163 .. function:: heapmin()
164
165 Force the :c:func:`malloc` heap to clean itself up and return unused blocks to
166 the operating system. On failure, this raises :exc:`OSError`.
167
168
169 .. function:: set_error_mode(mode)
170
171 Changes the location where the C runtime writes an error message for an error
172 that might end the program. *mode* must be one of the :const:`!OUT_\*`
173 constants listed below or :const:`REPORT_ERRMODE`. Returns the old setting
174 or -1 if an error occurs. Only available in
175 :ref:`debug build of Python <debug-build>`.
176
177
178 .. data:: OUT_TO_DEFAULT
179
180 Error sink is determined by the app's type. Only available in
181 :ref:`debug build of Python <debug-build>`.
182
183
184 .. data:: OUT_TO_STDERR
185
186 Error sink is a standard error. Only available in
187 :ref:`debug build of Python <debug-build>`.
188
189
190 .. data:: OUT_TO_MSGBOX
191
192 Error sink is a message box. Only available in
193 :ref:`debug build of Python <debug-build>`.
194
195
196 .. data:: REPORT_ERRMODE
197
198 Report the current error mode value. Only available in
199 :ref:`debug build of Python <debug-build>`.
200
201
202 .. function:: CrtSetReportMode(type, mode)
203
204 Specifies the destination or destinations for a specific report type
205 generated by :c:func:`!_CrtDbgReport` in the MS VC++ runtime. *type* must be
206 one of the :const:`!CRT_\*` constants listed below. *mode* must be one of the
207 :const:`!CRTDBG_\*` constants listed below. Only available in
208 :ref:`debug build of Python <debug-build>`.
209
210
211 .. function:: CrtSetReportFile(type, file)
212
213 After you use :func:`CrtSetReportMode` to specify :const:`CRTDBG_MODE_FILE`,
214 you can specify the file handle to receive the message text. *type* must be
215 one of the :const:`!CRT_\*` constants listed below. *file* should be the file
216 handle your want specified. Only available in
217 :ref:`debug build of Python <debug-build>`.
218
219
220 .. data:: CRT_WARN
221
222 Warnings, messages, and information that doesn't need immediate attention.
223
224
225 .. data:: CRT_ERROR
226
227 Errors, unrecoverable problems, and issues that require immediate attention.
228
229
230 .. data:: CRT_ASSERT
231
232 Assertion failures.
233
234
235 .. data:: CRTDBG_MODE_DEBUG
236
237 Writes the message to the debugger's output window.
238
239
240 .. data:: CRTDBG_MODE_FILE
241
242 Writes the message to a user-supplied file handle. :func:`CrtSetReportFile`
243 should be called to define the specific file or stream to use as
244 the destination.
245
246
247 .. data:: CRTDBG_MODE_WNDW
248
249 Creates a message box to display the message along with the ``Abort``,
250 ``Retry``, and ``Ignore`` buttons.
251
252
253 .. data:: CRTDBG_REPORT_MODE
254
255 Returns current *mode* for the specified *type*.
256
257
258 .. data:: CRT_ASSEMBLY_VERSION
259
260 The CRT Assembly version, from the :file:`crtassem.h` header file.
261
262
263 .. data:: VC_ASSEMBLY_PUBLICKEYTOKEN
264
265 The VC Assembly public key token, from the :file:`crtassem.h` header file.
266
267
268 .. data:: LIBRARIES_ASSEMBLY_NAME_PREFIX
269
270 The Libraries Assembly name prefix, from the :file:`crtassem.h` header file.