newlib/winsup/doc/faq-using.xml

<!-- faq-problems.xml -->
<qandaentry id="faq.using.missing-dlls">
<question><para>Why can't my application locate cygncurses5.dll?  or cygintl.dll?  or cygreadline5.dll?  or ...?</para></question>
<answer>

<para>If you upgraded recently, and suddenly vim (or some other Cygwin
application) cannot find <literal>cygncurses5.dll</literal>, it probably means that you did
not follow these instructions properly:
<ulink url="http://cygwin.com/ml/cygwin-announce/2001/msg00124.html">http://cygwin.com/ml/cygwin-announce/2001/msg00124.html</ulink>.  To
repair the damage, you must run Cygwin Setup again, and re-install the
<literal>libncurses5</literal> package.
</para>
<para>Note that Cygwin Setup won't show this option by default.  In the
``Select packages to install'' dialog, click on the <literal>Full/Part</literal>
button.  This lists all packages, even those that are already
installed.  Scroll down to locate the <literal>libncurses5</literal> package.
Click on the ``cycle'' glyph until it says ``Reinstall''.  Continue
with the installation.
</para>
<para>Similarly, if something cannot find <literal>cygintl.dll</literal>, then run
Cygwin Setup and re-install the <literal>libintl</literal> and <literal>libintl1</literal>
packages.
</para>
<para>For a detailed explanation of the general problem, and how to extend
it to other missing DLLs (like cygreadline5.dll) and identify their
containing packages, see
<ulink url="http://cygwin.com/ml/cygwin/2002-01/msg01619.html">http://cygwin.com/ml/cygwin/2002-01/msg01619.html</ulink>.
</para>
</answer></qandaentry>

<qandaentry id="faq.using.slow">
<question><para>Why is Cygwin suddenly <emphasis>so</emphasis> slow?</para></question>
<answer>

<para>If you recently upgraded and suddenly <emphasis>every</emphasis> command takes a
<emphasis>very</emphasis> long time, then something is probably attempting to 
access a network share.  You may have the obsolete <literal>//c</literal>
notation in your PATH or startup files.  This now means the
<emphasis>network share</emphasis> <literal>c</literal>, which will slow things down
tremendously if it does not exist.  
</para>
<para>Using //c (for C:) doesn't work anymore.  (Similarly for any drive
letter, e.g. <literal>//z</literal> for <literal>Z:</literal>) This ``feature'' has long been
deprecated, and no longer works at all in the latest release.  As of
release 1.3.3, <literal>//c</literal> now means the <emphasis>network share</emphasis> <literal>c</literal>.
For a detailed discussion of why this change was made, and how deal
with it now, refer to
<ulink url="http://sources.redhat.com/ml/cygwin/2001-09/msg00014.html">http://sources.redhat.com/ml/cygwin/2001-09/msg00014.html</ulink>.
</para>
</answer></qandaentry>

<qandaentry id="faq.using.services">
<question><para>Why don't my services work?</para></question>
<answer>

<para>Most Windows services run as a special user called <literal>SYSTEM</literal>.  If you
installed Cygwin for "Just Me", the <literal>SYSTEM</literal> user won't see your
Cygwin mount table.  You need to re-mount all of your mounts as
"system" for services to work. You can re-run <literal>setup.exe</literal> and
select "Install for All Users", or this script will do the trick:
</para>
<screen>
eval "`mount -m | sed -e 's/ -u / -s /g' -e 's/$/;/'`"
</screen>
</answer></qandaentry>

<qandaentry id="faq.using.shares">
<question><para>Why can't my services access network shares?</para></question>
<answer>

<para>When a service switches to a certain user, it is running as 
<literal>SYSTEM</literal> impersonating the user account. During
impersonation, the user's password is not available and so non-public
network shares are not available.  For more information, see
<ulink url="http://cygwin.com/cygwin-ug-net/ntsec.html" />.
</para>
<para>Workarounds include using public network share that does not require
authentication (for non-critical files), providing your password to a
<command>net use</command> command, or running the service as your own
user with <literal>cygrunsrv -u</literal> (see
<literal>/usr/share/doc/Cygwin/cygrunsrv.README</literal> for more
information).
</para>
</answer></qandaentry>

<qandaentry id="faq.using.path">
<question><para>How should I set my PATH?</para></question>
<answer>

<para>This is done for you in the file /etc/profile, which is sourced by bash
when you start it from the Desktop or Start Menu shortcut, created by
<literal>setup.exe</literal>.  The line is
</para>
<screen>
	PATH="/usr/local/bin:/usr/bin:/bin:$PATH"
</screen>

<para>Effectively, this <emphasis role='bold'>prepends</emphasis> /usr/local/bin and /usr/bin to your
Windows system path.  If you choose to reset your PATH, say in
$HOME/.bashrc, or by editing etc/profile directly, then you should
follow this rule.  You <emphasis role='bold'>must</emphasis> have <literal>/usr/bin</literal> in your PATH
<emphasis role='bold'>before</emphasis> any Windows system directories.  (And you must not omit
the Windows system directories!)  Otherwise you will likely encounter
all sorts of problems running Cygwin applications.
</para>
</answer></qandaentry>

<qandaentry id="faq.using.not-found">
<question><para>Bash says "command not found", but it's right there!</para></question>
<answer>

<para>If you compile a program, you might find that you can't run it:
</para>
<screen>
	bash$ gcc -o hello hello.c
        bash$ hello
        bash: hello: command not found
</screen>

