mirror of
https://github.com/python/cpython.git
synced 2024-11-26 19:34:19 +08:00
110 lines
3.9 KiB
TeX
110 lines
3.9 KiB
TeX
\section{\module{msvcrt} --
|
|
Useful routines from the MS VC++ runtime}
|
|
|
|
\declaremodule{builtin}{msvcrt}
|
|
\platform{Windows}
|
|
\modulesynopsis{Miscellaneous useful routines from the MS VC++ runtime.}
|
|
\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
|
|
|
|
|
|
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}
|