documentation/console

   1
   2 Console - First Pass
   3 --------------------
   4
   5 Consoles are just xterms created with the -Sxxn switch.
   6 A pty is opened and the master goes to the xterm side
   7 and the slave is held by the wine side.  The console
   8 itself it turned into a few HANDLE32s and is set
   9 to the STD_*_HANDLES.
  10
  11 It is possible to use the WriteFile and ReadFile commands
  12 to write to a win32 console.  To accomplish this, all K32OBJs
  13 that support I/O have a read and write function pointer.
  14 So, WriteFile calls K32OBJ_WriteFile which calls the K32OBJ's
  15 write function pointer, which then finally calls write.
  16
  17 [this paragraph is now out of date]
  18 If the command line console is to be inheirited or
  19 a process inherits its parent's console (-- can that happen???),
  20 the console is created at process init time via PROCESS_InheritConsole.
  21 The 0, 1, and 2 file descriptors are duped to be the
  22 STD_*_HANDLES in this case.  Also in this case a flag is set
  23 to indicate that the console comes from the parent process or
  24 command line.
  25
  26 If a process doesn't have a console at all, its
  27 pdb->console is set to NULL.  This helps indicate when
  28 it is possible to create a new console (via AllocConsole).
  29
  30
  31 When FreeConsole is called, all handles that the process has
  32 open to the console are closed.  Like most k32objs, if the
  33 console's refcount reaches zero, its k32obj destroy function
  34 is called.  The destroy kills the xterm if one was open.
  35
  36 Also like most k32 objects, we assume that (K32OBJ) header is the
  37 first field so the casting (from K32OBJ *to CONSOLE *)
  38 works correctly.
  39
  40 FreeConsole is called on process exit (in ExitProcess) if
  41 pdb->console is not NULL.
  42
  43
  44 BUGS
  45 ----
  46 Console processes do not inherit their parent's handles.  I think
  47 there needs to be two cases, one where they have to inherit
  48 the stdin/stdout/stderr from unix, and one where they have to
  49 inherit from another windows app.
  50
  51 SetConsoleMode -- UNIX only has ICANON and various ECHOs
  52 to play around with for processing input.  Win32 has
  53 line-at-a-time processing, character processing, and
  54 echo.  I'm putting together an intermediate driver
  55 that will handle this (and hopefully won't be any more
  56 buggy then the NT4 console implementation).
  57
  58
  59 ================================================================
  60
  61 experimentation with NT4 yields that:
  62
  63 WriteFile
  64 ---------
  65         o does not truncate file on 0 length write
  66         o 0 length write or error on write changes numcharswritten to 0
  67         o 0 length write returns TRUE
  68         o works with console handles
  69
  70 _lwrite
  71 -------
  72         o does truncate/expand file at current position on 0 length write
  73         o returns 0 on a zero length write
  74         o works with console handles (typecasted)
  75
  76 WriteConsole
  77 ------------
  78         o expects only console handles
  79
  80
  81 SetFilePointer
  82 --------------
  83         o returns -1 (err 6) when used with a console handle
  84
  85
  86 FreeConsole
  87 -----------
  88         o even when all the handles to it are freed, the win32 console
  89           stays visible, the only way I could find to free it
  90           was via the FreeConsole
  91
  92
  93 Is it possible to interrupt win32's FileWrite?  I'm not sure.
  94 It may not be possible to interrupt any system calls.
  95
  96
  97 DOS (Generic) Console Support
  98 -----------------------------
  99
 100 I. Command Line Configuration
 101
 102    DOS consoles must be configured either on the command line or in a dot
 103    resource file (.console). A typical configuration consists of a string
 104    of driver keywords separated by plus ('+') signs. To change the
 105    configuration on the command-line, use the -console switch.
 106
 107    For example:
 108
 109       wine -console ncurses+xterm <apllication>
 110
 111    Possible drivers:
 112
 113       tty       - Generic text-only support. Supports redirection.
 114       ncurses   - Full-screen graphical support with color.
 115       xterm     - Load a new window to display the console in. Also
 116                   supports resizing windows.
 117
 118
 119 II. Wine.conf Configuration
 120
 121    In the wine.conf file, you can create a section called [console] that
 122    contains configuration options that are respected by the assorted
 123    console drivers.
 124
 125    Current Options:
 126
 127       XtermProg=<program>
 128
 129          Use this program instead of xterm. This eliminates the need for a
 130          recompile. See the table below for a comparison of various
 131          terminals.
 132
 133       InitialRows=<number>
 134
 135          Attempt to start all drivers with this number of rows. This
 136          causes xterms to be resized, for instance.
 137
 138          Note: This information is passed on the command-line with the
 139          -g switch.
 140
 141       InitialColumns=<number>
 142
 143          Attempt to start all drivers with this number of columns. This
 144          causes xterms to be resized, for instance.
 145
 146          Note: This information is passed on the command-line with the
 147          -g switch.
 148
 149       TerminalType=<name>
 150
 151          Tell any driver that is interested (ncurses) which termcap
 152          and/or terminfo type to use. The default is xterm which is
 153          appropiate for most uses. "nxterm" may give you better support
 154          if you use that terminal. This can also be changed to
 155          "linux" (or "console" on older systems) if you manage to hack
 156          the ability to write to the console into this driver.
 157
 158 III. Terminal Types
 159
 160    There are a large number of potential terminals that can be used with
 161    Wine, depending on what you are trying to do. Unfortunately, I am still
 162    looking for the "best" driver combination.
 163
 164    Note that 'slave' is required for use in Wine, currently.
 165
 166    Program     | Color? | Resizing? | Slave?
 167    -----------------------------------------
 168    xterm           N          Y         Y
 169    nxterm          Y          N         Y
 170    rxvt            Y          ?         N
 171
 172    (linux console) Y          N         ?
 173
 174    As X terminals typically use a 24x80 screen resolution rather than the
 175    typical 25x80 one, it is necessary to resize the screen to allow a DOS
 176    program to work full-screen. There is a wine.conf option to work
 177    around this in some cases but run-time resizing will be disabled.