<para>Unlike Windows, bash does not look for programs in <literal>.</literal> (the current
directory) by default.  You can add <literal>.</literal> 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:
</para>
<screen>
	bash$ gcc -o hello hello.c
        bash$ ./hello
        Hello World!
</screen>

</answer></qandaentry>

<qandaentry id="faq.using.converting-paths">
<question><para>How do I convert between Windows and UNIX paths?</para></question>
<answer>

<para>Use the 'cygpath' utility.  Type '<literal>cygpath --help</literal>' for
information.  For example (on my installation):
<screen>
	bash$ cygpath --windows ~/.bashrc
        D:\starksb\.bashrc
        bash$ cygpath --unix C:/cygwin/bin/cygwin.bat
        /usr/bin/cygwin.bat
        bash$ cygpath --unix C:\\cygwin\\bin\\cygwin.bat
        /usr/bin/cygwin.bat
</screen>
Note that bash interprets the backslash '\' as an escape character, so
you must type it twice in the bash shell if you want it to be recognized
as such.
</para>
</answer></qandaentry>

<qandaentry id="faq.using.bashrc">
<question><para>Why doesn't bash read my .bashrc file on startup?</para></question>
<answer>

<para>Your .bashrc is read from your home directory specified by the HOME
environment variable.  It uses /.bashrc if HOME is not set.  So you need
to set HOME correctly, or move your .bashrc to the top of the drive
mounted as / in Cygwin.
</para>
</answer></qandaentry>

<qandaentry id="faq.using.bash-insensitive">
<question><para>How can I get bash filename completion to be case insensitive?</para></question>
<answer>

<para>Add the following to your <literal>~/.bashrc</literal> file:
</para>
<screen>
	shopt -s nocaseglob
</screen>

<para>and add the following to your <literal>~/.inputrc</literal> file:
</para>
<screen>
	set completion-ignore-case on
</screen>

</answer></qandaentry>

<qandaentry id="faq.using.filename-spaces">
<question><para>Can I use paths/filenames containing spaces in them?</para></question>
<answer>

<para>Cygwin does support spaces in filenames and paths.  That said, some
utilities that use the library may not, since files don't typically
contain spaces in Unix.  If you stumble into problems with this, you
will need to either fix the utilities or stop using spaces in filenames
used by Cygwin tools.
</para>
<para>In particular, bash interprets space as a word separator.  You would have
to quote a filename containing spaces, or escape the space character.
For example:
<screen>
	bash-2.03$ cd '/cygdrive/c/Program Files'
</screen>
or
<screen>
	bash-2.03$ cd /cygdrive/c/Program\ Files
</screen>
</para>
</answer></qandaentry>

<qandaentry id="faq.using.shortcuts">
<question><para>Why can't I cd into a shortcut to a directory?</para></question>
<answer>

<para>Cygwin versions &lt; 1.3.0 do not follow MS Windows Explorer Shortcuts
(*.lnk files).  It sees a shortcut as a regular file and this you
cannot "cd" into it.
</para>
<para>Since version 1.3.0, Cygwin uses shortcuts as symlinks by default.
</para>
<para>Cygwin shortcuts are different from shortcuts created by native Windows
applications.  Windows applications can usually make use of Cygwin
shortcuts but not vice versa.  This is by choice.  The reason is that
Windows shortcuts may contain a bunch of extra information which would
get lost, if, for example, Cygwin tar archives and extracts them as
symlinks.
</para>
<para>Changing a Cygwin shortcut in Windows Explorer usually changes a Cygwin
shortcut into a Windows native shortcut.  Afterwards, Cygwin will not
recognize it as symlink anymore.
</para>
</answer></qandaentry>

<qandaentry id="faq.using.find">
<question><para>I'm having basic problems with find.  Why?</para></question>
<answer>

<para>Make sure you are using the find that came with Cygwin and that you
aren't picking up the Win32 find command instead.  You can verify that
you are getting the right one by doing a "type find" in bash.
</para>
<para>If the path argument to find, including current directory (default), is
itself a symbolic link, then find will not traverse it unless you
specify the <literal>-follow</literal> option.  This behavior is different than most
other UNIX implementations, but is not likely to change.
</para>
<para>If find does not seem to be producing enough results, or seems to be
missing out some directories, you may be experiencing a problem with one
of find's optimisations.  The absence of <literal>.</literal> and <literal>..</literal>
directories on some filesystems, such as DVD-R UDF, can confuse find.
See the documentation for the option <literal>-noleaf</literal> in the man page.
</para>
</answer></qandaentry>

<qandaentry id="faq.using.su">
<question><para>Why doesn't <literal>su</literal> work?</para></question>
<answer>

<para>The <literal>su</literal> command has been in and out of Cygwin distributions, but
it has not been ported to Cygwin and has never worked.  It is
currently installed as part of the sh-utils, but again, it does not work.
</para>
<para>You may be able to use <literal>login</literal> instead, but you should read
<ulink url="http://www.cygwin.com/ml/cygwin/2001-03/msg00337.html">http://www.cygwin.com/ml/cygwin/2001-03/msg00337.html</ulink> first.
</para>
<para>For some technical background into why <literal>su</literal> doesn't work, read
<ulink url="http://www.cygwin.com/ml/cygwin/2003-06/msg00897.html">http://www.cygwin.com/ml/cygwin/2003-06/msg00897.html</ulink> and
related messages.
</para>
</answer></qandaentry>

<qandaentry id="faq.using.man">
<question><para>Why doesn't man (or apropos) work?</para></question>
<answer>

