documentation/consoles.sgml

   1   <chapter id="consoles">
   2     <title>Consoles in Wine</title>
   3
   4     <sect1 id="wine-consoles">
   5       <title>Consoles</title>
   6
   7       <para>
   8         Written by &name-john-richardson; <email>&email-john-richardson;</email>
   9         Maintained by &name-joseph-pranevich; <email>&email-joseph-pranevich;</email>
  10       </para>
  11       <para>
  12         (Extracted from <filename>wine/documentation/console</filename>)
  13       </para>
  14
  15       <sect2>
  16         <title>Console - First Pass</title>
  17
  18         <para>
  19           Consoles are just xterms created with the
  20           <parameter>-Sxxn</parameter> switch. A
  21           <systemitem>pty</systemitem> is opened and the master goes
  22           to the <filename>xterm</filename> side and the slave is held
  23           by the wine side.  The console itself is turned into a few
  24           <type>HANDLE32</type>s and is set to the
  25           <varname>STD_*_HANDLES</varname>.
  26         </para>
  27         <para>
  28           It is possible to use the <function>WriteFile</function> and
  29           <function>ReadFile</function> commands to write to a win32
  30           console.  To accomplish this, all <type>K32OBJ</type>s that
  31           support I/O have a read and write function pointer. So,
  32           <function>WriteFile</function> calls
  33           <function>K32OBJ_WriteFile</function> which calls the
  34           <type>K32OBJ</type>'s write function pointer, which then
  35           finally calls <function>write</function>.
  36         </para>
  37         <para>
  38           <emphasis>[this paragraph is now out of date]</emphasis> If
  39           the command line console is to be inherited or a process
  40           inherits its parent's console (-- can that happen???), the
  41           console is created at process init time via
  42           <function>PROCESS_InheritConsole</function>. The
  43           <literal>0</literal>, <literal>1</literal>, and
  44           <literal>2</literal> file descriptors are duped to be the
  45           <varname>STD_*_HANDLES</varname> in this case.  Also in this
  46           case a flag is set to indicate that the console comes from
  47           the parent process or command line.
  48         </para>
  49         <para>
  50           If a process doesn't have a console at all, its
  51           <varname>pdb-&gt;console</varname> is set to
  52           <constant>NULL</constant>.  This helps indicate when it is
  53           possible to create a new console (via
  54           <function>AllocConsole</function>).
  55         </para>
  56         <para>
  57           When <function>FreeConsole</function> is called, all handles that the process has
  58           open to the console are closed.  Like most <type>K32OBJ</type>s, if the
  59           console's refcount reaches zero, its <type>K32OBJ</type> destroy function
  60           is called.  The destroy kills the xterm if one was open.
  61         </para>
  62         <para>
  63           Also like most k32 objects, we assume that
  64           (<type>K32OBJ</type>) header is the first field so the
  65           casting (from <type>K32OBJ*</type>to <type>CONSOLE*</type>)
  66           works correctly.
  67         </para>
  68         <para>
  69           <function>FreeConsole</function> is called on process exit
  70           (in <function>ExitProcess</function>) if
  71           <varname>pdb-&gt;console</varname> is not
  72           <constant>NULL</constant>.
  73         </para>
  74       </sect2>
  75
  76       <sect2>
  77         <title>BUGS</title>
  78
  79         <para>
  80           Console processes do not inherit their parent's handles.  I
  81           think there needs to be two cases, one where they have to
  82           inherit the <filename>stdin</filename> /
  83           <filename>stdout</filename> / <filename>stderr</filename>
  84           from unix, and one where they have to inherit from another
  85           windows app.
  86         </para>
  87         <para>
  88           <function>SetConsoleMode</function> -- UNIX only has
  89           <constant>ICANON</constant> and various
  90           <constant>ECHO</constant>s to play around with for
  91           processing input.  Win32 has line-at-a-time processing,
  92           character processing, and echo. I'm putting together an
  93           intermediate driver that will handle this (and hopefully
  94           won't be any more buggy than the NT4 console
  95           implementation).
  96         </para>
  97       </sect2>
  98
  99       <sect2>
 100         <title>Experimentation</title>
 101
 102         <para>
 103           experimentation with NT4 yields that:
 104         </para>
 105
 106         <variablelist>
 107           <varlistentry>
 108             <term><function>WriteFile</function></term>
 109             <listitem>
 110               <itemizedlist>
 111                 <listitem>
 112                   <para>does not truncate file on 0 length write</para>
 113                 </listitem>
 114                 <listitem>
 115                   <para>
 116                     0 length write or error on write changes
 117                     <varname>numcharswritten</varname> to
 118                     <literal>0</literal>
 119                   </para>
 120                 </listitem>
 121                 <listitem>
 122                   <para>0 length write returns <constant>TRUE</constant></para>
 123                 </listitem>
 124                 <listitem>
 125                   <para>works with console handles</para>
 126                 </listitem>
 127               </itemizedlist>
 128             </listitem>
 129           </varlistentry>
 130           <varlistentry>
 131             <term><function>_lwrite</function></term>
 132             <listitem>
 133               <itemizedlist>
 134                 <listitem>
 135                   <para>does truncate/expand file at current position on 0 length write</para>
 136                 </listitem>
 137                 <listitem>
 138                   <para>returns 0 on a zero length write</para>
 139                 </listitem>
 140                 <listitem>
 141                   <para>works with console handles (typecasted)</para>
 142                 </listitem>
 143               </itemizedlist>
 144             </listitem>
 145           </varlistentry>
 146           <varlistentry>
 147             <term><function>WriteConsole</function></term>
 148             <listitem>
 149               <itemizedlist>
 150                 <listitem>
 151                   <para>expects only console handles</para>
 152                 </listitem>
 153               </itemizedlist>
 154             </listitem>
 155           </varlistentry>
 156           <varlistentry>
 157             <term><function>SetFilePointer</function></term>
 158             <listitem>
 159               <itemizedlist>
 160                 <listitem>
 161                   <para>returns -1 (err 6) when used with a console handle</para>
 162                 </listitem>
 163               </itemizedlist>
 164             </listitem>
 165           </varlistentry>
 166           <varlistentry>
 167             <term><function>FreeConsole</function></term>
 168             <listitem>
 169               <itemizedlist>
 170                 <listitem>
 171                   <para>
 172                     even when all the handles to it are freed, the
 173                     win32 console stays visible, the only way I could
 174                     find to free it was via the <function>FreeConsole</function>
 175                   </para>
 176                 </listitem>
 177               </itemizedlist>
 178             </listitem>
 179           </varlistentry>
 180         </variablelist>
 181
 182         <para>
 183           Is it possible to interrupt win32's
 184           <function>FileWrite</function>?  I'm not sure. It may not be
 185           possible to interrupt any system calls.
 186         </para>
 187       </sect2>
 188
 189       <sect2>
 190         <title>DOS (Generic) Console Support</title>
 191
 192         <sect3>
 193           <title>I. Command Line Configuration</title>
 194
 195           <para>
 196             DOS consoles must be configured either on the command line
 197             or in a dot resource file (<filename>.console</filename>).
 198             A typical configuration consists of a string of driver
 199             keywords separated by plus ('+') signs. To change the
 200             configuration on the command-line, use the
 201             <parameter>-console</parameter> switch.
 202           </para>
 203           <para>
 204             For example:
 205           </para>
 206           <screen>
 207 wine -console ncurses+xterm &lt;application&gt;
 208           </screen>
 209           <para>
 210             Possible drivers:
 211           </para>
 212
 213           <variablelist>
 214             <varlistentry>
 215               <term>tty:</term>
 216               <listitem>
 217                 <para>Generic text-only support. Supports redirection.</para>
 218               </listitem>
 219             </varlistentry>
 220             <varlistentry>
 221               <term>ncurses:</term>
 222               <listitem>
 223                 <para>Full-screen graphical support with color.</para>
 224               </listitem>
 225             </varlistentry>
 226             <varlistentry>
 227               <term>xterm:</term>
 228               <listitem>
 229                 <para>
 230                   Load a new window to display the console in. Also
 231                   supports resizing windows.
 232                 </para>
 233               </listitem>
 234             </varlistentry>
 235           </variablelist>
 236         </sect3>
 237
 238         <sect3>
 239           <title>II. wine config file configuration</title>
 240
 241           <para>
 242             In the wine config file, you can create
 243             a section called [console] that contains configuration
 244             options that are respected by the assorted console
 245             drivers.
 246           </para>
 247           <para>
 248             Current Options:
 249           </para>
 250
 251           <variablelist>
 252             <varlistentry>
 253               <term>XtermProg=&lt;program&gt;</term>
 254               <listitem>
 255                 <para>
 256                   Use this program instead of
 257                   <command>xterm</command>. This eliminates the need
 258                   for a recompile. See the table below for a
 259                   comparison of various terminals.
 260                 </para>
 261               </listitem>
 262             </varlistentry>
 263             <varlistentry>
 264               <term>InitialRows=&lt;number&gt;</term>
 265               <listitem>
 266                 <para>
 267                   Attempt to start all drivers with this number of
 268                   rows. This causes xterms to be resized, for
 269                   instance.
 270                 </para>
 271                 <note>
 272                   <para>
 273                     This information is passed on the command-line
 274                     with the <parameter>-g</parameter> switch.
 275                   </para>
 276                 </note>
 277               </listitem>
 278             </varlistentry>
 279             <varlistentry>
 280               <term>InitialColumns=&lt;number&gt;</term>
 281               <listitem>
 282                 <para>
 283                   Attempt to start all drivers with this number of
 284                   columns. This causes xterms to be resized, for
 285                   instance.
 286                 </para>
 287                 <note>
 288                   <para>
 289                     This information is passed on the command-line
 290                     with the <parameter>-g</parameter> switch.
 291                   </para>
 292                 </note>
 293               </listitem>
 294             </varlistentry>
 295             <varlistentry>
 296               <term>TerminalType=&lt;name&gt;</term>
 297               <listitem>
 298                 <para>
 299                   Tell any driver that is interested (ncurses) which
 300                   termcap and/or terminfo type to use. The default is
 301                   xterm which is appropriate for most uses.
 302                   <command>nxterm</command> may give you better
 303                   support if you use that terminal. This can also be
 304                   changed to "linux" (or "console" on older systems)
 305                   if you manage to hack the ability to write to the
 306                   console into this driver.
 307                 </para>
 308               </listitem>
 309             </varlistentry>
 310           </variablelist>
 311         </sect3>
 312
 313         <sect3>
 314           <title>III. Terminal Types</title>
 315
 316           <para>
 317             There are a large number of potential terminals that can
 318             be used with Wine, depending on what you are trying to do.
 319             Unfortunately, I am still looking for the "best" driver
 320             combination.
 321           </para>
 322           <note>
 323             <para>
 324               'slave' is required for use in Wine, currently.
 325             </para>
 326           </note>
 327
 328           <informaltable>
 329             <tgroup cols="4">
 330               <thead>
 331                 <row>
 332                   <entry>Program</entry>
 333                   <entry>Color?</entry>
 334                   <entry>Resizing?</entry>
 335                   <entry>Slave?</entry>
 336                 </row>
 337               </thead>
 338               <tfoot>
 339                 <row>
 340                   <entry>(linux console)</entry>
 341                   <entry>Y</entry>
 342                   <entry>N</entry>
 343                   <entry>?</entry>
 344                 </row>
 345               </tfoot>
 346               <tbody>
 347                 <row>
 348                   <entry>xterm</entry>
 349                   <entry>N</entry>
 350                   <entry>Y</entry>
 351                   <entry>Y</entry>
 352                 </row>
 353                 <row>
 354                   <entry>nxterm</entry>
 355                   <entry>Y</entry>
 356                   <entry>N</entry>
 357                   <entry>Y</entry>
 358                 </row>
 359                 <row>
 360                   <entry>rxvt</entry>
 361                   <entry>Y</entry>
 362                   <entry>?</entry>
 363                   <entry>N</entry>
 364                 </row>
 365               </tbody>
 366             </tgroup>
 367           </informaltable>
 368
 369           <para>
 370             As X terminals typically use a 24x80 screen resolution
 371             rather than the typical 25x80 one, it is necessary to
 372             resize the screen to allow a DOS program to work
 373             full-screen. There is a wine config file
 374             option to work around this in some cases but run-time
 375             resizing will be disabled.
 376           </para>
 377         </sect3>
 378       </sect2>
 379     </sect1>
 380   </chapter>
 381
 382 <!-- Keep this comment at the end of the file
 383 Local variables:
 384 mode: sgml
 385 sgml-parent-document:("wine-doc.sgml" "set" "book" "part" "chapter" "")
 386 End:
 387 -->