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