<para>Before you can use <literal>man -k</literal> or <literal>apropos</literal>, you
must create the whatis database.  Just run the command
</para>
<screen>
	/usr/sbin/makewhatis
</screen>

<para>(it may take a minute to complete).
</para>
</answer></qandaentry>

<qandaentry id="faq.using.chmod">
<question><para>Why doesn't <literal>chmod</literal> work?</para></question>
<answer>

<para>The most common case is that your <literal>/etc/passwd</literal>
or <literal>/etc/group</literal> files are not properly set up. If 
<literal>ls -l</literal> shows a group of <literal>mkpasswd</literal> 
or <literal>mkgroup</literal>, you need to run one or both of those
commands.
</para>
<para>If you're using FAT32 instead of NTFS, <literal>chmod</literal> 
will fail since FAT32 does not provide any security. You might consider 
converting the drive to NTFS with <literal>CONVERT.EXE</literal>.
</para>
<para>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 at <ulink url="http://cygwin.com/cygwin-ug-net/ntsec.html" />
for more information on how Cygwin maps Windows permissions.
</para>
</answer></qandaentry>

<qandaentry id="faq.using.mkdir-network">
<question><para>Why doesn't <literal>mkdir -p</literal> work on a network share?</para></question>
<answer>

<para>Starting with <literal>coreutils-5.3.0-6</literal> and <literal>cygwin-1.5.17</literal>, you can
do something like this:
</para>
<screen>
bash$ mkdir -p //MACHINE/Share/path/to/new/dir
</screen>

<para>However, coreutils expects Unix path names, so something like
<literal>mkdir -p \\\\machine\\share\\path</literal> will fail. 
</para>
</answer></qandaentry>

<qandaentry id="faq.using.shell-scripts">
<question><para>Why doesn't my shell script work?</para></question>
<answer>

<para>There are two basic problems you might run into.  One is the fact that
<command>/bin/sh</command> is really <command>bash</command> (prior to
<command>bash-3.0-6</command>, <command>/bin/sh</command> was ash).  and is
missing some features you might expect in <command>/bin/sh</command>,
particularly if you are used to <command>/bin/sh</command> actually being
<command>zsh</command> (MacOS X "Panther") or <command>ksh</command> (Tru64).  
</para>

<para>Or, it could be a permission problem, and Cygwin doesn't understand that your script is executable.  Because <literal>chmod</literal> may not work (see FAQ entry above), Cygwin must read the contents of files to determine if
they are executable.  If your script does not start with
</para>
<screen>
	#! /bin/sh
</screen>

