winsup/doc/cygwinenv.sgml

   1 <sect1 id="using-cygwinenv"><title>The <envar>CYGWIN</envar> environment
   2 variable</title>
   3
   4 <sect2 id="cygwinenv-implemented-options">
   5 <title>Implemented options</title>
   6
   7 <para>The <envar>CYGWIN</envar> environment variable is used to configure
   8 many global settings for the Cygwin runtime system. It contains the options
   9 listed below, separated by blank characters. Many options can be turned off
  10 by prefixing with <literal>no</literal>.</para>
  11
  12 <itemizedlist mark="bullet">
  13
  14 <listitem>
  15 <para><envar>(no)dosfilewarning</envar> - If set, Cygwin will warn the
  16 first time a user uses an "MS-DOS" style path name rather than a POSIX-style
  17 path name.  Defaults to set.</para>
  18 </listitem>
  19
  20 <listitem>
  21 <para><envar>(no)envcache</envar> - If set, environment variable
  22 conversions (between Win32 and POSIX) are cached.  Note that this may
  23 cause problems if the mount table changes, as the cache is not invalidated
  24 and may contain values that depend on the previous mount table
  25 contents. Defaults to set.</para>
  26 </listitem>
  27
  28 <listitem>
  29 <para><envar>(no)export</envar> - If set, the final values of these
  30 settings are re-exported to the environment as <envar>CYGWIN</envar> again.
  31 Defaults to off.</para>
  32 </listitem>
  33
  34 <listitem>
  35 <para>
  36 <envar>error_start:Win32filepath</envar> - if set, runs
  37 <filename>Win32filepath</filename> when cygwin encounters a fatal error,
  38 which is useful for debugging.  <filename>Win32filepath</filename> is
  39 usually set to the path to <command>gdb</command> or
  40 <command>dumper</command>, for example
  41 <filename>C:\cygwin\bin\gdb.exe</filename>.
  42 There is no default set.
  43 </para>
  44 </listitem>
  45
  46 <listitem>
  47 <para><envar>forkchunk:32768</envar> - causes <function>fork()</function>
  48 to copy memory some number of bytes at a time, in the above example
  49 32768 bytes (32Kb) at a time. The default is to copy as many bytes as
  50 possible, which is preferable in most cases but may slow some older systems
  51 down.
  52 </para>
  53 </listitem>
  54
  55 <listitem>
  56 <para><envar>proc_retry:n</envar> - causes <function>fork()</function> and
  57 <function>exec*()</function> to retry n times when a child process fails
  58 due to certain windows-specific errors.  These errors usually occur when
  59 processes are being started while a user is logging off.
  60 </para>
  61 </listitem>
  62
  63 <listitem>
  64 <para><envar>(no)glob[:ignorecase]</envar> - if set, command line arguments
  65 containing UNIX-style file wildcard characters (brackets, question mark,
  66 asterisk, escaped with \) are expanded into lists of files that match
  67 those wildcards.
  68 This is applicable only to programs running from a DOS command line prompt.
  69 Default is set.</para>
  70 <para>This option also accepts an optional <literal>[no]ignorecase</literal> modifer.
  71 If supplied, wildcard matching is case insensitive.  The default is <literal>noignorecase</literal></para>
  72 </listitem>
  73
  74 <listitem>
  75 <para><envar>(no)reset_com</envar> - if set, serial ports are reset
  76 to 9600-8-N-1 with no flow control when used. This is done at open
  77 time and when handles are inherited.  Defaults to set.</para>
  78 </listitem>
  79
  80 <listitem>
  81 <para><envar>(no)strip_title</envar> - if set, strips the directory
  82 part off the window title, if any.  Default is not set.</para>
  83 </listitem>
  84
  85 <listitem>
  86 <para><envar>(no)title</envar> - if set, the title bar
  87 reflects the name of the program currently running.  Default is not
  88 set.</para>
  89 </listitem>
  90
  91 <listitem>
  92 <para><envar>(no)tty</envar> - if set, Cygwin enables extra support
  93 (i.e., termios) for UNIX-like ttys in the Windows console.
  94 It is not compatible with some Windows programs.
  95 Defaults to not set, in which case the tty is opened in text mode.
  96 Note that this has been changed such that ^D works as
  97 expected instead of ^Z, and is settable via <command>stty</command>.
  98 This option must be specified before starting a Cygwin shell
  99 and it cannot be changed in the shell.  It should not be set when using
 100 other terminals (i.e., rxvt or xterm).
 101 </para>
 102 </listitem>
 103
 104 <listitem>
 105 <para><envar>(no)upcaseenv</envar> - if set, Cygwin converts all
 106 environment variables to all-uppercase, when a Cygwin process is started
 107 from a non-Cygwin native Windows process.  This was the default behavior in
 108 releases prior to Cygwin 1.7.  If not set, Cygwin does not change the case
 109 of environment variables, except for a restricted set to maintain minimal
 110 backward compatibility and for correct handling of certain essential
 111 variables.  The current list of always uppercased variables is:</para>
 112 <screen>
 113   ALLUSERSPROFILE
 114   COMMONPROGRAMFILES
 115   COMPUTERNAME
 116   COMSPEC
 117   HOME
 118   HOMEDRIVE
 119   HOMEPATH
 120   NUMBER_OF_PROCESSORS
 121   OS
 122   PATH
 123   PATHEXT
 124   PROCESSOR_ARCHITECTURE
 125   PROCESSOR_IDENTIFIER
 126   PROCESSOR_LEVEL
 127   PROCESSOR_REVISION
 128   PROGRAMFILES
 129   SYSTEMDRIVE
 130   SYSTEMROOT
 131   TEMP
 132   TERM
 133   TMP
 134   TMPDIR
 135   WINDIR
 136 </screen>
 137 <para>Defaults to not set.</para>
 138 </listitem>
 139
 140 <listitem>
 141 <para><envar>(no)winsymlinks</envar> - if set, Cygwin creates
 142 symlinks as Windows shortcuts with a special header and the R/O attribute
 143 set. If not set, Cygwin creates symlinks as plain files with a magic number,
 144 a path and the system attribute set. Defaults to not set since plain
 145 file symlinks are faster to write and faster to read.</para>
 146
 147 <para>Please note that symlinks created under Cygwin 1.7 or later are
 148 not readable by older Cygwin releases because the new symlinks use UTF-16
 149 to encode the target filename, while the old symlinks used the current
 150 ANSI or OEM charset.</para>
 151 </listitem>
 152
 153 </itemizedlist>
 154
 155 </sect2>
 156
 157 <sect2 id="cygwinenv-removed-options">
 158 <title>Obsolete options</title>
 159
 160 <para>
 161 Certain CYGWIN options available in past releases have been removed in
 162 Cygwin 1.7 for one reason or another.  These obsolete options are listed
 163 below.</para>
 164
 165 <itemizedlist mark="bullet">
 166
 167 <listitem>
 168 <para><envar>(no)binmode</envar> - This option has been removed because
 169 all file opens default to binary mode, unless the open mode has been specified
 170 explicitly in the open(2) call.
 171 </para>
 172 </listitem>
 173
 174 <listitem>
 175 <para><envar>check_case</envar> - This option has been removed in favor of
 176 real case sensitivity and the per-mount option "posix=[0|1]".  For more
 177 information, read the documentation in <xref linkend="mount-table"></xref> and
 178 <xref linkend="pathnames-casesensitive"></xref>.</para>
 179 </listitem>
 180
 181 <listitem>
 182 <para><envar>codepage:[ansi|oem]</envar> - This option controled
 183 which character set is used for file and console operations.  Since Cygwin
 184 is now doing all character conversion by itself, depending on the
 185 application call to the <function>setlocale()</function> function, and in
 186 turn by the setting of the environment variables <envar>$LANG</envar>,
 187 <envar>$LC_ALL</envar>, or <envar>$LC_CTYPE</envar>, this setting
 188 became superfluous.</para>
 189 </listitem>
 190
 191 <listitem>
 192 <para><envar>(no)ntea</envar> -  This option has been removed since it
 193 only fakes security which is considered dangerous and useless.  It also
 194 created an uncontrollably large file on FAT and was entirely useless
 195 on FAT32.</para>
 196 </listitem>
 197
 198 <listitem>
 199 <para><envar>(no)ntsec</envar> - This option has been removed in favor of
 200 the per-mount option "acl"/"noacl".  For more information, read the
 201 documentation in <xref linkend="mount-table"></xref>.</para>
 202 </listitem>
 203
 204 <listitem>
 205 <para><envar>(no)server</envar> - Originally this option had to be
 206 enabled on the client side to use features only available when running
 207 <command>cygserver</command>.  This option has been removed because Cygwin now
 208 always tries to contact cygserver if a function is called which requires
 209 cygserver being available.  For more information, read the documentation
 210 in <xref linkend="using-cygserver"></xref>.</para>
 211 </listitem>
 212
 213 <listitem>
 214 <para><envar>(no)smbntsec</envar> - This option has been removed in favor of
 215 the per-mount option "acl"/"noacl".  For more information, read the
 216 documentation in <xref linkend="mount-table"></xref>.</para>
 217 </listitem>
 218
 219 <listitem>
 220 <para><envar>(no)transparent_exe</envar> - This option has been removed
 221 because the behaviour it switched on is now the standard behaviour in
 222 Cygwin.</para>
 223 </listitem>
 224
 225 <listitem>
 226 <para><envar>(no)traverse</envar> - This option has been removed because
 227 traverse checking is not quite correctly implemented by Microsoft and
 228 it's behaviour has been getting worse with each new OS version.  This
 229 complicates its usage so the option has been removed for now.</para>
 230 </listitem>
 231
 232 </itemizedlist>
 233
 234 </sect2>
 235
 236 </sect1>