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. <fdrake@acm.org> 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