<para>(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 shell
idiom
</para>
<screen>
	:
	# This is the 2nd line, assume processing by /bin/sh
</screen>

<para>also works.
</para>
<para>Note that you can use <literal>mount -x</literal> to force Cygwin to treat all files
under the mount point as executable.  This can be used for individual
files as well as directories.  Then Cygwin will not bother to read files
to determine whether they are executable.
</para>
</answer></qandaentry>

<qandaentry id="faq.using.printing">
<question><para>How do I print under Cygwin?</para></question>
<answer>

<para>There is no working lp or lpr system as you would find on UNIX.
</para>
<para>Jason Tishler has written a couple of messages that explain how to use
a2ps (for nicely formatted text in PostScript) and ghostscript (to print
PostScript files on non-PostScript Windows printers).  Start at
<ulink url="http://cygwin.com/ml/cygwin/2001-04/msg00657.html">http://cygwin.com/ml/cygwin/2001-04/msg00657.html</ulink>.  Note that the
<literal>file</literal> command is now available as part of Cygwin setup.
</para>
<para>Alternatively, on NT, you can use the Windows <literal>print</literal> command.  (It
does not seem to be available on Win9x.)  Type
</para>
<screen>
	bash$ print /\?
</screen>

<para>for usage instructions (note the <literal>?</literal> must be escaped from the
shell).
</para>
<para>Finally, you can simply <literal>cat</literal> the file to the printer's share name:
</para>
<screen>
	bash$ cat myfile &gt; //host/printer
</screen>

<para>You may need to press the formfeed button on your printer or append the
formfeed character to your file.
</para>
</answer></qandaentry>

<qandaentry id="faq.using.unicode">
<question><para>Why don't international (Unicode) characters work?</para></question>
<answer>

<para>Internationalization is a complex issue. The short answer is that
Cygwin is not Unicode-aware, so things that might work in Linux will
not necessarily work on Cygwin. However, some things do work. To type
international characters (&pound;&auml;&ouml;) in <literal>bash</literal>, add the following
lines to your <literal>~/.inputrc</literal> file and restart <literal>bash</literal>:
</para>
<screen>
	set meta-flag on 
        set convert-meta off 
        set output-meta on 
	set input-meta on
	set kanji-code sjis
</screen>

<para>These are options to the <literal>readline</literal> library, which you can read
about in the <literal>bash(1)</literal> and <literal>readline(3)</literal> man pages. Other
tools that do not use <literal>readline</literal> for display, such as <literal>less</literal>
and <literal>ls</literal>, require additional settings, which could be put in your
<literal>~/.bashrc</literal>:
<screen>
alias less='/bin/less -r'
alias ls='/bin/ls -F --color=tty --show-control-chars'
export LANG="ja_JP.SJIS"
export OUTPUT_CHARSET="sjis"
</screen>
These examples use the Japanese Shift-JIS character set, obviously
you will want to change them for your own locale. 
</para>

</answer></qandaentry>

<qandaentry id="faq.using.cursor">
<question><para>Why don't cursor keys work under Win95/Win98?</para></question>
<answer>

<para><emphasis role='bold'>(Please note: This section has not yet been updated for the latest net release.)</emphasis>
</para>
<para>Careful examination shows that they not just non-functional, but
rather behave strangely, for example, with NumLock off, keys on numeric
keyboard work, until you press usual cursor keys, when even numeric
stop working, but they start working again after hitting alphanumeric
key, etc. This reported to happen on localized versions of Win98 and
Win95, and not specific to Cygwin; there are known cases of Alt+Enter
(fullscreen/windowed toggle) not working and shifts sticking with
other programs. The cause of this problem is Microsoft keyboard
localizer which by default installed in 'autoexec.bat'. Corresponding
line looks like:
</para>
<screen>
keyb ru,,C:\WINDOWS\COMMAND\keybrd3.sys
</screen>

<para>(That's for russian locale.) You should comment that line if you want
your keys working properly. Of course, this will deprive you of your
local alphabet keyboard support, so you should think about
another localizer. ex-USSR users are of course knowledgeable of Keyrus
localizer, and it might work for other locales too, since it has keyboard
layout editor. But it has russian messages and documentation ;-(
Reference URL is http://www.hnet.ru/software/contrib/Utils/KeyRus/
(note the you may need to turn off Windows logo for Keyrus to operate
properly).
</para>
</answer></qandaentry>

<qandaentry id="faq.using.multiple-copies">
<question><para>Is it OK to have multiple copies of the DLL?</para></question>
<answer>

<para>You should only have one copy of the Cygwin DLL on your system.  If you
have multiple versions, they will conflict and cause problems.
</para>
<para>If you get the error "shared region is corrupted" or "shared region
version mismatch" it means you have multiple versions of cygwin1.dll
running at the same time.  This could happen, for example, if you update
cygwin1.dll without exiting <emphasis>all</emphasis> Cygwin apps (including inetd)
beforehand.
</para>
<para>The only DLL that is sanctioned by the Cygwin project is the one that
you get by running <ulink url="http://cygwin.com/setup.exe">setup.exe</ulink>, installed in the
directory controlled by this program.  If you have other versions on
your system and desire help from the cygwin project, you should delete
or rename all DLLs that are not installed by <filename>setup.exe</filename>.
</para>
<para>If you're trying to find multiple versions of the DLL that are causing
this problem, reboot first, in case DLLs still loaded in memory are the
cause.  Then use the Windows System find utility to search your whole
machine, not just components in your PATH (as 'type' would do) or
cygwin-mounted filesystems (as Cygwin 'find' would do).
</para>
</answer></qandaentry>

<qandaentry id="faq.using.third-party.multiple-copies">
<question><para>
I read the above but I want to bundle Cygwin with a product, and ship it
to customer sites.  How can I do this without conflicting with any
Cygwin installed by the user?
</para></question>
<answer><para>
Third party developers who wish to use Cygwin should check if
there is a version of cygwin installed and use the installed
version if it is newer, or conditionally upgrade if it is not.
(If you write a tool to make this easy, consider contributing
it for others to use)
</para></answer></qandaentry>

<qandaentry id="faq.using.bundling-cygwin">
<question><para>
Can I bundle Cygwin with my product for free?
</para></question>
<answer><para>
Only if you comply with Cygwin's <ulink
url="http://cygwin.com/license.html">license</ulink> very carefully.  If you
choose to distribute cygwin1.dll, you must be willing to distribute the
exact source code used to build that copy of cygwin1.dll as per the
terms of the GPL.  If you ship applications that link with cygwin1.dll,
you must either provide those applications' source code under a
GPL-compatible license, *or* purchase a cygwin license from Red Hat.
</para></answer></qandaentry>

<qandaentry id="faq.using.private-cygwin">
<question><para>
So I can't install a private version of the Cygwin DLL without
conflictng with the system cygwin?
</para></question>
<answer><para>
Actually, if you are very careful, you can have two different versions
of the Cygwin DLL installed on your system at the same time but they
must be run serially.  This means that you can't be running programs
using both versions of Cygwin at the same time.  Please be aware that
currently both versions will use the same mount table entries although
this wil change in Cygwin version 1.7.x.
</para><para>
This usage is not recommeded for novices.  Only limited support will be
provided in the <ulink url="http://cygwin.com/lists.html">mailing lists</ulink>
if you run into problems.
</para></answer></qandaentry>

<qandaentry id="faq.using.older-cygwin-conflict">
<question><para>
But doesn't that mean that if some application installs an older Cygwin
DLL on top of a newer DLL, my application will break?
</para></question>
<answer><para>
It depends on what you mean by "break".  If the application installs a
version of the Cygwin DLL in another location than Cygwin's /bin
directory then the rules in 9.3 apply.  If the application installs an
older version of the DLL in /bin then you should complain loudly to the
application provider.
</para><para>
Remember that the Cygwin DLL strives to be backwards compatible so a
newer 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 your
system and it should always be the latest version which matches your
installed distribution.
</para></answer></qandaentry>

<qandaentry id="faq.using.missing-packages">
<question><para>Why isn't package XYZ available in Cygwin?</para></question>
<answer>

<para>Probably because there is nobody willing or able to maintain it.  It
takes time, and the priority for the Cygwin Team is the Cygwin package.
The rest is a volunteer effort.  Want to contribute?  See
<ulink url="http://cygwin.com/setup.html">http://cygwin.com/setup.html</ulink>.
</para>
</answer></qandaentry>

<qandaentry id="faq.using.old-packages">
<question><para>Why is the Cygwin package of XYZ so out of date?</para></question>
<answer>

<para>(Also: Why is the version of package XYZ older than the version that I
can download from the XYZ web site?  Why is the version of package XYZ
older than the version that I installed on my linux system?  Is there
something special about Cygwin which requires that only an older version
of package XYZ will work on it?)
</para>
<para>Every package in the Cygwin distribution has a maintainer who is
responsible for sending out updates of the package.  This person is a
volunteer who is rarely the same person as the official developer of the
package.  If you notice that a version of a package seems to be out of
date, the reason is usually pretty simple -- the person who is
maintaining the package hasn't gotten around to updating it yet. Rarely,
the newer package actually requires complex changes that the maintainer
is working out. 
</para>
<para>If you urgently need an update, sending a polite message to the cygwin
mailing list pinging the maintainer is perfectly acceptable.  There are
no guarantees that the maintainer will have time to update the package
or that you'll receive a response to your request, however.
</para>
<para>Remeber that the operative term here is "volunteer".
</para>
</answer></qandaentry>

<qandaentry id="faq.using.accessing-drives">
<question><para>How can I access other drives?</para></question>
<answer>

<para>You have some flexibility here.
</para>
<para>Cygwin has a builtin "cygdrive prefix" for drives that are not mounted.
You can access any drive, say Z:, as '/cygdrive/z/'.
</para>
<para>In some applications (notably bash), you can use the familiar windows
&lt;drive&gt;:/path/, using posix forward-slashes ('/') instead of Windows
backward-slashes ('\').  (But see the warning below!)  This maps in the
obvious way to the Windows path, but will be converted internally to use
the Cygwin path, following mounts (default or explicit).  For example:
<screen>
	bash$ cd C:/Windows
	bash$ pwd
        /cygdrive/c/Windows
</screen>
and
<screen>
	bash$ cd C:/cygwin
	bash$ pwd
        /
</screen>
for a default setup.  You could also use backward-slashes in the
Windows path, but these would have to be escaped from the shell.
</para>
<para><emphasis role='bold'>Warning:</emphasis> There is some ambiguity in going from a Windows path
to the posix path, because different posix paths, through different
mount points, could map to the same Windows directory.  This matters
because different mount points may be binmode or textmode, so the
behavior of Cygwin apps will vary depending on the posix path used to
get there.
</para>
<para>You can avoid the ambiguity of Windows paths, and avoid typing
"/cygdrive", by explicitly mounting drives to posix paths.  For example:
<screen>
	bash$ mkdir /c
	bash$ mount c:/ /c
	bash$ ls /c
</screen>
Then <literal>/cygdrive/c/Windows</literal> becomes <literal>/c/Windows</literal> which is a
little less typing.
</para>
<para>Note that you only need to mount drives once.  The mapping is kept
in the registry so mounts stay valid pretty much indefinitely.
You can only get rid of them with umount, or the registry editor.
</para>
<para>The '-b' option to mount mounts the mountpoint in binary mode
("binmode") where text and binary files are treated equivalently.  This
should only be necessary for badly ported Unix programs where binary
flags are missing from open calls.  It is also the setting for /,
/usr/bin and /usr/lib in a default Cygwin installation.  The default for
new mounts is text mode ("textmode"), which is also the mode for all
"cygdrive" mounts.
</para>
<para>You can change the default <literal>cygdrive</literal> prefix and whether it is
binmode or textmode using the <literal>mount</literal> command.  For example,
<screen>
	bash$ mount -b --change-cygdrive-prefix cygdrive
</screen>
will change all <literal>/cygdrive/...</literal> mounts to binmode.
</para>
</answer></qandaentry>

<qandaentry id="faq.using.copy-and-paste">
<question><para>How can I copy and paste into Cygwin console windows?</para></question>
<answer>

<para>First, consider using rxvt instead of the standard console window.  In
rxvt, selecting with the left-mouse also copies, and middle-mouse
pastes.  It couldn't be easier!
</para>
<para>Under Windows NT, open the properties dialog of the console window.
The options contain a toggle button, named "Quick edit mode".  It must
be ON.  Save the properties.
</para>
<para>Under Windows 9x, open the properties dialog of the console window.
Select the Misc tab.  Uncheck Fast Pasting.  Check QuickEdit.
</para>
<para>You can also bind the insert key to paste from the clipboard by adding 
the following line to your .inputrc file: 
<screen>
	"\e[2~": paste-from-clipboard 
</screen>
</para>
</answer></qandaentry>

<qandaentry id="faq.using.firewall">
<question><para>What firewall should I use with Cygwin? </para></question>
<answer>

<para>We have had good reports about Kerio Personal Firewall, ZoneLabs
Integrity Desktop, and the built-in firewall in Windows XP. Other
well-known products including ZoneAlarm and Norton Internet Security have
caused problems for some users but work fine for others. At last report,
Agnitum Outpost did not work with Cygwin.  If you are having strange
connection-related problems, disabling the firewall is a good
troubleshooting step (as is closing or disabling all other running
applications, especially resource-intensive processes such as indexed
search).
</para>
<para>On the whole, Cygwin doesn't care which firewall is used.  The few rare
exceptions 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 winsock
stack (with the 'layered service provider' API) and install hooks
throughout.  Sadly the mailing list archives are littered with examples
of poorly written firewall-type software that causes things to break.
Note that with many of these products, simply disabling the firewall
does not remove these changes; it must be completely uninstalled.
</para>
<para>See also <ulink url="http://cygwin.com/faq/faq.using.html#faq.using.bloda" />
for a list of applications that have been known, at one time or another, to 
interfere with the normal functioning of Cygwin.
</para>
</answer></qandaentry>

<qandaentry id="faq.using.sharing-files">
<question><para>How can I share files between Unix and Windows?</para></question>
<answer>

<para>During development, we have both Linux boxes running Samba and Windows
machines.  We often build with cross-compilers under Linux and copy
binaries and source to the Windows system or just toy with them
directly off the Samba-mounted partition.  On dual-boot NT/Windows 9x
machines, we usually use the FAT filesystem so we can also access the
files under Windows 9x.
</para>
</answer></qandaentry>

<qandaentry id="faq.using.case-sensitive">
<question><para>Is Cygwin case-sensitive? What are managed mounts?</para></question>
<answer>

<para>Several Unix programs expect to be able to use to filenames
spelled the same way, but with different case.  A prime example
of this is perl's configuration script, which wants <literal>Makefile</literal> and
<literal>makefile</literal>.  WIN32 can't tell the difference between files with
just different case, so the configuration fails.
</para>
<para>To help with this problem, starting in <literal>cygwin-1.5.0</literal> it is
possible to have a case sensitive Cygwin managed mount. This is an
experimental feature and should be used with caution. You should only
use it for directories that are initially unpopulated and are due to
be completely managed by cygwin (hence the name).  So, the best use
would be to create an empty directory, mount it, and then add files to
it:  
</para>
<screen>
mkdir /managed-dir
mount -o managed c:/cygwin/managed-dir /managed-dir
cd /managed-dir/
touch makefile
touch Makefile
</screen>

</answer></qandaentry>

<qandaentry id="faq.using.dos-filenames">
<question><para>What about DOS special filenames?</para></question>
<answer>

<para>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 have
trouble.  Unix programs don't avoid these names which can make things
interesting.  E.g., the perl distribution has a file called
<literal>aux.sh</literal>.  The perl configuration tries to make sure that
<literal>aux.sh</literal> is there, but an operation on a file with the magic
letters 'aux' in it will hang.
</para>
</answer></qandaentry>

<qandaentry id="faq.using.hangs">
<question><para>When it hangs, how do I get it back?</para></question>
<answer>

<para>If something goes wrong and the tools hang on you for some reason (easy
to do if you try and read a file called aux.sh), first try hitting ^C to
return to bash or the cmd prompt.
</para>
<para>If you start up another shell, and applications don't run, it's a good
bet that the hung process is still running somewhere.  Use the Task
Manager, pview, or a similar utility to kill the process.
</para>
<para>And, if all else fails, there's always the reset button/power switch.
This should never be necessary under Windows NT.
</para>
</answer></qandaentry>

<qandaentry id="faq.using.directory-structure">
<question><para>Why the weird directory structure?</para></question>
<answer>

<para>Why do /lib and /usr/lib (and /bin, /usr/bin) point to the same thing?
</para>
<para>Why use mounts instead of symbolic links?
</para>
<para>Can I use a disk root (e.g., C:\) as Cygwin root?  Why is this discouraged?
</para>
<para>After a new installation in the default location, your mount points will
look something like this:
</para>
<screen>
	bash$ mount
	C:\cygwin\bin on /usr/bin type system (binmode)
	C:\cygwin\lib on /usr/lib type system (binmode)
	C:\cygwin on / type system (binmode)
</screen>

<para>(Exactly what you see depends on what options you gave to <literal>setup.exe</literal>.)
</para>
<para>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 mounts
unless you <emphasis>really</emphasis> know what you are doing.
</para>
<para>Various applications and packages may expect to be installed in /lib or
/usr/lib (similarly /bin or /usr/bin).  Rather than distinguish between
them and try to keep track of them (possibly requiring the occasional
duplication or symbolic link), it was decided to maintain only one
actual directory, with equivalent ways to access it.
</para>
<para>Symbolic links had been considered for this purpose, but were dismissed
because they do not always work on Samba drives.  Also, mounts are
faster to process because no disk access is required to resolve them.
</para>
<para>Note that non-cygwin applications will not observe Cygwin mounts (or
symlinks for that matter).  For example, if you use WinZip to unpack the
tar distribution of a Cygwin package, it may not get installed to the
correct Cygwin path.  <emphasis>So don't do this!</emphasis>
</para>
<para>It is strongly recommended not to make the Cygwin root directory the
same as your drive's root directory, unless you know what you are doing
and are prepared to deal with the consequences.  It is generally easier
to maintain the Cygwin hierarchy if it is isolated from, say, C:\.  For
one 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 about
things you might add in the future?)
</para>
</answer></qandaentry>

<qandaentry id="faq.using.anti-virus">
<question><para>How do anti-virus programs like Cygwin?</para></question>
<answer>

<para>Users have reported that NAI (formerly McAfee) VirusScan for NT (and
others?) is incompatible with Cygwin.  This is because it tries to scan
the newly loaded shared memory in cygwin1.dll, which can cause fork() to
fail, wreaking havoc on many of the tools.  (It is not confirmed that
this is still a problem, however.)
</para>
<para>There have been several reports of NAI VirusScan causing the system to
hang when unpacking tar.gz archives.  This is surely a bug in VirusScan,
and should be reported to NAI.  The only workaround is to disable
VirusScan when accessing these files.  This can be an issue during
setup, and is discussed in that FAQ entry.
</para>
<para>Some users report a significant performance hit using Cygwin when their
anti-virus software is enabled.  Rather than disable the anti-virus
software completely, it may be possible to specify directories whose
contents are exempt from scanning.  In a default installation, this
would be <literal>C:\cygwin\bin</literal>.  Obviously, this could be
exploited by a hostile non-Cygwin program, so do this at your own risk.
</para>
<para>See also <ulink url="http://cygwin.com/faq/faq.using.html#faq.using.bloda" />
for a list of applications that have been known, at one time or another, to
interfere with the normal functioning of Cygwin.
</para>
</answer></qandaentry>

<qandaentry id="faq.using.emacs">
<question><para>Is there a Cygwin port of GNU Emacs?</para></question>
<answer>

<para>Yes!  It uses the X11 (<ulink url="http://cygwin.com/xfree/">http://cygwin.com/xfree/</ulink>) Windows
interface.  From a remote login shell, this ``emacs -nw'' works fine.
There is also a non-X11 version which just provides the text-only
terminal interface.  Use Cygwin Setup to install either one (or both).
</para>
</answer></qandaentry>

<qandaentry id="faq.using.ntemacs">
<question><para>What about NT Emacs?</para></question>
<answer>

<para>If you want GNU Emacs with a native Microsoft Windows interface, but
without X, then you must use the native Windows port, commonly known
as ``NT Emacs''.  You get NT Emacs from any GNU mirror.  It is not
available from Cygwin Setup.
</para>
<para>NT Emacs uses the Windows command shell by default.  Since it is not a
Cygwin application, it has no knowledge of Cygwin mounts.  With those
points in mind, you need to add the following code to your ~/.emacs
(or ~/_emacs) file in order to use Cygwin bash.  This is particularly useful
for the JDEE package (<ulink url="http://jdee.sunsite.dk/">http://jdee.sunsite.dk/</ulink>).  The following
settings are for Emacs 21.1:
</para>
<screen>
	;; This assumes that Cygwin is installed in C:\cygwin (the
	;; default) and that C:\cygwin\bin is not already in your
	;; Windows Path (it generally should not be).
	;;
	(setq exec-path (cons "C:/cygwin/bin" exec-path))
	(setenv "PATH" (concat "C:\\cygwin\\bin;" (getenv "PATH")))
	;;
	;; NT-emacs assumes a Windows command shell, which you change
	;; here.
	;;
	(setq shell-file-name "bash")
	(setenv "SHELL" shell-file-name) 
	(setq explicit-shell-file-name shell-file-name) 
	;;
	;; This removes unsightly ^M characters that would otherwise
	;; appear in the output of java applications.
	;;
	(add-hook 'comint-output-filter-functions
	          'comint-strip-ctrl-m)
</screen>

<para>If you want NT Emacs to understand Cygwin paths, get
cygwin-mount.el from <ulink url="http://www.emacswiki.org/elisp/index.html">http://www.emacswiki.org/elisp/index.html</ulink>.
</para>
<para>Note that all of this ``just works'' if you use the Cygwin port of
Emacs from Cygwin Setup.
</para>
</answer></qandaentry>

<qandaentry id="faq.using.xemacs">
<question><para>What about XEmacs?</para></question>
<answer>

<para>For a concise description of the current situation with XEmacs, see
this message from the Cygwin mailing list:
<ulink url="http://cygwin.com/ml/cygwin/2002-11/msg00609.html">http://cygwin.com/ml/cygwin/2002-11/msg00609.html</ulink>.
</para>
</answer></qandaentry>

<qandaentry id="faq.using.console-window">
<question><para>Is there a better alternative to the standard console window?</para></question>
<answer>

<para>Yes!  Use rxvt instead.  It's an optional package in Cygwin Setup.
You can use it with or without X11.  You can resize it easily by
dragging an edge or corner.  Copy and paste is easy with the left and
middle mouse buttons, respectively.  It will honor settings in your
~/.Xdefaults file, even without X.  For details see
<literal>/usr/share/doc/Cygwin/rxvt-&lt;ver&gt;.README</literal>.
</para>
</answer></qandaentry>

<qandaentry id="faq.using.info-error">
<question><para>info error "dir: No such file or directory"</para></question>
<answer>

<para>Cygwin packages install their info documentation in the
<literal>/usr/share/info</literal> directory.  But you need to create a <literal>dir</literal>
file there before the standalone info program (probably
<literal>/usr/bin/info</literal>) can be used to read those info files.  This is how
you do it:
<screen>
	bash$ cd /usr/share/info
	bash$ for f in *.info ; do install-info $f dir ; done
</screen>
This may generate warnings:
<screen>
	install-info: warning: no info dir entry in `gzip.info'
	install-info: warning: no info dir entry in `time.info'
</screen>
The <literal>install-info</literal> command cannot parse these files, so you will
have to add their entries to <literal>/usr/share/info/dir</literal> by hand.
</para>
<para>Even if the dir file already exists, you may have to update it when
you install new Cygwin packages.  Some packages update the dir file
for you, but many don't.
</para>
</answer></qandaentry>

<qandaentry id="faq.using.out-of-queue">
<question><para>Why do I get a message saying Out of Queue slots?</para></question>
<answer>

<para>"Out of queue slots!" generally occurs when you're trying to remove
many files that you do not have permission to remove (either because
you don't have permission, they are opened exclusively, etc).  What
happens is Cygwin queues up these files with the supposition that it
will be possible to delete these files in the future.  Assuming that
the permission of an affected file does change later on, the file will
be deleted as requested.  However, if too many requests come in to
delete inaccessible files, the queue overflows and you get the message
you're asking about.  Usually you can remedy this with a quick chmod,
close of a file, or other such thing.  (Thanks to Larry Hall for
this explanation).
</para>
</answer></qandaentry>

<qandaentry id="faq.using.symlinks-samba">
<question><para>Why don't symlinks work on samba-mounted filesystems?</para></question>
<answer>

<para>Symlinks are marked with "system" file attribute.  Samba does not
enable this attribute by default.  To enable it, consult your Samba
documentation and then add these lines to your samba configuration
file:
</para>
<screen>
	map system = yes
	create mask = 0775
</screen>

<para>Note that the 0775 can be anything as long as the 0010 bit is set.
</para>
</answer></qandaentry>

<qandaentry id="faq.using.df-incorrect">
<question><para>Why does df report sizes incorrectly.</para></question>
<answer>

<para>There is a bug in the Win32 API function GetFreeDiskSpace that
makes it return incorrect values for disks larger than 2 GB in size.
Perhaps that may be your problem?
</para>
</answer></qandaentry>

<qandaentry id="faq.using.tcl-tk">
<question><para>Why doesn't Cygwin tcl/tk understand Cygwin paths?</para></question>
<answer>

<para>The versions of Tcl/Tk distributed with Cygwin (e.g. cygtclsh80.exe,
cygwish80.exe) are not actually "Cygwin versions" of those tools.
They are built with the <literal>-mno-cygwin</literal> option to <literal>gcc</literal>, which
means they do not understand Cygwin mounts or symbolic links.
</para>
<para>See the entry "How do I convert between Windows and UNIX paths?"
elsewhere in this FAQ.
</para></answer></qandaentry>

<qandaentry id="faq.using.bloda">
<question><para>What applications have been found to interfere with Cygwin?</para></question>
<answer>

<para>From time to time, people have reported strange failures and problems in
Cygwin and Cygwin packages that seem to have no rational explanation.  Among
the most common symptoms they report are fork failures, memory leaks, and file
access denied problems.  These problems, when they have been traced, often appear
to be caused by interference from other software installed on the same PC.  Security
software, 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 hooks
are not implemented in an entirely transparent fashion, and cause changes in the
behaviour which affect the operation of other programs, such as Cygwin.
</para>
<para>Among the software that has been found to cause difficulties are:</para>
<para><itemizedlist>
<listitem><para>Sonic Solutions burning software containing DLA component</para></listitem>
<listitem><para>Norton/MacAffee/Symantec antivirus or antispyware</para></listitem>
<listitem><para>Logitech webcam software with "Logitech process monitor" service</para></listitem>
<listitem><para>Kerio, Agnitum or ZoneAlarm Personal Firewall</para></listitem>
<listitem><para>Iolo System Mechanic/AntiVirus/Firewall</para></listitem>
<listitem><para>LanDesk</para></listitem>
<listitem><para>Windows Defender </para></listitem>
<listitem><para>Embassy Trust Suite fingerprint reader software wxvault.dll</para></listitem>
<listitem><para>NOD32 Antivirus</para></listitem>
<listitem><para>ByteMobile laptop optimization client</para></listitem>
</itemizedlist></para>
<para>Sometimes these problems can be worked around, by temporarily or partially
disabling the offending software.  For instance, it may be possible to disable
on-access scanning in your antivirus, or configure it to ignore files under the
Cygwin installation root.  Often, unfortunately, this is not possible; even disabling
the software may not work, since many applications that hook the operating system
leave their hooks installed when disabled, and simply set them into what is intended
to be a completely transparent pass-through mode.  Sometimes this pass-through is not
as 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.
</para>
<para>Some of the symptoms you may experience are:</para>
<para><itemizedlist>
<listitem>
<para>Random fork() failures.</para>
<para>Caused by hook DLLs that load themselves into every process in the
system.  POSIX fork() semantics require that the memory map of the child process
must be an exact duplicate of the parent process' layout.  If one of these DLLs
loads itself at a different base address in the child's memory space as compared
to the address it was loaded at in the parent, it can end up taking the space that
belonged to a different DLL in the parent.  When Cygwin can't load the original
DLL at that same address in the child, the fork() call has to fail.
</para>
</listitem>
<listitem>
<para>File access problems.</para>
<para>Some programs (e.g., virus scanners with on-access scanning) scan or
otherwise operate on every file accessed by all the other software running on
your computer.  In some cases they may retain an open handle on the file even
after the software that is really using the file has closed it.  This has been
known to cause operations such as deletes, renames and moves to fail with
access denied errors.  In extreme cases it has been known for scanners to leak
file handles, leading to kernel memory starvation.
</para>
</listitem>
<listitem>
<para>Networking issues</para>
<para>Firewall software sometimes gets a bit funny about Cygwin.  It's not
currently understood why; Cygwin only uses the standard Winsock2 API, but
perhaps in some less-commonly used fashion that doesn't get as well tested
by the publishers of firewalls.  Symptoms include mysterious failures to
connect, or corruption of network data being sent or received.</para>
</listitem>
<listitem>
<para>Memory and/or handle leaks</para>
<para>Some applications that hook into the Windows operating system exhibit
bugs when interacting with Cygwin that cause them to leak allocated memory
or other system resources.  Symptoms include complaints about out-of-memory
errors and even virtual memory exhaustion dialog boxes from the O/S; it is
often possible to see the excess memory allocation using a tool such as
Task Manager or Sysinternals' Process Explorer, although interpreting the
statistics they present is not always straightforward owing to complications
such as virtual memory paging and file caching.</para>
</listitem>
</itemizedlist></para>
</answer></qandaentry>