ChangeLog:

[newlib-cygwin.git] / winsup / doc / cygwinenv.sgml

<sect1 id="using-cygwinenv"><title>The <envar>CYGWIN</envar> environment
variable</title>

<sect2 id="cygwinenv-implemented-options">
<title>Implemented options</title>

<para>The <envar>CYGWIN</envar> environment variable is used to configure
many global settings for the Cygwin runtime system. It contains the options
listed below, separated by blank characters. Many options can be turned off
by prefixing with <literal>no</literal>.</para>

<itemizedlist mark="bullet">

<listitem>
<para><envar>codepage:[ansi|oem|utf8]</envar> - This option controls
which single- or multibyte character set is used for file and console
operations.  Windows is using UTF-16 characters internally and this
option specifies how 8-byte character sets are converted to UTF-16 and
vice versa.  The default setting is <envar>ansi</envar> which means,
conversion is based on the current ANSI codepage, typically 1252 in
many Western language versions of Windows.  The name originates from the
ANSI Latin1 (ISO 8859-1) standard, used in Windows 1.0, though the
character sets have since diverged from any standard.  The second
setting selects an older, DOS-based character set, containing various
line drawing and special characters.  It is called <envar>oem</envar>
since it was originally encoded in the firmware of IBM PCs by original
equipment manufacturers (OEMs).</para>
<para>If you find that some characters (especially non-US or 'graphical' ones)
do not display correctly in Cygwin, you can use this option to select an
appropriate codepage.  Finally, <envar>utf8</envar> treats all file names
and console characters as UTF-8 chars.  Please note that, for correct
operation, you have to set the environment variable LC_CTYPE to "C-UTF-8"
for the time being.  The reason is that newlib's multibyte conversion
functions require this setting.</para>
</listitem>

<listitem>
<para><envar>(no)dosfilewarning</envar> - If set, Cygwin will warn the
first time a user uses an "MS-DOS" style path name rather than a POSIX-style
path name.  Defaults to set.</para>
</listitem>

<listitem>
<para><envar>(no)envcache</envar> - If set, environment variable
conversions (between Win32 and POSIX) are cached.  Note that this may
cause problems if the mount table changes, as the cache is not invalidated
and may contain values that depend on the previous mount table
contents. Defaults to set.</para>
</listitem>

<listitem>
<para><envar>(no)export</envar> - If set, the final values of these
settings are re-exported to the environment as <envar>CYGWIN</envar> again.
Defaults to off.</para>
</listitem>

<listitem>
<para>
<envar>error_start:Win32filepath</envar> - if set, runs 
<filename>Win32filepath</filename> when cygwin encounters a fatal error,
which is useful for debugging.  <filename>Win32filepath</filename> is
usually set to the path to <command>gdb</command> or
<command>dumper</command>, for example
<filename>C:\cygwin\bin\gdb.exe</filename>. 
There is no default set.
</para>
</listitem>

<listitem>
<para><envar>forkchunk:32768</envar> - causes the <function>fork()</function>
to copy memory some number of bytes at a time, in the above example 
32768 bytes (32Kb) at a time. The default is to copy as many bytes as 
possible, which is preferable in most cases but may slow some older systems
down.
</para>
</listitem>

<listitem>
<para><envar>proc_retry:n</envar> - causes the <function>fork()</function> and <function>exec*()</function>
to retry n times when a child process fails due to certain windows-specific errors.  These errors usually
occur when processes are being started while a user is logging off.
</para>
</listitem>

<listitem>
<para><envar>(no)glob[:ignorecase]</envar> - if set, command line arguments
containing UNIX-style file wildcard characters (brackets, question mark,
asterisk, escaped with \) are expanded into lists of files that match 
those wildcards.
This is applicable only to programs running from a DOS command line prompt.
Default is set.</para>
<para>This option also accepts an optional <literal>[no]ignorecase</literal> modifer.
If supplied, wildcard matching is case insensitive.  The default is <literal>noignorecase</literal></para>
</listitem>

<listitem>
<para><envar>(no)reset_com</envar> - if set, serial ports are reset
to 9600-8-N-1 with no flow control when used. This is done at open
time and when handles are inherited.  Defaults to set.</para>
</listitem>

<listitem>
<para><envar>(no)strip_title</envar> - if set, strips the directory
part off the window title, if any.  Default is not set.</para>
</listitem>

