Cygwin

Get that Linux feeling — on Windows

This is the home of the Cygwin project

. is it?

• a large collection of GNU and Open Source tools which provide functionality similar to a Linux distribution on Windows.
• a DLL (cygwin1.dll) which provides substantial POSIX API functionality.

. isn’t it?

• a way to run native Linux apps on Windows. You must rebuild your application from source if you want it to run on Windows.
• a way to magically make native Windows apps aware of UNIX® functionality like signals, ptys, etc. Again, you need to build your apps from source if you want to take advantage of Cygwin functionality.

The Cygwin DLL currently works with all recent, commercially released x86_64 versions of Windows, starting with Windows Vista. For more information see the FAQ.

Cygwin version

The most recent version of the Cygwin DLL is 3.2.0.

Installing Cygwin

Use the setup program to perform a fresh install or to update an existing installation.

Keep in mind that individual packages in the distribution are updated separately from the DLL so the Cygwin DLL version is not useful as a general Cygwin distribution release number.

Support for Cygwin

For all Cygwin-related questions and observations, please check the resources available at this site, such as the FAQ, the User’s Guide and the mailing list archives. If you’ve exhausted these resources then please send email to an appropriate mailing list. This includes observations about web pages, setup questions, questions about where to find things, questions about why things are done a certain way, questions about the color preferences of Cygwin developers, questions about the meaning of the number 42, etc.

Please send notification of technical problems (bad html, broken links) concerning these web pages to the Cygwin mailing list.

Please do not send personal email with «quick questions» to individual Cygwin contributors. The Cygwin mailing lists are the places for all questions. Really. I mean it.

32 bit Cygwin

Address space is a very limiting factor for Cygwin. These days, a full 32 bit Cygwin distro is not feasible anymore, and will in all likelihood fail in random places due to an issue with the fork(2) system call.

Therefore we recommend using 32 bit Cygwin only in limited scenarios, with only a minimum of necessary packages installed, and only if there’s no way to run 64 bit Cygwin instead.

You have been warned. If you’re still sure you really need a 32 bit Cygwin, and there’s absolutely no way around it, you may run the setup-x86.exe installer.

The Cygwin DLL and utilities are Copyright © Cygwin authors. Other packages have other copyrights.
UNIX ® is a registered trademark of the Open Group in the United States and other countries.

Cygwin

Get that Linux feeling — on Windows

Installing and Updating Cygwin Packages

Installing and Updating Cygwin for 64-bit versions of Windows

Run setup-x86_64.exe any time you want to update or install a Cygwin package for 64-bit windows. The signature for setup-x86_64.exe can be used to verify the validity of this binary.

Installing and Updating Cygwin for 32-bit versions of Windows

Run setup-x86.exe any time you want to update or install a Cygwin package for 32-bit windows. The signature for setup-x86.exe can be used to verify the validity of this binary.

Signing key transition

See this mail for more details.

General installation notes

When installing packages for the first time, the setup program does not install every package. Only the minimal base packages from the Cygwin distribution are installed by default, which takes up about 100 MB.

Clicking on categories and packages in the setup program package installation screen allows you to select what is installed or updated.

Individual packages like bash, gcc, less, etc. are released independently of the Cygwin DLL, so the Cygwin DLL version is not useful as a general Cygwin release number. The setup program tracks the versions of all installed components and provides the mechanism for installing or updating everything available from this site for Cygwin.

Once you’ve installed your desired subset of the Cygwin distribution, the setup program will remember what you selected, so re-running it will update your system with any new package releases.

On Windows Vista and later, the setup program will check by default if it runs with administrative privileges and, if not, will try to elevate the process. If you want to avoid this behaviour and install under an unprivileged account just for your own usage, run setup with the --no-admin option.

Q: How do I add a package to my existing Cygwin installation?

A: Run the setup program and select the package you want to add.

Tip: if you don’t want to also upgrade existing packages, select ‘Keep’ at the top-right of the package chooser page.

Q: Is there a command-line installer?

A: Yes and no. The setup program understands command-line arguments which allow you to control its behavior and choose individual packages to install. While this provides some functionality similar to such tools as apt-get or yum it is not as full-featured as those package managers.

