"msvcrt" --- Rotinas úteis do runtime MS VC++
*********************************************

======================================================================

Essas funções fornecem acesso a alguns recursos úteis em plataformas
Windows. Alguns módulos de nível superior usam essas funções para
construir as implementações de seus serviços no Windows. Por exemplo,
o módulo "getpass" usa isso na implementação da função "getpass()".

Mais documentação sobre essas funções pode ser encontrada na
documentação da API da plataforma.

O módulo implementa as variantes normal e ampla de caracteres da API
de E/S do console. A API normal lida apenas com caracteres ASCII e é
de uso limitado para aplicativos internacionalizados. A API ampla de
caracteres deve ser usada sempre que possível.

Alterado na versão 3.3: As operações neste módulo agora levantam
"OSError" onde "IOError" foi levantado.


Operações com arquivos
======================

msvcrt.locking(fd, mode, nbytes)

   Trava parte de um arquivo com base no descritor de arquivo *fd* do
   runtime do C. Levanta "OSError" em caso de falha. A região travada
   do arquivo se estende da posição atual do arquivo por *nbytes*
   bytes e pode continuar além do final do arquivo. *mode* deve ser
   uma das constantes "LK_*" listadas abaixo. Várias regiões em um
   arquivo podem ser travadas ao mesmo tempo, mas não podem se
   sobrepor. Regiões adjacentes não são mescladas; elas devem ser
   destravadas individualmente.

   Levanta um evento de auditoria "msvcrt.locking" com os argumentos
   "fd", "mode", "nbytes".

msvcrt.LK_LOCK
msvcrt.LK_RLCK

   Trava os bytes especificados. Se os bytes não puderem ser travados,
   o programa tenta novamente imediatamente após 1 segundo. Se, após
   10 tentativas, os bytes não puderem ser travados, "OSError" é
   levantada.

msvcrt.LK_NBLCK
msvcrt.LK_NBRLCK

   Trava os bytes especificados. Se os bytes não puderem ser travados,
   uma exceção "OSError" é levantada.

msvcrt.LK_UNLCK

   Destrava os bytes especificados, que devem ter sido travados
   anteriormente.

msvcrt.setmode(fd, flags)

   Defina o modo de conversão de final de linha para o descritor de
   arquivo *fd*. Para configurá-lo no modo de texto, *flags* deve ser
   "os.O_TEXT"; para binário, deve ser "os.O_BINARY".

msvcrt.open_osfhandle(handle, flags)

   Crie um descritor de arquivo de tempo de execução do C a partir do
   identificador de arquivo *handle*. O parâmetro *flags* deve ser um
   OU bit a bit de "os.O_APPEND", "os.O_RDONLY", "os.O_TEXT" e
   "os.O_NOINHERIT". O descritor de arquivo retornado pode ser usado
   como parâmetro para "os.fdopen()" para criar um objeto de arquivo.

   O descritor de arquivo é herdável por padrão. Passe o sinalizador
   "os.O_NOINHERIT" para torná-lo não herdável.

   Levanta um evento de auditoria "msvcrt.open_osfhandle" com os
   argumentos "handle", "flags".

msvcrt.get_osfhandle(fd)

   Retorna o identificador de arquivo para o descritor de arquivo
   *fd*. Levanta "OSError" se *fd* não for reconhecido.

   Levanta um evento de auditoria "msvcrt.get_osfhandle" com o
   argumento "fd".


E/S de console
==============

msvcrt.kbhit()

   Returns a nonzero value if a keypress is waiting to be read.
   Otherwise, return 0.

msvcrt.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 "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 "Control"-"C" keypress cannot be read with this
   function.

msvcrt.getwch()

   Variante com caractere largo de "getch()", retornando um valor
   Unicode.

msvcrt.getche()

   Similar to "getch()", but the keypress will be echoed if it
   represents a printable character.

msvcrt.getwche()

   Variante com caractere largo de "getche()", retornando um valor
   Unicode.

msvcrt.putch(char)

   Imprime a string de bytes *char* no console sem armazenar em
   buffer.

msvcrt.putwch(unicode_char)

   Variante com caractere largo de "putch()", retornando um valor
   Unicode.

msvcrt.ungetch(char)

   Faz com que a string de bytes *char* seja "empurrada" para o buffer
   do console; será o próximo caractere lido por "getch()" ou
   "getche()".

msvcrt.ungetwch(unicode_char)

   Variante com caractere largo de "ungetch()", retornando um valor
   Unicode.


Outras funções
==============

msvcrt.heapmin()

   Força o heap "malloc()" a ser limpado e retorna os blocos não
   utilizados ao sistema operacional. Em caso de falha, isso levanta
   "OSError".

msvcrt.set_error_mode(mode)

   Changes the location where the C runtime writes an error message
   for an error that might end the program. *mode* must be one of the
   "OUT_*" constants listed below  or "REPORT_ERRMODE". Returns the
   old setting or -1 if an error occurs. Only available in debug build
   of Python.

msvcrt.OUT_TO_DEFAULT

   Error sink is determined by the app's type. Only available in debug
   build of Python.

msvcrt.OUT_TO_STDERR

   Error sink is a standard error. Only available in debug build of
   Python.

msvcrt.OUT_TO_MSGBOX

   Error sink is a message box. Only available in debug build of
   Python.

msvcrt.REPORT_ERRMODE

   Report the current error mode value. Only available in debug build
   of Python.

msvcrt.CrtSetReportMode(type, mode)

   Specifies the destination or destinations for a specific report
   type generated by "_CrtDbgReport()" in the MS VC++ runtime. *type*
   must be one of the "CRT_*" constants listed below. *mode* must be
   one of the "CRTDBG_*" constants listed below. Only available in
   debug build of Python.

msvcrt.CrtSetReportFile(type, file)

   After you use "CrtSetReportMode()" to specify "CRTDBG_MODE_FILE",
   you can specify the file handle to receive the message text. *type*
   must be one of the "CRT_*" constants listed below. *file* should be
   the file handle your want specified. Only available in debug build
   of Python.

msvcrt.CRT_WARN

   Warnings, messages, and information that doesn't need immediate
   attention.

msvcrt.CRT_ERROR

   Errors, unrecoverable problems, and issues that require immediate
   attention.

msvcrt.CRT_ASSERT

   Assertion failures.

msvcrt.CRTDBG_MODE_DEBUG

   Writes the message to the debugger's output window.

msvcrt.CRTDBG_MODE_FILE

   Writes the message to a user-supplied file handle.
   "CrtSetReportFile()" should be called to define the specific file
   or stream to use as the destination.

msvcrt.CRTDBG_MODE_WNDW

   Creates a message box to display the message along with the
   "Abort", "Retry", and "Ignore" buttons.

msvcrt.CRTDBG_REPORT_MODE

   Returns current *mode* for the specified *type*.

msvcrt.CRT_ASSEMBLY_VERSION

   A versão do CRT Assembly, do arquivo de cabeçalho "crtassem.h".

msvcrt.VC_ASSEMBLY_PUBLICKEYTOKEN

   O token da chave pública do VC Assembly, do arquivo de cabeçalho
   "crtassem.h".

msvcrt.LIBRARIES_ASSEMBLY_NAME_PREFIX

   O prefixo do nome de Libraries Assembly, do arquivo de cabeçalho
   "crtassem.h".
