The CYGWIN environment variable
Prev | Chapter 3. Using Cygwin | Next

## The `CYGWIN` environment variable

### Implemented options

The `CYGWIN` 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 `no`.

- `codepage:[ansi|oem|utf8]` - 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 `ansi` 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 `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. Finally, `utf8` 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.

- `(no)dosfilewarning` - 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.

- `(no)envcache` - 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.

- `(no)export` - If set, the final values of these settings are re-exported to the environment as `CYGWIN` again. Defaults to off.

- `error_start:Win32filepath` - if set, runs `Win32filepath` when cygwin encounters a fatal error, which is useful for debugging. `Win32filepath` is usually set to the path to gdb or dumper, for example `C:\cygwin\bin\gdb.exe`. There is no default set.

- `forkchunk:32768` - causes the `fork()` 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.

- `proc_retry:n` - causes the `fork()` and `exec*()` 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.

- `(no)glob[:ignorecase]` - 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.

  This option also accepts an optional `[no]ignorecase` modifer. If supplied, wildcard matching is case insensitive. The default is `noignorecase`

- `(no)reset_com` - 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.

- `(no)server` - 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 (`msgget`, `semget`, `shmget`, and friends) successfully. These function calls will return with `ENOSYS`, "Bad system call".

- `(no)strip_title` - if set, strips the directory part off the window title, if any. Default is not set.

- `(no)title` - if set, the title bar reflects the name of the program currently running. Default is not set.

- `(no)tty` - 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 stty. 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).

- `(no)upcaseenv` - 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:

        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

  Defaults to not set.

- `(no)winsymlinks` - 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.

### Removed options

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

- `(no)binmode` - 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.

- `check_case` - 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 the section called “The Cygwin Mount Table” and the section called “Case sensitive filenames”.

- `(no)ntea` - 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.

- `(no)ntsec` - This option has been removed in favor of the per-mount option "acl"/"noacl". For more information, read the documentation in the section called “The Cygwin Mount Table”.

- `(no)smbntsec` - This option has been removed in favor of the per-mount option "acl"/"noacl". For more information, read the documentation in the section called “The Cygwin Mount Table”.

- `(no)transparent_exe` - This option has been removed because the behaviour it switched on is now the standard behaviour in Cygwin.

- `(no)traverse` - 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.

Prev | Up | Next
Special filenames | Home | Cygserver