/Doc/library/msvcrt.rst

http://unladen-swallow.googlecode.com/ · ReStructuredText · 158 lines · 88 code · 70 blank · 0 comment · 0 complexity · 86c3595dc0713f8457a482eb97113124 MD5 · raw file

  1. :mod:`msvcrt` -- Useful routines from the MS VC++ runtime
  2. =========================================================
  3. .. module:: msvcrt
  4. :platform: Windows
  5. :synopsis: Miscellaneous useful routines from the MS VC++ runtime.
  6. .. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
  7. These functions provide access to some useful capabilities on Windows platforms.
  8. Some higher-level modules use these functions to build the Windows
  9. implementations of their services. For example, the :mod:`getpass` module uses
  10. this in the implementation of the :func:`getpass` function.
  11. Further documentation on these functions can be found in the Platform API
  12. documentation.
  13. The module implements both the normal and wide char variants of the console I/O
  14. api. The normal API deals only with ASCII characters and is of limited use
  15. for internationalized applications. The wide char API should be used where
  16. ever possible
  17. .. _msvcrt-files:
  18. File Operations
  19. ---------------
  20. .. function:: locking(fd, mode, nbytes)
  21. Lock part of a file based on file descriptor *fd* from the C runtime. Raises
  22. :exc:`IOError` on failure. The locked region of the file extends from the
  23. current file position for *nbytes* bytes, and may continue beyond the end of the
  24. file. *mode* must be one of the :const:`LK_\*` constants listed below. Multiple
  25. regions in a file may be locked at the same time, but may not overlap. Adjacent
  26. regions are not merged; they must be unlocked individually.
  27. .. data:: LK_LOCK
  28. LK_RLCK
  29. Locks the specified bytes. If the bytes cannot be locked, the program
  30. immediately tries again after 1 second. If, after 10 attempts, the bytes cannot
  31. be locked, :exc:`IOError` is raised.
  32. .. data:: LK_NBLCK
  33. LK_NBRLCK
  34. Locks the specified bytes. If the bytes cannot be locked, :exc:`IOError` is
  35. raised.
  36. .. data:: LK_UNLCK
  37. Unlocks the specified bytes, which must have been previously locked.
  38. .. function:: setmode(fd, flags)
  39. Set the line-end translation mode for the file descriptor *fd*. To set it to
  40. text mode, *flags* should be :const:`os.O_TEXT`; for binary, it should be
  41. :const:`os.O_BINARY`.
  42. .. function:: open_osfhandle(handle, flags)
  43. Create a C runtime file descriptor from the file handle *handle*. The *flags*
  44. parameter should be a bitwise OR of :const:`os.O_APPEND`, :const:`os.O_RDONLY`,
  45. and :const:`os.O_TEXT`. The returned file descriptor may be used as a parameter
  46. to :func:`os.fdopen` to create a file object.
  47. .. function:: get_osfhandle(fd)
  48. Return the file handle for the file descriptor *fd*. Raises :exc:`IOError` if
  49. *fd* is not recognized.
  50. .. _msvcrt-console:
  51. Console I/O
  52. -----------
  53. .. function:: kbhit()
  54. Return true if a keypress is waiting to be read.
  55. .. function:: getch()
  56. Read a keypress and return the resulting character. Nothing is echoed to the
  57. console. This call will block if a keypress is not already available, but will
  58. not wait for :kbd:`Enter` to be pressed. If the pressed key was a special
  59. function key, this will return ``'\000'`` or ``'\xe0'``; the next call will
  60. return the keycode. The :kbd:`Control-C` keypress cannot be read with this
  61. function.
  62. .. function:: getwch()
  63. Wide char variant of :func:`getch`, returning a Unicode value.
  64. .. versionadded:: 2.6
  65. .. function:: getche()
  66. Similar to :func:`getch`, but the keypress will be echoed if it represents a
  67. printable character.
  68. .. function:: getwche()
  69. Wide char variant of :func:`getche`, returning a Unicode value.
  70. .. versionadded:: 2.6
  71. .. function:: putch(char)
  72. Print the character *char* to the console without buffering.
  73. .. function:: putwch(unicode_char)
  74. Wide char variant of :func:`putch`, accepting a Unicode value.
  75. .. versionadded:: 2.6
  76. .. function:: ungetch(char)
  77. Cause the character *char* to be "pushed back" into the console buffer; it will
  78. be the next character read by :func:`getch` or :func:`getche`.
  79. .. function:: ungetwch(unicode_char)
  80. Wide char variant of :func:`ungetch`, accepting a Unicode value.
  81. .. versionadded:: 2.6
  82. .. _msvcrt-other:
  83. Other Functions
  84. ---------------
  85. .. function:: heapmin()
  86. Force the :cfunc:`malloc` heap to clean itself up and return unused blocks to
  87. the operating system. This only works on Windows NT. On failure, this raises
  88. :exc:`IOError`.