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 

    11 These functions provide access to some useful capabilities on Windows platforms.

    12 Some higher-level modules use these functions to build the  Windows

    13 implementations of their services.  For example, the :mod:`getpass` module uses

    14 this in the implementation of the :func:`getpass` function.

    15 

    16 Further documentation on these functions can be found in the Platform API

    17 documentation.

    18 

    19 The module implements both the normal and wide char variants of the console I/O

    20 api. The normal API deals only with ASCII characters and is of limited use

    21 for internationalized applications. The wide char API should be used where 

    22 ever possible

    23 

    24 .. _msvcrt-files:

    25 

    26 File 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 

    83 Console 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 

   149 Other 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