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`, :const:`os.O_RDONLY`, 79 and :const:`os.O_TEXT`. The returned file descriptor may be used as a parameter 80 to :func:`os.fdopen` to create a file object. 81 82 .. audit-event:: msvcrt.open_osfhandle handle,flags msvcrt.open_osfhandle 83 84 85.. function:: get_osfhandle(fd) 86 87 Return the file handle for the file descriptor *fd*. Raises :exc:`OSError` if 88 *fd* is not recognized. 89 90 .. audit-event:: msvcrt.get_osfhandle fd msvcrt.get_osfhandle 91 92 93.. _msvcrt-console: 94 95Console I/O 96----------- 97 98 99.. function:: kbhit() 100 101 Return ``True`` if a keypress is waiting to be read. 102 103 104.. function:: getch() 105 106 Read a keypress and return the resulting character as a byte string. 107 Nothing is echoed to the console. This call will block if a keypress 108 is not already available, but will not wait for :kbd:`Enter` to be 109 pressed. If the pressed key was a special function key, this will 110 return ``'\000'`` or ``'\xe0'``; the next call will return the keycode. 111 The :kbd:`Control-C` keypress cannot be read with this function. 112 113 114.. function:: getwch() 115 116 Wide char variant of :func:`getch`, returning a Unicode value. 117 118 119.. function:: getche() 120 121 Similar to :func:`getch`, but the keypress will be echoed if it represents a 122 printable character. 123 124 125.. function:: getwche() 126 127 Wide char variant of :func:`getche`, returning a Unicode value. 128 129 130.. function:: putch(char) 131 132 Print the byte string *char* to the console without buffering. 133 134 135.. function:: putwch(unicode_char) 136 137 Wide char variant of :func:`putch`, accepting a Unicode value. 138 139 140.. function:: ungetch(char) 141 142 Cause the byte string *char* to be "pushed back" into the console buffer; 143 it will be the next character read by :func:`getch` or :func:`getche`. 144 145 146.. function:: ungetwch(unicode_char) 147 148 Wide char variant of :func:`ungetch`, accepting a Unicode value. 149 150 151.. _msvcrt-other: 152 153Other Functions 154--------------- 155 156 157.. function:: heapmin() 158 159 Force the :c:func:`malloc` heap to clean itself up and return unused blocks to 160 the operating system. On failure, this raises :exc:`OSError`. 161