<listitem>
<para><envar>(no)title</envar> - if set, the title bar
reflects the name of the program currently running.  Default is not
set.</para>
</listitem>

<listitem>
<para><envar>(no)tty</envar> - if set, Cygwin enables extra support
(i.e., termios) for UNIX-like ttys in the Windows console. 
It is not compatible with some Windows programs.
Defaults to not set, in which case the tty is opened in text mode.
Note that this has been changed such that ^D works as
expected instead of ^Z, and is settable via <command>stty</command>.
This option must be specified before starting a Cygwin shell 
and it cannot be changed in the shell.  It should not be set when using
other terminals (i.e., rxvt or xterm). 
</para>
</listitem>

<listitem>
<para><envar>(no)upcaseenv</envar> - if set, Cygwin converts all
environment variables to all-uppercase, when a Cygwin process is started
from a non-Cygwin native Windows process.  This is how it has been done
until Cygwin 1.5.  If not set, Cygwin does not change the case of environment
variables, except for a restricted set to maintain minimal backward
compatibility and for correct handling of certain essential variables.
The current list of always uppercased variables is:</para>
<screen>
  ALLUSERSPROFILE
  COMMONPROGRAMFILES
  COMPUTERNAME
  COMSPEC
  HOME
  HOMEDRIVE
  HOMEPATH
  NUMBER_OF_PROCESSORS
  OS
  PATH
  PATHEXT
  PROCESSOR_ARCHITECTURE
  PROCESSOR_IDENTIFIER
  PROCESSOR_LEVEL
  PROCESSOR_REVISION
  PROGRAMFILES
  SYSTEMDRIVE
  SYSTEMROOT
  TEMP
  TERM
  TMP
  TMPDIR
  WINDIR
</screen>
<para>Defaults to not set.</para>
</listitem>

<listitem>
<para><envar>(no)winsymlinks</envar> - if set, Cygwin creates
symlinks as Windows shortcuts with a special header and the R/O attribute
set. If not set, Cygwin creates symlinks as plain files with a magic number,
a path and the system attribute set. Defaults to not set since plain
file symlinks are faster to write and faster to read.</para>
</listitem>

</itemizedlist>

</sect2>

<sect2 id="cygwinenv-removed-options">
<title>Removed options</title>

<para>
Some CYGWIN options have been removed in Cygwin 1.7 for one reason or another.
These removed options are listed below.</para>

<itemizedlist mark="bullet">

<listitem>
<para><envar>(no)binmode</envar> - This option has been removed because
all file opens default to binary mode, unless the open mode has been specified
explicitely in the open(2) call.
</para>
</listitem>

<listitem>
<para><envar>check_case</envar> - This option has been removed in favor of
real case sensitivity and the per-mount option "posix=[0|1]".  For more
information, read the documentation in <xref linkend="mount-table"></xref> and
<xref linkend="pathnames-casesensitive"></xref>.</para>
</listitem>

<listitem>
<para><envar>(no)ntea</envar> -  This option has been removed since it
only fakes security which is considered dangerous and useless.  It also
created an uncontrollably large file on FAT and was entirely useless
on FAT32.</para>
</listitem>

<listitem>
<para><envar>(no)ntsec</envar> - This option has been removed in favor of
the per-mount option "acl"/"noacl".  For more information, read the
documentation in <xref linkend="mount-table"></xref>.</para>
</listitem>

<listitem>
<para><envar>(no)server</envar> - Originally this option had to be
enabled on the client side to use features only available when running
<command>cygserver</command>.  This option has been removed because Cygwin now
always tries to contact cygserver if a function is called which requires
cygserver being available.  For more information, read the documentation
in <xref linkend="using-cygserver"></xref>.</para>
</listitem>

<listitem>
<para><envar>(no)smbntsec</envar> - This option has been removed in favor of
the per-mount option "acl"/"noacl".  For more information, read the
documentation in <xref linkend="mount-table"></xref>.</para>
</listitem>

<listitem>
<para><envar>(no)transparent_exe</envar> - This option has been removed
because the behaviour it switched on is now the standard behaviour in
Cygwin.</para>
</listitem>

<listitem>
<para><envar>(no)traverse</envar> - This option has been removed because
traverse checking is not quite correctly implemented by Microsoft and
it's behaviour is getting worse with each new OS version.</para>
</listitem>

</itemizedlist>

</sect2>

</sect1>