298 lines
11 KiB
XML
298 lines
11 KiB
XML
<?xml version="1.0" encoding='UTF-8'?>
|
|
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
|
|
|
|
<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>(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
|
|
can be useful for debugging. Defaults to not set.
|
|
</para>
|
|
<para>
|
|
<filename>Win32filepath</filename> is typically set to <command>gdb</command> or
|
|
<command>dumper</command>. If giving a path in
|
|
<filename>Win32filepath</filename>, note that it is a Windows-style path and not
|
|
a Cygwin path.
|
|
</para>
|
|
<para>
|
|
The filename of the executing program and it's Windows process id are appended
|
|
to the command as arguments.
|
|
</para>
|
|
<para>
|
|
Note: This takes priority over writing core dump or .stackdump files, if
|
|
enabled by <function>setrlimit(RLIMIT_CORE)</function> (e.g. via
|
|
<command>ulimit -c</command>).
|
|
</para>
|
|
<para>
|
|
Note: This has no effect if a debugger is already attached when the fatal
|
|
error occurs.
|
|
</para>
|
|
<para>
|
|
Note: The command invoked must either (i) attach to the errored process with
|
|
<function>DebugActiveProcess()</function>, or (ii) forcibly terminate the
|
|
errored process (with <function>TerminateProcess()</function> or similar), as
|
|
otherwise the errored process will wait forever for a debugger to attach.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><envar>(no)glob[:ignorecase]</envar> - if set, command line arguments
|
|
containing UNIX-style file wildcard characters (brackets, braces, question mark,
|
|
asterisk, escaped with \) are expanded into lists of files that match
|
|
those wildcards.
|
|
This is applicable only to programs run from non-Cygwin programs such as a CMD prompt.
|
|
That means that this setting does not affect globbing operations for shells such as
|
|
bash, sh, tcsh, zsh, etc.
|
|
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)pipe_byte</envar> - if set, Cygwin opens pipes in byte mode rather than
|
|
message mode. This is the default starting with Cygwin 3.4.0.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><envar>proc_retry:n</envar> - causes <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)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)wincmdln</envar> - if set, the windows complete command
|
|
line (truncated to ~32K) will be passed on any processes that it creates
|
|
in addition to the normal UNIX argv list. Defaults to not set.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><envar>(no)winjitdebug</envar> - if set, non-Cygwin executables
|
|
started from a Cygwin process will have their error mode reset to the
|
|
system default. That means, if they don't call SetErrorMode()
|
|
explicitly, the OS will display error dialog boxes in the GUI if some
|
|
fatal error occurs. Defaults to not set, so fatal errors in a
|
|
non-Cygwin child process will just result in an error code be propagated
|
|
back to the parent process.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><envar>winsymlinks:{lnk,native,nativestrict,sys}</envar></para>
|
|
|
|
<itemizedlist mark="square">
|
|
<listitem>
|
|
<para>If set to just
|
|
<literal>winsymlinks</literal> or <literal>winsymlinks:lnk</literal>,
|
|
Cygwin creates symlinks as Windows shortcuts with a special header and
|
|
the R/O attribute set.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If set to <literal>winsymlinks:native</literal> or
|
|
<literal>winsymlinks:nativestrict</literal>, Cygwin creates symlinks as
|
|
native Windows symlinks on filesystems and OS versions supporting them.</para>
|
|
|
|
<para>The difference between <literal>winsymlinks:native</literal> and
|
|
<literal>winsymlinks:nativestrict</literal> is this: If the filesystem
|
|
supports native symlinks and Cygwin fails to create a native symlink for
|
|
some reason, it will fall back to creating Cygwin default symlinks
|
|
with <literal>winsymlinks:native</literal>, while with
|
|
<literal>winsymlinks:nativestrict</literal> the <literal>symlink(2)</literal>
|
|
system call will immediately fail.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If set to <literal>winsymlinks:sys</literal>, Cygwin creates symlinks as
|
|
plain files with the <literal>system</literal> attribute, containing a magic
|
|
cookie followed by the path to which the link points.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>Note that this setting has no effect where Cygwin knows that the
|
|
filesystem only supports a creating symlinks in a specific way.</para>
|
|
|
|
<para>For more information on symbolic links, see
|
|
<xref linkend="pathnames-symlinks"></xref>.</para>
|
|
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><envar>disable_pcon</envar> - if set, pseudo console support in
|
|
pty will be disabled. This is for programs which do not work properly
|
|
under pty with pseudo console enabled. Defaults to not set.</para>
|
|
</listitem>
|
|
|
|
</itemizedlist>
|
|
|
|
</sect2>
|
|
|
|
<sect2 id="cygwinenv-removed-options">
|
|
<title>Obsolete options</title>
|
|
|
|
<para>
|
|
Certain CYGWIN options available in past releases have been removed over
|
|
time for one reason or another. These obsolete 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
|
|
explicitly in the open(2) call.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><envar>(no)detect_bloda</envar> - No case of a BLODA found by this
|
|
option has been reported in years.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><envar>(no)dosfilewarning</envar> - This option had been disabled for
|
|
quite some time and nobody missed it.</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>codepage:[ansi|oem]</envar> - This option controlled
|
|
which character set is used for file and console operations. Since Cygwin
|
|
is now doing all character conversion by itself, depending on the
|
|
application call to the <function>setlocale()</function> function, and in
|
|
turn by the setting of the environment variables <envar>$LANG</envar>,
|
|
<envar>$LC_ALL</envar>, or <envar>$LC_CTYPE</envar>, this setting
|
|
became superfluous.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><envar>(no)envcache</envar> - Originally, <envar>envcache</envar>
|
|
controlled caching of environment variable conversion between Win32 and
|
|
POSIX. The default setting works fine, the option was just useless.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><envar>forkchunk:[intval]</envar> - This option allowed to influence
|
|
the <function>fork()</function> function in the way the memory of the
|
|
parent process gets copied to the child process. This functionality was
|
|
only useful for Windows 95/98/Me.
|
|
</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)strip_title</envar> - Removed because setting the Window title
|
|
can be controlled by the application via Escape sequences.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><envar>(no)title</envar> - Removed because setting the Window title
|
|
can be controlled by the application via Escape sequences.</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 has been getting worse with each new OS version. This
|
|
complicates its usage so the option has been removed for now.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><envar>(no)tty</envar> - If set, Cygwin enabled extra support
|
|
(i.e., termios) for UNIX-like ttys in the Windows console. This option
|
|
has been removed because it can be easily replaced by using a terminal
|
|
like <command>mintty</command>, and it does not work well with some
|
|
Windows programs.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><envar>(no)upcaseenv</envar> - This option could be used to convert
|
|
all environment variables to uppercase. This was the default behavior in
|
|
older releases of Cygwin. Since keeping the case of environment variables
|
|
intact is POSIXly correct, Cygwin now does not change the case
|
|
of environment variables, except for a restricted set to maintain minimal
|
|
backward compatibility. The current list of always uppercased variables is:
|
|
</para>
|
|
<screen>
|
|
COMMONPROGRAMFILES
|
|
COMSPEC
|
|
PATH
|
|
SYSTEMDRIVE
|
|
SYSTEMROOT
|
|
TEMP
|
|
TMP
|
|
WINDIR
|
|
</screen>
|
|
</listitem>
|
|
|
|
</itemizedlist>
|
|
|
|
</sect2>
|
|
|
|
</sect1>
|