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 (a] acm.org> 9 10 -------------- 11 12 These functions provide access to some useful capabilities on Windows platforms. 13 Some higher-level modules use these functions to build the Windows 14 implementations of their services. For example, the :mod:`getpass` module uses 15 this in the implementation of the :func:`getpass` function. 16 17 Further documentation on these functions can be found in the Platform API 18 documentation. 19 20 The module implements both the normal and wide char variants of the console I/O 21 api. The normal API deals only with ASCII characters and is of limited use 22 for internationalized applications. The wide char API should be used where 23 ever 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 32 File 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 46 .. data:: LK_LOCK 47 LK_RLCK 48 49 Locks the specified bytes. If the bytes cannot be locked, the program 50 immediately tries again after 1 second. If, after 10 attempts, the bytes cannot 51 be locked, :exc:`OSError` is raised. 52 53 54 .. data:: LK_NBLCK 55 LK_NBRLCK 56 57 Locks the specified bytes. If the bytes cannot be locked, :exc:`OSError` is 58 raised. 59 60 61 .. data:: LK_UNLCK 62 63 Unlocks the specified bytes, which must have been previously locked. 64 65 66 .. function:: setmode(fd, flags) 67 68 Set the line-end translation mode for the file descriptor *fd*. To set it to 69 text mode, *flags* should be :const:`os.O_TEXT`; for binary, it should be 70 :const:`os.O_BINARY`. 71 72 73 .. function:: open_osfhandle(handle, flags) 74 75 Create a C runtime file descriptor from the file handle *handle*. The *flags* 76 parameter should be a bitwise OR of :const:`os.O_APPEND`, :const:`os.O_RDONLY`, 77 and :const:`os.O_TEXT`. The returned file descriptor may be used as a parameter 78 to :func:`os.fdopen` to create a file object. 79 80 81 .. function:: get_osfhandle(fd) 82 83 Return the file handle for the file descriptor *fd*. Raises :exc:`OSError` if 84 *fd* is not recognized. 85 86 87 .. _msvcrt-console: 88 89 Console I/O 90 ----------- 91 92 93 .. function:: kbhit() 94 95 Return true if a keypress is waiting to be read. 96 97 98 .. function:: getch() 99 100 Read a keypress and return the resulting character as a byte string. 101 Nothing is echoed to the console. This call will block if a keypress 102 is not already available, but will not wait for :kbd:`Enter` to be 103 pressed. If the pressed key was a special function key, this will 104 return ``'\000'`` or ``'\xe0'``; the next call will return the keycode. 105 The :kbd:`Control-C` keypress cannot be read with this function. 106 107 108 .. function:: getwch() 109 110 Wide char variant of :func:`getch`, returning a Unicode value. 111 112 113 .. function:: getche() 114 115 Similar to :func:`getch`, but the keypress will be echoed if it represents a 116 printable character. 117 118 119 .. function:: getwche() 120 121 Wide char variant of :func:`getche`, returning a Unicode value. 122 123 124 .. function:: putch(char) 125 126 Print the byte string *char* to the console without buffering. 127 128 129 .. function:: putwch(unicode_char) 130 131 Wide char variant of :func:`putch`, accepting a Unicode value. 132 133 134 .. function:: ungetch(char) 135 136 Cause the byte string *char* to be "pushed back" into the console buffer; 137 it will 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 145 .. _msvcrt-other: 146 147 Other Functions 148 --------------- 149 150 151 .. function:: heapmin() 152 153 Force the :c:func:`malloc` heap to clean itself up and return unused blocks to 154 the operating system. On failure, this raises :exc:`OSError`. 155
