ref: a8d00e5d56b261376410c3c87c46327362763bd8
dir: /sys/src/cmd/python/Doc/lib/libmsvcrt.tex/
\section{\module{msvcrt} -- Useful routines from the MS V\Cpp\ runtime} \declaremodule{builtin}{msvcrt} \platform{Windows} \modulesynopsis{Miscellaneous useful routines from the MS V\Cpp\ runtime.} \sectionauthor{Fred L. Drake, Jr.}{[email protected]} These functions provide access to some useful capabilities on Windows platforms. Some higher-level modules use these functions to build the Windows implementations of their services. For example, the \refmodule{getpass} module uses this in the implementation of the \function{getpass()} function. Further documentation on these functions can be found in the Platform API documentation. \subsection{File Operations \label{msvcrt-files}} \begin{funcdesc}{locking}{fd, mode, nbytes} Lock part of a file based on file descriptor \var{fd} from the C runtime. Raises \exception{IOError} on failure. The locked region of the file extends from the current file position for \var{nbytes} bytes, and may continue beyond the end of the file. \var{mode} must be one of the \constant{LK_\var{*}} constants listed below. Multiple regions in a file may be locked at the same time, but may not overlap. Adjacent regions are not merged; they must be unlocked individually. \end{funcdesc} \begin{datadesc}{LK_LOCK} \dataline{LK_RLCK} Locks the specified bytes. If the bytes cannot be locked, the program immediately tries again after 1 second. If, after 10 attempts, the bytes cannot be locked, \exception{IOError} is raised. \end{datadesc} \begin{datadesc}{LK_NBLCK} \dataline{LK_NBRLCK} Locks the specified bytes. If the bytes cannot be locked, \exception{IOError} is raised. \end{datadesc} \begin{datadesc}{LK_UNLCK} Unlocks the specified bytes, which must have been previously locked. \end{datadesc} \begin{funcdesc}{setmode}{fd, flags} Set the line-end translation mode for the file descriptor \var{fd}. To set it to text mode, \var{flags} should be \constant{os.O_TEXT}; for binary, it should be \constant{os.O_BINARY}. \end{funcdesc} \begin{funcdesc}{open_osfhandle}{handle, flags} Create a C runtime file descriptor from the file handle \var{handle}. The \var{flags} parameter should be a bit-wise OR of \constant{os.O_APPEND}, \constant{os.O_RDONLY}, and \constant{os.O_TEXT}. The returned file descriptor may be used as a parameter to \function{os.fdopen()} to create a file object. \end{funcdesc} \begin{funcdesc}{get_osfhandle}{fd} Return the file handle for the file descriptor \var{fd}. Raises \exception{IOError} if \var{fd} is not recognized. \end{funcdesc} \subsection{Console I/O \label{msvcrt-console}} \begin{funcdesc}{kbhit}{} Return true if a keypress is waiting to be read. \end{funcdesc} \begin{funcdesc}{getch}{} Read a keypress and return the resulting character. Nothing is echoed to the console. This call will block if a keypress is not already available, but will not wait for \kbd{Enter} to be pressed. If the pressed key was a special function key, this will return \code{'\e000'} or \code{'\e xe0'}; the next call will return the keycode. The \kbd{Control-C} keypress cannot be read with this function. \end{funcdesc} \begin{funcdesc}{getche}{} Similar to \function{getch()}, but the keypress will be echoed if it represents a printable character. \end{funcdesc} \begin{funcdesc}{putch}{char} Print the character \var{char} to the console without buffering. \end{funcdesc} \begin{funcdesc}{ungetch}{char} Cause the character \var{char} to be ``pushed back'' into the console buffer; it will be the next character read by \function{getch()} or \function{getche()}. \end{funcdesc} \subsection{Other Functions \label{msvcrt-other}} \begin{funcdesc}{heapmin}{} Force the \cfunction{malloc()} heap to clean itself up and return unused blocks to the operating system. This only works on Windows NT. On failure, this raises \exception{IOError}. \end{funcdesc}