cpython/Doc/library/msvcrt.rst

148 lines
4.1 KiB
ReStructuredText
Raw Normal View History

2007-08-15 11:28:22 -03:00
:mod:`msvcrt` -- Useful routines from the MS VC++ runtime
=========================================================
.. module:: msvcrt
:platform: Windows
:synopsis: Miscellaneous useful routines from the MS VC++ runtime.
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
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
.. _msvcrt-files:
File Operations
---------------
.. function:: locking(fd, mode, nbytes)
Lock part of a file based on file descriptor *fd* from the C runtime. Raises
:exc:`IOError` 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 :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.
.. 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
be locked, :exc:`IOError` is raised.
.. data:: LK_NBLCK
LK_NBRLCK
Locks the specified bytes. If the bytes cannot be locked, :exc:`IOError` is
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.
.. function:: get_osfhandle(fd)
Return the file handle for the file descriptor *fd*. Raises :exc:`IOError` if
*fd* is not recognized.
.. _msvcrt-console:
Console I/O
-----------
.. function:: kbhit()
Return true if a keypress is waiting to be read.
.. function:: getch()
Read a keypress and return the resulting character. 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.
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 character *char* to the console without buffering.
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 character *char* to be "pushed back" into the console buffer; it will
be the next character read by :func:`getch` or :func:`getche`.
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 :cfunc:`malloc` heap to clean itself up and return unused blocks to
Merged revisions 77167 via svnmerge from svn+ssh://pythondev@svn.python.org/python/branches/py3k ................ r77167 | benjamin.peterson | 2009-12-30 21:11:23 -0600 (Wed, 30 Dec 2009) | 61 lines Merged revisions 76847,76851,76869,76882,76891-76892,76924,77007,77070,77092,77096,77120,77126,77155 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r76847 | benjamin.peterson | 2009-12-14 21:25:27 -0600 (Mon, 14 Dec 2009) | 1 line adverb ........ r76851 | benjamin.peterson | 2009-12-15 21:28:52 -0600 (Tue, 15 Dec 2009) | 1 line remove lib2to3 resource ........ r76869 | vinay.sajip | 2009-12-17 08:52:00 -0600 (Thu, 17 Dec 2009) | 1 line Issue #7529: logging: Minor correction to documentation. ........ r76882 | georg.brandl | 2009-12-19 11:30:28 -0600 (Sat, 19 Dec 2009) | 1 line #7527: use standard versionadded tags. ........ r76891 | georg.brandl | 2009-12-19 12:16:31 -0600 (Sat, 19 Dec 2009) | 1 line #7479: add note about function availability on Unices. ........ r76892 | georg.brandl | 2009-12-19 12:20:18 -0600 (Sat, 19 Dec 2009) | 1 line #7480: remove tautology. ........ r76924 | georg.brandl | 2009-12-20 08:28:05 -0600 (Sun, 20 Dec 2009) | 1 line Small indentation fix. ........ r77007 | gregory.p.smith | 2009-12-23 03:31:11 -0600 (Wed, 23 Dec 2009) | 3 lines Fix possible integer overflow in lchown and fchown functions. For issue1747858. ........ r77070 | amaury.forgeotdarc | 2009-12-27 14:06:44 -0600 (Sun, 27 Dec 2009) | 2 lines Fix a typo in comment ........ r77092 | georg.brandl | 2009-12-28 02:48:24 -0600 (Mon, 28 Dec 2009) | 1 line #7404: remove reference to non-existing example files. ........ r77096 | benjamin.peterson | 2009-12-28 14:51:17 -0600 (Mon, 28 Dec 2009) | 1 line document new fix_callable behavior ........ r77120 | georg.brandl | 2009-12-29 15:09:17 -0600 (Tue, 29 Dec 2009) | 1 line #7595: fix typo in argument default constant. ........ r77126 | amaury.forgeotdarc | 2009-12-29 17:06:17 -0600 (Tue, 29 Dec 2009) | 2 lines #7579: Add docstrings to the msvcrt module ........ r77155 | georg.brandl | 2009-12-30 13:03:00 -0600 (Wed, 30 Dec 2009) | 1 line We only support Windows NT derivatives now. ........ ................
2009-12-30 23:30:26 -04:00
the operating system. On failure, this raises :exc:`IOError`.