Update to switch FAQ from texinfo to DocBook.

1 files changed, 951 insertions, 0 deletions

diff --git a/winsup/doc/faq-using.xml b/winsup/doc/faq-using.xml
new file mode 100644
index 000000000..ce66c9de2
--- /dev/null
+++ b/winsup/doc/faq-using.xml
@@ -0,0 +1,951 @@
+<!-- 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 (or access network shares)?</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>
+
+<para>The <literal>SYSTEM</literal> user cannot access network shares that require
+authentication.  For more information, see
+<ulink url="http://cygwin.com/cygwin-ug-net/ntsec.html">http://cygwin.com/cygwin-ug-net/ntsec.html</ulink>.
+</para>
+<para>Workarounds include using public network share that does not require
+authentication (for non-critical files), 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 chmod work?</para></question>
+<answer>
+
+<para><literal>ntsec</literal> will allow UNIX permissions in Windows NT on NTFS file
+systems.  This is on by default (a recent change).
+</para>
+<para><literal>ntea</literal> works on NTFS <emphasis>and</emphasis> FAT but it creates a huge,
+<emphasis role='bold'>undeletable</emphasis> file on FAT filesystems.
+</para>
+<para>(The <literal>ntsec</literal> and <literal>ntea</literal> settings are values for the
+<literal>CYGWIN</literal> environment variable.  See the Cygwin User's Guide at
+<ulink url="http://cygwin.com/cygwin-ug-net/cygwin-ug-net.html">http://cygwin.com/cygwin-ug-net/cygwin-ug-net.html</ulink> for more
+information on this variable and its settings.)
+</para>
+<para>There is no solution at all for Windows 9x.
+</para>
+<para>If you have an application that requires a certain permission mode on a
+file, you may be able to work around this requirement by modifying the
+application's source code.  For a hint, based on work done by Corinna
+Vinschen for OpenSSH, see this message from the cygwin mailing list:
+<ulink url="http://cygwin.com/ml/cygwin/2000-11/msg01176.html">http://cygwin.com/ml/cygwin/2000-11/msg01176.html</ulink>.
+</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
+	set meta-flag on
+</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">http://cygwin.com/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.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>
+</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>
+</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 process-coding-system-alist '(("bash" . undecided-unix)))
+	(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.
+</para>
+<para>Don't invoke as simply ``rxvt'' because that will run /bin/sh (really
+ash) which is not a good interactive shell.  For details see
+<literal>/usr/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>
+