+2005-08-05 Joshua Daniel Franklin <joshuadfranklin@yahoo.com>
+
+ * cygwin.dsl: Add default DOCTYPE and output filename.
+ * Makefile: Update to switch FAQ from texinfo to DocBook.
+ * faq.xml: New file.
+ * faq-api.xml: New file.
+ * faq-problems.xml: New file.
+ * faq-programming.xml: New file.
+ * faq-resources.xml: New file.
+ * faq-sections.xml: New file.
+ * faq-setup.xml: New file.
+ * faq-using.xml: New file.
+ * faq-what.xml: New file.
+
2005-07-10 Joshua Daniel Franklin <joshuadfranklin@yahoo.com>
* cygwinenv.sgml: Update tty section to mention rxvt and xterm.
include $(srcdir)/../Makefile.common
TOCLEAN:=faq.txt ./*.html readme.txt doctool.o doctool.exe *.junk \
- cygwin-ug.sgml cygwin-ug \
+ cygwin-ug.sgml cygwin-ug cygwin-ug-net.html.gz \
cygwin-ug-net.sgml cygwin-ug-net cygwin-ug-net.html \
- cygwin-api.sgml cygwin-api cygwin-api-int.sgml cygwin-api-int
+ cygwin-api.sgml cygwin-api cygwin-api-int.sgml cygwin-api-int \
+ faq
.SUFFIXES:
all : \
cygwin-ug-net/cygwin-ug-net.html \
- cygwin-ug-net.html \
+ cygwin-ug-net/cygwin-ug-net.html.gz \
cygwin-api/cygwin-api.html \
- $(HTMLDOC)
+ faq/faq.html faq/faq-nochunks.html
clean:
rm -Rf $(TOCLEAN)
install: all
-cygwin-ug-net.html : cygwin-ug-net.sgml doctool
+cygwin-ug-net/cygwin-ug-net.html.gz : cygwin-ug-net.sgml doctool
-xmlto html-nochunks -m $(srcdir)/cygwin.dsl $<
-cp cygwin-ug-net.html cygwin-ug-net/cygwin-ug-net-nochunks.html
-rm -f cygwin-ug-net/cygwin-ug-net-nochunks.html.gz
cygwin-ug-net/cygwin-ug-net.html : cygwin-ug-net.sgml doctool
-xmlto html -o cygwin-ug-net/ -m $(srcdir)/cygwin.dsl $<
- -mv cygwin-ug-net/index.html cygwin-ug-net/cygwin-ug-net.html
cygwin-ug-net.sgml : cygwin-ug-net.in.sgml ./doctool Makefile
-./doctool -m $(SGMLDIRS) -s $(srcdir) -o $@ $<
cygwin-api/cygwin-api.html : cygwin-api.sgml
-xmlto html -o cygwin-api/ -m $(srcdir)/cygwin.dsl $<
- -mv cygwin-api/index.html cygwin-api/cygwin-api.html
cygwin-api.sgml : cygwin-api.in.sgml ./doctool Makefile
-./doctool -m $(SGMLDIRS) -s $(srcdir) -o $@ $<
+faq/faq.html :
+ -xmlto html -o faq -m $(srcdir)/cygwin.dsl $(srcdir)/faq-sections.xml
+
+faq/faq-nochunks.html :
+ -xmlto html -o faq -m $(srcdir)/cygwin.dsl $(srcdir)/faq.xml
+
./doctool : doctool.c
gcc -g $< -o $@
-$(MAKEINFO) -I$(srcdir) --no-split --no-headers $< -o - |\
sed '/^Concept Index/,$$d' > $@
-faq0.html: $(srcdir)/faq.texinfo $(srcdir)/*.texinfo
- -rm -f faq_toc.html; \
- for i in $(srcdir)/*.texinfo ; do \
- sed < $$i -e 's?@file{\([fth]*p://[^}]*\)}?@strong{<A HREF="\1">\1</A>}?' \
- -e 's?\([.+a-zA-Z0-9-]*@@[.a-zA-Z0-9-]*[a-zA-Z0-9]\)?<A HREF="mailto:\1">\1</A>?' >./`basename $$i` ; done; \
- $(TEXI2HTML) -monolithic ./faq.texinfo; \
- rm -f *.texinfo; \
- sed -e 's;"faq.html;"faq0.html;g' faq.html > faq0.html; \
- rm -f faq.html; exit 0
-
-faq.html: $(srcdir)/faq.texinfo $(srcdir)/*.texinfo
- -rm -f faq_toc.html; \
- for i in $(srcdir)/*.texinfo ; do \
- sed < $$i -e 's?@file{\([fth]*p://[^}]*\)}?@strong{<A HREF="\1">\1</A>}?' \
- -e 's?\([.+a-zA-Z0-9-]*@@[.a-zA-Z0-9-]*[a-zA-Z0-9]\)?<A HREF="mailto:\1">\1</A>?' >./`basename $$i` ; done; \
- $(TEXI2HTML) -split_chapter ./faq.texinfo; \
- rm -f *.texinfo; \
- [ -r faq_toc.html ] && mv faq_toc.html faq.html; exit 0
+#faq0.html: $(srcdir)/faq.texinfo $(srcdir)/*.texinfo
+# -rm -f faq_toc.html; \
+# for i in $(srcdir)/*.texinfo ; do \
+# sed < $$i -e 's?@file{\([fth]*p://[^}]*\)}?@strong{<A HREF="\1">\1</A>}?' \
+# -e 's?\([.+a-zA-Z0-9-]*@@[.a-zA-Z0-9-]*[a-zA-Z0-9]\)?<A HREF="mailto:\1">\1</A>?' >./`basename $$i` ; done; \
+# $(TEXI2HTML) -monolithic ./faq.texinfo; \
+# rm -f *.texinfo; \
+# sed -e 's;"faq.html;"faq0.html;g' faq.html > faq0.html; \
+# rm -f faq.html; exit 0
+#
+#faq.html: $(srcdir)/faq.texinfo $(srcdir)/*.texinfo
+# -rm -f faq_toc.html; \
+# for i in $(srcdir)/*.texinfo ; do \
+# sed < $$i -e 's?@file{\([fth]*p://[^}]*\)}?@strong{<A HREF="\1">\1</A>}?' \
+# -e 's?\([.+a-zA-Z0-9-]*@@[.a-zA-Z0-9-]*[a-zA-Z0-9]\)?<A HREF="mailto:\1">\1</A>?' >./`basename $$i` ; done; \
+# $(TEXI2HTML) -split_chapter ./faq.texinfo; \
+# rm -f *.texinfo; \
+# [ -r faq_toc.html ] && mv faq_toc.html faq.html; exit 0
TBFILES = cygwin-ug-net.dvi cygwin-ug-net.rtf cygwin-ug-net.ps \
cygwin-ug-net.pdf cygwin-ug-net.sgml \
version='1.0'>
<!-- See /usr/share/docbook-xsl/params/ -->
+<xsl:param name="chunker.output.doctype-public"
+ select="'-//W3C//DTD HTML 4.01 Transitional//EN'" />
<xsl:param name="html.stylesheet" select="'docbook.css'"/>
<xsl:param name="use.id.as.filename" select="1" />
+<xsl:param name="root.filename" select="@id" />
<!-- TODO: make URLs and paths wrap with PDF output -->
--- /dev/null
+<!-- faq-api.xml -->
+<qandaentry id="faq.api.everything">
+<question><para>How does everything work?</para></question>
+<answer>
+
+<para>There's a C library which provides a Unix-style API. The
+applications are linked with it and voila - they run on Windows.
+</para>
+<para>The aim is to add all the goop necessary to make your apps run on
+Windows into the C library. Then your apps should run on Unix and
+Windows with no changes at the source level.
+</para>
+<para>The C library is in a DLL, which makes basic applications quite small.
+And it allows relatively easy upgrades to the Win32/Unix translation
+layer, providing that DLL changes stay backward-compatible.
+</para>
+<para>For a good overview of Cygwin, you may want to read the paper on Cygwin
+published by the Usenix Association in conjunction with the 2d Usenix NT
+Symposium in August 1998. It is available in HTML format on the project
+WWW site.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.api.snapshots">
+<question><para>Are development snapshots for the Cygwin library available?</para></question>
+<answer>
+
+<para>Yes. They're made whenever anything interesting happens inside the
+Cygwin library (usually roughly on a nightly basis, depending on how much
+is going on). They are only intended for those people who wish to
+contribute code to the project. If you aren't going to be happy
+debugging problems in a buggy snapshot, avoid these and wait for a real
+release. The snapshots are available from
+<ulink url="http://cygwin.com/snapshots/">http://cygwin.com/snapshots/</ulink>.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.api.cr-lf">
+<question><para>How is the DOS/Unix CR/LF thing handled?</para></question>
+<answer>
+
+<para>Let's start with some background.
+</para>
+<para>In UNIX, a file is a file and what the file contains is whatever 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 the
+program/programmer/user but also the file processing mode.
+</para>
+<para>When processing in text mode, certain values of data are treated
+specially. A \n (new line) written to the file will prepend a \r
+(carriage return) so that if you `printf("Hello\n") you in fact get
+"Hello\r\n". Upon reading this combination, the \r is removed and the
+number of bytes returned by the read is 1 less than was actually read.
+This tends to confuse programs dependent on ftell() and fseek(). A
+Ctrl-Z encountered while reading a file sets the End Of File flags even
+though it truly isn't the end of file.
+</para>
+<para>One of Cygwin's goals is to make it possible to easily mix Cygwin-ported
+Unix programs with generic Windows programs. As a result, Cygwin opens
+files in text mode as is normal under Windows. In the accompanying
+tools, tools that deal with binaries (e.g. objdump) operate in Unix
+binary mode and tools that deal with text files (e.g. bash) operate in
+text mode.
+</para>
+<para>Some people push the notion of globally setting the default processing
+mode to binary via mount point options or by setting the CYGWIN
+environment variable. But that creates a different problem. In
+binary mode, the program receives all of the data in the file, including
+a \r. Since the programs will no longer deal with these properly for
+you, you would have to remove the \r from the relevant text files,
+especially scripts and startup resource files. This is a porter "cop
+out", forcing the user to deal with the \r for the porter.
+</para>
+<para>It is rather easy for the porter to fix the source code by supplying the
+appropriate file processing mode switches to the open/fopen functions.
+Treat all text files as text and treat all binary files as binary. To be
+specific, you can select binary mode by adding <literal>O_BINARY</literal> to
+the second argument of an <literal>open</literal> call, or
+<literal>"b"</literal> to second argument of an <literal>fopen</literal> call.
+You can also call <literal>setmode (fd, O_BINARY)</literal>.
+</para>
+<para>Note that because the open/fopen switches are defined by ANSI, they
+exist under most flavors of Unix; open/fopen will just ignore the switch
+since they have no meaning to UNIX.
+</para>
+<para>Explanation adapted from mailing list email by Earnie Boyd
+<earnie_boyd (at) yahoo.com>.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.api.threads">
+<question><para>Is the Cygwin library multi-thread-safe?</para></question>
+<answer>
+
+<para>Yes.
+</para>
+<para>There is also extensive support for 'POSIX threads', see the file
+<literal>cygwin.din</literal> for the list of POSIX thread functions provided.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.api.winnt">
+<question><para>Why is some functionality only supported in Windows NT?</para></question>
+<answer>
+
+<para>Windows 9x: n.
+32 bit extensions and a graphical shell for a 16 bit patch to an
+8 bit operating system originally coded for a 4 bit microprocessor,
+written by a 2 bit company that can't stand 1 bit of competition.
+</para>
+<para>But seriously, Windows 9x lacks most of the security-related calls and
+has several other deficiencies with respect to its version of the Win32
+API. See the calls.texinfo document for more information as to what
+is not supported in Win 9x.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.api.fork">
+<question><para>How is fork() implemented?</para></question>
+<answer>
+
+<para>Cygwin fork() essentially works like a non-copy on write version
+of fork() (like old Unix versions used to do). Because of this it
+can be a little slow. In most cases, you are better off using the
+spawn family of calls if possible.
+</para>
+<para>Here's how it works:
+</para>
+<para>Parent initializes a space in the Cygwin process table for child.
+Parent creates child suspended using Win32 CreateProcess call, giving
+the same path it was invoked with itself. Parent calls setjmp to save
+its own context and then sets a pointer to this in the Cygwin shared
+memory area (shared among all Cygwin tasks). Parent fills in the child's
+.data and .bss subsections by copying from its own address space into
+the suspended child's address space. Parent then starts the child.
+Parent waits on mutex for child to get to safe point. Child starts and
+discovers if has been forked and then longjumps using the saved jump
+buffer. Child sets mutex parent is waiting on and then blocks on
+another mutex waiting for parent to fill in its stack and heap. Parent
+notices child is in safe area, copies stack and heap from itself into
+child, releases the mutex the child is waiting on and returns from the
+fork call. Child wakes from blocking on mutex, recreates any mmapped
+areas passed to it via shared area and then returns from fork itself.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.api.globbing">
+<question><para>How does wildcarding (globbing) work?</para></question>
+<answer>
+
+<para>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 means
+that if you type <literal>LS *.EXE</literal> from DOS, it will do what you might
+expect.
+</para>
+<para>Beware: globbing uses <literal>malloc</literal>. If your application defines
+<literal>malloc</literal>, that will get used. This may do horrible things to you.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.api.symlinks">
+<question><para>How do symbolic links work?</para></question>
+<answer>
+
+<para>Cygwin knows of two ways to create symlinks.
+</para>
+<para>The old method is the only valid one up to but not including version 1.3.0.
+If it's enabled (from 1.3.0 on by setting `nowinsymlinks' in the environment
+variable CYGWIN) Cygwin generates link files with a magic header. When you
+open a file or directory that is a link to somewhere else, it opens the file
+or directory listed in the magic header. Because we don't want to have to
+open every referenced file to check symlink status, Cygwin marks symlinks
+with the system attribute. Files without the system attribute are not
+checked. Because remote samba filesystems do not enable the system
+attribute by default, symlinks do not work on network drives unless you
+explicitly enable this attribute.
+</para>
+<para>The new method which is introduced with Cygwin version 1.3.0 is enabled
+by default or if `winsymlinks' is set in the environment variable CYGWIN.
+Using this method, Cygwin generates symlinks by creating Windows shortcuts.
+Cygwin created shortcuts have a special header (which is in that way never
+created by Explorer) and the R/O attribute set. A DOS path is stored in
+the shortcut as usual and the description entry is used to store the POSIX
+path. While the POSIX path is stored as is, the DOS path has perhaps to be
+rearranged to result in a valid path. This may result in a divergence
+between the DOS and the POSIX path when symlinks are moved crossing mount
+points. When a user changes the shortcut, this will be detected by Cygwin
+and it will only use the DOS path then. While Cygwin shortcuts are shown
+without the ".lnk" suffix in `ls' output, non-Cygwin shortcuts are shown
+with the suffix. However, both are treated as symlinks.
+</para>
+<para>Both, the old and the new symlinks can live peacefully together since Cygwin
+treats both as symlinks regardless of the setting of `(no)winsymlinks' in
+the environment variable CYGWIN.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.api.executables">
+<question><para>Why do some files, which are not executables have the 'x' type.</para></question>
+<answer>
+
+<para>When working out the Unix-style attribute bits on a file, the library
+has to fill out some information not provided by the WIN32 API.
+</para>
+<para>It guesses that files ending in .exe and .bat are executable, as are
+ones which have a "#!" as their first characters.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.api.secure">
+<question><para>How secure is Cygwin in a multi-user environment?</para></question>
+<answer>
+
+<para>As of version 1.5.13, the Cygwin developers are not aware of any feature
+in the cygwin dll that would allow users to gain privileges or to access
+objects to which they have no rights under Windows. However there is no
+guarantee that Cygwin is as secure as the Windows it runs on. Cygwin
+processes share some variables and are thus easier targets of denial of
+service type of attacks.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.api.net-functions">
+<question><para>How do the net-related functions work?</para></question>
+<answer>
+
+<para><emphasis role='bold'>(Please note: This section has not yet been updated for the latest net release.)</emphasis>
+</para>
+<para>The network support in Cygwin is supposed to provide the Unix API, not
+the Winsock API.
+</para>
+<para>There are differences between the semantics of functions with the same
+name under the API.
+</para>
+<para>E.g., the select system call on Unix can wait on a standard file handles
+and handles to sockets. The select call in Winsock can only wait on
+sockets. Because of this, cygwin.dll does a lot of nasty stuff behind
+the scenes, trying to persuade various Winsock/win32 functions to do what
+a Unix select would do.
+</para>
+<para>If you are porting an application which already uses Winsock, then
+using the net support in Cygwin is wrong.
+</para>
+<para>But you can still use native Winsock, and use Cygwin. The functions
+which cygwin.dll exports are called 'cygwin_<name>'. There
+are a load of defines which map the standard Unix names to the names
+exported by the DLL-- check out include/netdb.h:
+</para>
+<screen>
+..etc..
+void cygwin_setprotoent (int);
+void cygwin_setservent (int);
+void cygwin_setrpcent (int);
+..etc..
+#ifndef __INSIDE_CYGWIN_NET__
+#define endprotoent cygwin_endprotoent
+#define endservent cygwin_endservent
+#define endrpcent cygwin_endrpcent
+..etc..
+</screen>
+
+<para>The idea is that you'll get the Unix->Cygwin mapping if you include
+the standard Unix header files. If you use this, you won't need to
+link with libwinsock.a - all the net stuff is inside the DLL.
+</para>
+<para>The mywinsock.h file is a standard winsock.h which has been hacked to
+remove the bits which conflict with the standard Unix API, or are
+defined in other headers. E.g., in mywinsock.h, the definition of
+struct hostent is removed. This is because on a Unix box, it lives in
+netdb. It isn't a good idea to use it in your applications.
+</para>
+<para>As of the b19 release, this information may be slightly out of date.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.api.winsock">
+<question><para>I don't want Unix sockets, how do I use normal Win32 winsock?</para></question>
+<answer>
+
+<para><emphasis role='bold'>(Please note: This section has not yet been updated for the latest net release.)</emphasis>
+</para>
+<para>To use the vanilla Win32 winsock, you just need to #define Win32_Winsock
+and #include "windows.h" at the top of your source file(s). You'll also
+want to add -lwsock32 to the compiler's command line so you link against
+libwsock32.a.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.api.versions">
+<question><para>What version numbers are associated with Cygwin?</para></question>
+<answer>
+
+<para>Cygwin versioning is relatively complicated because of its status as a
+shared library. First of all, since October 1998 every Cygwin DLL has
+been named <literal>cygwin1.dll</literal> and has a 1 in the release name.
+Additionally, there are DLL major and minor numbers that correspond to
+the name of the release, and a release number. In other words,
+cygwin-1.5.10-2 is <literal>cygwin1.dll</literal>, major version 5, minor version
+10, release 2.
+</para>
+<para>The <literal>cygwin1.dll</literal> major version number gets incremented only when a
+change is made that makes existing software incompatible. For example,
+the first major version 5 release, cygwin-1.5.0-1, added 64-bit file I/O
+operations, which required many libraries to be recompiled and relinked.
+The minor version changes every time we make a new backward compatible
+Cygwin release available. There is also a <literal>cygwin1.dll</literal> release
+version number. The release number is only incremented if we update an
+existing release in a way that does not effect the DLL (like a missing
+header file).
+</para>
+<para>There are also Cygwin API major and minor numbers. The major number
+tracks important non-backward-compatible interface changes to the API.
+An executable linked with an earlier major number will not be compatible
+with the latest DLL. The minor number tracks significant API additions
+or changes that will not break older executables but may be required by
+newly compiled ones.
+</para>
+<para>Then there is a shared memory region compatibility version number. It is
+incremented when incompatible changes are made to the shared memory
+region or to any named shared mutexes, semaphores, etc. Finally there
+is a mount point registry version number which keeps track
+of non-backwards-compatible changes to the registry mount table layout.
+This has been <literal>mounts v2</literal> for a long time. For more exciting Cygwin
+version number details, check out the <literal>/usr/include/cygwin/version.h</literal>
+file.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.api.timezone">
+<question><para>Why isn't _timezone set correctly?</para></question>
+<answer>
+
+<para><emphasis role='bold'>(Please note: This section has not yet been updated for the latest net release.)</emphasis>
+</para>
+<para>Did you explicitly call tzset() before checking the value of _timezone?
+If not, you must do so.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.api.mouse">
+<question><para>Is there a mouse interface?</para></question>
+<answer>
+
+<para>There is no way to capture mouse events from Cygwin. There are
+currently no plans to add support for this.
+</para>
+</answer></qandaentry>
+
--- /dev/null
+<!-- faq-problems.xml -->
+<para>Aware of the problem, no solution known.</para>
+
+<qandaentry id="faq.known-problems.hyperthreading">
+<question><para>Hangs with Hyperthreaded Processor</para></question>
+<answer>
+
+<para>Some users using processors with Intel's Hyperthreading turned on have
+reported hangs that do not appear with Hyperthreading off. So far
+the Cygwin developers have not been able to reproduce this problem.
+See <ulink url="http://www.cygwin.com/ml/cygwin/2004-07/msg01100.html">http://www.cygwin.com/ml/cygwin/2004-07/msg01100.html</ulink> and
+related messages for details.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.known-problems.pipe-key">
+<question><para>Pipe key (<literal>|</literal>) doesn't work on non-US keyboards in Win9x/ME</para></question>
+<answer>
+
+<para>This might get fixed someday, but meanwhile, just use rxvt, which does
+not have this problem. This is no real loss, because rxvt has many
+other advantages. (Do not attempt to use the "broken" pipe key
+(<literal>&brokenpipe;</literal>) as a substitute, it is a different character.)
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.known-problems.win9x-tape">
+<question><para>Cannot access tape devices with mt on Win9x</para></question>
+<answer>
+
+<para>Win9x does not support the API used by the Cygwin fhandler_dev_tape
+class. Details at
+<ulink url="http://sources.redhat.com/ml/cygwin/2000-12/msg00331.html">http://sources.redhat.com/ml/cygwin/2000-12/msg00331.html</ulink>.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.known-problems.win9x-scp">
+<question><para>On Win9x, scp leaves ssh processes running.</para></question>
+<answer>
+<para>
+You can stop them by hand with the Task Manager.
+</para>
+</answer></qandaentry>
+
--- /dev/null
+<!-- faq-programming.xml -->
+
+<qandaentry id="faq.programming.packages">
+<question><para>How do I contribute a package?</para></question>
+<answer>
+
+<para>If you are willing to be a package maintainer, great! We urgently need
+volunteers to prepare and maintain packages, because the priority of the
+Cygwin Team is Cygwin itself.
+</para>
+<para>The Cygwin Package Contributor's Guide at
+<ulink url="http://cygwin.com/setup.html">http://cygwin.com/setup.html</ulink> details everything you need to know
+about being a package maintainer. The quickest way to get started is to
+read the <emphasis>Initial packaging procedure, script-based</emphasis> section on
+that page. The <literal>generic-build-script</literal> found there works well for
+most packages.
+</para>
+<para>For questions about package maintenance, use the cygwin-apps mailing
+list (start at <ulink url="http://cygwin.com/lists.html">http://cygwin.com/lists.html</ulink>) <emphasis>after</emphasis>
+searching and browsing the cygwin-apps list archives, of course. Be
+sure to look at the <emphasis>Submitting a package</emphasis> checklist at
+<ulink url="http://cygwin.com/setup.html">http://cygwin.com/setup.html</ulink> before sending an ITP (Intent To
+Package) email to cygwin-apps.
+</para>
+<para>You should also announce your intentions to the general cygwin list, in
+case others were thinking the same thing.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.contribute">
+<question><para>How do I contribute to Cygwin?</para></question>
+<answer>
+
+<para>If you want to contribute to Cygwin itself, see
+<ulink url="http://cygwin.com/contrib.html">http://cygwin.com/contrib.html</ulink>.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.huge-executables">
+<question><para>Why are compiled executables so huge?!?</para></question>
+<answer>
+
+<para>By default, gcc compiles in all symbols. You'll also find that gcc
+creates large executables on UNIX.
+</para>
+<para>If that bothers you, just use the 'strip' program, part of the binutils
+package. Or compile with the <literal>-s</literal> option to gcc.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.glibc">
+<question><para>Where is glibc?</para></question>
+<answer>
+
+<para>Cygwin does not provide glibc. It uses newlib instead, which provides
+much (but not all) of the same functionality. Porting glibc to Cygwin
+would be difficult.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.objective-c">
+<question><para>Where is Objective C?</para></question>
+<answer>
+
+<para>Objective C is not distributed with the Cygwin version of gcc, and there
+are no plans to do so. The gcc package maintainer had difficulty
+building it, and once built there were problems using it. It appears
+that there is only minimal support for the Objective C front-end in the
+main GCC distribution, anyway.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.make-execvp">
+<question><para>Why does my make fail on Cygwin with an execvp error? </para></question>
+<answer>
+
+<para>First of all, if you are using <literal>make -j[N]</literal>, then stop. It doesn't
+work well. Also beware of using non-portable shell features in your
+Makefiles (see tips at <ulink url="http://cygwin.com/faq/faq_3.html#SEC46">http://cygwin.com/faq/faq_3.html#SEC46</ulink>).
+</para>
+<para>Errors of <literal>make: execvp: /bin/sh: Illegal Argument</literal> or
+<literal>make: execvp: /bin/sh: Argument list too long</literal> are often
+caused by the command-line being to long for the Windows execution model.
+To circumvent this, mount the path of the executable using the -X switch
+to enable cygexec for all executables in that folder; you will also need
+to exclude non-cygwin executables with the -x switch. Enabling cygexec
+causes cygwin executables to talk directly to one another, which increases
+the command-line limit. To enable cygexec for <literal>/bin</literal> and
+<literal>/usr/bin</literal>, you can use these commands in a batch file:
+</para>
+<screen>
+mount -X -b -f c:\cygwin\bin /bin
+mount -X -b -f c:\cygwin\bin /usr/bin
+mount -x -b -f c:\cygwin\bin\strace.exe /usr/bin/strace.exe
+mount -x -b -f c:\cygwin\bin\strace.exe /bin/strace.exe
+mount -x -b -f c:\cygwin\bin\cygcheck.exe /usr/bin/cygcheck.exe
+mount -x -b -f c:\cygwin\bin\cygcheck.exe /bin/cygcheck.exe
+</screen>
+
+<para>Note that you must specifically exclude <literal>strace</literal> and <literal>cygcheck</literal>,
+which are not linked to the Cygwin DLL.
+</para>
+<para>(See <ulink url="http://www.cygwin.com/cygwin-ug-net/using-utils.html#mount">http://www.cygwin.com/cygwin-ug-net/using-utils.html#mount</ulink>
+for more information.)
+</para>
+
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.winmain">
+<question><para>Why the undefined reference to <literal>WinMain@16</literal>?</para></question>
+<answer>
+
+<para>If you're using <literal>gcc</literal>, try adding an empty main() function to one
+of your sources. Or, perhaps you have <literal>-lm</literal> too early in the
+link command line. It should be at the end:
+</para>
+<screen>
+ bash$ gcc hello.c -lm
+ bash$ ./a.exe
+ Hello World!
+</screen>
+
+<para>works, but
+</para>
+<screen>
+ 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
+</screen>
+
+<para>If you're using GCJ, you need to pass a "--main" flag:
+</para>
+<screen>
+gcj --main=Hello Hello.java
+</screen>
+
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.win32-api">
+<question><para>How do I use Win32 API calls?</para></question>
+<answer>
+
+<para><emphasis role='bold'>(Please note: This section has not yet been updated for the latest net release.)</emphasis>
+</para>
+<para>It's pretty simple actually. Cygwin tools require that you explicitly
+link the import libraries for whatever Win32 API functions that you
+are going to use, with the exception of kernel32, which is linked
+automatically (because the startup and/or built-in code uses it).
+</para>
+<para>For example, to use graphics functions (GDI) you must link
+with gdi32 like this:
+</para>
+<para>gcc -o foo.exe foo.o bar.o -lgdi32
+</para>
+<para>or (compiling and linking in one step):
+</para>
+<para>gcc -o foo.exe foo.c bar.c -lgdi32
+</para>
+<para>The following libraries are available for use in this way:
+</para>
+<para>advapi32 largeint ole32 scrnsave vfw32
+cap lz32 oleaut32 shell32 win32spl
+comctl32 mapi32 oledlg snmp winmm
+comdlg32 mfcuia32 olepro32 svrapi winserve
+ctl3d32 mgmtapi opengl32 tapi32 winspool
+dlcapi mpr penwin32 th32 winstrm
+gdi32 msacm32 pkpd32 thunk32 wow32
+glaux nddeapi rasapi32 url wsock32
+glu32 netapi32 rpcdce4 user32 wst
+icmp odbc32 rpcndr uuid
+imm32 odbccp32 rpcns4 vdmdbg
+kernel32 oldnames rpcrt4 version
+</para>
+<para>The regular setup allows you to use the option -mwindows on the
+command line to include a set of the basic libraries (and also
+make your program a GUI program instead of a console program),
+including user32, gdi32 and, IIRC, comdlg32.
+</para>
+<para>Note that you should never include -lkernel32 on your link line
+unless you are invoking ld directly. Do not include the same import
+library twice on your link line. Finally, 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.
+</para>
+<para>The first two are related to problems the linker has (as of b18 at least)
+when import libraries are referenced twice. Tables get messed up and
+programs crash randomly. The last point has to do with the fact that
+gcc processes the files listed on the command line in sequence and
+will only resolve references to libraries if they are given after
+the file that makes the reference.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.win32-no-cygwin">
+<question><para>How do I compile a Win32 executable that doesn't use Cygwin?</para></question>
+<answer>
+
+<para>The -mno-cygwin flag to gcc makes gcc link against standard Microsoft
+DLLs instead of Cygwin. This is desirable for native Windows programs
+that don't need a UNIX emulation layer.
+</para>
+<para>This is not to be confused with 'MinGW' (Minimalist GNU for Windows),
+which is a completely separate effort. That project's home page is
+<ulink url="http://www.mingw.org/index.shtml">http://www.mingw.org/index.shtml</ulink>.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.static-linking">
+<question><para>Can I build a Cygwin program that does not require cygwin1.dll at runtime?</para></question>
+<answer>
+
+<para>No. If your program uses the Cygwin API, then your executable cannot
+run without cygwin1.dll. In particular, it is not possible to
+statically link with a Cygwin library to obtain an independent,
+self-contained executable.
+</para>
+<para>If this is an issue because you intend to distribute your Cygwin
+application, then you had better read and understand
+<ulink url="http://cygwin.com/licensing.html">http://cygwin.com/licensing.html</ulink>, which explains the licensing
+options. Unless you purchase a special commercial license from Red
+Hat, then your Cygwin application must be Open Source.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.msvcrt-and-cygwin">
+<question><para>Can I link with both MSVCRT*.DLL and cygwin1.dll?</para></question>
+<answer>
+
+<para>No, you must use one or the other, they are mutually exclusive.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.no-console-window">
+<question><para>How do I make the console window go away?</para></question>
+<answer>
+
+<para>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.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.make-spaces">
+<question><para>Why does make complain about a "missing separator"?</para></question>
+<answer>
+
+<para>This problem usually occurs as a result of someone editing a Makefile
+with a text editor that replaces tab characters with spaces. Command
+lines must start with tabs. This is not specific to Cygwin.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.win32-headers">
+<question><para>Why can't we redistribute Microsoft's Win32 headers?</para></question>
+<answer>
+
+<para>Subsection 2.d.f of the `Microsoft Open Tools License agreement' looks
+like it says that one may not "permit further redistribution of the
+Redistributables to their end users". We take this to mean that we can
+give them to you, but you can't give them to anyone else, which is
+something that Red Hat can't agree to. Fortunately, we
+have our own Win32 headers which are pretty complete.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.msvs-mingw">
+<question><para>How do I use <literal>cygwin1.dll</literal> with Visual Studio or MinGW?</para></question>
+<answer>
+
+<para>Before you begin, note that Cygwin is licensed under the GNU GPL (as
+indeed are all other Cygwin-based libraries). That means that if your
+code links against the cygwin dll (and if your program is calling
+functions from Cygwin, it must, as a matter of fact, be linked against
+it), you must apply the GPL to your source as well. Of course, this
+only matters if you plan to distribute your program in binary form. For
+more information, see <ulink url="http://gnu.org/licenses/gpl-faq.html">http://gnu.org/licenses/gpl-faq.html</ulink>. If
+that is not a problem, read on.
+</para>
+<para>If you want to load the DLL dynamically, read
+<literal>winsup/cygwin/how-cygtls-works.txt</literal> and the sample code in
+<literal>winsup/testsuite/cygload</literal> to understand how this works.
+The short version is:
+</para>
+<orderedlist><listitem><para>Make sure you have 4K of scratch space at the bottom of your stack.
+</para></listitem>
+<listitem><para>Invoke <literal>cygwin_dll_init()</literal>:
+<screen>
+HMODULE h = LoadLibrary("cygwin1.dll");
+void (*init)() = GetProcAddress(h, "cygwin_dll_init");
+init();
+</screen>
+</para></listitem>
+</orderedlist>
+
+<para>If you want to link statically from Visual Studio, to my knowledge
+none of the Cygwin developers have done this, but we have this report
+from the mailing list that it can be done this way:
+</para>
+<orderedlist><listitem><para>Use the impdef program to generate a .def file for the cygwin1.dll
+(if you build the cygwin dll from source, you will already have a def
+file)
+</para>
+<screen>
+impdef cygwin1.dll > cygwin1.def
+</screen>
+
+</listitem>
+<listitem><para>Use the MS VS linker (lib) to generate an import library
+</para>
+<screen>
+lib /def=cygwin1.def /out=cygwin1.lib
+</screen>
+
+</listitem>
+<listitem><para>Create a file "my_crt0.c" with the following contents
+</para>
+<screen>
+#include <sys/cygwin.h>
+#include <stdlib.h>
+
+typedef int (*MainFunc) (int argc, char *argv[], char **env);
+
+void
+ my_crt0 (MainFunc f)
+ {
+ cygwin_crt0(f);
+ }
+</screen>
+
+</listitem>
+<listitem><para>Use gcc in a Cygwin prompt to build my_crt0.c into a DLL
+ (e.g. my_crt0.dll). Follow steps 1 and 2 to generate .def and
+ .lib files for the DLL.
+</para>
+</listitem>
+<listitem><para>Download crt0.c from the cygwin website and include it in
+ your sources. Modify it to call my_crt0() instead of
+ cygwin_crt0().
+</para>
+</listitem>
+<listitem><para>Build your object files using the MS VC compiler cl.
+</para>
+</listitem>
+<listitem><para>Link your object files, cygwin1.lib, and my_crt0.lib (or
+ whatever you called it) into the executable.
+</para></listitem>
+</orderedlist>
+
+<para>Note that if you are using any other Cygwin based libraries
+that you will probably need to build them as DLLs using gcc and
+then generate import libraries for the MS VC linker.
+</para>
+<para>Thanks to Alastair Growcott (alastair dot growcott at bakbone dot co
+dot uk) for this tip.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.linking-lib">
+<question><para>How do I link against a <literal>.lib</literal> file?</para></question>
+<answer>
+
+<para>If your <literal>.lib</literal> file is a normal static or import library with
+C-callable entry points, you can list <literal>foo.lib</literal> as an object file for
+gcc/g++, just like any <literal>*.o</literal> file. Otherwise, here are some steps:
+</para>
+<orderedlist><listitem><para>Build a C file with a function table. Put all functions you intend
+to use in that table. This forces the linker to include all the object
+files from the .lib. Maybe there is an option to force LINK.EXE to
+include an object file.
+</para></listitem>
+<listitem><para>Build a dummy 'LibMain'.
+</para></listitem>
+<listitem><para>Build a .def with all the exports you need.
+</para></listitem>
+<listitem><para>Link with your .lib using link.exe.
+</para></listitem>
+</orderedlist>
+
+<para>or
+</para>
+<orderedlist><listitem><para>Extract all the object files from the .lib using LIB.EXE.
+</para></listitem>
+<listitem><para>Build a dummy C file referencing all the functions you need, either
+ with a direct call or through an initialized function pointer.
+</para></listitem>
+<listitem><para>Build a dummy LibMain.
+</para></listitem>
+<listitem><para>Link all the objects with this file+LibMain.
+</para></listitem>
+<listitem><para>Write a .def.
+</para></listitem>
+<listitem><para>Link.
+</para></listitem>
+</orderedlist>
+
+<para>You can use these methods to use MSVC (and many other runtime libs)
+with Cygwin development tools.
+</para>
+<para>Note that this is a lot of work (half a day or so), but much less than
+rewriting the runtime library in question from specs...
+</para>
+<para>Thanks to Jacob Navia (root at jacob dot remcomp dot fr) for this explanation.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.building-cygwin">
+<question><para>How do I build Cygwin on my own?</para></question>
+<answer>
+
+<para>First, you need to get the Cygwin source. Ideally, you should check out
+what you need from CVS (<ulink url="http://cygwin.com/cvs.html">http://cygwin.com/cvs.html</ulink>). This is the
+<emphasis>preferred method</emphasis> for acquiring the sources. Otherwise, you can
+install the cygwin source package from the distribution.
+</para>
+<para>If you are trying to duplicate a cygwin release then you should just
+download the corresponding source package and use "tar xjf" to unpack
+it. This will unpack the sources into a directory named cygwin-x.y.z-n,
+where x.y.z-n correspond to the version numbering of the tar.bz2
+package.
+</para>
+<screen>
+tar xjf cygwin-1.5.12-1-src.tar.bz2
+cd cygwin-1.5.12-1
+</screen>
+
+<para>You <emphasis>must</emphasis> build cygwin in a separate directory from the source,
+so create something like a <literal>build/</literal> directory. You will also want
+to install to a temporary location:
+</para>
+<screen>
+mkdir build
+mkdir /install
+cd build
+(../configure --prefix=/install -v; make) >& make.out
+make install > install.log 2>&1
+</screen>
+
+<para>Normally, this procedure ignore errors in building the documentation.
+which requires the <literal>docbook-xml</literal>, <literal>docbook-xsl</literal>, and
+<literal>xmlto</literal> packages. For more information on building the
+documentation, see the README included in the cygwin-doc package.
+</para>
+<para>To check a cygwin1.dll, run "make check" in the winsup/testsuite
+directory. If that works, install everything <emphasis>except</emphasis> the dll (if
+you can). Then, close down all cygwin programs (including bash windows,
+inetd, etc.), save your old dll, and copy the new dll to the correct
+place. Then start up a bash window, or run a cygwin program from the
+Windows command prompt, and see what happens.
+</para>
+<para>If you get the error "shared region is corrupted" it means that two
+different versions of cygwin1.dll are running on your machine at the
+same time. Remove all but one.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.debugging-cygwin">
+<question><para>I may have found a bug in Cygwin, how can I debug it (the symbols in gdb look funny)?</para></question>
+<answer>
+
+<para>Debugging symbols are stripped from distibuted Cygwin binaries, so any
+symbols that you see in gdb are basically meaningless. It is also a good
+idea to use the latest code in case the bug has been fixed, so we
+recommend trying the latest snapshot from
+<ulink url="http://cygwin.com/snapshots/">http://cygwin.com/snapshots/</ulink> or build the DLL from CVS.
+</para>
+<para>To build a debugging version of the Cygwin DLL, you will need to follow
+the instructions at <ulink url="http://cygwin.com/faq/faq_3.html#SEC102">http://cygwin.com/faq/faq_3.html#SEC102</ulink>. You
+can also contact the mailing list for pointers (a simple test case that
+demonstrates the bug is always welcome).
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.compiling-unsupported">
+<question><para>How can I compile Cygwin for an unsupported platform (PowerPC, Alpha, ARM, Itanium)?</para></question>
+<answer>
+
+<para>Unfortunately, this will be difficult. Exception handling and signals
+support semantics and args have been designed for x86 so you would need
+to write specific support for your platform. We don't know of any other
+incompatibilities. Please send us patches if you do this work!
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.adjusting-heap">
+<question><para>How can I adjust the heap/stack size of an application?</para></question>
+<answer>
+
+<para>If you need to change the maximum amount of memory available to Cygwin, see
+<ulink url="http://cygwin.com/cygwin-ug-net/setup-maxmem.html">http://cygwin.com/cygwin-ug-net/setup-maxmem.html</ulink>. Otherwise,
+just pass heap/stack linker arguments to gcc. To create foo.exe with
+a heap size of 1024 and a stack size of 4096, you would invoke
+gcc as:
+</para>
+<para><literal>gcc -Wl,--heap,1024,--stack,4096 -o foo foo.c</literal>
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.dll-cygcheck">
+<question><para>How can I find out which DLLs are needed by an executable?</para></question>
+<answer>
+
+<para><literal>objdump -p</literal> provides this information, but is rather verbose.
+</para>
+<para><literal>cygcheck</literal> will do this much more concisely, and operates
+recursively, provided the command is in your path.
+</para>
+<para>Note there is currently a bug in cygcheck in that it will not report
+on a program in a Windows system dir (e.g., C:\Windows or C:\WINNT) even
+if it's in your path. To work around this, supply the full Win32 path
+to the executable, including the .exe extension:
+</para>
+<screen>
+cygcheck c:\\winnt\\system32\\cmd.exe
+</screen>
+
+<para>(Note the windows path separator must be escaped if this is typed in
+bash.)
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.dll-building">
+<question><para>How do I build a DLL?</para></question>
+<answer>
+
+<para>There's documentation that explains the process in the Cygwin User's
+Guide here: <ulink url="http://cygwin.com/cygwin-ug-net/dll.html">http://cygwin.com/cygwin-ug-net/dll.html</ulink>
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.breakpoint">
+<question><para>How can I set a breakpoint at MainCRTStartup?</para></question>
+<answer>
+
+<para><emphasis role='bold'>(Please note: This section has not yet been updated for the latest net release.)</emphasis>
+</para>
+<para>Set a breakpoint at *0x401000 in gdb and then run the program in
+question.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.dll-relocatable">
+<question><para>How can I build a relocatable dll?</para></question>
+<answer>
+
+<para><emphasis role='bold'>(Please note: This section has not yet been updated for the latest net release. However, there was a discussion on the cygwin mailing list recently that addresses this issue. Read <ulink url="http://cygwin.com/ml/cygwin/2000-06/msg00688.html">http://cygwin.com/ml/cygwin/2000-06/msg00688.html</ulink> and related messages.)</emphasis>
+</para>
+<para>You must execute the following sequence of five commands, in this
+order:
+</para>
+<screen>
+$(LD) -s --base-file BASEFILE --dll -o DLLNAME OBJS LIBS -e ENTRY
+
+$(DLLTOOL) --as=$(AS) --dllname DLLNAME --def DEFFILE \
+ --base-file BASEFILE --output-exp EXPFILE
+
+$(LD) -s --base-file BASEFILE EXPFILE -dll -o DLLNAME OBJS LIBS -e ENTRY
+
+$(DLLTOOL) --as=$(AS) --dllname DLLNAME --def DEFFILE \
+ --base-file BASEFILE --output-exp EXPFILE
+
+$(LD) EXPFILE --dll -o DLLNAME OBJS LIBS -e ENTRY
+</screen>
+
+<para>In this example, $(LD) is the linker, ld.
+</para>
+<para>$(DLLTOOL) is dlltool.
+</para>
+<para>$(AS) is the assembler, as.
+</para>
+<para>DLLNAME is the name of the DLL you want to create, e.g., tcl80.dll.
+</para>
+<para>OBJS is the list of object files you want to put into the DLL.
+</para>
+<para>LIBS is the list of libraries you want to link the DLL against. For
+example, you may or may not want -lcygwin. You may want -lkernel32.
+Tcl links against -lcygwin -ladvapi32 -luser32 -lgdi32 -lcomdlg32
+-lkernel32.
+</para>
+<para>DEFFILE is the name of your definitions file. A simple DEFFILE would
+consist of ``EXPORTS'' followed by a list of all symbols which should
+be exported from the DLL. Each symbol should be on a line by itself.
+Other programs will only be able to access the listed symbols.
+</para>
+<para>BASEFILE is a temporary file that is used during this five stage
+process, e.g., tcl.base.
+</para>
+<para>EXPFILE is another temporary file, e.g., tcl.exp.
+</para>
+<para>ENTRY is the name of the function which you want to use as the entry
+point. This function should be defined using the WINAPI attribute,
+and should take three arguments:
+ int WINAPI startup (HINSTANCE, DWORD, LPVOID)
+</para>
+<para>This means that the actual symbol name will have an appended @12, so if
+your entry point really is named <literal>startup</literal>, the string you should
+use for ENTRY in the above examples would be <literal>startup@12</literal>.
+</para>
+<para>If your DLL calls any Cygwin API functions, the entry function will need
+to initialize the Cygwin impure pointer. You can do that by declaring
+a global variable <literal>_impure_ptr</literal>, and then initializing it in the
+entry function. Be careful not to export the global variable
+<literal>_impure_ptr</literal> from your DLL; that is, do not put it in DEFFILE.
+</para>
+<screen>
+/* This is a global variable. */
+struct _reent *_impure_ptr;
+extern struct _reent *__imp_reent_data;
+
+int entry (HINSTANT hinst, DWORD reason, LPVOID reserved)
+{
+ _impure_ptr = __imp_reent_data;
+ /* Whatever else you want to do. */
+}
+</screen>
+
+<para>You may put an optional `--subsystem windows' on the $(LD) lines. The
+Tcl build does this, but I admit that I no longer remember whether
+this is important. Note that if you specify a --subsytem <x> flag to ld,
+the -e entry must come after the subsystem flag, since the subsystem flag
+sets a different default entry point.
+</para>
+<para>You may put an optional `--image-base BASEADDR' on the $(LD) lines.
+This will set the default image base. Programs using this DLL will
+start up a bit faster if each DLL occupies a different portion of the
+address space. Each DLL starts at the image base, and continues for
+whatever size it occupies.
+</para>
+<para>Now that you've built your DLL, you may want to build a library so
+that other programs can link against it. This is not required: you
+could always use the DLL via LoadLibrary. However, if you want to be
+able to link directly against the DLL, you need to create a library.
+Do that like this:
+</para>
+<para>$(DLLTOOL) --as=$(AS) --dllname DLLNAME --def DEFFILE --output-lib LIBFILE
+</para>
+<para>$(DLLTOOL), $(AS), DLLNAME, and DEFFILE are the same as above. Make
+sure you use the same DLLNAME and DEFFILE, or things won't work right.
+</para>
+<para>LIBFILE is the name of the library you want to create, e.g.,
+libtcl80.a. You can then link against that library using something
+like -ltcl80 in your linker command.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.debug">
+<question><para>How can I debug what's going on?</para></question>
+<answer>
+
+<para>You can debug your application using <literal>gdb</literal>. Make sure you
+compile it with the -g flag! If your application calls functions in
+MS DLLs, gdb will complain about not being able to load debug information
+for them when you run your program. This is normal since these DLLs
+don't contain debugging information (and even if they did, that debug
+info would not be compatible with gdb).
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.system-trace">
+<question><para>Can I use a system trace mechanism instead?</para></question>
+<answer>
+
+<para>Yes. You can use the <literal>strace.exe</literal> utility to run other cygwin
+programs with various debug and trace messages enabled. For information
+on using <literal>strace</literal>, see the Cygwin User's Guide or the file
+<literal>winsup/utils/utils.sgml</literal>.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.gdb-signals">
+<question><para>Why doesn't gdb handle signals?</para></question>
+<answer>
+
+<para>Unfortunately, there is only minimal signal handling support in gdb
+currently. Signal handling only works with Windows-type signals.
+SIGINT may work, SIGFPE may work, SIGSEGV definitely does. You cannot
+'stop', 'print' or 'nopass' signals like SIGUSR1 or SIGHUP to the
+process being debugged.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.linker">
+<question><para>The linker complains that it can't find something.</para></question>
+<answer>
+
+<para>A common error is to put the library on the command line before
+the thing that needs things from it.
+</para>
+<para>This is wrong <literal>gcc -lstdc++ hello.cc</literal>.
+This is right <literal>gcc hello.cc -lstdc++</literal>.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.undeclared-functions">
+<question><para>I use a function I know is in the API, but I still get a link error.</para></question>
+<answer>
+
+<para>The function probably isn't declared in the header files, or
+the UNICODE stuff for it isn't filled in.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.libc">
+<question><para>Can you make DLLs that are linked against libc ?</para></question>
+<answer>
+
+<para>Yes.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.malloc-h">
+<question><para>Where is malloc.h?</para></question>
+<answer>
+
+<para><emphasis role='bold'>(Please note: This section has not yet been updated for the latest net release.)</emphasis>
+</para>
+<para>Include stdlib.h instead of malloc.h.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.own-malloc">
+<question><para>Can I use my own malloc?</para></question>
+<answer>
+
+<para>If you define a function called <literal>malloc</literal> in your own code, and link
+with the DLL, the DLL <emphasis>will</emphasis> call your <literal>malloc</literal>. Needless to
+say, you will run into serious problems if your malloc is buggy.
+</para>
+<para>If you run any programs from the DOS command prompt, rather than from in
+bash, the DLL will try and expand the wildcards on the command line.
+This process uses <literal>malloc</literal> <emphasis>before</emphasis> your main line is started.
+If you have written your own <literal>malloc</literal> to need some initialization
+to occur after <literal>main</literal> is called, then this will surely break.
+</para>
+<para>Moreover, there is an outstanding issue with <literal>_malloc_r</literal> in
+<literal>newlib</literal>. This re-entrant version of <literal>malloc</literal> will be called
+directly from within <literal>newlib</literal>, by-passing your custom version, and
+is probably incompatible with it. But it may not be possible to replace
+<literal>_malloc_r</literal> too, because <literal>cygwin1.dll</literal> does not export it and
+Cygwin does not expect your program to replace it. This is really a
+newlib issue, but we are open to suggestions on how to deal with it.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.msvc-gcc-objects">
+<question><para>Can I mix objects compiled with msvc++ and gcc?</para></question>
+<answer>
+
+<para>Yes, but only if you are combining C object files. MSVC C++ uses a
+different mangling scheme than GNU C++, so you will have difficulties
+combining C++ objects.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.gdb-msvc">
+<question><para>Can I use the gdb debugger to debug programs built by VC++?</para></question>
+<answer>
+
+<para>No, not for full (high level source language) debugging.
+The Microsoft compilers generate a different type of debugging
+symbol information, which gdb does not understand.
+</para>
+<para>However, the low-level (assembly-type) symbols generated by
+Microsoft compilers are coff, which gdb DOES understand.
+Therefore you should at least be able to see all of your
+global symbols; you just won't have any information about
+data types, line numbers, local variables etc.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.x86-assembly">
+<question><para>Where can I find info on x86 assembly?</para></question>
+<answer>
+
+<para>CPU reference manuals for Intel's current chips are available in
+downloadable PDF form on Intel's web site:
+</para>
+<para><ulink url="http://developer.intel.com/design/pro/manuals/">http://developer.intel.com/design/pro/manuals/</ulink>
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.make-scripts">
+<question><para>Shell scripts aren't running properly from my makefiles?</para></question>
+<answer>
+
+<para>If your scripts are in the current directory, you must have <literal>.</literal>
+(dot) in your $PATH. (It is not normally there by default.) Otherwise,
+you would need to add /bin/sh in front of each and every shell script
+invoked in your Makefiles.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.preprocessor">
+<question><para>What preprocessor do I need to know about?</para></question>
+<answer>
+
+<para>We use _WIN32 to signify access to the Win32 API and __CYGWIN__ for
+access to the Cygwin environment provided by the dll.
+</para>
+<para>We chose _WIN32 because this is what Microsoft defines in VC++ and
+we thought it would be a good idea for compatibility with VC++ code
+to follow their example. We use _MFC_VER to indicate code that should
+be compiled with VC++.
+</para>
+<para>_WIN32 is only defined when you use either the -mno-cygwin or -mwin32
+gcc command line options. This is because Cygwin is supposed to be a
+Unix emulation environment and defining _WIN32 confuses some programs
+which think that they have to make special concessions for a Windows
+environment which Cygwin handles automatically.
+</para>
+<para>Note that using -mno-cygwin replaces __CYGWIN__ with __MINGW32__ as to
+tell which compiler (or settings) you're running.
+Check this out in detail by running, for example
+</para>
+<screen>
+ $ gcc -dM -E -xc /dev/null >gcc.txt
+ $ gcc -mno-cygwin -dM -E -xc /dev/null >gcc-mno-cygwin.txt
+ $ gcc -mwin32 -dM -E -xc /dev/null >gcc-mwin32.txt
+</screen>
+<para>Then use the diff and grep utilities to check
+what the difference is.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.unix-gui">
+<question><para>How should I port my Unix GUI to Windows?</para></question>
+<answer>
+
+<para>There are two basic strategies for porting Unix GUIs to Windows.
+</para>
+<para>The first is to use a portable graphics library such as tcl/tk, X11, or
+V (and others?). Typically, you will end up with a GUI on Windows that
+requires some runtime support. With tcl/tk, you'll want to include the
+necessary library files and the tcl/tk DLLs. In the case of X11, you'll
+need everyone using your program to have an X11 server installed.
+</para>
+<para>The second method is to rewrite your GUI using Win32 API calls (or MFC
+with VC++). If your program is written in a fairly modular fashion, you
+may still want to use Cygwin if your program contains a lot of shared
+(non-GUI-related) code. That way you still gain some of the portability
+advantages inherent in using Cygwin.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.programming.djgpp">
+<question><para>Why not use DJGPP ?</para></question>
+<answer>
+
+<para>DJGPP is a similar idea, but for DOS instead of Win32. DJGPP uses a
+"DOS extender" to provide a more reasonable operating interface for its
+applications. The Cygwin toolset doesn't have to do this since all of
+the applications are native WIN32. Applications compiled with the
+Cygwin tools can access the Win32 API functions, so you can write
+programs which use the Windows GUI.
+</para>
+<para>You can get more info on DJGPP by following
+<ulink url="http://www.delorie.com/">http://www.delorie.com/</ulink>.
+</para></answer></qandaentry>
+
--- /dev/null
+<!-- faq-resources.xml -->
+<qandaentry id="faq.resources.documentation">
+<question><para>Where's the documentation?</para></question>
+<answer>
+
+<para>If you have installed Cygwin, you can find lots of documentation in
+<literal>/usr/share/doc/</literal>. Some packages have Cygwin specific
+instructions in a file
+<literal>/usr/share/doc/Cygwin/<replaceable>package_name</replaceable>.README</literal>.
+In addition, many packages ship with standard documentation, which you can
+find in
+<literal>/usr/share/doc/<replaceable>package_name</replaceable></literal> or
+by using the <literal>man</literal> or <literal>info</literal> tools. (Hint:
+use <literal>cygcheck -l <replaceable>package_name</replaceable></literal> to
+list what man pages the package includes.) Some older packages still keep
+their documentation in <literal>/usr/doc/</literal>
+instead of <literal>/usr/share/doc/</literal>.
+</para>
+<para>There are links to quite a lot of documentation on the main Cygwin
+project web page, <ulink url="http://cygwin.com/">http://cygwin.com/</ulink>,
+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.
+</para>
+<para>There is a comprehensive 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>
+and an API Reference at <ulink
+url="http://cygwin.com/cygwin-api/cygwin-api.html">http://cygwin.com/cygwin-api/cygwin-api.html</ulink>.
+</para>
+<para>You can find documentation for the individual GNU tools at <ulink
+url="http://www.fsf.org/manual/">http://www.fsf.org/manual/</ulink>. (You
+should read GNU manuals from a local mirror, check <ulink
+url="http://www.fsf.org/server/list-mirrors.html">http://www.fsf.org/server/list-mirrors.html</ulink>
+for a list of them.)
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.resources.mailing-lists">
+<question><para>What Cygwin mailing lists can I join?</para></question>
+<answer>
+
+<para>Comprehensive information about the Cygwin mailing lists can be found at
+<ulink url="http://cygwin.com/lists.html">http://cygwin.com/lists.html</ulink>.
+</para>
+<para>To subscribe to the main list, send a message to
+cygwin-subscribe@cygwin.com. To unsubscribe from the
+main list, send a message to cygwin-unsubscribe@cygwin.com.
+In both cases, the subject and body of the message are ignored.
+</para>
+<para>Similarly, to subscribe to the Cygwin announcements list, send a message
+to cygwin-announce-subscribe@cygwin.com. To unsubscribe,
+send a message to cygwin-announce-unsubscribe@cygwin.com.
+</para>
+<para>If you want to contribe to Cygwin tools & applications, rather than
+the library itself, then you should subscribe to cygwin-apps. There
+is also a low-volume list called cygwin-developers which is reserved
+for knowledgeable people who regularly contribute to the Cygwin DLL.
+Please do not ask for read-only access to this mailing list. Both
+cygwin-developers and cygwin-apps are by-approval lists. The same
+mechanism as described for the first two lists works for these as
+well.
+</para>
+<para>There is a searchable archive of the main mailing list at
+<ulink url="http://cygwin.com/ml/cygwin/">http://cygwin.com/ml/cygwin/</ulink>. There is an alternate
+archive, also searchable, at <ulink url="http://www.delorie.com/archives/">http://www.delorie.com/archives/</ulink>.
+You can also search at <ulink url="http://www.google.com/">http://www.google.com/</ulink> and include
+"cygwin" in the list of search terms.
+</para>
+<para>Cygwin mailing lists are not gatewayed to USENET, so anti-spam measures
+in your email address are neither required nor appreciated. Also, avoid
+sending HTML content to Cygwin mailing lists.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.resources.posting">
+<question><para>Posting Guidelines (Or: Why won't you/the mailing list answer my questions?)</para></question>
+<answer>
+
+<para>If you follow these guidelines, you are much more likely to get a
+helpful response from the Cygwin developers and/or the Cygwin community at
+large:
+</para>
+<itemizedlist><listitem><para>Read the User's Guide and the FAQ first.
+</para></listitem>
+<listitem><para>Check the mailing list archives. Your topic may have come up
+before. (It may even have been answered!) Use the search facilities
+at the links above. Try the alternate site if the main archive is not
+producing search results.
+</para></listitem>
+<listitem><para>Explain your problem carefully and completely. "I installed Blah
+and it doesn't work!" wastes everybody's time. It provides no
+information for anyone to help you with your problem. You should
+provide:
+</para>
+<itemizedlist><listitem><para>A problem statement: How does it behave, how do you think it
+should behave, and what makes you think it's broken? (Oh yeah, and what
+is <emphasis>"it"</emphasis>?)
+</para></listitem>
+<listitem><para>Information about your Windows OS ("Win95 OSR2" or "NT4/SP3" or
+"Win2K" or "Win98 SE" or ...).
+</para></listitem>
+<listitem><para>Details about your installation process, or attempts at same. (Internet or
+Directory install? If the former, exactly when and from what mirror?
+If the latter, which packages did you download? Which version of
+setup.exe? Any subsequent updates?)
+</para></listitem>
+<listitem><para>Details about your Cygwin setup, accomplished by <emphasis>attaching</emphasis>
+the output of 'cygcheck -s -v -r' to your message. (Do not paste the
+output into your message.)
+</para></listitem>
+<listitem><para>A valid return address, so that a reply doesn't require manual editing of
+the 'To:' header.
+</para></listitem>
+</itemizedlist>
+
+</listitem>
+<listitem><para>Your message must be relevant to the list. Messages that are
+<emphasis>not</emphasis> directly related to Cygwin are considered off-topic and are
+unwelcome. For example, the following are off-topic:
+</para>
+<itemizedlist><listitem><para>General programming language questions
+</para></listitem>
+<listitem><para>General Windows programming questions
+</para></listitem>
+<listitem><para>General UNIX shell programming questions
+</para></listitem>
+<listitem><para>General application usage questions
+</para></listitem>
+<listitem><para>How to make millions by working at home
+</para></listitem>
+<listitem><para>Announcements from LaserJet toner cartridge suppliers
+</para></listitem>
+</itemizedlist>
+
+</listitem>
+<listitem><para>Read and obey ``How To Ask Questions The Smart Way'' by Eric
+S. Raymond, at <ulink url="http://www.catb.org/~esr/faqs/smart-questions.html">http://www.catb.org/~esr/faqs/smart-questions.html</ulink>.
+</para>
+</listitem>
+</itemizedlist>
+
+<para>If you do not follow the above guidelines, you may still elicit a
+response, but you may not appreciate it!
+</para>
+<para>For inquiries about support contracts and commercial licensing, visit
+<ulink url="http://www.redhat.com/software/cygwin/">http://www.redhat.com/software/cygwin/</ulink>.
+</para>
+<para>Beyond that, perhaps nobody has time to answer your question. Perhaps
+nobody knows the answer.
+</para>
+</answer></qandaentry>
+
--- /dev/null
+<?xml version='1.0'?>
+<!DOCTYPE article PUBLIC '-//OASIS//DTD DocBook XML V4.2//EN'
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+ <!-- see http://www.unicode.org/charts/PDF/U0080.pdf -->
+ <!ENTITY pound "£">
+ <!ENTITY brokenpipe "¦">
+
+ <!-- all the files -->
+ <!ENTITY FAQ-WHAT SYSTEM "faq-what.xml">
+ <!ENTITY FAQ-SETUP SYSTEM "faq-setup.xml">
+ <!ENTITY FAQ-RESOURCES SYSTEM "faq-resources.xml">
+ <!ENTITY FAQ-USING SYSTEM "faq-using.xml">
+ <!ENTITY FAQ-API SYSTEM "faq-api.xml">
+ <!ENTITY FAQ-PROGRAMMING SYSTEM "faq-programming.xml">
+ <!ENTITY FAQ-PROBLEMS SYSTEM "faq-problems.xml">
+]>
+
+<article id="faq" lang="en">
+ <articleinfo>
+ <title>Cygwin FAQ</title>
+ </articleinfo>
+
+<sect1 id="faq.about">
+<title>About Cygwin</title>
+<qandaset><?dbhtml toc="1"?>
+&FAQ-WHAT;
+</qandaset></sect1>
+
+<sect1 id="faq.setup">
+<title>Setting up Cygwin</title>
+<qandaset><?dbhtml toc="1"?>
+&FAQ-SETUP;
+</qandaset></sect1>
+
+<sect1 id="faq.resources">
+<title>Further Resources</title>
+<qandaset><?dbhtml toc="1"?>
+&FAQ-RESOURCES;
+</qandaset></sect1>
+
+<sect1 id="faq.using">
+<title>Using Cygwin</title>
+<qandaset><?dbhtml toc="1"?>
+&FAQ-USING;
+</qandaset></sect1>
+
+<sect1 id="faq.api">
+<title>Cygwin API Questions</title>
+<qandaset><?dbhtml toc="1"?>
+&FAQ-API;
+</qandaset></sect1>
+
+<sect1 id="faq.programming">
+<title>Programming Questions</title>
+<qandaset><?dbhtml toc="1"?>
+&FAQ-PROGRAMMING;
+</qandaset></sect1>
+
+<sect1 id="faq.known-problems">
+<title>Known Problems in the Latest Net Release</title>
+<qandaset><?dbhtml toc="1"?>
+&FAQ-PROBLEMS;
+</qandaset></sect1>
+
+<sect1 id="faq.copyright">
+<title>Copyright</title>
+<qandaset><?dbhtml toc="1"?>
+
+
+<qandaentry id="faq.what.copyright">
+<question><para>What are the copyrights ?</para></question>
+<answer>
+
+<para>The general idea</para>
+
+<para>Most of the tools are covered by the GNU General Public License (GPL),
+although some are public domain, and others have a X11-style
+copyright. To cover the GNU GPL requirements, the basic rule is if
+you give out any binaries, you must also make the source available.
+For the full details, be sure to read the text of the GNU GPL which
+follows.
+</para>
+<para>The Cygwin API library found in the winsup subdirectory of the source
+code is also covered by the GNU GPL. By default, all executables link
+against this library (and in the process include GPL'd Cygwin glue
+code). This means that unless you modify the tools so that compiled
+executables do not make use of the Cygwin library, your compiled
+programs will also have to be free software distributed under the GPL
+with source code available to all.
+</para>
+<para>Cygwin is currently available for proprietary use only through a
+proprietary-use license. Please see
+<ulink url="http://www.redhat.com/software/cygwin/">http://www.redhat.com/software/cygwin/</ulink> for more information
+about the Red Hat Cygwin Product.
+</para>
+<para>In accordance with section 10 of the GPL, Red Hat, Inc. permits
+programs whose sources are distributed under a license that complies
+with the Open Source definition to be linked with libcygwin.a without
+libcygwin.a itself causing the resulting program to be covered by the
+GNU GPL.
+</para>
+<para>This means that you can port an Open Source(tm) application to cygwin,
+and distribute that executable as if it didn't include a copy of
+libcygwin.a linked into it. Note that this does not apply to the
+cygwin DLL itself. If you distribute a (possibly modified) version of
+the DLL you must adhere to the terms of the GPL, i.e., you must
+provide sources for the cygwin DLL.
+</para>
+<para>See <ulink url="http://www.opensource.org/docs/definition_plain.html">http://www.opensource.org/docs/definition_plain.html</ulink> for
+the precise Open Source Definition referenced above.
+</para>
+
+<para>GNU GENERAL PUBLIC LICENSE</para>
+<screen>
+ GNU GENERAL PUBLIC LICENSE
+ Version 2, June 1991
+
+ Copyright (C) 1989, 1991 Free Software Foundation, Inc.
+ 675 Mass Ave, Cambridge, MA 02139, USA
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+ Preamble
+
+ The licenses for most software are designed to take away your
+freedom to share and change it. By contrast, the GNU General Public
+License is intended to guarantee your freedom to share and change free
+software--to make sure the software is free for all its users. This
+General Public License applies to most of the Free Software
+Foundation's software and to any other program whose authors commit to
+using it. (Some other Free Software Foundation software is covered by
+the GNU Library General Public License instead.) You can apply it to
+your programs, too.
+
+ When we speak of free software, we are referring to freedom, not
+price. Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+this service if you wish), that you receive source code or can get it
+if you want it, that you can change the software or use pieces of it
+in new free programs; and that you know you can do these things.
+
+ To protect your rights, we need to make restrictions that forbid
+anyone to deny you these rights or to ask you to surrender the rights.
+These restrictions translate to certain responsibilities for you if you
+distribute copies of the software, or if you modify it.
+
+ For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must give the recipients all the rights that
+you have. You must make sure that they, too, receive or can get the
+source code. And you must show them these terms so they know their
+rights.
+
+ We protect your rights with two steps: (1) copyright the software, and
+(2) offer you this license which gives you legal permission to copy,
+distribute and/or modify the software.
+
+ Also, for each author's protection and ours, we want to make certain
+that everyone understands that there is no warranty for this free
+software. If the software is modified by someone else and passed on, we
+want its recipients to know that what they have is not the original, so
+that any problems introduced by others will not reflect on the original
+authors' reputations.
+
+ Finally, any free program is threatened constantly by software
+patents. We wish to avoid the danger that redistributors of a free
+program will individually obtain patent licenses, in effect making the
+program proprietary. To prevent this, we have made it clear that any
+patent must be licensed for everyone's free use or not licensed at all.
+
+ The precise terms and conditions for copying, distribution and
+modification follow.
+
+ GNU GENERAL PUBLIC LICENSE
+ TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+ 0. This License applies to any program or other work which contains
+a notice placed by the copyright holder saying it may be distributed
+under the terms of this General Public License. The "Program", below,
+refers to any such program or work, and a "work based on the Program"
+means either the Program or any derivative work under copyright law:
+that is to say, a work containing the Program or a portion of it,
+either verbatim or with modifications and/or translated into another
+language. (Hereinafter, translation is included without limitation in
+the term "modification".) Each licensee is addressed as "you".
+
+Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope. The act of
+running the Program is not restricted, and the output from the Program
+is covered only if its contents constitute a work based on the
+Program (independent of having been made by running the Program).
+Whether that is true depends on what the Program does.
+
+ 1. You may copy and distribute verbatim copies of the Program's
+source code as you receive it, in any medium, provided that you
+conspicuously and appropriately publish on each copy an appropriate
+copyright notice and disclaimer of warranty; keep intact all the
+notices that refer to this License and to the absence of any warranty;
+and give any other recipients of the Program a copy of this License
+along with the Program.
+
+You may charge a fee for the physical act of transferring a copy, and
+you may at your option offer warranty protection in exchange for a fee.
+
+ 2. You may modify your copy or copies of the Program or any portion
+of it, thus forming a work based on the Program, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you also meet all of these conditions:
+
+ a) You must cause the modified files to carry prominent notices
+ stating that you changed the files and the date of any change.
+
+ b) You must cause any work that you distribute or publish, that in
+ whole or in part contains or is derived from the Program or any
+ part thereof, to be licensed as a whole at no charge to all third
+ parties under the terms of this License.
+
+ c) If the modified program normally reads commands interactively
+ when run, you must cause it, when started running for such
+ interactive use in the most ordinary way, to print or display an
+ announcement including an appropriate copyright notice and a
+ notice that there is no warranty (or else, saying that you provide
+ a warranty) and that users may redistribute the program under
+ these conditions, and telling the user how to view a copy of this
+ License. (Exception: if the Program itself is interactive but
+ does not normally print such an announcement, your work based on
+ the Program is not required to print an announcement.)
+
+These requirements apply to the modified work as a whole. If
+identifiable sections of that work are not derived from the Program,
+and can be reasonably considered independent and separate works in
+themselves, then this License, and its terms, do not apply to those
+sections when you distribute them as separate works. But when you
+distribute the same sections as part of a whole which is a work based
+on the Program, the distribution of the whole must be on the terms of
+this License, whose permissions for other licensees extend to the
+entire whole, and thus to each and every part regardless of who wrote it.
+
+Thus, it is not the intent of this section to claim rights or contest
+your rights to work written entirely by you; rather, the intent is to
+exercise the right to control the distribution of derivative or
+collective works based on the Program.
+
+In addition, mere aggregation of another work not based on the Program
+with the Program (or with a work based on the Program) on a volume of
+a storage or distribution medium does not bring the other work under
+the scope of this License.
+
+ 3. You may copy and distribute the Program (or a work based on it,
+under Section 2) in object code or executable form under the terms of
+Sections 1 and 2 above provided that you also do one of the following:
+
+ a) Accompany it with the complete corresponding machine-readable
+ source code, which must be distributed under the terms of Sections
+ 1 and 2 above on a medium customarily used for software interchange; or,
+
+ b) Accompany it with a written offer, valid for at least three
+ years, to give any third party, for a charge no more than your
+ cost of physically performing source distribution, a complete
+ machine-readable copy of the corresponding source code, to be
+ distributed under the terms of Sections 1 and 2 above on a medium
+ customarily used for software interchange; or,
+
+ c) Accompany it with the information you received as to the offer
+ to distribute corresponding source code. (This alternative is
+ allowed only for noncommercial distribution and only if you
+ received the program in object code or executable form with such
+ an offer, in accord with Subsection b above.)
+
+The source code for a work means the preferred form of the work for
+making modifications to it. For an executable work, complete source
+code means all the source code for all modules it contains, plus any
+associated interface definition files, plus the scripts used to
+control compilation and installation of the executable. However, as a
+special exception, the source code distributed need not include
+anything that is normally distributed (in either source or binary
+form) with the major components (compiler, kernel, and so on) of the
+operating system on which the executable runs, unless that component
+itself accompanies the executable.
+
+If distribution of executable or object code is made by offering
+access to copy from a designated place, then offering equivalent
+access to copy the source code from the same place counts as
+distribution of the source code, even though third parties are not
+compelled to copy the source along with the object code.
+
+ 4. You may not copy, modify, sublicense, or distribute the Program
+except as expressly provided under this License. Any attempt
+otherwise to copy, modify, sublicense or distribute the Program is
+void, and will automatically terminate your rights under this License.
+However, parties who have received copies, or rights, from you under
+this License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+ 5. You are not required to accept this License, since you have not
+signed it. However, nothing else grants you permission to modify or
+distribute the Program or its derivative works. These actions are
+prohibited by law if you do not accept this License. Therefore, by
+modifying or distributing the Program (or any work based on the
+Program), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying
+the Program or works based on it.
+
+ 6. Each time you redistribute the Program (or any work based on the
+Program), the recipient automatically receives a license from the
+original licensor to copy, distribute or modify the Program subject to
+these terms and conditions. You may not impose any further
+restrictions on the recipients' exercise of the rights granted herein.
+You are not responsible for enforcing compliance by third parties to
+this License.
+
+ 7. If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License. If you cannot
+distribute so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you
+may not distribute the Program at all. For example, if a patent
+license would not permit royalty-free redistribution of the Program by
+all those who receive copies directly or indirectly through you, then
+the only way you could satisfy both it and this License would be to
+refrain entirely from distribution of the Program.
+
+If any portion of this section is held invalid or unenforceable under
+any particular circumstance, the balance of the section is intended to
+apply and the section as a whole is intended to apply in other
+circumstances.
+
+It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system, which is
+implemented by public license practices. Many people have made
+generous contributions to the wide range of software distributed
+through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing
+to distribute software through any other system and a licensee cannot
+impose that choice.
+
+This section is intended to make thoroughly clear what is believed to
+be a consequence of the rest of this License.
+
+ 8. If the distribution and/or use of the Program is restricted in
+certain countries either by patents or by copyrighted interfaces, the
+original copyright holder who places the Program under this License
+may add an explicit geographical distribution limitation excluding
+those countries, so that distribution is permitted only in or among
+countries not thus excluded. In such case, this License incorporates
+the limitation as if written in the body of this License.
+
+ 9. The Free Software Foundation may publish revised and/or new versions
+of the General Public License from time to time. Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+Each version is given a distinguishing version number. If the Program
+specifies a version number of this License which applies to it and "any
+later version", you have the option of following the terms and conditions
+either of that version or of any later version published by the Free
+Software Foundation. If the Program does not specify a version number of
+this License, you may choose any version ever published by the Free Software
+Foundation.
+
+ 10. If you wish to incorporate parts of the Program into other free
+programs whose distribution conditions are different, write to the author
+to ask for permission. For software which is copyrighted by the Free
+Software Foundation, write to the Free Software Foundation; we sometimes
+make exceptions for this. Our decision will be guided by the two goals
+of preserving the free status of all derivatives of our free software and
+of promoting the sharing and reuse of software generally.
+
+ NO WARRANTY
+
+ 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
+FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
+OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
+PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
+OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
+TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
+PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
+REPAIR OR CORRECTION.
+
+ 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
+REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
+INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
+OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
+TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
+YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
+PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGES.
+
+ END OF TERMS AND CONDITIONS
+
+ Appendix: How to Apply These Terms to Your New Programs
+
+ If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+ To do so, attach the following notices to the program. It is safest
+to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+ <one line to give the program's name and a brief idea of what it does.>
+ Copyright (C) 19yy <name of author>
+
+ This program is free software; you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation; either version 2 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License
+ along with this program; if not, write to the Free Software
+ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+
+Also add information on how to contact you by electronic and paper mail.
+
+If the program is interactive, make it output a short notice like this
+when it starts in an interactive mode:
+
+ Gnomovision version 69, Copyright (C) 19yy name of author
+ Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+ This is free software, and you are welcome to redistribute it
+ under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License. Of course, the commands you use may
+be called something other than `show w' and `show c'; they could even be
+mouse-clicks or menu items--whatever suits your program.
+
+You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a "copyright disclaimer" for the program, if
+necessary. Here is a sample; alter the names:
+
+ Yoyodyne, Inc., hereby disclaims all copyright interest in the program
+ `Gnomovision' (which makes passes at compilers) written by James Hacker.
+
+ <signature of Ty Coon>, 1 April 1989
+ Ty Coon, President of Vice
+
+This General Public License does not permit incorporating your program into
+proprietary programs. If your program is a subroutine library, you may
+consider it more useful to permit linking proprietary applications with the
+library. If this is what you want to do, use the GNU Library General
+Public License instead of this License.
+
+</screen>
+
+</answer></qandaentry>
+</qandaset></sect1>
+
+</article>
--- /dev/null
+<!-- faq-setup.xml -->
+<qandaentry id="faq.setup.setup">
+<question><para>What is the recommended installation procedure?</para></question>
+<answer>
+
+<para>There is only one recommended way to install Cygwin, which is to use the GUI
+installer ``Cygwin Setup''. It is flexible and easy to use.
+You can pick and choose the packages you wish to install, and update
+them individually. Full source code is available for all packages and
+tools. More information on using Cygwin Setup may be found at
+<ulink url="http://cygwin.com/cygwin-ug-net/setup-net.html">http://cygwin.com/cygwin-ug-net/setup-net.html</ulink>.
+</para>
+<para>If you do it any other way, you're on your own! That said, keep in mind
+that the GUI installer is a "work in progress", so there might be a few
+difficulties, especially if you are behind a firewall or have other
+specific requirements. If something doesn't work right for you, and
+it's not covered here or in the latest development snapshot at
+<ulink url="http://cygwin.com/setup/">http://cygwin.com/setup/</ulink>, then by all means report it to the
+mailing list.
+</para>
+<para>For a searchable list of packages that can be installed with Cygwin,
+see <ulink url="http://cygwin.com/packages/">http://cygwin.com/packages/</ulink>.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.setup.c">
+<question><para>Why not install in C:\?</para></question>
+<answer>
+
+<para>The Cygwin Setup program will prompt you for a "root" directory.
+The default is <literal>C:\cygwin</literal>, but you can change it. You are urged not to
+choose something like <literal>C:\</literal> (the root directory on the system drive) for
+your Cygwin root. If you do, then critical Cygwin system directories
+like <literal>etc</literal>, <literal>lib</literal> and <literal>bin</literal> could easily be corrupted by
+other (non-Cygwin) applications or packages that use <literal>\etc</literal>,
+<literal>\lib</literal> or <literal>\bin</literal>. Perhaps there is no conflict now, but who
+knows what you might install in the future? It's also just good common
+sense to segregate your Cygwin "filesystems" from the rest of your
+Windows system disk.
+</para>
+<para>(In the past, there had been genuine bugs that would cause problems
+for people who installed in <literal>C:\</literal>, but we believe those are gone
+now.)
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.setup.old-versions">
+<question><para>Can I use Cygwin Setup to get old versions of packages (like gcc-2.95)?</para></question>
+<answer>
+
+<para>Cygwin Setup can be used to install any packages that are on a
+Cygwin mirror, which usually includes one version previous to the
+current one. The complete list may be searched at
+<ulink url="http://cygwin.com/packages/">http://cygwin.com/packages/</ulink>. There is no complete archive of
+older packages. If you have a problem with the current version of
+a Cygwin package, please report it to the mailing list using the
+guidelines at <ulink url="http://cygwin.com/problems.html">http://cygwin.com/problems.html</ulink>.
+</para>
+<para>That said, if you really need an older package, you may be able to find
+an outdated or archival mirror by searching the web for an old package
+version (for example, <literal>gcc2-2.95.3-10-src.tar.bz2</literal>), but keep in
+mind that this older version will not be supported by the mailing list
+and that installing the older version will not help improve Cygwin.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.setup.virus">
+<question><para>Is Cygwin Setup, or one of the packages, infected with a virus?</para></question>
+<answer>
+
+<para>Unlikely. Unless you can confirm it, please don't report it to the
+mailing list. Anti-virus products have been known to detect false
+positives when extracting compressed tar archives. If this causes
+problems for you, consider disabling your anti-virus software when
+running <literal>setup</literal>. Read the next entry for a fairly safe way to do
+this.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.setup.hang">
+<question><para>My computer hangs when I run Cygwin Setup!</para></question>
+<answer>
+
+<para>Both Network Associates (formerly McAfee) and Norton anti-virus
+products have been reported to "hang" when extracting Cygwin tar
+archives. If this happens to you, consider disabling your anti-virus
+software when running Cygwin Setup. The following procedure should be
+a fairly safe way to do that:
+</para>
+<orderedlist><listitem><para>Download <literal>setup.exe</literal> and scan it explicitly.
+</para>
+</listitem>
+<listitem><para>Turn off the anti-virus software.
+</para>
+</listitem>
+<listitem><para>Run setup to download and extract all the tar files.
+</para>
+</listitem>
+<listitem><para>Re-activate your anti-virus software and scan everything
+in C:\cygwin (or wherever you chose to install), or your entire hard
+disk if you are paranoid.
+</para>
+</listitem>
+</orderedlist>
+
+<para>This should be safe, but only if Cygwin Setup is not substituted by
+something malicious, and no mirror has been compromised.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.setup.what-packages">
+<question><para>What packages should I download? Where are 'make', 'gcc', 'vi', etc? </para></question>
+<answer>
+<para>When using Cygwin Setup for the first time, the default is to install
+a minimal subset of packages. If you want anything beyond that, you
+will have to select it explicitly. See
+<ulink url="http://cygwin.com/packages/">http://cygwin.com/packages/</ulink> for a searchable list of available
+packages.
+</para>
+<para>If you want to build programs, of course you'll need <literal>gcc</literal>,
+<literal>binutils</literal>, <literal>make</literal> and probably other packages from the
+``Devel'' category. Text editors can be found under ``Editors''.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.setup.everything">
+<question><para>How do I just get everything?</para></question>
+<answer>
+
+<para>Long ago, the default was to install everything, much to the
+irritation of most users. Now the default is to install only a basic
+core of packages. Cygwin Setup is designed to make it easy to browse
+categories and select what you want to install or omit from those
+categories. It's also easy to install everything:
+</para>
+<orderedlist>
+<listitem><para>At the ``Select Packages'' screen, in ``Categories'' view, at the line
+marked ``All'', click on the word ``default'' so that it changes to
+``install''. (Be patient, there is some computing to do at this step.
+It may take a second or two to register the change.) This tells Setup
+to install <emphasis>everything</emphasis>, not just what it thinks you should have
+by default.
+</para>
+</listitem>
+<listitem><para>Now click on the ``View'' button (twice) until you get the
+``Partial'' view. This shows exactly which packages are about to be
+downloaded and installed.
+</para>
+</listitem>
+</orderedlist>
+
+<para>This procedure only works for packages that are currently available.
+There is no way to tell Cygwin Setup to install all packages by
+default from now on. As new packages become available that would not
+be installed by default, you have to repeat the above procedure to get
+them.
+</para>
+<para>In general, a better method (in my opinion), is to:
+</para>
+<orderedlist>
+<listitem><para>First download & install all packages that would normally be
+installed by default. This includes fundamental packages and any
+updates to what you have already installed. Then...
+</para>
+</listitem>
+<listitem><para>Run Cygwin Setup again, and apply the above technique to get all
+new packages that would not be installed by default. You can check
+the list in the Partial View before proceeding, in case there's
+something you really <emphasis>don't</emphasis> want.
+</para>
+</listitem>
+<listitem><para>In the latest version of Cygwin Setup, if you click the ``View''
+button (twice) more, it shows packages not currently installed. You
+ought to check whether you <emphasis>really</emphasis> want to install everything!
+</para>
+</listitem>
+</orderedlist>
+
+</answer></qandaentry>
+
+<qandaentry id="faq.setup.disk-space">
+<question><para>How much disk space does Cygwin require?</para></question>
+<answer>
+
+<para>That depends, obviously, on what you've chosen to download and
+install. A full installation today is probably larger than 800MB
+installed, not including the package archives themselves nor the source
+code.
+</para>
+<para>After installation, the package archives remain in your ``Local
+Package Directory'', by default the location of <literal>setup.exe</literal>. You
+may conserve disk space by deleting the subdirectories there. These
+directories will have very weird looking names, being encoded with
+their URLs.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.setup.what-upgraded">
+<question><para>How do I know which version I upgraded from?</para></question>
+<answer>
+
+<para>Detailed logs of the most recent Cygwin Setup session can be found in
+<literal>/var/log/setup.log.full</literal> and less verbose information about
+prior actions is in <literal>/var/log/setup.log</literal>.
+</para>
+
+</answer></qandaentry>
+
+<qandaentry id="faq.setup.setup-fails">
+<question><para>What if setup fails?</para></question>
+<answer>
+
+<para>First, make sure that you are using the latest version of Cygwin Setup.
+The latest version is always available from the 'Install Cygwin now' link on
+the Cygwin Home Page at <ulink
+url="http://cygwin.com/">http://cygwin.com/</ulink>. </para>
+<para>If you are downloading from the Internet, setup will fail if it cannot
+download the list of mirrors at <ulink
+url="http://cygwin.com/mirrors.html">http://cygwin.com/mirrors.html</ulink>.
+It could be that the network is too busy. Something similar could be the
+cause of a download site not working. Try another mirror, or try again
+later.
+</para>
+<para>If setup refuses to download a package that you know needs to be
+upgraded, try deleting that package's entry from /etc/setup. If you are
+reacting quickly to an announcement on the mailing list, it could be
+that the mirror you are using doesn't have the latest copy yet. Try
+another mirror, or try again tomorrow.
+</para>
+<para>If setup has otherwise behaved strangely, check the files
+<literal>setup.log</literal> and <literal>setup.log.full</literal> in
+<literal>/var/log</literal> (<literal>C:\cygwin\var\log</literal> by
+default). It may provide some clues as to what went wrong and why.
+</para>
+<para>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 mailing
+list. You must provide complete details in your query: version of
+setup, options you selected, contents of setup.log and setup.log.full,
+what happened that wasn't supposed to happen, etc.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.setup.name-with-space">
+<question><para>My Windows logon name has a space in it, will this cause problems?</para></question>
+<answer>
+
+<para>Most definitely yes! UNIX shells (and thus Cygwin) use the space
+character as a word delimiter. Under certain circumstances, it is
+possible to get around this with various shell quoting mechanisms, but
+you are much better off if you can avoid the problem entirely.
+</para>
+<para>On Windows NT/2000/XP you have two choices:
+</para><orderedlist>
+<listitem><para>You can rename the user in the Windows User Manager GUI and then
+run mkpasswd.
+</para>
+</listitem>
+<listitem><para>You can simply edit the /etc/passwd file and change the Cygwin user name
+(first field). It's also a good idea to avoid spaces in the home directory.
+</para>
+</listitem>
+</orderedlist>
+
+<para>On Windows 95/98/ME you can create a new user and run mkpasswd,
+or you can delete the offending entry from /etc/passwd.
+Cygwin will then use the name in the default entry with uid 500.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.setup.home">
+<question><para>My <literal>HOME</literal> environment variable is not what I want.</para></question>
+<answer>
+
+<para>When starting Cygwin from Windows, <literal>HOME</literal> is determined as follows
+in order of decreasing priority:
+</para>
+<orderedlist>
+<listitem><para><literal>HOME</literal> from the Windows environment, translated to POSIX form.
+</para>
+</listitem>
+<listitem><para>The entry in /etc/passwd
+</para>
+</listitem>
+<listitem><para><literal>HOMEDRIVE</literal> and <literal>HOMEPATH</literal> from the Windows environment
+</para>
+</listitem>
+<listitem><para>/
+</para>
+</listitem>
+</orderedlist>
+
+<para>When using Cygwin from the network (telnet, ssh,...), <literal>HOME</literal> is set
+from /etc/passwd.
+</para>
+<para>If your <literal>HOME</literal> 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.
+</para>
+<para>Access to shared drives is often restricted when starting from the network,
+thus Domain users may wish to have a different <literal>HOME</literal> in the
+Windows environment (on shared drive) than in /etc/passwd (on local drive).
+Note that ssh only considers /etc/passwd, disregarding <literal>HOME</literal>.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.setup.uninstall-packages">
+<question><para>How do I uninstall individual packages?</para></question>
+<answer>
+
+<para>Run Cygwin Setup as you would to install packages. In the list of
+packages to install, browse the relevant category or click on the
+``View'' button to get a full listing. Click on the cycle glyph until
+the action reads ``Uninstall''. Proceed by clicking ``Next''.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.setup.uninstall-all">
+<question><para>How do I uninstall <emphasis role='bold'>all</emphasis> of Cygwin?</para></question>
+<answer>
+
+<para>Setup has no automatic uninstall facility. The recommended method to remove all
+of Cygwin is as follows:
+</para>
+<orderedlist>
+<listitem><para>Remove all Cygwin services. If a service is currently running, it must
+first be stopped with <literal>cygrunsrv -E name</literal>, where <literal>name</literal>
+is the name of the service. Then use <literal>cygrunsrv -R name</literal> to uninstall the
+service from the registry. Repeat this for all services that you installed.
+Common services that might have been installed are <literal>sshd</literal>, <literal>cron</literal>,
+<literal>cygserver</literal>, <literal>inetd</literal>, <literal>apache</literal>, and so on.
+</para>
+</listitem>
+<listitem><para>Stop the X11 server if it is running, and terminate any Cygwin programs
+that might be running in the background. Remove all mount information by typing
+<literal>umount -A</literal> and then exit the command prompt and ensure that no Cygwin
+processes remain. Note: If you want to save your mount points for a later
+reinstall, first save the output of <literal>mount -m</literal> as described at
+<ulink url="http://cygwin.com/cygwin-ug-net/using-utils.html#mount">http://cygwin.com/cygwin-ug-net/using-utils.html#mount</ulink>.
+</para>
+</listitem>
+<listitem><para>Delete the Cygwin root folder and all subfolders. If you get an error
+that an object is in use, then ensure that you've stopped all services and
+closed all Cygwin programs. If you get a 'Permission Denied' error then you
+will need to modify the permissions and/or ownership of the files or folders
+that are causing the error. For example, sometimes files used by system
+services end up owned by the SYSTEM account and not writable by regular users.
+</para>
+<para>The quickest way to delete the entire tree if you run into this problem is to
+change the ownership of all files and folders to your account. To do this in
+Windows Explorer, right click on the root Cygwin folder, choose Properties, then
+the Security tab. Select Advanced, then go to the Owner tab and make sure your
+account is listed as the owner. Select the 'Replace owner on subcontainers and
+objects' checkbox and press Ok. After Explorer applies the changes you should
+be able to delete the entire tree in one operation. Note that you can also
+achieve this in Cygwin by typing <literal>chown -R user /</literal> or by using other tools
+such as CACLS.EXE.
+</para>
+</listitem>
+<listitem><para>Delete the Cygwin shortcuts on the Desktop and Start Menu, and anything
+left by setup.exe in the download directory. However, if you plan to reinstall
+Cygwin it's a good idea to keep your setup.exe download directory since you can
+reinstall the packages left in its cache without redownloading them.
+</para>
+</listitem>
+<listitem><para>If you added Cygwin to your system path, you should remove it unless you
+plan to reinstall Cygwin to the same location. Similarly, if you set your
+CYGWIN environment variable system-wide and don't plan to reinstall, you should
+remove it.
+</para>
+</listitem>
+<listitem><para>Finally, if you want to be thorough you can delete the registry tree
+<literal>Software\Cygnus Solutions</literal> under <literal>HKEY_LOCAL_MACHINE</literal> and/or
+<literal>HKEY_CURRENT_USER</literal>. However, if you followed the directions above you
+will have already removed all the mount information which is typically the only
+thing stored in the registry.
+</para>
+</listitem>
+</orderedlist>
+
+</answer></qandaentry>
+
+<qandaentry id="faq.setup.snapshots">
+<question><para>How do I install snapshots?</para></question>
+<answer>
+
+<para>First, are you sure you want to do this? Snapshots are risky. They
+have not been tested. Use them <emphasis role='bold'>only</emphasis> if there is a feature or
+bugfix that you need to try, and you are willing to deal with any
+problems.
+</para>
+<para>Before installing a snapshot, you must first Close <emphasis role='bold'>all</emphasis> Cygwin
+applications, including shells and services (e.g. inetd, sshd), before
+updating <literal>cygwin1.dll</literal>. You may have to restart Windows to clear
+the DLL from memory.
+</para>
+<para>You cannot use Setup to install a snapshot.
+</para>
+<para>You should generally install the full
+<literal>cygwin-inst-YYYYMMDD.tar.bz2</literal> update, rather than just the DLL,
+otherwise some components may be out of sync. Cygwin tar won't be
+able to update <literal>/usr/bin/cygwin1.dll</literal>, but it should succeed with
+everything else.
+</para>
+<orderedlist>
+<listitem><para>Download the snapshot, and run:
+<screen>
+ cd /
+ tar jxvf /posix/path/to/cygwin-inst-YYYYMMDD.tar.bz2 --exclude=usr/bin/cygwin1.dll
+ cd /tmp
+ tar jxvf /posix/path/to/cygwin-inst-YYYYMMDD.tar.bz2 usr/bin/cygwin1.dll
+</screen>
+</para>
+</listitem>
+<listitem><para>After closing all Cygwin apps (see above), use Explorer or the
+Windows command shell to move <literal>C:\cygwin\tmp\usr\bin\cygwin1.dll</literal>
+to <literal>C:\cygwin\bin\cygwin1.dll</literal>.
+</para>
+</listitem>
+</orderedlist>
+
+</answer></qandaentry>
+
+<qandaentry id="faq.setup.mirror">
+<question><para>Can Cygwin Setup maintain a ``mirror''?</para></question>
+<answer>
+
+<para>NO. Cygwin Setup cannot do this for you. Use a tool designed for
+this purpose. See <ulink url="http://rsync.samba.org/">http://rsync.samba.org/</ulink>,
+<ulink url="http://wget.sunsite.dk/">http://wget.sunsite.dk/</ulink> for utilities that can do this for you.
+For more information on setting up a custom Cygwin package server, see
+the Cygwin Setup homepage at
+<ulink url="http://sources.redhat.com/cygwin-apps/setup.html">http://sources.redhat.com/cygwin-apps/setup.html</ulink>.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.setup.cd">
+<question><para>How can I make my own portable Cygwin on CD?</para></question>
+<answer>
+
+<para>While some users have successfully done this, for example Indiana
+University's XLiveCD <ulink url="http://xlivecd.indiana.edu/">http://xlivecd.indiana.edu/</ulink>, there is no
+easy way to do it. Full instructions for constructing a porttable Cygwin
+on CD by hand can be found on the mailing list at
+<ulink url="http://www.cygwin.com/ml/cygwin/2003-07/msg01117.html">http://www.cygwin.com/ml/cygwin/2003-07/msg01117.html</ulink>. (Thanks
+to fergus at bonhard dot uklinux dot net for these instructions.)
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.setup.registry">
+<question><para>How do I save, restore, delete, or modify the Cygwin information stored in the registry?</para></question>
+<answer>
+
+<para>Currently Cygwin stores its mount table information in the registry. It
+is recommended that you use the <literal>mount</literal> and <literal>umount</literal> commands
+to manipulate the mount information instead of directly modifying the
+registry.
+</para>
+<para>To save the mount information to a file for later restoration, use
+<literal>mount -m > mounts.bat</literal> To remove all mount information use
+<literal>umount -A</literal>. To reincorporate saved mount information just run the
+batch file. For more information on using <literal>mount</literal>, see
+<ulink url="http://cygwin.com/cygwin-ug-net/using-utils.html#mount">http://cygwin.com/cygwin-ug-net/using-utils.html#mount</ulink>.
+</para></answer></qandaentry>
+
--- /dev/null
+<!-- 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 < 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 > //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 (£äö) 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
+<drive>:/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-<ver>.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>
+
--- /dev/null
+<!-- faq-what.xml -->
+<qandaentry id="faq.what">
+<question><para>What is it?</para></question>
+<answer>
+
+<para>The Cygwin tools are ports of the popular GNU development tools for
+Microsoft Windows. They run thanks to the Cygwin library which
+provides the UNIX system calls and environment these programs expect.
+</para>
+<para>With these tools installed, it is possible to write Win32 console or
+GUI applications that make use of the standard Microsoft Win32 API
+and/or the Cygwin API. As a result, it is possible to easily
+port many significant Unix programs without the need
+for extensive changes to the source code. This includes configuring
+and building most of the available GNU software (including the packages
+included with the Cygwin development tools themselves). Even if
+the development tools are of little to no use to you, you may have
+interest in the many standard Unix utilities provided with the package.
+They can be used both from the bash shell (provided) or from the
+standard Windows command shell.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.what.supported">
+<question><para>What versions of Windows are supported?</para></question>
+<answer>
+
+<para>Wait a minute... Cygwin is only <emphasis>supported</emphasis> if you are paying for
+it, such as through a support contract with Red Hat. For information
+about getting a Red Hat support contract, see
+<ulink url="http://www.redhat.com/software/tools/cygwin/">http://www.redhat.com/software/tools/cygwin/</ulink>.
+</para>
+<para>That said, Cygwin can be expected to run on all modern 32 bit versions of
+Windows, except Windows CE. This includes Windows 95/98/ME/NT/2000/XP.
+</para>
+<para>Keep in mind that Cygwin can only do as much as the underlying OS
+supports. Because of this, Cygwin will behave differently, and
+exhibit different limitations, on the various versions of Windows.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.what.where">
+<question><para>Where can I get it?</para></question>
+<answer>
+
+<para>The home page for the Cygwin project is <ulink url="http://cygwin.com/">http://cygwin.com/</ulink>.
+There you should find everything you need for Cygwin, including links
+for download and setup, a current list of mirror sites, a User's
+Guide, an API Reference, mailing lists and archives, and additional
+ported software.
+</para>
+<para>You can find documentation for the individual GNU tools at
+<ulink url="http://www.fsf.org/manual/">http://www.fsf.org/manual/</ulink>. (You should read GNU manuals from a
+local mirror. Check <ulink url="http://www.fsf.org/server/list-mirrors.html">http://www.fsf.org/server/list-mirrors.html</ulink>
+for a list of them.)
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.what.free">
+<question><para>Is it free software?</para></question>
+<answer>
+
+<para>Yes. Parts are GNU software (gcc, gas, ld, etc...), parts are covered
+by the standard X11 license, some of it is public domain, some of
+it was written by Cygnus and placed under the GPL. None of it is
+shareware. You don't have to pay anyone to use it but you should be
+sure to read the copyright section of the FAQ for more information on
+how the GNU General Public License may affect your use of these tools.
+</para>
+<para>In particular, if you intend to port a proprietary (non-GPL'd)
+application using Cygwin, you will need the proprietary-use license
+for the Cygwin library. This is available for purchase; please visit
+<ulink url="http://www.redhat.com/software/tools/cygwin/">http://www.redhat.com/software/tools/cygwin/</ulink> for more information.
+All other questions should be sent to the project
+mailing list cygwin@cygwin.com.
+</para>
+<para>Note that when we say "free" we mean freedom, not price. The goal of
+such freedom is that the people who use a given piece of software
+should be able to change it to fit their needs, learn from it, share
+it with their friends, etc. The Cygwin license allows you those
+freedoms, so it is free software.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.what.version">
+<question><para>What version of Cygwin <emphasis>is</emphasis> this, anyway?</para></question>
+<answer>
+
+<para>To find the version of the Cygwin DLL installed, you can use
+<filename>uname</filename> as on Linux or <filename>cygcheck</filename>. Refer to each command's
+<literal>--help</literal> output and the <ulink url='http://cygwin.com/cygwin-ug-net/'>Cygwin User's Guide</ulink> for more information.
+</para>
+<para>If you are looking for the version number for the whole Cygwin
+release, there is none. Each package in the Cygwin release has its own
+version. The packages in Cygwin are continually improving, thanks to
+the efforts of net volunteers who maintain the Cygwin binary ports.
+Each package has its own version numbers and its own release process.
+</para>
+<para>So, how do you get the most up-to-date version of Cygwin? Easy. Just
+download the Cygwin Setup program from
+<ulink url='http://cygwin.com/setup.exe'>http://cygwin.com/setup.exe</ulink>. This program will handle the task
+of updating the packages on your system to the latest version. For
+more information about using Cygwin's <filename>setup.exe</filename>, see
+<ulink url='http://cygwin.com/cygwin-ug-net/setup-net.html'>Setting Up Cygwin</ulink>
+in the Cygwin User's Guide.
+</para></answer></qandaentry>
+
+<qandaentry id="faq.what.history">
+<question><para>History</para></question>
+<answer>
+<para>See <ulink url="http://cygwin.com/history.html">http://cygwin.com/history.html</ulink>.
+</para>
+</answer></qandaentry>
+
+<qandaentry id="faq.what.who">
+<question><para>Who's behind the project?</para></question>
+<answer>
+
+<para><emphasis role='bold'>(Please note that if you have cygwin-specific questions, all of these people will appreciate it if you use the cygwin mailing lists rather than sending personal email.)</emphasis>
+</para>
+<para>Chris Faylor is behind many of the recent changes in Cygwin. Prior to
+joining Cygnus, he contributed significant fixes to the process control
+and environ code, reworked the strace mechanism, and rewrote the
+signal-related code from scratch as a Net contributor. In addition to
+continuing to make technical contributions, Chris is also currently the
+group's manager.
+</para>
+<para>Corinna Vinschen has contributed several useful fixes to the path
+handling code, console support, improved security handling, and raw
+device support. Corinna is currently employed by Red Hat as a
+GDB/Cygwin engineer.
+</para>
+<para>DJ Delorie has done important work in profiling Cygwin,
+worked on the Dejagnu automated testing framework, merged the dlltool
+functionality into ld, wrote a good deal of the Cygwin Users' Guide,
+authored the cygcheck utility, and made automated snapshots available
+from our project WWW page. DJ is currently employed by Red Hat as
+a GCC engineer.
+</para>
+<para>Egor Duda has contributed many useful fixes. He is responsible for
+Cygwin's ability to start a debugger on detection of a fatal error
+as well as produce core dumps.
+</para>
+<para>Robert Collins has contributed many improvements to thread handling
+as well as generic fixes to cygwin itself.
+</para>
+<para>Kazuhiro Fujieda has contributed many bug fixes and bug reports.
+</para>
+<para>Earnie Boyd has contributed many bug fixes and is the mingw and w32api
+maintainer.
+</para>
+<para>David Starks-Browning is our dedicated FAQ maintainer.
+</para>
+<para>Geoffrey Noer took over the Cygwin project from its initial author Steve
+Chamberlain in mid-1996. As maintainer, he produced Net releases beta
+16 through 20; made the development snapshots; worked with Net
+contributors to fix bugs; made many various code improvements himself;
+wrote a paper on Cygwin for the 1998 Usenix NT Symposium; authored the
+project WWW pages, FAQ, README; etc. Geoffrey is not currently employed
+by Red Hat.
+</para>
+<para>Steve Chamberlain designed and implemented
+Cygwin in 1995-1996 while working for Cygnus. He worked with the Net
+to improve the technology, ported/integrated many of the user tools
+for the first time to Cygwin, and produced all of the releases up to
+beta 14. Steve is not currently employed by Red Hat.
+</para>
+<para>Marco Fuykschot and Peter Boncz of Data Distilleries contributed nearly
+all of the changes required to make Cygwin thread-safe. They also
+provided the pthreads interface.
+</para>
+<para>Sergey Okhapkin has been an invaluable Net contributor. He implemented
+the tty/pty support, has played a significant role in revamping signal
+and exception handling, and has made countless contributions throughout
+the library. He also provided binaries of the development snapshots to
+the Net after the beta 19 release.
+</para>
+<para>Mumit Khan has been most helpful on the EGCS end of things, providing
+quite a large number of stabilizing patches to the compiler tools for
+the B20 release.
+</para>
+<para>Philippe Giacinti contributed the implementation of dlopen, dlclose,
+dlsym, dlfork, and dlerror in Cygwin.
+</para>
+<para>Ian Lance Taylor did a much-needed rework of the path handling code for
+beta 18, and has made many assorted fixes throughout the code. Jeremy
+Allison made significant contributions in the area of file handling and
+process control, and rewrote select from scratch. Doug Evans rewrote
+the path-handling code in beta 16, among other things. Kim Knuttila and
+Michael Meissner put in many long hours working on the now-defunct
+PowerPC port. Jason Molenda and Mark Eichin have also made important
+contributions.
+</para>
+<para>Please note that all of us working on Cygwin try to
+be as responsive as possible and deal with patches and questions as we
+get them, but realistically we don't have time to answer all of the
+email that is sent to the main mailing list. Making Net releases of the
+Win32 tools and helping people on the Net out is not our primary job
+function, so some email will have to go unanswered.
+</para>
+<para>Many thanks to everyone using the tools for their many contributions in
+the form of advice, bug reports, and code fixes. Keep them coming!
+</para></answer></qandaentry>
+
--- /dev/null
+<?xml version='1.0'?>
+<!DOCTYPE article PUBLIC '-//OASIS//DTD DocBook XML V4.2//EN'
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+ <!-- see http://www.unicode.org/charts/PDF/U0080.pdf -->
+ <!ENTITY pound "£">
+ <!ENTITY brokenpipe "¦">
+
+ <!-- all the files -->
+ <!ENTITY FAQ-WHAT SYSTEM "faq-what.xml">
+ <!ENTITY FAQ-SETUP SYSTEM "faq-setup.xml">
+ <!ENTITY FAQ-RESOURCES SYSTEM "faq-resources.xml">
+ <!ENTITY FAQ-USING SYSTEM "faq-using.xml">
+ <!ENTITY FAQ-API SYSTEM "faq-api.xml">
+ <!ENTITY FAQ-PROGRAMMING SYSTEM "faq-programming.xml">
+ <!ENTITY FAQ-PROBLEMS SYSTEM "faq-problems.xml">
+]>
+
+<article id="faq-nochunks" lang="en">
+ <articleinfo>
+ <title>Cygwin FAQ</title>
+ </articleinfo>
+
+<qandaset>
+<?dbhtml toc="1"?>
+
+<qandadiv id="faq.about">
+<title>About Cygwin</title>
+&FAQ-WHAT;
+</qandadiv>
+
+<qandadiv id="faq.setup">
+<title>Setting up Cygwin</title>
+&FAQ-SETUP;
+</qandadiv>
+
+<qandadiv id="faq.resources">
+<title>Further Resources</title>
+&FAQ-RESOURCES;
+</qandadiv>
+
+<qandadiv id="faq.using">
+<title>Using Cygwin</title>
+&FAQ-USING;
+</qandadiv>
+
+<qandadiv id="faq.api">
+<title>Cygwin API Questions</title>
+&FAQ-API;
+</qandadiv>
+
+<qandadiv id="faq.programming">
+<title>Programming Questions</title>
+&FAQ-PROGRAMMING;
+</qandadiv>
+
+<qandadiv id="faq.known-problems">
+<title>Known Problems in the Latest Net Release</title>
+&FAQ-PROBLEMS;
+</qandadiv>
+
+<qandadiv id="faq.copyright">
+<title>Copyright</title>
+
+
+<qandaentry id="faq.what.copyright">
+<question><para>What are the copyrights ?</para></question>
+<answer>
+
+<para>The general idea</para>
+
+<para>Most of the tools are covered by the GNU General Public License (GPL),
+although some are public domain, and others have a X11-style
+copyright. To cover the GNU GPL requirements, the basic rule is if
+you give out any binaries, you must also make the source available.
+For the full details, be sure to read the text of the GNU GPL which
+follows.
+</para>
+<para>The Cygwin API library found in the winsup subdirectory of the source
+code is also covered by the GNU GPL. By default, all executables link
+against this library (and in the process include GPL'd Cygwin glue
+code). This means that unless you modify the tools so that compiled
+executables do not make use of the Cygwin library, your compiled
+programs will also have to be free software distributed under the GPL
+with source code available to all.
+</para>
+<para>Cygwin is currently available for proprietary use only through a
+proprietary-use license. Please see
+<ulink url="http://www.redhat.com/software/cygwin/">http://www.redhat.com/software/cygwin/</ulink> for more information
+about the Red Hat Cygwin Product.
+</para>
+<para>In accordance with section 10 of the GPL, Red Hat, Inc. permits
+programs whose sources are distributed under a license that complies
+with the Open Source definition to be linked with libcygwin.a without
+libcygwin.a itself causing the resulting program to be covered by the
+GNU GPL.
+</para>
+<para>This means that you can port an Open Source(tm) application to cygwin,
+and distribute that executable as if it didn't include a copy of
+libcygwin.a linked into it. Note that this does not apply to the
+cygwin DLL itself. If you distribute a (possibly modified) version of
+the DLL you must adhere to the terms of the GPL, i.e., you must
+provide sources for the cygwin DLL.
+</para>
+<para>See <ulink url="http://www.opensource.org/docs/definition_plain.html">http://www.opensource.org/docs/definition_plain.html</ulink> for
+the precise Open Source Definition referenced above.
+</para>
+
+<para>GNU GENERAL PUBLIC LICENSE</para>
+<screen>
+ GNU GENERAL PUBLIC LICENSE
+ Version 2, June 1991
+
+ Copyright (C) 1989, 1991 Free Software Foundation, Inc.
+ 675 Mass Ave, Cambridge, MA 02139, USA
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+ Preamble
+
+ The licenses for most software are designed to take away your
+freedom to share and change it. By contrast, the GNU General Public
+License is intended to guarantee your freedom to share and change free
+software--to make sure the software is free for all its users. This
+General Public License applies to most of the Free Software
+Foundation's software and to any other program whose authors commit to
+using it. (Some other Free Software Foundation software is covered by
+the GNU Library General Public License instead.) You can apply it to
+your programs, too.
+
+ When we speak of free software, we are referring to freedom, not
+price. Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+this service if you wish), that you receive source code or can get it
+if you want it, that you can change the software or use pieces of it
+in new free programs; and that you know you can do these things.
+
+ To protect your rights, we need to make restrictions that forbid
+anyone to deny you these rights or to ask you to surrender the rights.
+These restrictions translate to certain responsibilities for you if you
+distribute copies of the software, or if you modify it.
+
+ For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must give the recipients all the rights that
+you have. You must make sure that they, too, receive or can get the
+source code. And you must show them these terms so they know their
+rights.
+
+ We protect your rights with two steps: (1) copyright the software, and
+(2) offer you this license which gives you legal permission to copy,
+distribute and/or modify the software.
+
+ Also, for each author's protection and ours, we want to make certain
+that everyone understands that there is no warranty for this free
+software. If the software is modified by someone else and passed on, we
+want its recipients to know that what they have is not the original, so
+that any problems introduced by others will not reflect on the original
+authors' reputations.
+
+ Finally, any free program is threatened constantly by software
+patents. We wish to avoid the danger that redistributors of a free
+program will individually obtain patent licenses, in effect making the
+program proprietary. To prevent this, we have made it clear that any
+patent must be licensed for everyone's free use or not licensed at all.
+
+ The precise terms and conditions for copying, distribution and
+modification follow.
+
+ GNU GENERAL PUBLIC LICENSE
+ TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+ 0. This License applies to any program or other work which contains
+a notice placed by the copyright holder saying it may be distributed
+under the terms of this General Public License. The "Program", below,
+refers to any such program or work, and a "work based on the Program"
+means either the Program or any derivative work under copyright law:
+that is to say, a work containing the Program or a portion of it,
+either verbatim or with modifications and/or translated into another
+language. (Hereinafter, translation is included without limitation in
+the term "modification".) Each licensee is addressed as "you".
+
+Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope. The act of
+running the Program is not restricted, and the output from the Program
+is covered only if its contents constitute a work based on the
+Program (independent of having been made by running the Program).
+Whether that is true depends on what the Program does.
+
+ 1. You may copy and distribute verbatim copies of the Program's
+source code as you receive it, in any medium, provided that you
+conspicuously and appropriately publish on each copy an appropriate
+copyright notice and disclaimer of warranty; keep intact all the
+notices that refer to this License and to the absence of any warranty;
+and give any other recipients of the Program a copy of this License
+along with the Program.
+
+You may charge a fee for the physical act of transferring a copy, and
+you may at your option offer warranty protection in exchange for a fee.
+
+ 2. You may modify your copy or copies of the Program or any portion
+of it, thus forming a work based on the Program, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you also meet all of these conditions:
+
+ a) You must cause the modified files to carry prominent notices
+ stating that you changed the files and the date of any change.
+
+ b) You must cause any work that you distribute or publish, that in
+ whole or in part contains or is derived from the Program or any
+ part thereof, to be licensed as a whole at no charge to all third
+ parties under the terms of this License.
+
+ c) If the modified program normally reads commands interactively
+ when run, you must cause it, when started running for such
+ interactive use in the most ordinary way, to print or display an
+ announcement including an appropriate copyright notice and a
+ notice that there is no warranty (or else, saying that you provide
+ a warranty) and that users may redistribute the program under
+ these conditions, and telling the user how to view a copy of this
+ License. (Exception: if the Program itself is interactive but
+ does not normally print such an announcement, your work based on
+ the Program is not required to print an announcement.)
+
+These requirements apply to the modified work as a whole. If
+identifiable sections of that work are not derived from the Program,
+and can be reasonably considered independent and separate works in
+themselves, then this License, and its terms, do not apply to those
+sections when you distribute them as separate works. But when you
+distribute the same sections as part of a whole which is a work based
+on the Program, the distribution of the whole must be on the terms of
+this License, whose permissions for other licensees extend to the
+entire whole, and thus to each and every part regardless of who wrote it.
+
+Thus, it is not the intent of this section to claim rights or contest
+your rights to work written entirely by you; rather, the intent is to
+exercise the right to control the distribution of derivative or
+collective works based on the Program.
+
+In addition, mere aggregation of another work not based on the Program
+with the Program (or with a work based on the Program) on a volume of
+a storage or distribution medium does not bring the other work under
+the scope of this License.
+
+ 3. You may copy and distribute the Program (or a work based on it,
+under Section 2) in object code or executable form under the terms of
+Sections 1 and 2 above provided that you also do one of the following:
+
+ a) Accompany it with the complete corresponding machine-readable
+ source code, which must be distributed under the terms of Sections
+ 1 and 2 above on a medium customarily used for software interchange; or,
+
+ b) Accompany it with a written offer, valid for at least three
+ years, to give any third party, for a charge no more than your
+ cost of physically performing source distribution, a complete
+ machine-readable copy of the corresponding source code, to be
+ distributed under the terms of Sections 1 and 2 above on a medium
+ customarily used for software interchange; or,
+
+ c) Accompany it with the information you received as to the offer
+ to distribute corresponding source code. (This alternative is
+ allowed only for noncommercial distribution and only if you
+ received the program in object code or executable form with such
+ an offer, in accord with Subsection b above.)
+
+The source code for a work means the preferred form of the work for
+making modifications to it. For an executable work, complete source
+code means all the source code for all modules it contains, plus any
+associated interface definition files, plus the scripts used to
+control compilation and installation of the executable. However, as a
+special exception, the source code distributed need not include
+anything that is normally distributed (in either source or binary
+form) with the major components (compiler, kernel, and so on) of the
+operating system on which the executable runs, unless that component
+itself accompanies the executable.
+
+If distribution of executable or object code is made by offering
+access to copy from a designated place, then offering equivalent
+access to copy the source code from the same place counts as
+distribution of the source code, even though third parties are not
+compelled to copy the source along with the object code.
+
+ 4. You may not copy, modify, sublicense, or distribute the Program
+except as expressly provided under this License. Any attempt
+otherwise to copy, modify, sublicense or distribute the Program is
+void, and will automatically terminate your rights under this License.
+However, parties who have received copies, or rights, from you under
+this License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+ 5. You are not required to accept this License, since you have not
+signed it. However, nothing else grants you permission to modify or
+distribute the Program or its derivative works. These actions are
+prohibited by law if you do not accept this License. Therefore, by
+modifying or distributing the Program (or any work based on the
+Program), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying
+the Program or works based on it.
+
+ 6. Each time you redistribute the Program (or any work based on the
+Program), the recipient automatically receives a license from the
+original licensor to copy, distribute or modify the Program subject to
+these terms and conditions. You may not impose any further
+restrictions on the recipients' exercise of the rights granted herein.
+You are not responsible for enforcing compliance by third parties to
+this License.
+
+ 7. If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License. If you cannot
+distribute so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you
+may not distribute the Program at all. For example, if a patent
+license would not permit royalty-free redistribution of the Program by
+all those who receive copies directly or indirectly through you, then
+the only way you could satisfy both it and this License would be to
+refrain entirely from distribution of the Program.
+
+If any portion of this section is held invalid or unenforceable under
+any particular circumstance, the balance of the section is intended to
+apply and the section as a whole is intended to apply in other
+circumstances.
+
+It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system, which is
+implemented by public license practices. Many people have made
+generous contributions to the wide range of software distributed
+through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing
+to distribute software through any other system and a licensee cannot
+impose that choice.
+
+This section is intended to make thoroughly clear what is believed to
+be a consequence of the rest of this License.
+
+ 8. If the distribution and/or use of the Program is restricted in
+certain countries either by patents or by copyrighted interfaces, the
+original copyright holder who places the Program under this License
+may add an explicit geographical distribution limitation excluding
+those countries, so that distribution is permitted only in or among
+countries not thus excluded. In such case, this License incorporates
+the limitation as if written in the body of this License.
+
+ 9. The Free Software Foundation may publish revised and/or new versions
+of the General Public License from time to time. Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+Each version is given a distinguishing version number. If the Program
+specifies a version number of this License which applies to it and "any
+later version", you have the option of following the terms and conditions
+either of that version or of any later version published by the Free
+Software Foundation. If the Program does not specify a version number of
+this License, you may choose any version ever published by the Free Software
+Foundation.
+
+ 10. If you wish to incorporate parts of the Program into other free
+programs whose distribution conditions are different, write to the author
+to ask for permission. For software which is copyrighted by the Free
+Software Foundation, write to the Free Software Foundation; we sometimes
+make exceptions for this. Our decision will be guided by the two goals
+of preserving the free status of all derivatives of our free software and
+of promoting the sharing and reuse of software generally.
+
+ NO WARRANTY
+
+ 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
+FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
+OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
+PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
+OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
+TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
+PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
+REPAIR OR CORRECTION.
+
+ 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
+REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
+INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
+OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
+TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
+YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
+PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGES.
+
+ END OF TERMS AND CONDITIONS
+
+ Appendix: How to Apply These Terms to Your New Programs
+
+ If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+ To do so, attach the following notices to the program. It is safest
+to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+ <one line to give the program's name and a brief idea of what it does.>
+ Copyright (C) 19yy <name of author>
+
+ This program is free software; you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation; either version 2 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License
+ along with this program; if not, write to the Free Software
+ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+
+Also add information on how to contact you by electronic and paper mail.
+
+If the program is interactive, make it output a short notice like this
+when it starts in an interactive mode:
+
+ Gnomovision version 69, Copyright (C) 19yy name of author
+ Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+ This is free software, and you are welcome to redistribute it
+ under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License. Of course, the commands you use may
+be called something other than `show w' and `show c'; they could even be
+mouse-clicks or menu items--whatever suits your program.
+
+You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a "copyright disclaimer" for the program, if
+necessary. Here is a sample; alter the names:
+
+ Yoyodyne, Inc., hereby disclaims all copyright interest in the program
+ `Gnomovision' (which makes passes at compilers) written by James Hacker.
+
+ <signature of Ty Coon>, 1 April 1989
+ Ty Coon, President of Vice
+
+This General Public License does not permit incorporating your program into
+proprietary programs. If your program is a subroutine library, you may
+consider it more useful to permit linking proprietary applications with the
+library. If this is what you want to do, use the GNU Library General
+Public License instead of this License.
+
+</screen>
+
+</answer></qandaentry>
+</qandadiv>
+</qandaset>
+
+</article>