Q: Why not use apt, yum, my favourite package manager, etc.?

A: The basic reason for not using a more full-featured package manager is that such a program would need full access to all of Cygwin’s POSIX functionality. That is, however, difficult to provide in a Cygwin-free environment, such as exists on first installation. Additionally, Windows does not easily allow overwriting of in-use executables so installing a new version of the Cygwin DLL while a package manager is using the DLL is problematic.

Q: How do I install everything?

A: You do not want to do this! This will install an enormous number of packages that you will never use, including debuginfo and source for every package.

If you really must do this, clicking on the «Default» label next to the «All» category to change it to «Install» will mark every Cygwin package for installation. Be advised that this will download and install tens of gigabytes of files to your computer.

Cygwin files in windows

Cygwin is not a full operating system, and so must rely on Windows for accomplishing some tasks. For example, Cygwin provides a POSIX view of the Windows filesystem, but does not provide filesystem drivers of its own. Therefore part of using Cygwin effectively is learning to use Windows effectively. Many Windows utilities provide a good way to interact with Cygwin’s predominately command-line environment. For example, ipconfig.exe provides information about network configuration, and net.exe views and configures network file and printer resources. Most of these tools support the /? switch to display usage information.

Unfortunately, no standard set of tools included with all versions of Windows exists. Generally, the younger the Windows version, the more complete are the on-board tools. Additionally, many independent sites such as download.com, simtel.net, and Microsoft’s own Sysinternals provide quite useful command-line utilities, as far as they are not already provided by Cygwin. A few Windows tools, such as find.exe , link.exe and sort.exe , may conflict with the Cygwin versions make sure that you use the full path ( /usr/bin/find ) or that your Cygwin bin directory comes first in your PATH .

Pathnames

Windows programs do not understand POSIX pathnames, so any arguments that reference the filesystem must be in Windows (or DOS) format or translated. Cygwin provides the cygpath utility for converting between Windows and POSIX paths. A complete description of its options and examples of its usage are in cygpath (1), including a shell script for starting Windows Explorer in any directory. The same format works for most Windows programs, for example

A few programs require a Windows-style, semicolon-delimited path list, which cygpath can translate from a POSIX path with the -p option. For example, a Java compilation from bash might look like this:

Since using quoting and subshells is somewhat awkward, it is often preferable to use cygpath in shell scripts.

Cygwin and Windows Networking

Many popular Cygwin packages, such as ncftp , lynx , and wget , require a network connection. Since Cygwin relies on Windows for connectivity, if one of these tools is not working as expected you may need to troubleshoot using Windows tools. The first test is to see if you can reach the URL’s host with ping.exe , one of the few utilities included with every Windows version since Windows 95. If you chose to install the inetutils package, you may have both Windows and Cygwin versions of utilities such as ftp and telnet . If you are having problems using one of these programs, see if the alternate one works as expected.

There are a variety of other programs available for specific situations. If your system does not have an always-on network connection, you may be interested in rasdial.exe for automating dialup connections. Users who frequently change their network configuration can script these changes with netsh.exe . For proxy users, the open source NTLM Authorization Proxy Server or the no-charge Hummingbird SOCKS Proxy may allow you to use Cygwin network programs in your environment.

Creating shortcuts

By default, Cygwin does not create symlinks as .lnk files, but there’s an option to do that, see the section called “The CYGWIN environment variable”. These symlink .lnk files are compatible with Windows-created .lnk files, but they are still different. They do not include much of the information that is available in a standard Microsoft shortcut, such as the working directory, an icon, etc. The cygutils package includes a mkshortcut utility for creating standard native Microsoft .lnk files from the command line.

But here’s the problem. If Cygwin handled these native shortcuts like any other symlink, you could not archive Microsoft .lnk files into tar archives and keep all the information in them. After unpacking, these shortcuts would have lost all the extra information and would be no different than standard Cygwin symlinks. Therefore these two types of links are treated differently. Unfortunately, this means that the usual Unix way of creating and using symlinks does not work with native Windows shortcuts.

Printing

