Movatterモバイル変換

1. About Cygwin

1.1.What is it?

1.2.What versions of Windows are supported?

1.3.Where can I get it?

1.4.Is it free software?

1.5.What version of Cygwin is this, anyway?

1.6.Who's behind the project?

1.1.

What is it?

Cygwin is a distribution of popular GNU and other Open Source toolsrunning on Microsoft Windows. The core part is the Cygwin library whichprovides the POSIX system calls and environment these programs expect.

The Cygwin distribution contains thousands of packages from the OpenSource world including most GNU tools, many BSD tools, an X server and a fullset of X applications. If you're a developer you will find tools, headersand libraries allowing to write Windows console or GUI applications that makeuse of significant parts of the POSIX API. Cygwin allows easy porting of manyUnix programs without the need for extensive changes to the source code. Thisincludes configuring and building most of the available GNU or BSD software,including the packages included with the Cygwin distribution themselves.They can be used from one of the provided Unix shells like bash, tcsh or zsh.

1.2.

What versions of Windows are supported?

Cygwin can be expected to run on all modern, released 64 bit versions ofWindows. This includes Windows 8.1, Windows Server 2012 R2 and all laterversions of Windows on AMD/Intel compatible PCs, as well as under x64 emulationon ARM PCs running Windows 11. Windows S mode is not supported due to itslimitations,

Keep in mind that Cygwin can only do as much as the underlying OSsupports. Because of this, Cygwin will behave differently, andexhibit different limitations, on the various versions of Windows.

1.3.

Where can I get it?

The home page for the Cygwin project ishttps://cygwin.com/.There you should find everything you need for Cygwin, including linksfor download and setup, a current list of mirror sites, a User'sGuide, an API Reference, mailing lists and archives.

You can find documentation for the individual GNU tools typicallyas man pages or info pages as part of the Cygwin net distribution.Additionally you can get the latest docs athttp://www.gnu.org/manual.

1.4.

Is it free software?

Yes. Parts are GNU software (gcc, gas, ld, etc...), parts are coveredby the standard X11 license, some of it is public domain, some ofit was written by Red Hat (or the former Cygnus Solutions) and placed underthe GPL. None of it is shareware. You don't have to pay anyone to use itbut you should be sure to read the copyright section of the FAQ for moreinformation on how the GNU General Public License may affect your use ofthese tools.

Note that when we say "free" we mean freedom, not price. The goal ofsuch freedom is that the people who use a given piece of softwareshould be able to change it to fit their needs, learn from it, shareit with their friends, etc. The GPL or LGPL licenses allows you thosefreedoms, so it is free software.

1.5.

What version of Cygwinis this, anyway?

To find the version of the Cygwin DLL installed, you can useuname-r as you would for a Unix kernel.As the Cygwin DLL takes the place of a Unix kernel,you can also use the Unix compatible command:head/proc/version,or the Cygwin specific command:cygcheck-V.Refer to each command's--help output and theCygwin User's Guidefor more information.

If you are looking for the version number for the whole Cygwinrelease, there is none.Each package in the Cygwin release has its own version, and thecygwin package containing the Cygwin DLL and Cygwinsystem specific utilities is just another (but very important!) package.The packages in Cygwin are continually improving, thanks tothe efforts of volunteers who maintain the Cygwin ports.Each package has its own version numbers and its own release process.

So, how do you get the most up-to-date version of Cygwin? Easy. Justdownload the Cygwin Setup program by following theinstallation instructions.The Setup program will handle the task of updating the packages on your systemto the latest version.For more information about using Cygwin's Setup program, seeSetting Up Cygwinin the Cygwin User's Guide.

1.6.

Who's behind the project?

(Please note that if you have cygwin-specificquestions, all of these people will appreciate it if you use the cygwinmailing lists rather than sending personal email.)

Corinna Vinschen is the current project lead,responsible for the Cygwin library and a lot more.

Yaakov Selkowitz is the guy behind the current build and packaging systemand maintained by far the most packages in the Cygwin distribution.

Jon Turney is maintainer of the Cygwin X server and related packages.

The packages are maintained by a large group ofvolunteers.

Please note that all of us volunteering on Cygwin try to be as responsive aspossible and deal with patches and questions as we get them, butrealistically we don't have time to answer all of the email that is sent tothe main mailing list.Making releases of the tools and packages is an activity in our spare time,helping people out is not our primary focus, so some email will have to gounanswered.

Many thanks to everyone using the tools for their many contributions inthe form of advice, bug reports, and code fixes. Keep them coming!

2. Setting up Cygwin

2.1.What is the recommended installation procedure?

2.2.What about an automated Cygwin installation?

2.3.Does the Cygwin Setup program accept command-line arguments?

2.4.Can I install Cygwin without administrator rights?

2.5.Why not install in C:\?

2.6.Can I use the Cygwin Setup program to get old versions of packages (like gcc-2.95)?

2.7.How does Cygwin secure the installation and update process?

2.8.What else can I do to ensure that my installation and updates are secure?

2.9.Is the Cygwin Setup program, or one of the packages, infected with a virus?

2.10.My computer hangs when I run Cygwin Setup!

2.11.What packages should I download? Where are 'make', 'gcc', 'vi', etc?

2.12.How do I just get everything?

2.13.How much disk space does Cygwin require?

2.14.How do I know which version I upgraded from?

2.15.What if the Cygwin Setup program fails?

2.16.My Windows logon name has a space in it, will this cause problems?

2.17.My HOME environment variable is not what I want.

2.18.How do I uninstall individual packages?

2.19.How do I uninstall a Cygwin service?

2.20.How do I uninstall all of Cygwin?

2.21.How do I install Cygwin test releases?

2.22.Can the Cygwin Setup program maintain a ``mirror''?

2.23.How can I make my own portable Cygwin on CD?

2.24.How do I save, restore, delete, or modify the Cygwin information stored in the registry?

2.1.

What is the recommended installation procedure?

There is only one recommended way to install Cygwin, which is to use theCygwin Setup program, a GUI installer.It is flexible and easy to use.You can pick and choose the packages you wish to install, and updatethem individually. Full source code is available for all packages andtools.More informationis available on using the Cygwin Setup program.

If you do it any other way, you're on your own!If something doesn't work right for you, and it's not covered here or inthe latest Cygwin test package (seeInstall Test Releases),then by all means report it to the mailing list.

For a searchable list of packages that can be installed with Cygwin,seehttps://cygwin.com/packages/.

2.2.

What about an automated Cygwin installation?

The Cygwin Setup program is designed to be interactive, but there area few different ways to automate it. If you are deploying to multiple systems,the best way is to run through a full installation once, saving the entire downloaded package tree. Then, on target systems, run the Cygwin Setup program as a"Local Install" pointed at your downloaded package tree. You could do thisnon-interactively with the command line options-q -L -l x:\cygwin-local\, where your downloaded package tree is inx:\cygwin-local\ (see the next FAQ foran explanation of those options.)

For other options, search the mailing lists with terms such ascygwin automated setup orautomated cygwin install.

2.3.

Does the Cygwin Setup program accept command-line arguments?

Yes, run the Cygwin Setup program with option--help for an up to date list:

    --allow-unsupported-windows    Allow old, unsupported Windows versions -a --arch                         Architecture to install (x86_64 or x86) -C --categories                   Specify categories to install    --compact-os                   Compress installed files with Compact OS                                   (xpress4k, xpress8k, xpress16k, lzx) -o --delete-orphans               Remove orphaned packages -A --disable-buggy-antivirus      Disable known or suspected buggy anti virus                                   software packages during execution -D --download                     Download packages from internet -f --force-current                Select the current version for all packages -h --help                         Print help -I --include-source               Automatically install source for every                                   package installed -i --ini-basename                 Use a different basename, e.g. "foo",                                   instead of "setup" -U --keep-untrusted-keys          Use untrusted keys and retain all    --lang                         Specify GUI language langid -L --local-install                Install packages from local directory -l --local-package-dir            Local package directory -m --mirror-mode                  Skip package availability check when                                   installing from local directory (requires                                   local directory to be clean mirror!) -B --no-admin                     Do not check for and enforce running as                                   Administrator -d --no-desktop                   Disable creation of desktop shortcut -r --no-replaceonreboot           Disable replacing in-use files on next reboot -n --no-shortcuts                 Disable creation of desktop and start menu                                   shortcuts -N --no-startmenu                 Disable creation of start menu shortcut -X --no-verify                    Don't verify setup.ini signatures    --no-version-check             Suppress checking if a newer version of                                   setup is available -w --no-warn-deprecated-windows   Don't warn about deprecated Windows versions    --enable-old-keys              Enable old cygwin.com keys -O --only-site                    Do not download mirror list.  Only use sites                                   specified with -s. -M --package-manager              Semi-attended chooser-only mode -P --packages                     Specify packages to install -p --proxy                        HTTP/FTP proxy (host:port) -Y --prune-install                Prune the installation to only the requested                                   packages -K --pubkey                       URL or absolute path of extra public key                                   file (RFC4880 format) -q --quiet-mode                   Unattended setup mode -c --remove-categories            Specify categories to uninstall -x --remove-packages              Specify packages to uninstall -R --root                         Root installation directory -S --sexpr-pubkey                 Extra DSA public key in s-expr format -s --site                         Download site URL    --symlink-type                 Symlink type (lnk, native, sys, wsl) -u --untrusted-keys               Use untrusted saved extra keys -g --upgrade-also                 Also upgrade installed packages    --user-agent                   User agent string for HTTP requests -v --verbose                      Verbose output -V --version                      Show version -W --wait                         When elevating, wait for elevated child                                   process

2.4.

Can I install Cygwin without administrator rights?

Yes. The default installation requests administrator rights becausethis allows to set up the Cygwin environment so that all users can starta Cygwin shell out of the box. However, if you don't have administratorrights for your machine, and the admins don't want to install it for you,you can install Cygwin just for yourself by downloading the Cygwin Setupprogram, and then startit from the command line or via the "Run..." dialog from the start menuusing the--no-admin option, for instance:

  setup-x86_64.exe --no-admin

2.5.

Why not install in C:\?

The Cygwin Setup program will prompt you for a "root" directory.The default isC:\cygwin, but you can change it. You are urged not tochoose something likeC:\ (the root directory on the system drive) foryour Cygwin root. If you do, then critical Cygwin system directorieslikeetc,lib andbin could easily be corrupted byother (non-Cygwin) applications or packages that use\etc,\lib or\bin. Perhaps there is no conflict now, but whoknows what you might install in the future? It's also just good commonsense to segregate your Cygwin "filesystems" from the rest of yourWindows system disk.

(In the past, there had been genuine bugs that would cause problemsfor people who installed inC:\, but we believe those are gonenow.)

2.6.

Can I use the Cygwin Setup program to get old versions of packages (like gcc-2.95)?

The Cygwin Setup program can be used to install any packages that are on aCygwin mirror, which usually includes at least one version previous to thecurrent one. The complete list may be searched athttps://cygwin.com/packages/. There is no complete archive ofolder packages. If you have a problem with the current version ofa Cygwin package, please report it to the mailing list using the guidelines athttps://cygwin.com/problems.html.

That said, if you really need an older package, you may be able to findan outdated or archival mirror by searching the web for an old packageversion (for example,gcc2-2.95.3-10-src.tar.bz2), but keep inmind that this older version will not be supported by the mailing listand that installing the older version will not help improve Cygwin.

2.7.

How does Cygwin secure the installation and update process?

Here is how Cygwin secures the installation and update process to counterman-in-the-middle (MITM) attacks:

Cygwin uses the cryptographic hash algorithm SHA-512 as of 2015-03-23.The earlier 2015-02-06 update of the setup program added support for SHA-512(Cygwin previously used MD5).There are no known practical exploits of SHA-512 (SHA-512 is part of thewidely-used SHA-2 suite of cryptographic hashes).

2.8.

What else can I do to ensure that my installation and updates are secure?

