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