wine/documentation/console

Console - First Pass
--------------------

Consoles are just xterms created with the -Sxxn switch.
A pty is opened and the master goes to the xterm side
and the slave is held by the wine side.  The console
itself it turned into a few HANDLE32s and is set 
to the STD_*_HANDLES.

It is possible to use the WriteFile and ReadFile commands
to write to a win32 console.  To accomplish this, all K32OBJs 
that support I/O have a read and write function pointer.
So, WriteFile calls K32OBJ_WriteFile which calls the K32OBJ's
write function pointer, which then finally calls write.

[this paragraph is now out of date]
If the command line console is to be inheirited or
a process inherits its parent's console (-- can that happen???),
the console is created at process init time via PROCESS_InheritConsole.
The 0, 1, and 2 file descriptors are duped to be the
STD_*_HANDLES in this case.  Also in this case a flag is set
to indicate that the console comes from the parent process or
command line.

If a process doesn't have a console at all, its 
pdb->console is set to NULL.  This helps indicate when
it is possible to create a new console (via AllocConsole).


When FreeConsole is called, all handles that the process has
open to the console are closed.  Like most k32objs, if the 
console's refcount reaches zero, its k32obj destroy function
is called.  The destroy kills the xterm if one was open.

Also like most k32 objects, we assume that (K32OBJ) header is the
first field so the casting (from K32OBJ *to CONSOLE *)
works correctly.

FreeConsole is called on process exit (in ExitProcess) if 
pdb->console is not NULL.


BUGS
----
Console processes do not inherit their parent's handles.  I think
there needs to be two cases, one where they have to inherit
the stdin/stdout/stderr from unix, and one where they have to
inherit from another windows app.

SetConsoleMode -- UNIX only has ICANON and various ECHOs
to play around with for processing input.  Win32 has
line-at-a-time processing, character processing, and
echo.  I'm putting together an intermediate driver
that will handle this (and hopefully won't be any more
buggy then the NT4 console implementation).


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

experimentation with NT4 yields that:

WriteFile
---------
	o does not truncate file on 0 length write
	o 0 length write or error on write changes numcharswritten to 0
	o 0 length write returns TRUE
	o works with console handles

_lwrite
-------
	o does truncate/expand file at current position on 0 length write
	o returns 0 on a zero length write
	o works with console handles (typecasted)

WriteConsole
------------
	o expects only console handles


SetFilePointer
--------------
	o returns -1 (err 6) when used with a console handle


FreeConsole
-----------
	o even when all the handles to it are freed, the win32 console
	  stays visible, the only way I could find to free it
	  was via the FreeConsole


Is it possible to interrupt win32's FileWrite?  I'm not sure.
It may not be possible to interrupt any system calls.


DOS (Generic) Console Support
-----------------------------

I. Command Line Configuration

   DOS consoles must be configured either on the command line or in a dot
   resource file (.console). A typical configuration consists of a string
   of driver keywords separated by plus ('+') signs. To change the 
   configuration on the command-line, use the -console switch.

   For example:

      wine -console ncurses+xterm <apllication>
   
   Possible drivers:

      tty	- Generic text-only support. Supports redirection.
      ncurses	- Full-screen graphical support with color.
      xterm	- Load a new window to display the console in. Also
                  supports resizing windows.


II. Wine.conf Configuration

   In the wine.conf file, you can create a section called [console] that
   contains configuration options that are respected by the assorted
   console drivers.

   Current Options:

      XtermProg=<program>

         Use this program instead of xterm. This eliminates the need for a
         recompile. See the table below for a comparison of various
         terminals.

      InitialRows=<number>

         Attempt to start all drivers with this number of rows. This
         causes xterms to be resized, for instance.

         Note: This information is passed on the command-line with the
         -g switch.

      InitialColumns=<number>

         Attempt to start all drivers with this number of columns. This
         causes xterms to be resized, for instance.

         Note: This information is passed on the command-line with the
         -g switch.

      TerminalType=<name>

         Tell any driver that is interested (ncurses) which termcap
         and/or terminfo type to use. The default is xterm which is
         appropiate for most uses. "nxterm" may give you better support
         if you use that terminal. This can also be changed to
         "linux" (or "console" on older systems) if you manage to hack
         the ability to write to the console into this driver.

III. Terminal Types

   There are a large number of potential terminals that can be used with
   Wine, depending on what you are trying to do. Unfortunately, I am still
   looking for the "best" driver combination.

   Note that 'slave' is required for use in Wine, currently.

   Program     | Color? | Resizing? | Slave?
   -----------------------------------------
   xterm	   N          Y         Y
   nxterm          Y          N         Y
   rxvt            Y          ?         N
   
   (linux console) Y          N         ?

   As X terminals typically use a 24x80 screen resolution rather than the
   typical 25x80 one, it is necessary to resize the screen to allow a DOS
   program to work full-screen. There is a wine.conf option to work
   around this in some cases but run-time resizing will be disabled.