# `msvcrt` --- 来自 MS VC++ 运行时的有用例程

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 `getpass` module uses this in the implementation of the `getpass()` function.

关于这些函数的更多信息可以在平台 API 文档中找到。

该模块实现了控制台 I/O API 的普通和宽字符变体。普通的 API 只处理ASCII字符，国际化应用受限。应该尽可能地使用宽字符 API 。

在 3.3 版本发生变更: 此模块中过去会引发 `IOError` 的操作现在将引发 `OSError`。

## 文件操作

msvcrt.locking(fd, mode, nbytes)

  Lock part of a file based on file descriptor fd from the C runtime. Raises `OSError` on failure. The locked region of the file extends from the current file position for nbytes bytes, and may continue beyond the end of the file. mode must be one of the `LK_*` 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.

  引发一个 审计事件 `msvcrt.locking`，附带参数 `fd`, `mode`, `nbytes`。

msvcrt.LK_LOCK
msvcrt.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, `OSError` is raised.

msvcrt.LK_NBLCK
msvcrt.LK_NBRLCK

  锁定指定的字节数据。 如果字节数据无法被锁定，则会引发 `OSError`。

msvcrt.LK_UNLCK

  解锁指定的字节数据，该对象必须在之前被锁定。

msvcrt.setmode(fd, flags)

  设置文件描述符 fd 的行结束符转写模式。 要将其设为文本模式，则 flags 应当为 `os.O_TEXT`；设为二进制模式，则应当为 `os.O_BINARY`。

msvcrt.open_osfhandle(handle, flags)

  Create a C runtime file descriptor from the file handle handle. The flags parameter should be a bitwise OR of `os.O_APPEND`, `os.O_RDONLY`, `os.O_TEXT` and `os.O_NOINHERIT`. The returned file descriptor may be used as a parameter to `os.fdopen()` to create a file object.

  The file descriptor is inheritable by default. Pass `os.O_NOINHERIT` flag to make it non inheritable.

  引发一个 审计事件 `msvcrt.open_osfhandle`，附带参数 `handle`, `flags`。

msvcrt.get_osfhandle(fd)

  Return the file handle for the file descriptor fd. Raises `OSError` if fd is not recognized.

  引发一个 审计事件 `msvcrt.get_osfhandle`，附带参数 `fd`。

## 控制台 I/O

msvcrt.kbhit()

  Returns a nonzero value if a keypress is waiting to be read. Otherwise, return 0.

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 keypress is not already available, but will not wait for `Enter` to be pressed. If the pressed key was a special function key, this will return `'\000'` or `'\xe0'`; the next call will return the keycode. The ``Control`-`C`` keypress cannot be read with this function.

msvcrt.getwch()

  `getch()` 的宽字符版本，返回一个 Unicode 值。

msvcrt.getche()

  Similar to `getch()`, but the keypress will be echoed if it represents a printable character.

msvcrt.getwche()

  `getche()` 的宽字符版本，返回一个 Unicode 值。

msvcrt.putch(char)

  将字符串 char 打印到终端，不使用缓冲区。

msvcrt.putwch(unicode_char)

  `putch()` 的宽字符版本，接受一个 Unicode 值。

msvcrt.ungetch(char)

  使得字节串 char 被“推回”终端缓冲区；它将是被 `getch()` 或 `getche()` 读取的下一个字符。

msvcrt.ungetwch(unicode_char)

  `ungetch()` 的宽字符版本，接受一个 Unicode 值。

## 其他函数

msvcrt.heapmin()

  强制 `malloc()` 堆清空自身并将未使用的块返回给操作系统。 失败时，这将引发 `OSError`。

msvcrt.set_error_mode(mode)

  Changes the location where the C runtime writes an error message for an error that might end the program. mode must be one of the `OUT_*` constants listed below or `REPORT_ERRMODE`. Returns the old setting or -1 if an error occurs. Only available in debug build of Python.

msvcrt.OUT_TO_DEFAULT

  Error sink is determined by the app's type. Only available in debug build of Python.

msvcrt.OUT_TO_STDERR

  Error sink is a standard error. Only available in debug build of Python.

msvcrt.OUT_TO_MSGBOX

  Error sink is a message box. Only available in debug build of Python.

msvcrt.REPORT_ERRMODE

  Report the current error mode value. Only available in debug build of Python.

msvcrt.CrtSetReportMode(type, mode)

  Specifies the destination or destinations for a specific report type generated by `_CrtDbgReport()` in the MS VC++ runtime. type must be one of the `CRT_*` constants listed below. mode must be one of the `CRTDBG_*` constants listed below. Only available in debug build of Python.

msvcrt.CrtSetReportFile(type, file)

  After you use `CrtSetReportMode()` to specify `CRTDBG_MODE_FILE`, you can specify the file handle to receive the message text. type must be one of the `CRT_*` constants listed below. file should be the file handle your want specified. Only available in debug build of Python.

msvcrt.CRT_WARN

  Warnings, messages, and information that doesn't need immediate attention.

msvcrt.CRT_ERROR

  Errors, unrecoverable problems, and issues that require immediate attention.

msvcrt.CRT_ASSERT

  Assertion failures.

msvcrt.CRTDBG_MODE_DEBUG

  Writes the message to the debugger's output window.

msvcrt.CRTDBG_MODE_FILE

  将消息写入用户提供的文件句柄。 应当调用 `CrtSetReportFile()` 来定义要用作写入目标的特定文件或流。

msvcrt.CRTDBG_MODE_WNDW

  创建一个消息框来显示消息并提供 `Abort`, `Retry` 和 `Ignore` 等按钮。

msvcrt.CRTDBG_REPORT_MODE

  返回指定 type 当前的 mode。

msvcrt.CRT_ASSEMBLY_VERSION

  CRT 汇编版，来自 `crtassem.h` 头文件。

msvcrt.VC_ASSEMBLY_PUBLICKEYTOKEN

  VC 汇编公钥凭据，来自 `crtassem.h` 头文件。

msvcrt.LIBRARIES_ASSEMBLY_NAME_PREFIX

  库汇编名称前缀，来自 `crtassem.h` 头文件。