/Doc/library/msvcrt.rst

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