cpython/Doc/library/msvcrt.rst

161 lines
4.5 KiB
ReStructuredText
Raw Normal View History

:mod:`msvcrt` --- Useful routines from the MS VC++ runtime
==========================================================
2007-08-15 11:28:22 -03:00
.. module:: msvcrt
:platform: Windows
:synopsis: Miscellaneous useful routines from the MS VC++ runtime.
2007-08-15 11:28:22 -03:00
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
--------------
2007-08-15 11:28:22 -03:00
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 :mod:`getpass` module uses
this in the implementation of the :func:`getpass` function.
Further documentation on these functions can be found in the Platform API
documentation.
The module implements both the normal and wide char variants of the console I/O
api. The normal API deals only with ASCII characters and is of limited use
2009-01-03 17:18:54 -04:00
for internationalized applications. The wide char API should be used where
ever possible.
2007-08-15 11:28:22 -03:00
2011-10-12 15:10:51 -03:00
.. versionchanged:: 3.3
Operations in this module now raise :exc:`OSError` where :exc:`IOError`
was raised.
2007-08-15 11:28:22 -03:00
.. _msvcrt-files:
File Operations
---------------
.. function:: locking(fd, mode, nbytes)
Lock part of a file based on file descriptor *fd* from the C runtime. Raises
2011-10-12 15:10:51 -03:00
:exc:`OSError` on failure. The locked region of the file extends from the
2007-08-15 11:28:22 -03:00
current file position for *nbytes* bytes, and may continue beyond the end of the
file. *mode* must be one of the :const:`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.
.. audit-event:: msvcrt.locking fd,mode,nbytes msvcrt.locking
2007-08-15 11:28:22 -03:00
.. data:: LK_LOCK
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
2011-10-12 15:10:51 -03:00
be locked, :exc:`OSError` is raised.
2007-08-15 11:28:22 -03:00
.. data:: LK_NBLCK
LK_NBRLCK
2011-10-12 15:10:51 -03:00
Locks the specified bytes. If the bytes cannot be locked, :exc:`OSError` is
2007-08-15 11:28:22 -03:00
raised.
.. data:: LK_UNLCK
Unlocks the specified bytes, which must have been previously locked.
.. function:: setmode(fd, flags)
Set the line-end translation mode for the file descriptor *fd*. To set it to
text mode, *flags* should be :const:`os.O_TEXT`; for binary, it should be
:const:`os.O_BINARY`.
.. function:: open_osfhandle(handle, flags)
Create a C runtime file descriptor from the file handle *handle*. The *flags*
Merged revisions 59703-59773 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r59704 | christian.heimes | 2008-01-04 04:15:05 +0100 (Fri, 04 Jan 2008) | 1 line Moved include "Python.h" in front of other imports to silence a warning. ........ r59706 | raymond.hettinger | 2008-01-04 04:22:53 +0100 (Fri, 04 Jan 2008) | 10 lines Minor fix-ups to named tuples: * Make the _replace() method respect subclassing. * Using property() to make _fields read-only wasn't a good idea. It caused len(Point._fields) to fail. * Add note to _cast() about length checking and alternative with the star-operator. ........ r59707 | jeffrey.yasskin | 2008-01-04 09:01:23 +0100 (Fri, 04 Jan 2008) | 3 lines Make math.{floor,ceil}({int,long}) return float again for backwards compatibility after r59671 made them return integral types. ........ r59709 | christian.heimes | 2008-01-04 14:21:07 +0100 (Fri, 04 Jan 2008) | 1 line Bug #1713: posixpath.ismount() claims symlink to a mountpoint is a mountpoint. ........ r59712 | lars.gustaebel | 2008-01-04 15:00:33 +0100 (Fri, 04 Jan 2008) | 5 lines Issue #1735: TarFile.extractall() now correctly sets directory permissions and times. (will backport to 2.5) ........ r59714 | andrew.kuchling | 2008-01-04 15:47:17 +0100 (Fri, 04 Jan 2008) | 1 line Update links to bug/patch tracker ........ r59716 | christian.heimes | 2008-01-04 16:23:30 +0100 (Fri, 04 Jan 2008) | 1 line Added interface to Windows' WSAIoctl and a simple example for a network sniffer. ........ r59717 | christian.heimes | 2008-01-04 16:29:00 +0100 (Fri, 04 Jan 2008) | 1 line And here is the rest of Hirokazu Yamamoto's patch for VS6.0 support. Thanks Hiro! ........ r59719 | christian.heimes | 2008-01-04 16:34:06 +0100 (Fri, 04 Jan 2008) | 1 line Reverted last transaction. It's the wrong branch. ........ r59721 | christian.heimes | 2008-01-04 16:48:06 +0100 (Fri, 04 Jan 2008) | 1 line socket.ioctl is only available on Windows ........ r59722 | andrew.kuchling | 2008-01-04 19:24:41 +0100 (Fri, 04 Jan 2008) | 1 line Fix markup ........ r59723 | andrew.kuchling | 2008-01-04 19:25:05 +0100 (Fri, 04 Jan 2008) | 1 line Fix markup ........ r59725 | guido.van.rossum | 2008-01-05 01:59:59 +0100 (Sat, 05 Jan 2008) | 3 lines Patch #1725 by Mark Dickinson, fixes incorrect conversion of -1e1000 and adds errors for -0x. ........ r59726 | guido.van.rossum | 2008-01-05 02:21:57 +0100 (Sat, 05 Jan 2008) | 2 lines Patch #1698 by Senthil: allow '@' in username when parsed by urlparse.py. ........ r59727 | raymond.hettinger | 2008-01-05 02:35:43 +0100 (Sat, 05 Jan 2008) | 1 line Improve namedtuple's _cast() method with a docstring, new name, and error-checking. ........ r59728 | raymond.hettinger | 2008-01-05 03:17:24 +0100 (Sat, 05 Jan 2008) | 1 line Add error-checking to namedtuple's _replace() method. ........ r59730 | fred.drake | 2008-01-05 05:38:38 +0100 (Sat, 05 Jan 2008) | 2 lines clean up a comment ........ r59731 | jeffrey.yasskin | 2008-01-05 09:47:13 +0100 (Sat, 05 Jan 2008) | 11 lines Continue rolling back pep-3141 changes that changed behavior from 2.5. This round included: * Revert round to its 2.6 behavior (half away from 0). * Because round, floor, and ceil always return float again, it's no longer necessary to have them delegate to __xxx___, so I've ripped that out of their implementations and the Real ABC. This also helps in implementing types that work in both 2.6 and 3.0: you return int from the __xxx__ methods, and let it get enabled by the version upgrade. * Make pow(-1, .5) raise a ValueError again. ........ r59736 | andrew.kuchling | 2008-01-05 16:13:49 +0100 (Sat, 05 Jan 2008) | 1 line Fix comment typo ........ r59738 | thomas.heller | 2008-01-05 18:15:44 +0100 (Sat, 05 Jan 2008) | 1 line Add myself. ........ r59739 | georg.brandl | 2008-01-05 18:49:17 +0100 (Sat, 05 Jan 2008) | 2 lines Fix C++-style comment. ........ r59742 | georg.brandl | 2008-01-05 20:28:16 +0100 (Sat, 05 Jan 2008) | 2 lines Remove with_statement future imports from 2.6 docs. ........ r59743 | georg.brandl | 2008-01-05 20:29:45 +0100 (Sat, 05 Jan 2008) | 2 lines Simplify index entries; fix #1712. ........ r59744 | georg.brandl | 2008-01-05 20:44:22 +0100 (Sat, 05 Jan 2008) | 2 lines Doc patch #1730 from Robin Stocker; minor corrections mostly to os.rst. ........ r59749 | georg.brandl | 2008-01-05 21:29:13 +0100 (Sat, 05 Jan 2008) | 2 lines Revert socket.rst to unix-eol. ........ r59750 | georg.brandl | 2008-01-05 21:33:46 +0100 (Sat, 05 Jan 2008) | 2 lines Set native svn:eol-style property for text files. ........ r59752 | georg.brandl | 2008-01-05 21:46:29 +0100 (Sat, 05 Jan 2008) | 2 lines #1719: capitalization error in "UuidCreate". ........ r59753 | georg.brandl | 2008-01-05 22:02:25 +0100 (Sat, 05 Jan 2008) | 2 lines Repair markup. ........ r59754 | georg.brandl | 2008-01-05 22:10:50 +0100 (Sat, 05 Jan 2008) | 2 lines Use markup. ........ r59757 | christian.heimes | 2008-01-05 22:35:52 +0100 (Sat, 05 Jan 2008) | 1 line Final adjustments for #1601 ........ r59758 | guido.van.rossum | 2008-01-05 23:19:06 +0100 (Sat, 05 Jan 2008) | 3 lines Patch #1637: fix urlparse for URLs like 'http://x.com?arg=/foo'. Fix by John Nagle. ........ r59759 | guido.van.rossum | 2008-01-05 23:20:01 +0100 (Sat, 05 Jan 2008) | 2 lines Add John Nagle (of issue #1637). ........ r59765 | raymond.hettinger | 2008-01-06 10:02:24 +0100 (Sun, 06 Jan 2008) | 1 line Small code simplification. Forgot that classmethods can be called from intances. ........ r59766 | martin.v.loewis | 2008-01-06 11:09:48 +0100 (Sun, 06 Jan 2008) | 2 lines Use vcbuild for VS 2009. ........ r59767 | martin.v.loewis | 2008-01-06 12:03:43 +0100 (Sun, 06 Jan 2008) | 2 lines Package using VS 2008. ........ r59768 | martin.v.loewis | 2008-01-06 12:13:16 +0100 (Sun, 06 Jan 2008) | 2 lines Don't try to package msvcr90 for the moment. ........ r59769 | georg.brandl | 2008-01-06 15:17:36 +0100 (Sun, 06 Jan 2008) | 4 lines #1696393: don't check for '.' and '..' in ntpath.walk since they aren't returned from os.listdir anymore. Reported by Michael Haggerty. ........ r59770 | georg.brandl | 2008-01-06 15:27:15 +0100 (Sun, 06 Jan 2008) | 3 lines #1742: don't raise exception on os.path.relpath("a", "a"), but return os.curdir. Reported by Jesse Towner. ........ r59771 | georg.brandl | 2008-01-06 15:33:52 +0100 (Sun, 06 Jan 2008) | 2 lines #1591: Clarify docstring of Popen3. ........ r59772 | georg.brandl | 2008-01-06 16:30:34 +0100 (Sun, 06 Jan 2008) | 2 lines #1680: fix context manager example function name. ........ r59773 | georg.brandl | 2008-01-06 16:34:57 +0100 (Sun, 06 Jan 2008) | 2 lines #1755097: document default values for [].sort() and sorted(). ........
2008-01-06 12:59:19 -04:00
parameter should be a bitwise OR of :const:`os.O_APPEND`, :const:`os.O_RDONLY`,
2007-08-15 11:28:22 -03:00
and :const:`os.O_TEXT`. The returned file descriptor may be used as a parameter
to :func:`os.fdopen` to create a file object.
.. audit-event:: msvcrt.open_osfhandle handle,flags msvcrt.open_osfhandle
2007-08-15 11:28:22 -03:00
.. function:: get_osfhandle(fd)
2011-10-12 15:10:51 -03:00
Return the file handle for the file descriptor *fd*. Raises :exc:`OSError` if
2007-08-15 11:28:22 -03:00
*fd* is not recognized.
.. audit-event:: msvcrt.get_osfhandle fd msvcrt.get_osfhandle
2007-08-15 11:28:22 -03:00
.. _msvcrt-console:
Console I/O
-----------
.. function:: kbhit()
Return ``True`` if a keypress is waiting to be read.
2007-08-15 11:28:22 -03:00
.. function:: 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 :kbd:`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 :kbd:`Control-C` keypress cannot be read with this function.
2007-08-15 11:28:22 -03:00
2009-01-03 17:18:54 -04:00
.. function:: getwch()
Wide char variant of :func:`getch`, returning a Unicode value.
2009-01-03 17:18:54 -04:00
2007-08-15 11:28:22 -03:00
.. function:: getche()
Similar to :func:`getch`, but the keypress will be echoed if it represents a
printable character.
.. function:: getwche()
Wide char variant of :func:`getche`, returning a Unicode value.
2009-01-03 17:18:54 -04:00
2007-08-15 11:28:22 -03:00
.. function:: putch(char)
Print the byte string *char* to the console without buffering.
2007-08-15 11:28:22 -03:00
2009-01-03 17:18:54 -04:00
.. function:: putwch(unicode_char)
Wide char variant of :func:`putch`, accepting a Unicode value.
2009-01-03 17:18:54 -04:00
2007-08-15 11:28:22 -03:00
.. function:: ungetch(char)
Cause the byte string *char* to be "pushed back" into the console buffer;
it will be the next character read by :func:`getch` or :func:`getche`.
2007-08-15 11:28:22 -03:00
2009-01-03 17:18:54 -04:00
.. function:: ungetwch(unicode_char)
Wide char variant of :func:`ungetch`, accepting a Unicode value.
2009-01-03 17:18:54 -04:00
2007-08-15 11:28:22 -03:00
.. _msvcrt-other:
Other Functions
---------------
.. function:: heapmin()
Force the :c:func:`malloc` heap to clean itself up and return unused blocks to
2011-10-12 15:10:51 -03:00
the operating system. On failure, this raises :exc:`OSError`.