There are several options for printing from Cygwin, including the lpr found in cygutils-extra (not to be confused with the native Windows lpr.exe ). The easiest way to use cygutils-extra ‘s lpr is to specify a default device name in the PRINTER environment variable. You may also specify a device on the command line with the -d or -P options, which will override the environment variable setting.

A device name may be a UNC path ( \\server_name\printer_name ), a reserved DOS device name ( prn , lpt1 ), or a local port name that is mapped to a printer share. Note that forward slashes may be used in a UNC path ( //server_name/printer_name ), which is helpful when using lpr from a shell that uses the backslash as an escape character.

lpr sends raw data to the printer; no formatting is done. Many, but not all, printers accept plain text as input. If your printer supports PostScript, packages such as a2ps and enscript can prepare text files for printing. The ghostscript package also provides some translation from PostScript to various native printer languages. Additionally, a native Windows application for printing PostScript, gsprint , is available from the Ghostscript website.

Chapter 3. Using Cygwin

Table of Contents

This chapter explains some key differences between the Cygwin environment and traditional UNIX systems. It assumes a working knowledge of standard UNIX commands.

Mapping path names

Introduction

The Cygwin DLL supports both POSIX- and Win32-style paths. Directory delimiters may be either forward slashes or backslashes. Paths using backslashes or starting with a drive letter are always handled as Win32 paths. POSIX paths must only use forward slashes as delimiter, otherwise they are treated as Win32 paths and file access might fail in surprising ways.

Although the Cygwin DLL supports Win32 paths, not all Cygwin applications support them. Moreover, the usage of Win32 paths circumvents important internal path handling mechanisms. This usage is therefore strongly deprecated and may be removed in a future release of Cygwin. See the section called “Using native Win32 paths” and the section called “Using the Win32 file API in Cygwin applications” for more information.

POSIX operating systems (such as Linux) do not have the concept of drive letters. Instead, all absolute paths begin with a slash (instead of a drive letter such as «c:») and all file systems appear as subdirectories (for example, you might buy a new disk and make it be the /disk2 directory).

Because many programs written to run on UNIX systems assume the existence of a single unified POSIX file system structure, Cygwin maintains a special internal POSIX view of the Win32 file system that allows these programs to successfully run under Windows. Cygwin uses this mapping to translate from POSIX to Win32 paths as necessary.

The Cygwin Mount Table

The /etc/fstab file is used to map Win32 drives and network shares into Cygwin’s internal POSIX directory tree. This is a similar concept to the typical UNIX fstab file. The mount points stored in /etc/fstab are globally set for all users. Sometimes there’s a requirement to have user specific mount points. The Cygwin DLL supports user specific fstab files. These are stored in the directory /etc/fstab.d and the name of the file is the Cygwin username of the user, as it’s created from the Windows account database or stored in the /etc/passwd file (see the section called “Mapping Windows accounts to POSIX accounts”). The structure of the user specific file is identical to the system-wide fstab file.

The file fstab contains descriptive information about the various file systems. fstab is only read by programs, and not written; it is the duty of the system administrator to properly create and maintain this file. Each filesystem is described on a separate line; fields on each line are separated by tabs or spaces. Lines starting with ‘#’ are comments.

The first field describes the block special device or remote filesystem to be mounted. On Cygwin, this is the native Windows path which the mount point links in. As path separator you MUST use a slash. Usage of a backslash might lead to unexpected results. UNC paths (using slashes, not backslashes) are allowed. If the path contains spaces these can be escaped as ‘\040’ .

The second field describes the mount point for the filesystem. If the name of the mount point contains spaces these can be escaped as ‘\040’.

The third field describes the type of the filesystem. Cygwin supports any string here, since the file system type is usually not evaluated. So it doesn’t matter if you write FAT into this field even if the filesystem is NTFS. Cygwin figures out the filesystem type and its capabilities by itself.

The only two exceptions are the file system types cygdrive and usertemp. The cygdrive type is used to set the cygdrive prefix. For a description of the cygdrive prefix see the section called “The cygdrive path prefix”, for a description of the usertemp file system type see the section called “The usertemp file system type”

The fourth field describes the mount options associated with the filesystem. It is formatted as a comma separated list of options. It contains at least the type of mount (binary or text) plus any additional options appropriate to the filesystem type. The list of the options, including their meaning, follows.

While normally the execute permission bits are used to evaluate executability, this is not possible on filesystems which don’t support permissions at all (like FAT/FAT32), or if ACLs are ignored on filesystems supporting them (see the aforementioned acl mount option). In these cases, the following heuristic is used to evaluate if a file is executable: Files ending in certain extensions (.exe, .com, .lnk) are assumed to be executable. Files whose first two characters are «#!», «MZ», or «:\n» are also considered to be executable. The exec option is used to instruct Cygwin that the mounted file is «executable». If the exec option is used with a directory then all files in the directory are executable. This option allows other files to be marked as executable and avoids the overhead of opening each file to check for «magic» bytes. The cygexec option is very similar to exec , but also prevents Cygwin from setting up commands and environment variables for a normal Windows program, adding another small performance gain. The opposite of these options is the notexec option, which means that no files should be marked as executable under that mount point.

A correct root directory is quite essential to the operation of Cygwin. A default root directory is evaluated at startup so a fstab entry for the root directory is not necessary. If it’s wrong, nothing will work as expected. Therefore, the root directory evaluated by Cygwin itself is treated as an immutable mount point and can’t be overridden in /etc/fstab. unless you think you really know what you’re doing. In this case, use the override flag in the options field in the /etc/fstab file. Since this is a dangerous thing to do, do so at your own risk.

/usr/bin and /usr/lib are by default also automatic mount points generated by the Cygwin DLL similar to the way the root directory is evaluated. /usr/bin points to the directory the Cygwin DLL is installed in, /usr/lib is supposed to point to the /lib directory. This choice is safe and usually shouldn’t be changed. An fstab entry for them is not required.

nouser mount points are not overridable by a later call to mount . Mount points given in /etc/fstab are by default nouser mount points, unless you specify the option user . This allows the administrator to set certain paths so that they are not overridable by users. In contrast, all mount points in the user specific fstab file are user mount points.

The fifth and sixth field are ignored. They are so far only specified to keep a Linux-like fstab file layout.

Note that you don’t have to specify an fstab entry for the root dir, unless you want to have the root dir pointing to somewhere entirely different (hopefully you know what you’re doing), or if you want to mount the root dir with special options (for instance, as text mount).

Just a normal mount point:

A mount point for a textmode mount with case sensitivity switched off:

A mount point for a Windows directory with spaces in it:

A mount point for a remote directory, don’t store POSIX permissions in ACLs:

This is just a comment:

Set the cygdrive prefix to /mnt:

Remount /var to /usr/var:

Assuming /var points to C:/cygwin/var , /usr/var now also points to C:/cygwin/var . This is equivalent to the Linux bind option available since Linux 2.4.0.

Whenever Cygwin generates a Win32 path from a POSIX one, it uses the longest matching prefix in the mount table. Thus, if C: is mounted as /c and also as / , then Cygwin would translate C:/foo/bar to /c/foo/bar . This translation is normally only used when trying to derive the POSIX equivalent current directory. Otherwise, the handling of MS-DOS filenames bypasses the mount table.

If you want to see the current set of mount points valid in your session, you can invoke the Cygwin tool mount without arguments:

Example 3.1. Displaying the current set of mount points

You can also use the mount command to add new mount points, and the umount to delete them. However, since they are only stored in memory, these mount points will disappear as soon as your last Cygwin process ends. See mount (1) and umount (1) for more information.

UNC paths

Apart from the unified POSIX tree starting at the / directory, UNC pathnames starting with two slashes and a server name ( //machine/share/. ) are supported as well. They are handled as POSIX paths if only containing forward slashes. There’s also a virtual directory // which allows to enumerate the fileservers known to the local machine with ls . Same goes for the UNC paths of the type //machine , which allow to enumerate the shares provided by the server machine . For often used UNC paths it makes sense to add them to the mount table (see the section called “The Cygwin Mount Table” so they are included in the unified POSIX path tree.

The cygdrive path prefix

As already outlined in the section called “File Access”, you can access arbitary drives on your system by using the cygdrive path prefix. The default value for this prefix is /cygdrive , and a path to any drive can be constructed by using the cygdrive prefix and appending the drive letter as subdirectory, like this:

This lists the content of the directory F:\somedir.

The cygdrive prefix is a virtual directory under which all drives on a system are subsumed. The mount options of the cygdrive prefix is used for all file access through the cygdrive prefixed drives. For instance, assuming the cygdrive mount options are binary,posix=0 , then any file /cygdrive/x/file will be opened in binary mode by default (mount option binary ), and the case of the filename doesn’t matter (mount option posix=0 ).

The cygdrive prefix flags are also used for all UNC paths starting with two slashes, unless they are accessed through a mount point. For instance, consider these /etc/fstab entries:

Assume there’s a file \\server\share\foo on the share. When accessing it as /mysrv/foo , then the flags posix=1,acl of the /mysrv mount point are used. When accessing it as //server/share/foo , then the flags for the cygdrive prefix, posix=0,noacl are used.

This only applies to UNC paths using forward slashes. When using backslashes the flags for native paths are used. See the section called “Using native Win32 paths”.

The cygdrive prefix may be changed in the fstab file as outlined above. Please note that you must not use the cygdrive prefix for any other mount point. For instance this:

will not make file access using the /mnt/d path prefix suddenly using textmode. If you want to mount any drive explicitly in another mode than the cygdrive prefix, use a distinct path prefix:

To simplify scripting, Cygwin also provides a /proc/cygdrive symlink, which allows to use a fixed path in scripts, even if the actual cygdrive prefix has been changed, or is different between different users. So, in scripts, conveniently use the /proc/cygdrive symlink to successfully access files independently from the current cygdrive prefix:

The usertemp file system type

On Windows, the environment variable TEMP specifies the location of the temp folder. It serves the same purpose as the /tmp/ directory in Unix systems. In contrast to /tmp/, it is by default a different folder for every Windows user. By using the special purpose usertemp file system, that temp folder can be mapped to /tmp/. This is particularly useful in setups where the administrator wants to write-protect the entire Cygwin directory. The usertemp file system can be configured in /etc/fstab like this:

Symbolic links

Symbolic links are supported by Windows only on NTFS and have a lot of quirks making them (almost) unusable in a POSIX context. POSIX applications are rightfully expecting to use symlinks and the symlink(2) system call, so Cygwin has worked around the Windows shortcomings.

Cygwin creates symbolic links potentially in multiple different ways.

The default symlinks created by Cygwin are either special reparse points shared with WSL on Windows 10, or plain files containing a magic cookie followed by the path to which the link points. The reparse point is used on NTFS, the plain file on almost any other filesystem.

Symlinks created by really old Cygwin releases (prior to Cygwin 1.7.0) are usually readable. However, you could run into problems if you’re now using another character set than the one you used when creating these symlinks (see the section called “Potential Problems when using Locales”).

On filesystems mounted via Microsoft’s NFS client, Cygwin always creates real NFS symlinks.

Native Windows symlinks are only created on filesystems supporting reparse points. Due to their weird restrictions and behaviour, they are only created if the user explicitely requests creating them. This is done by setting the environment variable CYGWIN to contain the string winsymlinks:native or winsymlinks:nativestrict . For the difference between these two settings, see the section called “The CYGWIN environment variable”. On AFS, native symlinks are the only supported type of symlink due to AFS lacking support for DOS attributes. This is independent from the winsymlinks setting.

Creation of native symlinks follows special rules to ensure the links are usable outside of Cygwin. This includes dereferencing any Cygwin-only symlinks that lie in the target path.

Shortcut style symlinks are Windows .lnk shortcut files with a special header and the DOS READONLY attribute set. This symlink type is created if the environment variable CYGWIN (see the section called “The CYGWIN environment variable”) is set to contain the string winsymlinks or winsymlinks:lnk . On the MVFS filesystem, which does not support the DOS SYSTEM attribute, this is the one and only supported symlink type, independently from the winsymlinks setting.

All of the above symlink types are recognized and used as symlinks under all circumstances. However, if the default plain file symlink type is lacking its DOS SYSTEM bit, or if the shortcut file is lacking the DOS READONLY attribute, they are not recognized as symlink.

Apart from these types, there’s also a Windows native type, so called directory junctions. They are recognized as symlink but never generated by Cygwin. Filesystem junctions on the other hand are not handled as symlinks, otherwise they would not be recognized as filesystem borders by commands like find -xdev .

Using native Win32 paths

Using native Win32 paths in Cygwin, while often possible, is generally inadvisable. Those paths circumvent all internal integrity checking and bypass the information given in the Cygwin mount table.

The following paths are treated as native Win32 paths by the Cygwin DLL (but not necessarily by Cygwin applications):

All paths starting with a drive specifier

All paths containing at least one backslash as path component

UNC paths using backslashes

When accessing files using native Win32 paths as above, Cygwin uses a default setting for the mount flags. All paths using DOS notation will be treated as case insensitive, and permissions are just faked as if the underlying drive is a FAT drive. This also applies to NTFS and other filesystems which usually are capable of case sensitivity and storing permissions.

Using the Win32 file API in Cygwin applications

Special care must be taken if your application uses Win32 file API functions like CreateFile to access files using relative pathnames, or if your application uses functions like CreateProcess or ShellExecute to start other applications.

When a Cygwin application is started, the Windows idea of the current working directory (CWD) is not necessarily the same as the Cygwin CWD. There are a couple of restrictions in the Win32 API, which disallow certain directories as Win32 CWD:

The Windows subsystem only supports CWD paths of up to 258 chars. This restriction doesn’t apply for Cygwin processes, at least not as long as they use the POSIX API (chdir, getcwd). This means, if a Cygwin process has a CWD using an absolute path longer than 258 characters, the Cygwin CWD and the Windows CWD differ.

The Win32 API call to set the current directory, SetCurrentDirectory , fails for directories for which the user has no permissions, even if the user is an administrator. This restriction doesn’t apply for Cygwin processes, if they are running under an administrator account.

SetCurrentDirectory does not support case-sensitive filenames.

Last, but not least, SetCurrentDirectory can’t work on virtual Cygwin paths like /proc or /cygdrive. These paths only exists in the Cygwin realm so they have no meaning to a native Win32 process.

As long as the Cygwin CWD is usable as Windows CWD, the Cygwin and Windows CWDs are in sync within a process. However, if the Cygwin process changes its working directory into one of the directories which are unusable as Windows CWD, we’re in trouble. If the process uses the Win32 API to access a file using a relative pathname, the resulting absolute path would not match the expectations of the process. In the worst case, the wrong files are deleted.

To workaround this problem, Cygwin sets the Windows CWD to a special directory in this case. This special directory points to a virtual filesystem within the native NT namespace ( \??\PIPE\ ). Since it’s not a real filesystem, the deliberate effect is that a call to, for instance, CreateFile («foo», . ); will fail, as long as the processes CWD doesn’t work as Windows CWD.

So, in general, don’t use the Win32 file API in Cygwin applications. If you really need to access files using the Win32 API, or if you really have to use CreateProcess to start applications, rather than the POSIX exec(3) family of functions, you have to make sure that the Cygwin CWD is set to some directory which is valid as Win32 CWD.

Additional Path-related Information

The cygpath program provides the ability to translate between Win32 and POSIX pathnames in shell scripts. See cygpath (1) for the details.

The HOME , PATH , and LD_LIBRARY_PATH environment variables are automatically converted from Win32 format to POSIX format (e.g. from c:/cygwin\bin to /bin , if there was a mount from that Win32 path to that POSIX path) when a Cygwin process first starts.

Symbolic links can also be used to map Win32 pathnames to POSIX. For example, the command ln -s //pollux/home/joe/data /data would have about the same effect as creating a mount point from //pollux/home/joe/data to /data using mount , except that symbolic links cannot set the default file access mode. Other differences are that the mapping is distributed throughout the file system and proceeds by iteratively walking the directory tree instead of matching the longest prefix in a kernel table. Note that symbolic links will only work on network drives that are properly configured to support the «system» file attribute. Many do not do so by default (the Unix Samba server does not by default, for example).