To best secure your installation and update process, downloadthe Cygwin Setup program, and thencheck its signature (using a signature-checking tool you trust)using the Cygwin public key(https://cygwin.com/key/pubring.asc).This was noted on the front page for installing and updating.

If you use the actual Cygwin public key, and have an existing securesignature-checking process, you will counter many otherattacks such as subversion of the Cygwin website andmalicious certificates issued by untrustworthy certificate authorities (CAs).One challenge, of course, is ensuring thatyou have the actual Cygwin public key.You can increase confidence in the Cygwin public key by checking older copiesof the Cygwin public key (to see if it's been the same over time).Another challenge is having a secure signature-checking process.You can use GnuPG to check signatures; if you have a trusted Cygwininstallation you can install GnuPG.Otherwise, to check the signature you must use an existing trusted tool orinstall a signature-checking tool you can trust.

Not everyone will go through this additional effort,but we make it possible for those who want that extra confidence.We also provide automatic mechanisms(such as our use of HTTPS) for those with limited time anddo not want to perform the signature checking on the Cygwin Setup program itself.Once the correct Setup program is running, it will counter other attacksas described inQ: 2.7.

2.9.

Is the Cygwin Setup program, or one of the packages, infected with a virus?

Unlikely. Unless you can confirm it, please don't report it to themailing list. Anti-virus products have been known to detect falsepositives when extracting compressed tar archives. If this causesproblems for you, consider disabling your anti-virus software whenrunning the Cygwin Setup program. Read the next entry for a fairly safe way to dothis.

2.10.

My computer hangs when I run Cygwin Setup!

Both Network Associates (formerly McAfee) and Norton anti-virusproducts have been reported to "hang" when extracting Cygwin tararchives. If this happens to you, consider disabling your anti-virussoftware when running the Cygwin Setup program. The following procedure should bea fairly safe way to do that:

This should be safe, but only if the Cygwin Setup program is not substituted bysomething malicious.See alsoQ: 2.7for a description of how theCygwin project counters man-in-the-middle (MITM) attacks.

See alsoBLODAfor a list of applications that have been known, at one time or another, tointerfere with the normal functioning of Cygwin.

2.11.

What packages should I download? Where are 'make', 'gcc', 'vi', etc?

When using the Cygwin Setup program for the first time, the default is to installa minimal subset of all available packages. If you want anything beyond that,you will have to select it explicitly. Seehttps://cygwin.com/packages/ for a searchable list of availablepackages, or usecygcheck -p as described in the CygwinUser's Guide athttps://cygwin.com/cygwin-ug-net/cygcheck.html.

If you want to build programs, of course you'll needgcc,binutils,make and probably other packages from the``Devel'' category. Text editors can be found under ``Editors''.

2.12.

How do I just get everything?

Long ago, the default was to install everything, much to theirritation of most users. Now the default is to install only a basiccore of packages. The Cygwin Setup program is designed to make it easy to browsecategories and select what you want to install or omit from thosecategories.There are now more than 10000 Cygwin packages requiring more than 150GBof disk space just to download and hundreds of GB more to install so youare strongly advised not to attempt toinstall everythingat once, unless you have a lot of free disk space, a very high speed networkconnection, and the system will not be required for any other purpose formany hours (or days) until installation completes.

2.13.

How much disk space does Cygwin require?

That depends, obviously, on what you've chosen to download andinstall. A full installation today is many hundreds of GBinstalled, not including the package archives themselves nor the sourcecode.

After installation, the package archives remain in your ``LocalPackage Directory''. By default the location of the Cygwin Setup program.You may conserve disk space bydeleting the subdirectories there. These directories will have very weirdlooking names, being encoded with their URLs(namedhttp%3a%2f...cygwin...%2f).

Of course, you can keep them around in case you want to reinstall apackage. If you want to clean out only the outdated packages, Michael Chasehas written a script calledclean_setup.pl, availableatunsupported/clean_setup.pl in a Cygwin mirror.

2.14.

How do I know which version I upgraded from?

Detailed logs of the most recent Cygwin Setup session can be found in/var/log/setup.log.full and less verbose information aboutprior actions is in/var/log/setup.log.

2.15.

What if the Cygwin Setup program fails?

First, make sure that you are using the latest version of the Cygwin Setup program.The latest version is always available from the Cygwin Home Page athttps://cygwin.com/.

If you are downloading from the Internet, setup will fail if it cannotdownload the list of mirrors athttps://cygwin.com/mirrors.lst.It could be that the network is too busy. Something similar could be thecause of a download site not working. Try another mirror, or try againlater.

If the Cygwin Setup program refuses to download a package that you know needs to beupgraded, try deleting that package's entry from /etc/setup. If you arereacting quickly to an announcement on the mailing list, it could bethat the mirror you are using doesn't have the latest copy yet. Tryanother mirror, or try again tomorrow.

If the Cygwin Setup program has otherwise behaved strangely, check the filessetup.log andsetup.log.full in/var/log (C:\cygwin\var\log bydefault). It may provide some clues as to what went wrong and why.

If you're still baffled, search the Cygwin mailing list for clues.Others may have the same problem, and a solution may be posted there.If that search proves fruitless, send a query to the Cygwin mailinglist. You must provide complete details in your query: version ofthe Cygwin Setup program, options you selected, contents of setup.log and setup.log.full,what happened that wasn't supposed to happen, etc.

2.16.

My Windows logon name has a space in it, will this cause problems?

Most definitely yes! UNIX shells (and thus Cygwin) use the spacecharacter as a word delimiter. Under certain circumstances, it ispossible to get around this with various shell quoting mechanisms, butyou are much better off if you can avoid the problem entirely.

You have two choices:

2.17.

MyHOME environment variable is not what I want.

When starting Cygwin from Windows,HOME is determinedas follows:

When using Cygwin from a network login (via ssh for instance),HOME is always taken from the passwd entry.

If yourHOME is set to a value such as /cygdrive/c,it is likely that it was set in Windows. Start a DOS Command Window and type "set HOME" to verify if this is the case.

Access to shared drives is often restricted when starting from thenetwork, thus Domain users may wish to have a differentHOMEin the Windows environment (on shared drive) than in Cygwin (on local drive).Note that ssh only considers the account information as retrieved bygetpwnam(3), disregardingHOME.

2.18.

How do I uninstall individual packages?

Run the Cygwin Setup program as you would to install packages. In the``Select packages to install'' dialog, choose ``Up To Date'' in theView drop-down menu, and locate the package. Choose the``Uninstall'' action from the drop-down menu in the ``New'' column. Proceed byclicking ``Next''.

2.19.

How do I uninstall a Cygwin service?

2.20.

How do I uninstallall of Cygwin?

Setup has no automatic uninstall facility. The recommended method to remove all of Cygwin is as follows:

2.21.

How do I install Cygwin test releases?

You can install Cygwin test releases just like test releases ofany other package using the Cygwin Setup program. Ideally, you installnot only thecygwin test package, butalso thecygwin-debuginfo test packagewith the same version number. The cygwin-debuginfo package allows sourcecode debugging using gdb. Install thecygwin-devel test package, if you alsowant to test building against a new API.

However, are you sure you want to do this? Test releases are risky.They have only been marginally tested most of the time. Use themonly if there is a feature or bugfix thatyou need to try, and you are willing to deal with any problems, or at therequest of a Cygwin developer.

The operative word in trying the test releases is"trying". If you notice a problem with the snapshotthat was not present in the release DLL (what we call a "regression"),please report it to the Cygwin mailing list(seehttps://cygwin.com/problems.html for problemreporting guidelines). If you wish to go back to the most recent non-testrelease of the Cygwin DLL, close all Cygwin processes, as usual, start theCygwin Setup program and choose the most recent non-test release of thecygwin package, as well as the cygwin-debuginfo and cygwin-devel packages.That's all there is to it.

2.22.

Can the Cygwin Setup program maintain a ``mirror''?

NO. The Cygwin Setup program cannot do this for you. Use a tool designed forthis purpose. Seehttp://rsync.samba.org/,http://www.gnu.org/software/wget/ for utilities that can do this for you.For more information on setting up a custom Cygwin package server, seetheCygwin Package Server page.

2.23.

How can I make my own portable Cygwin on CD?

While some users have successfully done this, for example IndianaUniversity's XLiveCDhttp://racinfo.indiana.edu/research/xlivecd.php, there is noeasy way to do it. Full instructions for constructing a portable Cygwinon CD by hand can be found on the mailing list athttps://www.cygwin.com/ml/cygwin/2003-07/msg01117.html(Thanks to fergus at bonhard dot uklinux dot net for these instructions.)Please note that these instructions are very old and are referring to thesomewhat different setup of a Cygwin 1.5.x release. As soon as somebody setthis up for recent Cygwin releases, we might add this information here.

2.24.

How do I save, restore, delete, or modify the Cygwin information stored in the registry?

Cygwin doesn't store anything important in the registry anymore forquite some time. There's no reason to save, restore or delete it.

3. Further Resources

3.1.Where's the documentation?

3.2.What Cygwin mailing lists can I join?

3.3.What if I have a problem? (Or: Why won't you/the mailing list answer my questions?)

3.1.

Where's the documentation?

If you have installed Cygwin, you can find lots of documentation in/usr/share/doc/. Some packages have Cygwin specificinstructions in a file/usr/share/doc/Cygwin/package_name.README.In addition, many packages ship with standard documentation, which you canfind in/usr/share/doc/package_name orby using theman orinfo tools. (Hint:usecygcheck -lpackage_name tolist what man pages the package includes.) Some older packages still keeptheir documentation in/usr/doc/instead of/usr/share/doc/.

There are links to quite a lot of documentation on the main Cygwinproject web page,https://cygwin.com/, including this FAQ.Be sure to at least read any 'Release Notes' or 'Readme' or 'read this'links on the main web page, if there are any.

There is a comprehensive Cygwin User's Guide athttps://cygwin.com/cygwin-ug-net/cygwin-ug-net.htmland an API Reference athttps://cygwin.com/cygwin-api/cygwin-api.html.

You can find documentation for the individual GNU tools athttp://www.gnu.org/manual/.

3.2.

What Cygwin mailing lists can I join?

Comprehensive information about the Cygwin mailing lists can be found athttps://cygwin.com/lists.html.

3.3.

What if I have a problem? (Or: Why won't you/the mailing list answer my questions?)

Comprehensive information about reporting problems with Cygwin can be found athttps://cygwin.com/problems.html.

4. Using Cygwin

4.1.Why can't my application locate cygncurses-8.dll? or cygintl-3.dll? or cygreadline6.dll? or ...?

4.2.Starting a new terminal window is slow. What's going on?

4.3.Why is Cygwin suddenly so slow?

4.4.Why can't my services access network shares?

4.5.How should I set my PATH?

4.6.Bash (or another shell) says "command not found", but it's right there!

4.7.How do I convert between Windows and UNIX paths?

4.8.Why doesn't bash read my .bashrc file on startup?

4.9.How can I get bash filename completion to be case insensitive?

4.10.Can I use paths/filenames containing spaces in them?

4.11.Why can't I cd into a shortcut to a directory?

4.12.I'm having basic problems with find. Why?

4.13.Why doesn't su work?

4.14.Why doesn't man -k,apropos or whatis work?

4.15.Why doesn't chmod work?

4.16.Why doesn't my shell script work?

4.17.How do I print under Cygwin?

4.18.Why don't international (Unicode) characters work?

4.19.My application prints international characters but I onlysee gray boxes

4.20.Is it OK to have multiple copies of the DLL?

4.21.I read the above but I want to bundle Cygwin with a product, and ship itto customer sites. How can I do this without conflicting with any Cygwininstalled by the user?

4.22.Can I bundle Cygwin with my product for free?

4.23.But doesn't that mean that if some application installs an older CygwinDLL on top of a newer DLL, my application will break?

4.24.Why isn't package XYZ available in Cygwin?

4.25.Why is the Cygwin package of XYZ so out of date?

4.26.How can I access other drives?

4.27.How can I copy and paste into Cygwin console windows?

4.28.What firewall should I use with Cygwin?

4.29.How can I share files between Unix and Windows?

4.30.Is Cygwin case-sensitive??

4.31.What about DOS special filenames?

4.32.Does Cygwin support sparse files?

4.33.When it hangs, how do I get it back?

4.34.Why the weird directory structure?

4.35.How do anti-virus programs like Cygwin?

4.36.Is there a Cygwin port of GNU Emacs?

4.37.Is there a Cygwin port of XEmacs?

4.38.Why don't some of my old symlinks work anymore?

4.39.Why don't symlinks work on Samba-mounted filesystems?

4.40.Why does public key authentication with ssh fail after updating to Cygwin 1.7.34 or later?

4.41.Why is my .rhosts file not recognized by rlogin anymore after updating to Cygwin 1.7.34?

4.42.Why do my files have extra permissions after updating to Cygwin 1.7.34?

4.43.Why do my Tk programs not work anymore?

4.44.What applications have been found to interfere with Cygwin?

4.45.How do I fix fork() failures?

4.46.How do I fix find_fast_cwd warnings?

4.1.

Why can't my application locate cygncurses-8.dll? or cygintl-3.dll? or cygreadline6.dll? or ...?

Well, something has gone wrong somehow...

To repair the damage, you must run the Cygwin Setup program again, and re-install thepackage which provides the missing DLL package.

If you already installed the package at one point, the Cygwin Setupprogram won't show the option to install the package by default. In the``Select packages to install'' dialog, choose ``Full'' in theView drop-down menu. This lists all packages, even thosethat are already installed. Scroll down to locate the missing package, forinstancelibncurses8. Choose the ``Reinstall'' action fromthe drop-down menu in the ``New'' column. Continue with the installation.

For a detailed explanation of the general problem, and how to extendit to other missing DLLs and identify their containing packages, seehttps://cygwin.com/ml/cygwin/2002-01/msg01619.html.

4.2.

Starting a new terminal window is slow. What's going on?

There are many possible causes for this.

If your terminal windows suddenly began starting slowly after aCygwin upgrade, it may indicate issues in the authenticationsetup.

For almost all its lifetime, Cygwin has used Unix-like/etc/passwd and/etc/groupfiles to mirror the contents of the Windows SAM and AD databases.Although these files can still be used, since Cygwin 1.7.34, newinstallations now use the SAM/AD databases directly.

To switch to the new method, move these two files out of the wayand restart the Cygwin terminal. That runs Cygwin in its new defaultmode.

If you are on a system that isn't using AD domain logins, thismakes Cygwin use the native Windows SAM database directly, which may befaster than the old method involving/etc/passwdand such. At worst, it will only be a bit slower. (The speed differenceyou see depends on which benchmark you run.) For the AD case, it can beslower than the old method, since it is trading a local file read for anetwork request. Version 1.7.35 will reduce the number of AD serverrequests the DLL makes relative to 1.7.34, with the consequence that youwill now have to alter/etc/nsswitch.conf in orderto change your Cygwin home directory, instead of being able to change itfrom the AD configuration.

If you are still experiencing very slow shell startups, there area number of other things you can look into:

If none of the above helps, the best troubleshooting method is torun your startup scripts in debug mode. Right-click your Cygwin Terminalicon, go to Properties, and edit the command. It should be somethinglikeC:\cygwin\bin\mintty.exe -i /Cygwin-Terminal.ico-. Assuming you are using Bash for your login shell, changeit toC:\cygwin\bin\mintty /bin/bash -lx then tryrunning Cygwin Terminal again. The-x option tells Bashto write every command it runs to the terminal before launching it. Ifthe terminal immediately starts filling with lines of text but thenpauses, the line where the output paused is your clue as to what's goingon. The Cygwin DLL proper probably isn't the cause of the slowdown inthis case, since those delays happen before the first line of textappears in the terminal.

4.3.

Why is Cygwin suddenlyso slow?

If suddenlyevery command takes avery long time, then something is probably attempting to access a network share. You may have the obsolete//cnotation in your PATH or startup files. Using//c meansto contact thenetwork serverc, whichwill slow things down tremendously if it does not exist.

4.4.

Why can't my services access network shares?

If your service is one of those which switch the user context(cygsshd, inetd, etc), then it depends on the method used to switch toanother user. This problem as well as its solution is described indetail in the Cygwin User's Guide, seehttps://cygwin.com/cygwin-ug-net/ntsec.html.

Workarounds include using public network share that does not requireauthentication (for non-critical files), providing your password to anet use command, or running the service as your ownuser withcygrunsrv -u (see/usr/share/doc/Cygwin/cygrunsrv.README for moreinformation).

4.5.

How should I set my PATH?

This is done for you in the file /etc/profile, which is sourced by bashwhen you start it from the Desktop or Start Menu shortcut, created bythe Cygwin Setup program. The line is

PATH="/usr/local/bin:/usr/bin:/bin:$PATH"

Effectively, thisprepends /usr/local/bin and /usr/bin to yourWindows system path. If you choose to reset your PATH, say in$HOME/.bashrc, or by editing etc/profile directly, then you shouldfollow this rule. Youmust have/usr/bin in your PATHbefore any Windows system directories. (And you must not omitthe Windows system directories!) Otherwise you will likely encounterall sorts of problems running Cygwin applications.

If you're using another shell than bash (say, tcsh), the mechanismis the same, just the names of the login scripts are different.

4.6.

Bash (or another shell) says "command not found", but it's right there!

If you compile a program, you might find that you can't run it:

bash$ gcc -o hello hello.c        bash$ hello        bash: hello: command not found

Unlike the Windows default behaviour, Unix shells like bash do not look for programs in. (the currentdirectory) by default. You can add. to your PATH (see above),but this is not recommended (at least on UNIX) for security reasons.Just tell bash where to find it, when you type it on the command line:

bash$ gcc -o hello hello.c        bash$ ./hello        Hello World!

4.7.

How do I convert between Windows and UNIX paths?

Use the 'cygpath' utility. Type 'cygpath --help' forinformation. For example (on my installation):

bash$ cygpath --windows ~/.bashrc        D:\starksb\.bashrc        bash$ cygpath --unix C:/cygwin/bin/ls.exe        /usr/bin/ls.exe        bash$ cygpath --unix C:\\cygwin\\bin\\ls.exe        /usr/bin/ls.exe

Note that bash interprets the backslash '\' as an escape character, soyou must type it twice in the bash shell if you want it to be recognizedas such.

4.8.

Why doesn't bash read my .bashrc file on startup?

Your .bashrc is read from your home directory specified by the HOMEenvironment variable. It uses /.bashrc if HOME is not set. So you needto set HOME (and the home dir in your passwd account information) correctly.

4.9.

How can I get bash filename completion to be case insensitive?

Add the following to your~/.bashrc file:

shopt -s nocaseglob

and add the following to your~/.inputrc file:

set completion-ignore-case on

4.10.

Can I use paths/filenames containing spaces in them?

Cygwin does support spaces in filenames and paths. That said, someutilities that use the library may not, since files don't typicallycontain spaces in Unix. If you stumble into problems with this, youwill need to either fix the utilities or stop using spaces in filenamesused by Cygwin tools.

In particular, bash interprets space as a word separator. You would haveto quote a filename containing spaces, or escape the space character.For example:

bash-2.03$ cd '/cygdrive/c/Program Files'

or

bash-2.03$ cd /cygdrive/c/Program\ Files

4.11.

Why can't I cd into a shortcut to a directory?

Cygwin does not follow MS Windows Explorer Shortcuts(*.lnk files). It sees a shortcut as a regular file and this youcannot "cd" into it.

Cygwin is also capable to create POSIX symlinks as Windows shortcuts (see the CYGWIN environment variable option "winsymlinks"), but theseshortcuts are different from shortcuts created by native Windowsapplications. Windows applications can usually make use of Cygwinshortcuts but not vice versa. This is by choice. The reason is thatWindows shortcuts may contain a bunch of extra information which wouldget lost, if, for example, Cygwin tar archives and extracts them assymlinks.

Changing a Cygwin shortcut in Windows Explorer usually changes a Cygwinshortcut into a Windows native shortcut. Afterwards, Cygwin will notrecognize it as symlink anymore.

4.12.

I'm having basic problems with find. Why?

Make sure you are using the find that came with Cygwin and that youaren't picking up the Win32 find command instead. You can verify thatyou are getting the right one by doing a "type find" in bash.

If the path argument to find, including current directory (default), isitself a symbolic link, then find will not traverse it unless youspecify the-follow option. This behavior is different than mostother UNIX implementations, but is not likely to change.

If find does not seem to be producing enough results, or seems to bemissing out some directories, you may be experiencing a problem with oneof find's optimisations. The absence of. and..directories on some filesystems, such as DVD-R UDF, can confuse find.See the documentation for the option-noleaf in the man page.

4.13.

Why doesn'tsu work?

Thesu command has been in and out of Cygwin distributions, butit has not been ported to Cygwin and has never worked. It iscurrently installed as part of the sh-utils, but again, it does not work.

You should rather installsshd as a service(the service will be calledcygsshd so as not tocollide with the Microsoftsshd service) and usessh username@localhost as asureplacement.

For some technical background into whysu doesn'twork, readhttps://www.cygwin.com/ml/cygwin/2003-06/msg00897.html andrelated messages.

4.14.

Why doesn'tman -k,apropos orwhatis work?

Before you can useman -k,aproposorwhatis, youmust create the whatis database. Just run the command

mandb

(it may take a few minutes to complete).

4.15.

Why doesn'tchmod work?

If you're using FAT32 instead of NTFS,chmod will fail since FAT32 does not provide any permission information.You should really consider converting the drive to NTFS withCONVERT.EXE. FAT and FAT32 are barely good enoughfor memory cards or USB sticks to exchange pictures...

For other cases, understand that Cygwin attempts to show UNIX permissions based on the security features of Windows, so the Windows ACLs are likely the source of your problem. See the Cygwin User's Guide athttps://cygwin.com/cygwin-ug-net/ntsec.htmlfor more information on how Cygwin maps Windows permissions.

4.16.

Why doesn't my shell script work?

There are two basic problems you might run into. One is the fact that/bin/sh is reallybash.It could be missing some features you might expect in/bin/sh, if you are used to/bin/shactually beingzsh (MacOS X "Panther") orksh (Tru64).

Or, it could be a permission problem, and Cygwin doesn't understandthat your script is executable. On NTFS or NFS just make the scriptexecutable usingchmod +x. However,chmod may not work due to restrictions of thefilesystem (see FAQ entry above). In this case Cygwin must read thecontents of files to determine if they are executable. If your scriptdoes not start with

#! /bin/sh

(or any path to a script interpreter, it does not have to be /bin/sh)then Cygwin will not know it is an executable script. The Bourne shellidiom

:# This is the 2nd line, assume processing by /bin/sh

also works.

Note that you can use the filesystem flagcygexec in/etc/fstab to force Cygwin to treat all filesunder the mount point as executable. This can be used for individualfiles as well as directories. Then Cygwin will not bother to read filesto determine whether they are executable.

4.17.

How do I print under Cygwin?

lpr is available in the cygutils package. Someusage hints are available courtesy of Rodrigo Medina.

Jason Tishler has written a couple of messages that explain how to usea2ps (for nicely formatted text in PostScript) and ghostscript (to printPostScript files on non-PostScript Windows printers). Start athttps://cygwin.com/ml/cygwin/2001-04/msg00657.html. Note thatthese are old mails anda2ps as well asfile are long available as part of the Cygwin distribution.

Alternatively, you can use the Windowsprintcommand. Type

bash$ print /\?

for usage instructions (note the? must be escapedfrom the shell).

Finally, you can simplycat the file to the printer's share name:

bash$ cat myfile > //host/printer

You may need to press the formfeed button on your printer or append theformfeed character to your file.

4.18.

Why don't international (Unicode) characters work?

Internationalization is a complex issue. The short answer is thatCygwin relies on the setting of the setting of LANG/LC_xxx environmentvariables. The long answer can be found in the User's Guide in thesectionInternationalization

Cygwin uses UTF-8 by default. To use a different character set, youneed to set the LC_ALL, LC_CTYPE or LANG environment variables.

4.19.

My application prints international characters but I onlysee gray boxes

In the case of Cygwin programs, this likely means that thecharacter set as determined by the LC_ALL, LC_CTYPE or LANG environmentvariables does not match the one set on the Text page of the Cygwin Terminal'soptions. Setting the locale in the terminal's options will set the LANGvariable accordingly.

Non-Cygwin programs in the Cygwin Terminal do not usually takeheed of the locale environment variables. Instead, they often use theso-called console codepage, which can be determined with the commandcmd /c chcp followed by the appropriate Windowscodepage number. The codepage number for Cygwin's default UTF-8 characterset is 65001.

4.20.

Is it OK to have multiple copies of the DLL?

Yes, as long as they are used in strictly separated installations.

The Cygwin DLL has to handle various sharing situations betweenmultiple processes. It has to keep a process table. It has to maintaina mount table which is based on the installation path of the Cygwin DLL.

For that reason, the Cygwin DLL maintains shared resources based ona hash value created from its own installation path. Each Cygwin DLLon the machine constitutes a Cygwin installation, with the directorythe Cygwin DLL resides in treated as "/bin", the parent directory as "/".

Therefore, you can install two or more separate Cygwin distros ona single machine. Each of these installations use their own Cygwin DLL,and they don't share the default POSIX paths, nor process tables, norany other shared resource used to maintain the installation.

However, a clean separation requires that you don't try to runexecutables of one Cygwin installation from processes running in anotherCygwin installation. This may or may not work, but the chances that theresult is not what you expect are pretty high.

If you get the error "shared region is corrupted" or "shared regionversion mismatch" it means you have multiple versions of cygwin1.dllrunning at the same time which conflict with each other. Apart frommixing executables of different Cygwin installations, this could also happenif you have one a single Cygwin installation, for example, if you update theCygwin package without exitingall Cygwin apps (includingservices like cygsshd) beforehand.

The only DLL that is sanctioned by the Cygwin project is the one thatyou get by running theCygwin Setup program,installed in a directory controlled by this program. If you have otherversions on your system and desire help from the cygwin project, you shoulddelete or rename all DLLs that are not installed bythe Cygwin Setup program.

If you're trying to find multiple versions of the DLL that are causingthis problem, reboot first, in case DLLs still loaded in memory are thecause. Then use the Windows System find utility to search your wholemachine, not just components in your PATH (as 'type' would do) orcygwin-mounted filesystems (as Cygwin 'find' would do).

4.21.

I read the above but I want to bundle Cygwin with a product, and ship itto customer sites. How can I do this without conflicting with any Cygwininstalled by the user?

Usually, if you keep your installation separate, nothing bad should happen.However, for the user's convenience, and to avoid potential problems whichstill can occur, consider to integrate your product with an already existingCygwin installation on the user's machine, or, if there is none, considerto install the official Cygwin distro on behalf of the user and integrateyour tools from there. (If you write a tool to make this easy, considercontributing it for others to use)

4.22.

Can I bundle Cygwin with my product for free?

Starting with Cygwin version 2.5.2, which is LGPL licensed, yes, albeitit's not recommended for interoperability reasons.

Cygwin versions prior to 2.5.2 were GPL licensed.If you choose to distribute an older cygwin1.dll, you must be willing todistribute the exact source code used to build that copy of cygwin1.dllas per the terms of the GPL. If you ship applications that link witholder cygwin1.dll, you must provide those applications' source codeunder a GPL-compatible license.

4.23.

But doesn't that mean that if some application installs an older CygwinDLL on top of a newer DLL, my application will break?

It depends on what you mean by "break". If the application installs aversion of the Cygwin DLL in another location than Cygwin's /bindirectory then the rules inQ: 4.21 apply. If the application installs an older version of the DLL in /bin then youshould complain loudly to the application provider.

Remember that the Cygwin DLL strives to be backwards compatible so anewer version of the DLL should always work with older executables. So,in general, it is always best to keep one version of the DLL on yoursystem and it should always be the latest version which matches yourinstalled distribution.

4.24.

Why isn't package XYZ available in Cygwin?

Probably because there is nobody willing or able to maintain it. Ittakes time, and the priority for the Cygwin Team is the Cygwin package.The rest is a volunteer effort. Want to contribute? Seehttps://cygwin.com/packaging.html.

4.25.

Why is the Cygwin package of XYZ so out of date?

(Also: Why is the version of package XYZ older than the version that Ican download from the XYZ web site? Why is the version of package XYZolder than the version that I installed on my linux system? Is theresomething special about Cygwin which requires that only an older versionof package XYZ will work on it?)

Every package in the Cygwin distribution has a maintainer who isresponsible for sending out updates of the package. This person is avolunteer who is rarely the same person as the official developer of thepackage. If you notice that a version of a package seems to be out ofdate, the reason is usually pretty simple -- the person who ismaintaining the package hasn't gotten around to updating it yet. Rarely,the newer package actually requires complex changes that the maintaineris working out.

If you urgently need an update, sending a polite message to the cygwinmailing list pinging the maintainer is perfectly acceptable. There areno guarantees that the maintainer will have time to update the packageor that you'll receive a response to your request, however.

Remember that the operative term here is "volunteer".

4.26.

How can I access other drives?

You have some flexibility here.

Cygwin has a builtin "cygdrive prefix" for drives that are not mounted.You can access any drive, say Z:, as '/cygdrive/z/'.

In some applications (notably bash), you can use the familiar windows<drive>:/path/, using posix forward-slashes ('/') instead of Windowsbackward-slashes ('\'). (But see the warning below!) This maps in theobvious way to the Windows path, but will be converted internally to usethe Cygwin path, following mounts (default or explicit). For example:

bash$ cd C:/Windowsbash$ pwd        /cygdrive/c/Windows

and

bash$ cd C:/cygwinbash$ pwd        /

for a default setup. You could also use backward-slashes in theWindows path, but these would have to be escaped from the shell.

Warning: There is some ambiguity in going from a Windows pathto the posix path, because different posix paths, through differentmount points, could map to the same Windows directory. This mattersbecause different mount points may be binmode or textmode, so thebehavior of Cygwin apps will vary depending on the posix path used toget there.

You can avoid the ambiguity of Windows paths, and avoid typing"/cygdrive", by explicitly mounting drives to posix paths. For example:

bash$ mkdir /cbash$ mount c:/ /cbash$ ls /c

Then/cygdrive/c/Windows becomes/c/Windows which is alittle less typing.

Note that you have to enter the mount point into the/etc/fstab file to keep it indefinitely. The mount command will only add the mount point for the lifetimeof your current Cygwin session.

You can change the defaultcygdrive prefix and whether it is binmode or textmode using the/etc/fstab fileas well. See the Cygwin User's Guide athttps://cygwin.com/cygwin-ug-net/using.html#mount-tablefor more details.

4.27.

How can I copy and paste into Cygwin console windows?

First, consider using mintty instead of the standard consolewindow. In mintty, selecting with the left-mouse also copies,and middle-mouse pastes. It couldn't be easier!

In Windows's console window, open the properties dialog.The options contain a toggle button, named "Quick edit mode". It mustbe ON. Save the properties.

You can also bind the insert key to paste from the clipboard by adding the following line to your .inputrc file:

"\e[2~": paste-from-clipboard

4.28.

What firewall should I use with Cygwin?

We have had good reports about Kerio Personal Firewall, ZoneLabsIntegrity Desktop, and the Windows built-in firewall. Other well-knownproducts including ZoneAlarm and Norton Internet Security have causedproblems for some users but work fine for others. At last report,Agnitum Outpost did not work with Cygwin. If you are having strangeconnection-related problems, disabling the firewall is a goodtroubleshooting step (as is closing or disabling all other runningapplications, especially resource-intensive processes such as indexedsearch).

On the whole, Cygwin doesn't care which firewall is used. The few rareexceptions have to do with socket code.Cygwin uses sockets to implement many of its functions, such as IPC.Some overzealous firewalls install themselves deeply into the winsockstack (with the 'layered service provider' API) and install hooksthroughout. Sadly the mailing list archives are littered with examplesof poorly written firewall-type software that causes things to break.Note that with many of these products, simply disabling the firewalldoes not remove these changes; it must be completely uninstalled.

See alsoBLODAfor a list of applications that have been known, at one time or another, to interfere with the normal functioning of Cygwin.

4.29.

How can I share files between Unix and Windows?

During development, we have Linux boxes running Samba and NFS as wellas Windows machines. We often build with cross-compilers under Linux and copybinaries and source to the Windows system or just toy with themdirectly off the Samba-mounted partition. Or, we use the Microsoft NFSclient and just use NFS shares on Linux from Windows. And then there aretools likescp,ftp,rsync, ...

4.30.

Is Cygwin case-sensitive??

Several Unix programs expect to be able to use to filenamesspelled the same way, but with different case. A prime exampleof this is perl's configuration script, which wantsMakefile andmakefile. Windows can'ttell the difference between files with just different case, so theconfiguration fails.

To help with this problem, Cygwin supports case sensitivity. For adetailed description how to use that feature see the Cygwin User's Guide athttps://cygwin.com/cygwin-ug-net/using-specialnames.html.

4.31.

What about DOS special filenames?

In Windows, files cannot be named com1, lpt1, or aux (to name a few);either as the root filename or as the extension part. If you do, you'll havetrouble. Unix programs don't avoid these names which can make thingsinteresting. E.g., the perl distribution has a file calledaux.sh. The perl configuration tries to make sure thataux.sh is there, but an operation on a file with the magicletters 'aux' in it will hang.

At least that's what happens when using native Windows tools. Cygwincan deal with these filenames just fine. Again, see the User's Guide athttps://cygwin.com/cygwin-ug-net/using-specialnames.htmlfor a detailed description of what's possible with filenames and what is not.

4.32.

Does Cygwin support sparse files?

Filesystems of Unix-like operating systems traditionally provideautomatic support for sparse files: no disk blocks are allocated for fileregions which are not explicitly written. The Windows NTFS filesystemsupports sparse files, but requires to enable it for individual files viaFILE_ATTRIBUTE_SPARSE_FILE. If the mount optionsparse is used or the mount point is on a solid statedevice, Cygwin heuristically detects skipped file regions and sets thisattribute then. Independent of mount option or SSD, sparse files may alsobe created if an application uses the related POSIX functionality(FALLOC_FL_PUNCH_HOLE) as thecpcommand does if--sparse=always is specified. In some usecases requiring only a single sparse file, for example creating disk imageswithdd orddrescue, it is alsopossible to preset the sparse attribute withchattr.

Example (sparse not set, no SSD):

$ mkdir 0$ > 0/is_sparse$ chattr +S 0/is_sparse$ dd if=/dev/zero bs=1M count=1 of=0/is_sparse conv=sparse,notrunc$ echo EOF >> 0/is_sparse$ dd if=/dev/zero bs=1M count=1 of=0/maybe_sparse conv=sparse$ echo EOF >> 0/maybe_sparse$ dd if=/dev/zero bs=1M count=1 of=0/not_sparse$ echo EOF >> 0/not_sparse$ cp -a 0 1$ cp -a --sparse=always 0 2$ ls -hls ?/* 64K -rw-r--r-- 1 user group 1.1M Feb 22 12:42 0/is_sparse1.1M -rw-r--r-- 1 user group 1.1M Feb 22 12:42 0/maybe_sparse1.1M -rw-r--r-- 1 user group 1.1M Feb 22 12:42 0/not_sparse1.1M -rw-r--r-- 1 user group 1.1M Feb 22 12:42 1/is_sparse1.1M -rw-r--r-- 1 user group 1.1M Feb 22 12:42 1/maybe_sparse1.1M -rw-r--r-- 1 user group 1.1M Feb 22 12:42 1/not_sparse 64K -rw-r--r-- 1 user group 1.1M Feb 22 12:42 2/is_sparse 64K -rw-r--r-- 1 user group 1.1M Feb 22 12:42 2/maybe_sparse 64K -rw-r--r-- 1 user group 1.1M Feb 22 12:42 2/not_sparse$ lsattr ?/*---a-S-------- 0/is_sparse---a---------- 0/maybe_sparse---a---------- 0/not_sparse---a---------- 1/is_sparse---a---------- 1/maybe_sparse---a---------- 1/not_sparse---a-S-------- 2/is_sparse---a-S-------- 2/maybe_sparse---a-S-------- 2/not_sparse

Withsparse mount option or a SSD, all?/maybe_sparse files would be sparse.

Note that the detection of solid state devices may be false negative invarious configurations, for example RAID volumes, USB flash drives, very oldSATA SSDs, or SSDs behind USB docking stations.

4.33.

When it hangs, how do I get it back?

If something goes wrong and the tools hang on you for some reason (easyto do if you try and read a file called aux.sh), first try hitting ^C toreturn to bash or the cmd prompt.

If you start up another shell, and applications don't run, it's a goodbet that the hung process is still running somewhere. Use the TaskManager, pview, or a similar utility to kill the process.

And, if all else fails, there's always the reset button/power switch.In theory this should never be necessary, though.

4.34.

Why the weird directory structure?

Why do /lib and /usr/lib (and /bin, /usr/bin) point to the same thing?

Why use mounts instead of symbolic links?

Can I use a disk root (e.g., C:\) as Cygwin root? Why is this discouraged?

After a new installation in the default location, your mount points willlook something like this:

bash$ mountC:\cygwin\bin on /usr/bin type ntfs (binary,auto)C:\cygwin\lib on /usr/lib type ntfs (binary,auto)C:\cygwin on / type ntfs (binary,auto)C: on /cygdrive/c type ntfs (binary,posix=0,user,noumount,auto)

Note that /bin and /usr/bin point to the same location, as do /lib and/usr/lib. This is intentional, and you should not undo these mountsunless youreally know what you are doing.

Various applications and packages may expect to be installed in /lib or/usr/lib (similarly /bin or /usr/bin). Rather than distinguish betweenthem and try to keep track of them (possibly requiring the occasionalduplication or symbolic link), it was decided to maintain only oneactual directory, with equivalent ways to access it.

Symbolic links had been considered for this purpose, but were dismissedbecause they do not always work on Samba drives. Also, mounts arefaster to process because no disk access is required to resolve them.

Note that non-cygwin applications will not observe Cygwin mounts (ormost symlinks for that matter). For example, if you use WinZip to unpack thetar distribution of a Cygwin package, it may not get installed to thecorrect Cygwin path.So don't do this!

It is strongly recommended not to make the Cygwin root directory thesame as your drive's root directory, unless you know what you are doingand are prepared to deal with the consequences. It is generally easierto maintain the Cygwin hierarchy if it is isolated from, say, C:\. Forone thing, you avoid possible collisions with other (non-cygwin)applications that may create (for example) \bin and \lib directories.(Maybe you have nothing like that installed now, but who knows aboutthings you might add in the future?)

4.35.

How do anti-virus programs like Cygwin?

Users have reported that NAI (formerly McAfee) VirusScan for NT (andothers?) is incompatible with Cygwin. This is because it tries to scanthe newly loaded shared memory in cygwin1.dll, which can cause fork() tofail, wreaking havoc on many of the tools. (It is not confirmed thatthis is still a problem, however.)

There have been several reports of NAI VirusScan causing the system tohang when unpacking tar.gz archives. This is surely a bug in VirusScan,and should be reported to NAI. The only workaround is to disableVirusScan when accessing these files. This can be an issue duringSetup, and is discussed in that FAQ entry.

Some users report a significant performance hit using Cygwin when theiranti-virus software is enabled. Rather than disable the anti-virussoftware completely, it may be possible to specify directories whosecontents are exempt from scanning. In a default installation, thiswould beC:\cygwin\bin. Obviously, this could beexploited by a hostile non-Cygwin program, so do this at your own risk.

See alsoBLODAfor a list of applications that have been known, at one time or another, tointerfere with the normal functioning of Cygwin.

4.36.

Is there a Cygwin port of GNU Emacs?

Yes. Install the emacs package. This provides everything youneed in order to run GNU emacs in a terminal window. If you also wantto be able to use the X11(https://x.cygwin.com/)GUI, install the emacs-X11 package. In either case, you run emacs bytyping 'emacs' or '/usr/bin/emacs'.

4.37.

Is there a Cygwin port of XEmacs?

Yes. It can be used in three different modes:

You have toset the DISPLAY environment variablebefore starting xemacs.

bash$ DISPLAY=127.0.0.1:0 xemacs &

You have tounset the DISPLAY environment variablebefore starting xemacs.

bash$ DISPLAY= xemacs &

Start xemacs with -nw in a terminal (native or X11) window

bash$ xemacs -nw

To use all the standard packages with XEmacs you should download the followingtwo packages:

4.38.

Why don't some of my old symlinks work anymore?

Cygwin supports multiple character sets. Symlinks created with Cygwinare using the UTF-16 character set, which is portable across all charactersets. Old symlinks were written using your current Windows codepage, whichis not portable across all character sets. If the target of the symlinkdoesn't resolve anymore, it's very likely that the symlink points to a targetfilename using native, non-ASCII characters, and you're now using anothercharacter set than way back when you created the symlink.

Solution: Delete the symlink and create it again under you new Cygwin.The new symlink will be correctly point to the target no matter what characterset you're using in future.

4.39.

Why don't symlinks work on Samba-mounted filesystems?

Default symlinks on Samba are marked with DOS SYSTEM fileattribute. Samba does not enable this attribute by default. To enableit, consult your Samba documentation and then add these lines to yoursamba configuration file:

map system = yescreate mask = 0775

Note that the 0775 can be anything as long as the 0010 bit is set.

Alternatively, use Windows shortcuts as symlinks. See the CYGWINenvironment variable option "winsymlinks:lnk"https://cygwin.com/cygwin-ug-net/using-cygwinenv.htmlNote that Samba does not support reparse points so some methods tocreate symlinks are just not available.

4.40.

Why does public key authentication with ssh fail after updating to Cygwin 1.7.34 or later?

This is the result of fixing a long-standing security problem in Cygwin'sPOSIX ACL handling. IEEE 1003.1e draft 17 defines that the permissionsof secondary user and group entries in an ACL are reflected in the grouppermission mask by or'ing the permissions of the file's primary group withall permissions of secondary users and groups in the ACL. The backgroundis that this way the standard POSIX permission bits reflect the fact thatsomebody else has additional, otherwisepotentially invisible permissions on the file. This relatively complexinterface has been defined in order to ensure that applications that arecompliant with IEEE 1003.1 (“POSIX.1”) will still function as expected onsystems with ACLs.

So, what does that mean for your situation? Typically this means theprivate key file, for instance~/.ssh/id_rsa, has tooopen permissions. OpenSSH expects the permissions of the private key fileto be 0600. Let's use the default SSH2 RSA keyfile as example:

  $ ls -l .ssh/id_rsa  -rw-------  1 user group 1766 Aug 26  2013 .ssh/id_rsa

However, if other accounts can read the file, the key is potentiallycompromised. Consider the file has additional rw- permissions for a groupbad_guys. Up to Cygwin 1.7.33 that would have lookedlike this:

  $ ls -l .ssh/id_rsa  -rw-------+ 1 user group 1766 Aug 26  2013 .ssh/id_rsa

Notice the extra+ character followingthe permission string. This shows that additional ACL entries are in the ACL.But an application only checking the POSIX permission bits (and ssh is one ofthem!), will not notice the fact, because it gets the permissions 0600 for thefile.

Starting with Cygwin 1.7.34, the extra permissions are reflected inthe group permission bits per IEEE 1003.1e draft 17:

  $ ls -l .ssh/id_rsa  -rw-rw----+ 1 user group 1766 Aug 26  2013 .ssh/id_rsa

So now ssh will notice that the file has extra permissions and it willcomplain. The same problem occurs if the file~/.ssh/authorized_keys has too open permissions. Onthe client side you won't get any helping text, though, other than that you'resuddenly asked for a password. That's a rather good hint to have a closerlook at the server's~/.ssh/authorized_keys file.

To fix the permissions of your private key file or your~/.ssh/authorized_keys file, simply use thesetfacl command with the-b option. This removes all additional ACL entries and thus fixes the permissions tobe not too open:

  $ ls -l .ssh/id_rsa  -rw-rw----+ 1 user group 1766 Aug 26  2013 .ssh/id_rsa  $ setfacl -b .ssh/id_rsa  $ ls -l .ssh/id_rsa  -rw-------  1 user group 1766 Aug 26  2013 .ssh/id_rsa

If the secondls command still gives you-rw-rw---- permissions after runningthe above commands, it is proably because the file's primary groupis your user's personal group:

  $ ls -l .ssh/id_rsa  -rw-rw----  1 Fred Fred 1766 Aug 26  2013 .ssh/id_rsa

Since the Windows security system treats groups and users asmuch the same thing, a change to the user or group permissions onsuch a file reflects the change to both user and group. In effect,mode 0600 becomes mode 0660. Because we are saying we want thesefiles to be readable only by our user, the fix for this is easy:

  $ chgrp `id -g` ~/.ssh/*

That resets the group on these files to your default groupwhich should be something likeUsers,depending on your local configuration. If that doesn't work, you cantry something like this instead:

  $ chgrp None ~/.ssh/*

That group always exists, but its name is different onnon-English versions of Windows. You might also want to use adomain group instead of a local group if your site uses Windowsdomains. For example, you might want to use theDomainUsers group instead.

For more information onsetfacl, seehttps://cygwin.com/cygwin-ug-net/setfacl.html

4.41.

Why is my .rhosts file not recognized by rlogin anymore after updating to Cygwin 1.7.34?

The problem is exactly the same as with the key files of SSH. SeeQ: 4.40.

The solution is the same:

  $ ls -l .rhosts  -rw-rw----+ 1 user group 42 Nov 12  2010 .rhosts  $ setfacl -b .rhosts  $ ls -l .rhosts  -rw-------  1 user group 42 Nov 12  2010 .rhosts

4.42.

Why do my files have extra permissions after updating to Cygwin 1.7.34?

The problem is exactly the same as with the key files of SSH. SeeQ: 4.40.

The solution is the same:

  $ ls -l *  -rw-rwxr--+ 1 user group 42 Nov 12  2010 file1  -rw-rwxr--+ 1 user group 42 Nov 12  2010 file2  $ setfacl -b *  $ ls -l *  -rw-r--r--  1 user group 42 Nov 12  2010 file1  -rw-r--r--  1 user group 42 Nov 12  2010 file2

You may find that newly-created files also have unexpectedpermissions:

  $ touch foo  $ ls -l foo  -rw-rwxr--+ 1 user group 42 Nov 12  2010 foo

This probably means that the directory in which you're creatingthe files has unwanted default ACL entries that are inherited bynewly-created files and subdirectories. The solution is again thesame:

  $ setfacl -b .  $ touch bar  $ ls -l bar  -rw-r--r--  1 user group 42 Nov 12  2010 bar

4.43.

Why do my Tk programs not work anymore?

Previous versions of Tcl/Tk distributed with Cygwin (e.g. tclsh84.exe,wish84.exe) were not actually "Cygwin versions" of those tools.They were built as native libraries, which means they did not understandCygwin mounts or symbolic links. This lead to all sorts of problems interactingwith true Cygwin programs.

As of February 2012, this was replaced with a version of Tcl/Tk whichuses Cygwin's POSIX APIs and X11 for GUI functionality. If you get a messagesuch as this when trying to start a Tk app:

  Application initialization failed: couldn't connect to display ""

Then you need to start an X server, or if one is already running, set theDISPLAY variable to the proper value. The Cygwin distributionincludes an X server; please see theCygwin/X User Guidefor installation and startup instructions.

4.44.

What applications have been found to interfere with Cygwin?

From time to time, people have reported strange failures and problems inCygwin and Cygwin packages that seem to have no rational explanation. Amongthe most common symptoms they report are fork failures, memory leaks, and fileaccess denied problems. These problems, when they have been traced, often appearto be caused by interference from other software installed on the same PC. Securitysoftware, in particular, such as anti-virus, anti-spyware, and firewall applications,often implements its functions by installing hooks into various parts of the system,including both the Explorer shell and the underlying kernel. Sometimes these hooksare not implemented in an entirely transparent fashion, and cause changes in thebehaviour which affect the operation of other programs, such as Cygwin.

Among the software that has been found to cause difficulties are:

Sometimes these problems can be worked around, by temporarily or partiallydisabling the offending software. For instance, it may be possible to disableon-access scanning in your antivirus, or configure it to ignore files under theCygwin installation root. Often, unfortunately, this is not possible; even disablingthe software may not work, since many applications that hook the operating systemleave their hooks installed when disabled, and simply set them into what is intendedto be a completely transparent pass-through mode. Sometimes this pass-through is notas transparent as all that, and the hooks still interfere with Cygwin; in these cases,it may be necessary to uninstall the software altogether to restore normal operation.

Some of the symptoms you may experience are:

4.45.

How do I fixfork() failures?

Unfortunately, Windows does not use the fork/exec model of process creation found in UNIX-like OSes, so it is difficult for Cygwin to implement a reliable and correctfork(), which can lead to error messages such as:

Potential solutions for the above errors:

See the process creation section of the User's Guide for the technical reasons it is so difficult to makefork() work reliably.

4.46.

How do I fixfind_fast_cwd warnings?

Older Cygwin releases asked users to report problems to the mailinglist with the message:

find_fast_cwd: WARNING: Couldn't compute FAST_CWD pointer. Please reportthis problem to the public mailing listcygwin@cygwin.com

Recent Cygwin releases changed this to the message:

This typically occurs if you're using an older Cygwin version on a newer Windows.Please update to the latest available Cygwin version fromhttps://cygwin.com/.If the problem persists, please seehttps://cygwin.com/problems.html.

This is not serious, just a warning that Cygwin may not always beable to exactly emulate all aspects of Unix current directory handlingunder your Windows release.

Unfortunately some projects and products still distribute olderCygwin releases which may not fully support newer Windows releases,instead of installing the current release from the Cygwin project.They also may not provide any obvious way to keep the Cygwin packagestheir application uses up to date with fixes for security issues andupgrades.

The solution is simply downloading and running the Cygwin Setup program,following the instructions in theInternet Setup section of ``Setting Up Cygwin'' in theCygwin User's Guide.

Please exit from all applications before running the Cygwin Setup program.When running Setup, you should not change most of the values presented,just select theNext button in most cases, as youalready have a Cygwin release installed, and only want to upgrade yourcurrent installation.You should make your own selection if the internet connection to yoursystem requires a proxy; and you must always pick an up to date Cygwindownload (mirror) site, preferably the site nearest to your system forfaster downloads, as shown, with more details to help you choose, on the Mirror Sites web page.

The Cygwin Setup program will download and apply upgrades to all packagesrequired for Cygwin itself and installed applications.Any problems with applying updates, or the application after updates,should be reported to the project or product supplier for remedialaction.

As Cygwin is a volunteer project, unable to provide support for olderreleases installed by projects or products, it would be helpful to letother users know what project or product you installed, in a quick email.

5. Cygwin API Questions

5.1.How does everything work?

5.2.Are development snapshots for the Cygwin library available?

5.3.Are test releases for the Cygwin library available?

5.4.How is the DOS/Unix CR/LF thing handled?

5.5.Is the Cygwin library multi-thread-safe?

5.6.How is fork() implemented?

5.7.How does wildcarding (globbing) work?

5.8.How do symbolic links work?

5.9.Why do some files, which are not executables have the 'x' type.

5.10.How secure is Cygwin in a multi-user environment?

5.11.How do the net-related functions work?

5.12.I don't want Unix sockets, how do I use normal Windows winsock?

5.13.What version numbers are associated with Cygwin?

5.14.Why isn't my time (or zone) set correctly?

5.15.Is there a mouse interface?

5.1.

How does everything work?

There's a C library which provides a POSIX-style API. Theapplications are linked with it and voila - they run on Windows.

The aim is to add all the goop necessary to make your apps run onWindows into the C library. Then your apps should (ideally) run on POSIXsystems (Unix/Linux) and Windows with no changes at the source level.

The C library is in a DLL, which makes basic applications quite small.And it allows relatively easy upgrades to the Windows/POSIX translationlayer, providing that DLL changes stay backward-compatible.

For a good overview of Cygwin, you may want to read the CygwinUser's Guide.

5.2.

Are development snapshots for the Cygwin library available?

Starting December 2022, the old developer snapshots have beendeprecated by regular, automated test releases. See the next FAQ entryTest Releases

5.3.

Are test releases for the Cygwin library available?

Yes. Starting December 2022, regular, automated test releasesare created whenever a significant patch is pushed to the Cygwin gitrepo athttps://cygwin.com/cgit/newlib-cygwin/.You can download the cygwin package test releases just like any othertest release for any Cgywin package using the Cygwin Setup program.For more info, seeInstall Test Releases.

5.4.

How is the DOS/Unix CR/LF thing handled?

Let's start with some background.

On POSIX systems, a file is a file and what the file contains iswhatever the program/programmer/user told it to put into it. In Windows,a file is also a file and what the file contains depends not only on theprogram/programmer/user but also the file processing mode.

When processing in text mode, certain values of data are treatedspecially. A \n (new line, NL) written to the file will prepend a \r(carriage return, CR) so that if you `printf("Hello\n") you in fact get"Hello\r\n". Upon reading this combination, the \r is removed and thenumber of bytes returned by the read is 1 less than was actually read.This tends to confuse programs dependent on ftell() and fseek(). ACtrl-Z encountered while reading a file sets the End Of File flags eventhough it truly isn't the end of file.

One of Cygwin's goals is to make it possible to mix Cygwin-portedPOSIX programs with generic Windows programs. As a result, Cygwin allowsto open files in text mode. In the accompanying tools, tools that dealwith binaries (e.g. objdump) operate in POSIX binary mode and many (butnot all) tools that deal with text files (e.g. bash) operate in text mode.There are also some text tools which operate in a mixed mode. They readfiles always in text mode, but write files in binary mode, or they writein the mode (text or binary) which is specified by the underlying mountpoint. For a description of mount points, see the Cygwin User's Guide.

Actually there's no really good reason to do text mode processingsince it only slows down reading and writing files. Additionally manyWindows applications can deal with POSIX \n line endings just fine(unfortunate exception: Notepad). So we suggest to use binary modeas much as possible and only convert files from or to DOS text modeusing tools specifically created to do that job, for instance, dos2unix andunix2dos from the dos2unix package.

It is rather easy for the porter of a Unix package to fix the sourcecode by supplying the appropriate file processing mode switches to theopen/fopen functions. Treat all text files as text and treat all binaryfiles as binary. To be specific, you can select binary mode by addingO_BINARY to the second argument of anopen call, or"b" to second argumentof anfopen call. You can also callsetmode (fd, O_BINARY). To select text mode addO_TEXT to the second argument of anopencall, or"t" to second argument of anfopen call, or just callsetmode (fd, O_TEXT).

You can also avoid to change the source code at all by linkingan additional object file to your executable. Cygwin provides variousobject files in the/usr/lib directory which,when linked to an executable, changes the default open modes of anyfile opened within the executed process itself. The files are

  binmode.o      - Open all files in binary mode.  textmode.o     - Open all files in text mode.  textreadmode.o - Open all files opened for reading in text mode.  automode.o     - Open all files opened for reading in text mode,                   all files opened for writing in binary mode.

Note that of the above flags only the "b" fopen flags are defined byANSI. They exist under most flavors of Unix. However, using O_BINARY,O_TEXT, or the "t" flag is non-portable.

5.5.

Is the Cygwin library multi-thread-safe?

Yes.

There is also extensive support for 'POSIX threads', see the filecygwin.din for the list of POSIX thread functions provided.

5.6.

How is fork() implemented?

Cygwin fork() essentially works like a non-copy on write versionof fork() (like old Unix versions used to do). Because of this itcan be a little slow. In most cases, you are better off using thespawn family of calls if possible.

Here's how it works:

Parent initializes a space in the Cygwin process table for child.Parent creates child suspended using Windows CreateProcess call, givingthe same path it was invoked with itself. Parent calls setjmp to saveits own context and then sets a pointer to this in the Cygwin sharedmemory area (shared among all Cygwin tasks). Parent fills in the child's.data and .bss subsections by copying from its own address space intothe suspended child's address space. Parent then starts the child.Parent waits on mutex for child to get to safe point. Child starts anddiscovers if has been forked and then longjumps using the saved jumpbuffer. Child sets mutex parent is waiting on and then blocks onanother mutex waiting for parent to fill in its stack and heap. Parentnotices child is in safe area, copies stack and heap from itself intochild, releases the mutex the child is waiting on and returns from thefork call. Child wakes from blocking on mutex, recreates any mmappedareas passed to it via shared area and then returns from fork itself.

When the executable or any dll in use by the parent was renamed ormoved into the hidden recycle bin, fork retries with creating hardlinksfor the old executable and any dll into per-user subdirectories in the/var/run/cygfork/ directory, when that one exists and resides on NTFS.

5.7.

How does wildcarding (globbing) work?

If the DLL thinks it was invoked from a DOS style prompt, it runs a`globber' over the arguments provided on the command line. This meansthat if you typeLS *.EXE from DOS, it will do what you mightexpect.

Beware: globbing usesmalloc. If your application definesmalloc, that will get used. This may do horrible things to you.

5.8.

How do symbolic links work?

Cygwin knows of five ways to create symlinks. This is reallycomplicated stuff since we started out way back when Windows didn'tknow symlinks at all. The rest is history...

5.9.

Why do some files, which are not executables have the 'x' type.

When working out the POSIX-style attribute bits on a file stored oncertain filesystems (FAT, FAT32), the library has to fill out some informationnot provided by these filesystems.

It guesses that files ending in .exe and .bat are executable, as areones which have a "#!" as their first characters. This guessing doesn'ttake place on filesystems providing real permission information (NTFS, NFS),unless you switch the permission handling off using the mount flag "noacl"on these filesystems.

5.10.

How secure is Cygwin in a multi-user environment?

As of version 1.5.13, the Cygwin developers are not aware of any featurein the cygwin dll that would allow users to gain privileges or to accessobjects to which they have no rights under Windows. However there is noguarantee that Cygwin is as secure as the Windows it runs on. Cygwinprocesses share some variables and are thus easier targets of denial ofservice type of attacks.

5.11.

How do the net-related functions work?

The network support in Cygwin is supposed to provide the POSIX API, notthe Winsock API.

There are differences between the semantics of functions with the samename under the API.

E.g., the POSIX select system call can wait on a standard file handlesand handles to sockets. The select call in Winsock can only wait onsockets. Because of this, the Cygwin dll does a lot of nasty stuff behindthe scenes, trying to persuade various Winsock/Windows functions to do whata Unix select would do.

If you are porting an application which already uses Winsock, thenporting the application to Cygwin means to port the application to usingthe POSIX net functions. You should never mix Cygwin net functions withdirect calls to Winsock functions. If you use Cygwin, use the POSIX API.

5.12.

I don't want Unix sockets, how do I use normal Windows winsock?

You don't. Look for the Mingw-w64 project to port applications usingnative Windows API/Winsock functions. Cross compilers packages to build Mingw-w64targets are available in the Cygwin distro.

5.13.

What version numbers are associated with Cygwin?

Cygwin versioning is relatively complicated because of its status as ashared library. First of all, since October 1998 every Cygwin DLL hasbeen namedcygwin1.dll and has a 1 in the release name.Additionally, there are DLL major and minor numbers that correspond tothe name of the release, and a release number. In other words,cygwin-2.4.1-1 iscygwin1.dll, major version 2, minorversion 4, release 1. -1 is a subrelease number required by the distroversioning scheme. It's not actually part of the Cygwin DLL version number.

Thecygwin1.dll major version number gets incrementedonly when a change is made that makes existing software incompatible. Forexample, the first major version 5 release, cygwin-1.5.0-1, added 64-bitfile I/O operations, which required many libraries to be recompiled andrelinked. The minor version changes every time we make a new backwardcompatible Cygwin release available. There is also acygwin1.dll release version number. The release numberis only incremented if we update an existing release in a way that does noteffect the DLL (like a missing header file).

There are also Cygwin API major and minor numbers. The major numbertracks important non-backward-compatible interface changes to the API.An executable linked with an earlier major number will not be compatiblewith the latest DLL. The minor number tracks significant API additionsor changes that will not break older executables but may be required bynewly compiled ones.

Then there is a shared memory region compatibility version number. It isincremented when incompatible changes are made to the shared memoryregion or to any named shared mutexes, semaphores, etc. For more excitingCygwin version number details, check out the/usr/include/cygwin/version.h file.

5.14.

Why isn't my time (or zone) set correctly?

Daylight saving (Summer time) and other time zone changes aredecided on by politicians, and announced by government officials,sometimes with short or no notice, so time zone updates are released atleast a few, and sometimes several, times a year.Details of changes are not known until they are announced publicly byofficials, often in foreign languages.Those details then have to be noticed, possibly translated, passed to,picked up, and applied by the officialtzdatasource package maintainers.That information has to be compiled, checked, and released publicly inan update to the officialtzdata source package.Then those changes have to be picked up and applied to the Cygwintzdata package, which has to be updated, built,tested, and released publicly.

Time zone settings are updates to the daylight saving (Summertime) rules for dates of changes, hour offsets from UTC of time zones,and the geographic regions to which those rules and offsets apply,provided in thetzdata package included in allCygwin installations.Have you run the Cygwin Setup program recently to update at leastthetzdata package?

Are you developing applications using times which may be affectedby time zones?Since thectime(),localtime(),mktime(), andstrftime() functionsare required to set time zone information as if by callingtzset(), there is no need for an explicittzset() call before using these functions.However, if none of the above functions are called first, applicationsshould ensuretzset() is called explicitly beforeusing any other time functions, or checking or using time zoneinformation.

5.15.

Is there a mouse interface?

If you're using X then use the X API to handle mouse events.In a Windows console window you can enable and capture mouse eventsusing the xterm escape sequences for mouse events.

6. Programming Questions

6.1.How do I contribute a package?

6.2.How do I contribute to Cygwin?

6.3.Why are compiled executables so huge?!?

6.4.What do I have to look out for when porting applications to 64 bit Cygwin?

6.5.My project doesn't build at all on 64 bit Cygwin. What's up?

6.6.Why is __CYGWIN64__ not defined for 64 bit?

6.7.Where is glibc?

6.8.Where is Objective C?

6.9.Why does my make fail on Cygwin with an execvp error?

6.10.How can I use IPC, or why do I get a Bad system callerror?

6.11.Why the undefined reference to WinMain@16?

6.12.How do I use Windows API calls?

6.13.How do I compile a Windows executable that doesn't use Cygwin?

6.14.Can I build a Cygwin program that does not require cygwin1.dll at runtime?

6.15.Can I link with both MSVCRT*.DLL and cygwin1.dll?

6.16.How do I make the console window go away?

6.17.Why does make complain about a "missing separator"?

6.18.Why can't we redistribute Microsoft's Windows API headers?

6.19.How do I use cygwin1.dll with Visual Studio or Mingw-w64?

6.20.How do I link against a .lib file?

6.21.How do I build Cygwin on my own?

6.22.I may have found a bug in Cygwin, how can I debug it (the symbols in gdb look funny)?

6.23.How can I compile Cygwin for an unsupported platform (PowerPC, Alpha, ARM, Itanium)?

6.24.How can I adjust the heap/stack size of an application?

6.25.How can I find out which DLLs are needed by an executable?

6.26.How do I build a DLL?

6.27.How can I set a breakpoint at mainCRTStartup?

6.28.How can I debug what's going on?

6.29.Can I use a system trace mechanism instead?

6.30.How does gdb handle signals?

6.31.The linker complains that it can't find something.

6.32.Why do I get an error using struct stat64?

6.33.Can you make DLLs that are linked against libc ?

6.34.Where is malloc.h?

6.35.Can I use my own malloc?

6.36.Can I mix objects compiled with msvc++ and gcc?

6.37.Can I use the gdb debugger to debug programs built by VC++?

6.38.Shell scripts aren't running properly from my makefiles?

6.39.What preprocessor macros do I need to know about?

6.40.How should I port my Unix GUI to Windows?

6.1.

How do I contribute a package?

If you are willing to be a package maintainer, great! We urgently needvolunteers to prepare and maintain packages, because the priority of theCygwin Team is Cygwin itself.

The Cygwin Package Contributor's Guide athttps://cygwin.com/packages.html details everything you need to knowabout Cygwin packaging.

For questions about package maintenance, use the cygwin-apps mailinglist (start athttps://cygwin.com/lists.html)aftersearching and browsing the cygwin-apps list archives, of course. Besure to look at theSubmitting a package checklist athttps://cygwin.com/packaging-contributors-guide.html#submittingbefore sending an ITP (Intent To Package) email to cygwin-apps.

You should also announce your intentions to the general cygwin list, incase others were thinking the same thing.

6.2.

How do I contribute to Cygwin?

If you want to contribute to Cygwin itself, seehttps://cygwin.com/contrib.html.

6.3.

Why are compiled executables so huge?!?

By default, gcc compiles in all symbols. You'll also find that gcccreates large executables on UNIX.

If that bothers you, just use the 'strip' program, part of the binutilspackage. Or compile with the-s option to gcc.

6.4.

What do I have to look out for when porting applications to 64 bit Cygwin?

The Cygwin x86_64 toolchain is using theLP64data model. That means, in contrast to Windows, which uses anLLP64data model, sizeof(long) != sizeof(int), just as on Linux.

For comparison:

                 Cygwin   Windows  Cygwin                 Linux    x86_64   Linux                 Windows           x86_64                 i686sizeof(int)         4        4        4sizeof(long)        4        4        8sizeof(size_t)      4        8        8sizeof(void*)       4        8        8

This difference can result in interesting problems, especially whenusing Windows API functions using pointers to Windowsdatatypes like LONG, ULONG, DWORD. Given that Windows is LLP64, all ofthe aforementioned types are 4 byte in size, on 32 as well as on 64 bitWindows, while `long' on 64 bit Cygwin is 8 bytes.

Take the example ReadFile:

  ReadFile (HANDLE, LPVOID, DWORD, LPDWORD, LPOVERLAPPED);

In the 32 bit Cygwin and Mingw-w64 environments, as well as in the 64 bitMingw-w64 environment, it is no problem to substitute DWORD with unsignedlong:

  unsigned long number_of_bytes_read;  [...]  ReadFile (fhdl, buf, buflen, &number_of_bytes_read, NULL);

However, in 64 bit Cygwin, using LP64, number_of_bytes_read is 8 bytesin size. But since ReadFile expects a pointer to a 4 byte type, the functionwill only change the lower 4 bytes of number_of_bytes_read on return, whilethe content of the upper 4 bytes stays undefined.

Here are a fewdonts which should help portingapplications from the known ILP32 data model of 32 bit Cygwin, to the LP64data model of 64 bit Cygwin. Note that these are not Cygwin-only problems.Many Linux applications suffered the same somewhat liberal handling ofdatatypes when the AMD64 CPU was new.

6.5.

My project doesn't build at all on 64 bit Cygwin. What's up?

Typically reasons for that are:

In all of this cases, please make sure to fix that upstream, or sendyour patches to the upstream maintainers, so the problems get fixed for thefuture.

6.6.

Why is __CYGWIN64__ not defined for 64 bit?

There is no__CYGWIN64__ because we would like tohave a unified way to handle Cygwin code in portable projects. Using__CYGWIN32__ and__CYGWIN64__ onlycomplicates the code for no good reason. Along the same lines you won'tfind predefined macros__linux32__ and__linux64__ on Linux.

If you really have to differ between 32 and 64 bit in some way, you havethree choices.

6.7.

Where is glibc?

Cygwin does not provide glibc. It uses newlib instead, which providesmuch (but not all) of the same functionality. Porting glibc to Cygwinwould be difficult.

6.8.

Where is Objective C?

Support for compiling Objective C is available in thegcc-objcpackage; resulting binaries will depend on thelibobjc2package at runtime.

6.9.

Why does my make fail on Cygwin with an execvp error?

Beware of using non-portable shell features in your Makefiles (see tipsatUsing Shell Scripts).

Errors ofmake: execvp: /bin/sh: Illegal Argument ormake: execvp: /bin/sh: Argument list too long are oftencaused by the command-line being to long for the Windows execution model.To circumvent this, mount the path of the executable using the -X switchto enable cygexec for all executables in that folder; you will also needto exclude non-cygwin executables with the -x switch. Enabling cygexeccauses cygwin executables to talk directly to one another, which increasesthe command-line limit. To enable cygexec for/bin and/usr/bin, you can add or change these entries in /etc/fstab:

C:/cygwin/bin /bin ntfs binary,cygexec 0 0C:/cygwin/bin /usr/bin ntfs binary,cygexec 0 0

If you have added other non-Cygwin programs to a path you want to mountcygexec, you can find them with a script like this:

#!/bin/shcd /bin; for f in `find . -type f -name '*.exe'`; docygcheck $f | (grep -Fqi cygwin1.dll || echo $f)done

Seehttps://cygwin.com/cygwin-ug-net/using.html#mount-table for more information on using mount.

6.10.

How can I use IPC, or why do I get aBad system callerror?

Try running cygserver. Readhttps://cygwin.com/cygwin-ug-net/using-cygserver.html. If you'retrying to use PostgreSQL, also read/usr/share/doc/Cygwin/postgresql-*.README.

6.11.

Why the undefined reference toWinMain@16?

If you're usinggcc, try adding an empty main() function to oneof your sources. Or, perhaps you have-lm too early in thelink command line. It should be at the end:

    bash$ gcc hello.c -lm    bash$ ./a.exe    Hello World!

works, but

    bash$  gcc -lm hello.c    /c/TEMP/ccjLEGlU.o(.text+0x10):hello.c: multiple definition of `main'    /usr/lib/libm.a(libcmain.o)(.text+0x0):libcmain.c: first defined here    /usr/lib/libm.a(libcmain.o)(.text+0x6a):libcmain.c: undefined reference to `WinMain@16'    collect2: ld returned 1 exit status

If you're using GCJ, you need to pass a "--main" flag:

gcj --main=Hello Hello.java

6.12.

How do I use Windows API calls?

Cygwin tools require that you explicitly link the import librariesfor whatever Windows API functions that you are going to use, with the exceptionof kernel32, which is linked automatically (because the startup and/orbuilt-in code uses it).

For example, to use graphics functions (GDI) you must linkwith gdi32 like this:

gcc -o foo.exe foo.o bar.o -lgdi32

or (compiling and linking in one step):

gcc -o foo.exe foo.c bar.c -lgdi32

The regular setup allows you to use the option -mwindows on thecommand line to include a set of the basic libraries (and alsomake your program a GUI program instead of a console program),including user32, gdi32 and comdlg32.

It is a good idea to put import libraries last on your link line,or at least after all the object files and static libraries that reference them.

6.13.

How do I compile a Windows executable that doesn't use Cygwin?

The compilers provided by themingw64-i686-gcc andmingw64-x86_64-gcc packages link against standard MicrosoftDLLs instead of Cygwin. This is desirable for native Windows programs thatdon't need a UNIX emulation layer.

6.14.

Can I build a Cygwin program that does not require cygwin1.dll at runtime?

No. If your program uses the Cygwin API, then your executable cannotrun without cygwin1.dll. In particular, it is not possible tostatically link with a Cygwin library to obtain an independent,self-contained executable.

If this is an issue because you intend to distribute your Cygwinapplication, then you had better read and understandhttps://cygwin.com/licensing.html, which explains thelicensing options.

6.15.

Can I link with both MSVCRT*.DLL and cygwin1.dll?

No, you must use one or the other, they are mutually exclusive.

6.16.

How do I make the console window go away?

The default during compilation is to produce a console application.It you are writing a GUI program, you should either compile with-mwindows as explained above, or add the string"-Wl,--subsystem,windows" to the GCC command line.

6.17.

Why does make complain about a "missing separator"?

This problem usually occurs as a result of someone editing a Makefilewith a text editor that replaces tab characters with spaces. Commandlines must start with tabs. This is not specific to Cygwin.

6.18.

Why can't we redistribute Microsoft's Windows API headers?

Subsection 2.d.f of the `Microsoft Open Tools License agreement' lookslike it says that one may not "permit further redistribution of theRedistributables to their end users". We take this to mean that we cangive them to you, but you can't give them to anyone else, which issomething that we can't agree to. Fortunately, wehave our own Windows API headers which are pretty complete.

6.19.

How do I usecygwin1.dll with Visual Studio or Mingw-w64?

If you want to load the DLL dynamically, readwinsup/cygwin/how-cygtls-works.txt and the sample code inwinsup/testsuite/cygload to understand how this works.The short version is:

If you want to link statically from Visual Studio, to my knowledgenone of the Cygwin developers have done this, but we have this reportfrom the mailing list that it can be done this way:

Note that if you are using any other Cygwin based librariesthat you will probably need to build them as DLLs using gcc andthen generate import libraries for the MS VC linker.

Thanks to Alastair Growcott (alastair dot growcott at bakbone dot codot uk) for this tip.

6.20.

How do I link against a.lib file?

If your.lib file is a normal static or import library withC-callable entry points, you can listfoo.lib as an object file forgcc/g++, just like any*.o file. Otherwise, here are some steps:

or

You can use these methods to use MSVC (and many other runtime libs)with Cygwin development tools.

Note that this is a lot of work (half a day or so), but much less thanrewriting the runtime library in question from specs...

Thanks to Jacob Navia (root at jacob dot remcomp dot fr) for this explanation.

6.21.

How do I build Cygwin on my own?

First, you need to make sure you have the necessary build toolsinstalled; you at least needgcc-g++,make,automake,autoconf,git,perl,cocom andpatch.

Additionally, building thedumper utility requiresgettext-devel,libiconv-devel,libzstd-devel andzlib-devel. Building this program can be disabled with the--disable-dumper option toconfigure.

Building those Cygwin utilities which are not themselves Cygwin programs(e.g.cygcheck andstrace) also requiresmingw64-x86_64-gcc-g++ andmingw64-x86_64-zlib.Building these programs can be disabled with the--without-cross-bootstrapoption toconfigure.

Building the documentation also requires thedblatex,docbook2X,docbook-xml45,docbook-xsl, andxmlto packages. Buildingthe documentation can be disabled with the--disable-docoption toconfigure.

Next, check out the Cygwin sources from theCygwin GIT source repository).This is thepreferred method for acquiring the sources.Otherwise, if you are trying to duplicate a cygwin release then you shoulddownload the corresponding source package(cygwin-x.y.z-n-src.tar.bz2).

Youmust build cygwin in a separate directory fromthe source, so create something like abuild/ directory.Assuming you checked out the source to/oss/src/newlib-cygwin/, and you want to install to thetemporary location/oss/install/, these are the requiredsteps to build Cygwin:

$ mkdir -p /oss/src/newlib-cygwin/build    # create build dir$ mkdir -p /oss/install                    # create install dir$ cd /oss/src/newlib-cygwin/winsup         # chdir into Cygwin source dir and...$ ./autogen.sh                             # create config files$ cd /oss/src/newlib-cygwin/build          # chdir into build dir$                                          # create makefiles...$ /oss/src/newlib-cygwin/configure --prefix=/oss/install$ make                                     # build Cygwin$ make install                             # install Cygwin into install dir

If the build worked, you can install everything you like into the currentlyrunning system,except the Cygwin DLLcygwin1.dll itself. For installing the DLL, close downall Cygwin programs (including bash windows, any servers likecygserver, etc.), save your old dll, and copy the new dllto the correct place. Then, for first testing, start up a Cygwin programfrom the Windows command prompt and see what happens.

If you get a lengthy error messages like"user shared memory version mismatch detected", it'svery likely a Cygwin process still running using the old DLL. Kill itin Windows' Task Manager ortaskkill and try again.If it's still not working, and if you're sure there's no older Cygwinprocess still running, it's probably a bug you introduced with your changes.From here on, you're on your own or discuss problems on theCygwin-developers mailing list.

6.22.

I may have found a bug in Cygwin, how can I debug it (the symbols in gdb look funny)?

Debugging symbols are stripped from distibuted Cygwin binaries, so todebug withgdb you will need to install thecygwin-debuginfo package to obtain the debug symbols forcygwin1.dll

If your bug causes an exception insidecygwin1.dll you willneed to use thegdb commandset cygwin-exceptionson to tellgdb to stop on exceptions inside theCygwin DLL (by default they are ignored, as they may be generated during normaloperation e.g. when checking a pointer is valid)

It is also a good idea to use the latest code in case the bug has been fixed,so we recommend trying the latest cygwin test release (seeInstall Test Releases) or building the DLL from git.

To build a debugging version of the Cygwin DLL, you will need to followthe instructions atBuild Cygwin.

You can also contact the mailing list for pointers (a simple test case that demonstrates the bug is always welcome).

6.23.

How can I compile Cygwin for an unsupported platform (PowerPC, Alpha, ARM, Itanium)?

Unfortunately, this will be difficult. Exception handling and signalssupport semantics and args have been designed for x86_64 so you would needto write specific support for your platform. We don't know of any otherincompatibilities. Please send us patches if you do this work!

6.24.

How can I adjust the heap/stack size of an application?

If you need to change the maximum amount of memory available to Cygwin, seehttps://cygwin.com/cygwin-ug-net/setup-maxmem.html. Otherwise,just pass heap/stack linker arguments to gcc. To create foo.exe witha heap size of 200MB and a stack size of 8MB, you would invokegcc as:

gcc -Wl,--heap,200000000,--stack,8000000 -o foo foo.c

6.25.

How can I find out which DLLs are needed by an executable?

objdump -p provides this information, but is rather verbose.

cygcheck will do this much more concisely, and operatesrecursively, provided the command is in your path.

6.26.

How do I build a DLL?

There's documentation that explains the process in the Cygwin User'sGuide here:https://cygwin.com/cygwin-ug-net/dll.html.

6.27.

How can I set a breakpoint at mainCRTStartup?

Set a breakpoint ingdb withb *0x401000 (for i686), orb *0x100401000 (for x86_64).

This entrypoint address can be computed as the sum of the ImageBase and AddressOfEntryPoint values given byobjdump -p.

Note that the DllMain entrypoints for linked DLLs will have been executed before this breakpoint is hit.

(It may be necessary to use thegdb commandset disable-randomization on to turn off ASLR for the debuggee to prevent the base address getting randomized.)

6.28.

How can I debug what's going on?

You can debug your application usinggdb. Make sure youcompile it with the -g flag! If your application calls functions inMS DLLs, gdb will complain about not being able to load debug informationfor them when you run your program. This is normal since these DLLsdon't contain debugging information (and even if they did, that debuginfo would not be compatible with gdb).

6.29.

Can I use a system trace mechanism instead?

Yes. You can use thestrace.exe utility to run other cygwinprograms with various debug and trace messages enabled. For informationon usingstrace, see the Cygwin User's Guide.

6.30.

How does gdb handle signals?

gdb maps known Windows exceptions to signals such as SIGSEGV, SIGFPE, SIGTRAP,SIGINT and SIGILL. Other Windows exceptions are passed on to the handler (ifany), and reported as an unknown signal if an unhandled (second chance)exception occurs.

There is also an experimental feature to notify gdb of purely Cygwin signalslike SIGABRT, SIGHUP or SIGUSR1. This currently has some known problems, forexample, single-stepping from these signals may not work as expected.

6.31.

The linker complains that it can't find something.

A common error is to put the library on the command line beforethe thing that needs things from it.

This is wronggcc -lstdc++ hello.cc.This is rightgcc hello.cc -lstdc++.

The first command above (usually) works on Linux, because:

Note that this won't work if the linker flags--as-needed or--no-undefined are used, or if the library being linked with is a static library.

PE/COFF executables work very differently, and the dynamic library which provides a symbol must be fully resolvedat link time (so the library which provides a symbol must follow a reference to it).

See point 3 inQ: 6.40 for more discussion of how this affects plugins.

This also has consequences for how weak symbols are resolved. Seehttps://cygwin.com/ml/cygwin/2010-04/msg00281.html for more discussion of that.

6.32.

Why do I get an error usingstruct stat64?

struct stat64 is not used in Cygwin, justusestruct stat. It's 64 bit aware.

6.33.

Can you make DLLs that are linked against libc ?

Yes.

6.34.

Where is malloc.h?

It exists, but you should rather include stdlib.h instead of malloc.h.stdlib.h is POSIX standard for defining malloc and friends, malloc.h isdefinitely non-standard.

6.35.

Can I use my own malloc?

If you define a function calledmalloc in your own code, and linkwith the DLL, the DLLwill call yourmalloc. Needless tosay, you will run into serious problems if your malloc is buggy.

If you run any programs from the DOS command prompt, rather than from inbash, the DLL will try and expand the wildcards on the command line.This process usesmallocbefore your main line is started.If you have written your ownmalloc to need some initializationto occur aftermain is called, then this will surely break.

Moreover, there is an outstanding issue with_malloc_r innewlib. This re-entrant version ofmalloc will be calleddirectly from withinnewlib, by-passing your custom version, andis probably incompatible with it. But it may not be possible to replace_malloc_r too, becausecygwin1.dll does not export it andCygwin does not expect your program to replace it. This is really anewlib issue, but we are open to suggestions on how to deal with it.

6.36.

Can I mix objects compiled with msvc++ and gcc?

Yes, but only if you are combining C object files. MSVC C++ uses adifferent mangling scheme than GNU C++, so you will have difficultiescombining C++ objects.

6.37.

Can I use the gdb debugger to debug programs built by VC++?

No, not for full (high level source language) debugging.The Microsoft compilers generate a different type of debuggingsymbol information, which gdb does not understand.

However, the low-level (assembly-type) symbols generated byMicrosoft compilers are coff, which gdb DOES understand.Therefore you should at least be able to see all of yourglobal symbols; you just won't have any information aboutdata types, line numbers, local variables etc.

6.38.

Shell scripts aren't running properly from my makefiles?

If your scripts are in the current directory, you must have.(dot) in your $PATH. (It is not normally there by default.) Better yet,add /bin/sh in front of each and every shell script invoked in your Makefiles.

6.39.

What preprocessor macros do I need to know about?

gcc for Cygwin defines __CYGWIN__ when building for a Cygwinenvironment.

Microsoft defines the preprocessor symbol _WIN32 in their Windowsdevelopment environment.

In gcc for Cygwin, _WIN32 is only defined when you use the -mwin32gcc command line options. This is because Cygwin is supposed to be aPOSIX emulation environment in the first place and defining _WIN32 confusessome programs which think that they have to make special concessions fora Windows environment which Cygwin handles automatically.

Check out the predefined symbols in detail by running, for example

       $ gcc  -dM -E -xc /dev/null >gcc.txt       $ gcc -mwin32 -dM -E -xc /dev/null >gcc-mwin32.txt

Then use the diff and grep utilities to check what the difference is.

6.40.

How should I port my Unix GUI to Windows?

Like other Unix-like platforms, the Cygwin distribution includes many ofthe common GUI toolkits, including X11, X Athena widgets, Motif, Tk, GTK+,and Qt. Many programs which rely on these toolkits will work with little, ifany, porting work if they are otherwise portable. However, there are a fewthings to look out for:

7. Copyright

7.1.What are the copyrights?

7.1.

What are the copyrights?

Please seehttps://cygwin.com/licensing.html for more information about Cygwin copyright and licensing.