msvcrt — Useful routines from the MS VC++ runtime

These functions provide access to some useful capabilities on Windows platforms.Some higher-level modules use these functions to build the Windowsimplementations of their services. For example, thegetpass module usesthis in the implementation of thegetpass() function.

Further documentation on these functions can be found in the Platform APIdocumentation.

The module implements both the normal and wide char variants of the console I/Oapi. The normal API deals only with ASCII characters and is of limited usefor internationalized applications. The wide char API should be used whereever possible.

Changed in version 3.3:Operations in this module now raiseOSError whereIOErrorwas raised.

File Operations

msvcrt.locking(fd,mode,nbytes)

Lock part of a file based on file descriptorfd from the C runtime. RaisesOSError on failure. The locked region of the file extends from thecurrent file position fornbytes bytes, and may continue beyond the end of thefile.mode must be one of theLK_* constants listed below. Multipleregions in a file may be locked at the same time, but may not overlap. Adjacentregions are not merged; they must be unlocked individually.

Raises anauditing eventmsvcrt.locking with argumentsfd,mode,nbytes.

msvcrt.LK_LOCK
msvcrt.LK_RLCK

Locks the specified bytes. If the bytes cannot be locked, the programimmediately tries again after 1 second. If, after 10 attempts, the bytes cannotbe locked,OSError is raised.

msvcrt.LK_NBLCK
msvcrt.LK_NBRLCK

Locks the specified bytes. If the bytes cannot be locked,OSError israised.

msvcrt.LK_UNLCK

Unlocks the specified bytes, which must have been previously locked.

msvcrt.setmode(fd,flags)

Set the line-end translation mode for the file descriptorfd. To set it totext mode,flags should beos.O_TEXT; for binary, it should beos.O_BINARY.

msvcrt.open_osfhandle(handle,flags)

Create a C runtime file descriptor from the file handlehandle. Theflagsparameter should be a bitwise OR ofos.O_APPEND,os.O_RDONLY,andos.O_TEXT. The returned file descriptor may be used as a parametertoos.fdopen() to create a file object.

Raises anauditing eventmsvcrt.open_osfhandle with argumentshandle,flags.

msvcrt.get_osfhandle(fd)

Return the file handle for the file descriptorfd. RaisesOSError iffd is not recognized.

Raises anauditing eventmsvcrt.get_osfhandle with argumentfd.

Console I/O

msvcrt.kbhit()

ReturnTrue if a keypress is waiting to be read.

msvcrt.getch()

Read a keypress and return the resulting character as a byte string.Nothing is echoed to the console. This call will block if a keypressis not already available, but will not wait forEnter to bepressed. If the pressed key was a special function key, this willreturn'\000' or'\xe0'; the next call will return the keycode.TheControl-C keypress cannot be read with this function.

msvcrt.getwch()

Wide char variant ofgetch(), returning a Unicode value.

msvcrt.getche()

Similar togetch(), but the keypress will be echoed if it represents aprintable character.

msvcrt.getwche()

Wide char variant ofgetche(), returning a Unicode value.

msvcrt.putch(char)

Print the byte stringchar to the console without buffering.

msvcrt.putwch(unicode_char)

Wide char variant ofputch(), accepting a Unicode value.

msvcrt.ungetch(char)

Cause the byte stringchar to be “pushed back” into the console buffer;it will be the next character read bygetch() orgetche().

msvcrt.ungetwch(unicode_char)

Wide char variant ofungetch(), accepting a Unicode value.

Other Functions

msvcrt.heapmin()

Force themalloc() heap to clean itself up and return unused blocks tothe operating system. On failure, this raisesOSError.