path: root/winsup/doc/cygwinenv.sgml

<sect1 id="using-cygwinenv"><title>The <envar>CYGWIN</envar> environment
variable</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)binmode</envar> - if set, non-disk 
(e.g. pipe and COM ports) file opens default to binary mode 
(no CRLF translation) instead of text mode.  Defaults to set (binary
mode).  By default, devices are opened in binary mode, so this option
has little effect on normal cygwin operations.

It does affect two things, however.  For non-NTFS filesystems, this
option will control the line endings for standard output/input/error
for redirection from the Windows command shell.  It will also affect
the default translation mode of a pipe, although most shells set the
pipe to binary by default.
</para>
</listitem>
<listitem>
<para><envar>check_case:level</envar> - Controls the behavior of
Cygwin when a user tries to open or create a file using a case different from
the case of the path as saved on the disk.
<literal>level</literal> is one of <literal>relaxed</literal>,
<literal>adjust</literal> and <literal>strict</literal>.</para>
<itemizedlist mark="bullet">
<listitem>
<para><envar>relaxed</envar> which is the default behaviour simply
ignores case. That's the default for native Windows applications as well.</para>
</listitem>
<listitem>
<para><envar>adjust</envar> behaves mostly invisible. The POSIX input
path is internally adjusted in case, so that the resulting DOS path uses the
correct case throughout. You can see the result when changing the directory
using a wrong case and calling <command>/bin/pwd</command> afterwards.</para>
</listitem>
<listitem>
<para><envar>strict</envar> results in a error message if the case
isn't correct. Trying to open a file <filename>Foo</filename> while a file
<filename>fOo</filename> exists results in a "no such file or directory"
error. Trying to create a file <filename>BAR</filename> while a file
<filename>Bar</filename> exists results in a "Filename exists with different
case" error.</para>
</listitem>
</itemizedlist>
</listitem>

<listitem>
<para><envar>codepage:[ansi|oem]</envar> - Windows console 
applications can use different character sets (codepages) for drawing
characters.  The first setting, called "ansi", is the default.
This character set contains various forms of latin characters used
in European languages.  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 "oem" since it was
originally encoded in the firmware of IBM PCs by original
equipment manufacturers (OEMs).  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.
</para>
</listitem>

<listitem>
<para><envar>(no)envcache</envar> - If set, environment variable
conversions (between Win32 and POSIX) are cached.  Note that this is 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 <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>(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)ntea</envar> - if set, use the full NT Extended
Attributes to store UNIX-like inode information.
This option only operates under Windows NT. Defaults to not set. </para>
<warning><title>Warning!</title> <para>This may create additional
<emphasis>large</emphasis> files on non-NTFS partitions.</para></warning>
</listitem>
<listitem>
<para><envar>(no)ntsec</envar> - if set, use the NT security
model to set UNIX-like permissions on files and processes. The
file permissions can only be set on NTFS partitions. FAT doesn't
support the NT file security. Defaults to set. For more information, read
the documentation in <xref linkend="ntsec"></xref>.</para>
</listitem>
<listitem>
<para><envar>(no)smbntsec</envar> - if set, use <envar>ntsec</envar> on remote
drives as well (default is "nosmbntesc"). When setting "smbntsec" there's
a chance that you get problems with Samba shares so you should use this
option with care.  One reason for a non working <envar>ntsec</envar> on
remote drives could be insufficient permissions of the users. The requires
user rights are somewhat dangerous (SeRestorePrivilege), so it's not always
an option to grant that rights to users.  However, this shouldn't be a
problem in NT domain environments.</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)server</envar> - if set, allows client applications
to use the Cygserver facilities.  This option must be enabled explicitely
on the client side, otherwise your applications won't be able to use the
XSI IPC function calls (<function>msgget</function>,
<function>semget</function>, <function>shmget</function>, and friends)
successfully.  These function calls will return with
<literal>ENOSYS</literal>, "Bad system call".
</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.  Note that under Win9x the title bar is always enabled and it is
stripped by default, but this is because of the way Win9x works.  In
order not to strip, specify <literal>title</literal> or <literal>title
nostrip_title</literal>.</para>
</listitem>
<listitem>
<para><envar>(no)traverse</envar> - This option only affects NT systems.
If set, Cygwin handles file permissions so that the parent directories'
permissions are checked, as it's default on POSIX systems.  If not set,
only the file's own permissions are taken into account.  This is the
default on Windows and called "bypass traverse checking".  Beginning with
version 1.5.13, traverse checking (as on POSIX) is enabled by default.
If you want to switch off traverse checking for Cygwin processes and child
processes started from Cygwin processes, you have to set "notraverse".</para>
</listitem>
<listitem>
<para><envar>(no)tty</envar> - if set, Cygwin enables extra support
(i.e., termios) for UNIX-like ttys. 
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.</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 set.</para>
</listitem>
</itemizedlist>
</sect1>