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