New files, contents of how.texinfo has been split into these.

4 files changed, 1361 insertions, 0 deletions

diff --git a/winsup/doc/how-api.texinfo b/winsup/doc/how-api.texinfo
new file mode 100644
index 000000000..83fb7ce03
--- /dev/null
+++ b/winsup/doc/how-api.texinfo
@@ -0,0 +1,284 @@
+@section Cygwin API Questions
+
+@subsection How does everything work?
+
+There's a C library which provides a Unix-style API.  The
+applications are linked with it and voila - they run on Windows.
+
+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.
+
+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.
+
+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.
+
+@subsection Are development snapshots for the Cygwin library available?
+
+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
+http://sources.redhat.com/cygwin/snapshots/
+
+
+@subsection How is the DOS/Unix CR/LF thing handled?
+
+@strong{(Please note: This section has not yet been updated for the latest
+net release.)}
+
+Let's start with some background.
+
+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.
+
+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 dependant 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.
+
+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.
+
+Some people push the notion of globally setting the default processing
+mode to binary via mount point options or by setting the CYGWIN32
+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.
+
+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 @code{O_BINARY} to
+the second argument of an @code{open} call, or @code{"b"} to second
+argument of an @code{fopen} call.  You can also call @code{setmode (fd,
+O_BINARY)}.
+
+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.
+
+Also note that @code{lseek} only works in binary mode.
+
+Explanation adapted from mailing list email by Earnie Boyd
+<earnie_boyd@@yahoo.com>.
+
+@subsection Is the Cygwin library multi-thread-safe?
+
+Multi-thread-safe support is turned on by default in 1.1.x releases
+(i.e., in the latest net release).  That does not mean that it is bug
+free!
+
+There is also limited support for 'POSIX threads', see the file
+@code{cygwin.din} for the list of POSIX thread functions provided.
+
+@subsection Why is some functionality only supported in Windows NT?
+
+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.
+
+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.
+
+@subsection How is fork() implemented?
+
+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.
+
+Here's how it works:
+
+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 childs
+.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.
+
+@subsection How does wildcarding (globbing) work?
+
+@strong{(Please note: This section has not yet been updated for the latest
+net release.)}
+
+If an application using CYGWIN.DLL starts up, and can't find the
+@code{PID} environment variable, it assumes that it has been started
+from the a DOS style command prompt.  This is pretty safe, since the
+rest of the tools (including bash) set PID so that a new process knows
+what PID it has when it starts up.
+
+If the DLL thinks it has come from a DOS style prompt, it runs a
+`globber' over the arguments provided on the command line.  This means
+that if you type @code{LS *.EXE} from DOS, it will do what you might
+expect.
+
+Beware: globbing uses @code{malloc}.  If your application defines
+@code{malloc}, that will get used.  This may do horrible things to you.
+
+@subsection How do symbolic links work?
+
+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.
+
+@subsection Why do some files, which are not executables have the 'x' type.
+
+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.  
+
+It guesses that files ending in .exe and .bat are executable, as are
+ones which have a "#!" as their first characters.
+
+@subsection How secure is Cygwin in a multi-user environment?
+
+Cygwin is not secure in a multi-user environment.  For
+example if you have a long running daemon such as "inetd"
+running as admin while ordinary users are logged in, or if
+you have a user logged in remotely while another user is logged
+into the console, one cygwin client can trick another into
+running code for it.  In this way one user may gain the
+priveledge of another cygwin program running on the machine.
+This is because cygwin has shared state that is accessible by 
+all processes.
+
+(Thanks to Tim Newsham (newsham@@lava.net) for this explanation).
+
+@subsection How do the net-related functions work?
+
+@strong{(Please note: This section has not yet been updated for the latest
+net release.)}
+
+The network support in Cygwin is supposed to provide the Unix API, not
+the Winsock API.
+
+There are differences between the semantics of functions with the same
+name under the API.
+
+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.
+
+If you are porting an application which already uses Winsock, then
+using the net support in Cygwin is wrong.
+
+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:
+
+@example
+..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..
+@end example
+
+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.
+
+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.
+
+As of the b19 release, this information may be slightly out of date.
+
+@subsection I don't want Unix sockets, how do I use normal Win32 winsock?
+
+@strong{(Please note: This section has not yet been updated for the latest
+net release.)}
+
+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.
+
+@subsection What version numbers are associated with Cygwin?
+
+@strong{(Please note: This section has not yet been updated for the latest
+net release.)}
+
+There is a cygwin.dll major version number that gets incremented
+every time we make a new Cygwin release available.  This
+corresponds to the name of the release (e.g. beta 19's major
+number is "19").  There is also a cygwin.dll minor version number.  If
+we release an update of the library for an existing release, the minor
+number would be incremented.
+
+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.
+
+Then there is a shared memory region compatibity 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 "B15.0" since the beta 15 release.
+
+@subsection Why isn't _timezone set correctly?
+
+@strong{(Please note: This section has not yet been updated for the latest
+net release.)}
+
+Did you explicitly call tzset() before checking the value of _timezone?
+If not, you must do so.
+
+@subsection Is there a mouse interface?
+
+There is no way to capture mouse events from Cygwin.  There are
+currently no plans to add support for this.
+
diff --git a/winsup/doc/how-programming.texinfo b/winsup/doc/how-programming.texinfo
new file mode 100644
index 000000000..7b74b7b8f
--- /dev/null
+++ b/winsup/doc/how-programming.texinfo
@@ -0,0 +1,536 @@
+@section Programming Questions
+
+@subsection Why are compiled executables so huge?!?
+
+By default, gcc compiles in all symbols.  You'll also find that gcc
+creates large executables on UNIX.
+
+If that bothers you, just use the 'strip' program, part of the binutils
+package.
+
+@subsection Where is glibc?
+
+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.
+
+@subsection Why is make behaving badly?
+
+@strong{(Please note: This section has not yet been updated for the latest
+net release.)}
+
+Starting with the beta 19 release, make defaults to a win32 mode in
+which backslashes in filenames are permitted and cmd.exe/command.com
+is used as the sub-shell.  In this mode, escape characters aren't
+allowed among other restrictions.  For this reason, you must set
+the environment variable MAKE_MODE to UNIX to run make on ordinary Unix
+Makefiles.  Here is the full scoop:
+
+MAKE_MODE selects between native Win32 make mode (the default) and
+a Unix mode where it behaves like a Unix make.  The Unix mode does
+allow specifying Win32-style paths but only containing forward slashes
+as the path separator.  The path list separator character is a colon
+in Unix mode.
+
+Win32 mode expects path separators to be either / or \.  Thus no
+Unix-style \s as escape are allowed.  Win32 mode also uses
+cmd.exe/command.com as the subshell which means "copy" and "del"
+(and other shell builtins) will work.  The path list separator
+character is semi-colon in Win32 mode.  People who want an nmake-like
+make might want to use this mode but no one should expect Unix
+Makefiles to compile in this mode.  That is why the default b19
+install sets MAKE_MODE to UNIX.
+
+@subsection Why the undefined reference to "WinMain@@16"?
+
+@strong{(Please note: This section has not yet been updated for the latest
+net release.)}
+
+Try adding an empty main() function to one of your sources.
+
+@subsection How do I use Win32 API calls?
+
+@strong{(Please note: This section has not yet been updated for the latest
+net release.)}
+
+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).
+
+For example, to use graphics functions (GDI) you must link
+with gdi32 like this:
+
+gcc -o foo.exe foo.o bar.o -lgdi32
+
+or (compiling and linking in one step):
+
+gcc -o foo.exe foo.c bar.c -lgdi32
+
+The following libraries are available for use in this way:
+
+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
+
+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.
+
+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.
+
+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.
+
+@subsection How do I compile a Win32 executable that doesn't use Cygwin?
+
+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.
+
+This is not to be confused with 'MinGW' (Minimalist GNU for Windows),
+which is a completely separate effort.  That project's home page is
+@file{http://www.mingw.org/index.shtml}.
+
+@subsection How do I make the console window go away?
+
+The default during compilation is to produce a console application.
+It you are writing a GUI program, you should either compile with
+-mwindows as explained above, or add the string
+"-Wl,--subsystem,windows" to the GCC commandline.
+
+@subsection Why does make complain about a "missing separator"?
+
+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.
+
+@subsection Why can't we redistribute Microsoft's Win32 headers?
+
+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 Cygnus (err... Red Hat) can't agree to.  Fortunately, we
+have our own Win32 headers which are pretty complete.
+
+@subsection How do I link against .lib files?
+
+@strong{(Please note: This section has not yet been updated for the latest
+net release.)}
+
+1. 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.
+2. Build a dummy 'LibMain'.
+3. Build a .def with all the exports you need.
+4. Link with your .lib using link.exe.
+
+or
+
+1. Extract all the object files from the .lib using LIB.EXE.
+2. Build a dummy C file referencing all the functions you need, either
+with a direct call or through an initialized function pointer.
+3. Build a dummy LibMain.
+4. Link all the objects with this file+LibMain.
+5. Write a .def.
+6. Link.
+
+You can use these methods to use MSVC (and many other runtime libs)
+with Cygwin development tools.
+
+Note that this is a lot of work (half a day or so), but much less than
+rewriting the runtime library in question from specs...
+
+(thanks to Jacob Navia (root@@jacob.remcomp.fr) for this explanation)
+
+@subsection How do I rebuild the tools on my NT box?
+
+@strong{Note:} You must build in a directory @emph{outside} the source
+tree.
+
+Assuming that you have the src installed as /src, will build in
+the directory /obj, and want to install the tools in /install:
+
+@example
+bash
+cd /obj
+/src/configure --prefix=/install -v > configure.log 2>&1
+make > make.log 2>&1
+make install > install.log 2>&1
+@end example
+
+Normally, this will also attempt to build the documentation, which
+additionally requires db2html, texi2html and possibly others.
+These tools are not included in the Cygwin distribution, but are readily
+obtainable:
+
+@table @samp
+@item db2html
+Part of docbook, from @file{http://sources.redhat.com/docbook-tools/}.
+@item texi2html
+From @file{http://www.mathematik.uni-kl.de/~obachman/Texi2html/}.
+@end table
+
+To check a cygwin1.dll, run "make check" in the winsup/cygwin directory.
+If that works, install everything @emph{except} 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 @emph{all} the
+places where the old dll was (if there is more than one on your
+machine).  Then start up a bash window and see what happens.  (Or better,
+run a cygwin program from the Windows command prompt.)
+
+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.
+
+@subsection How can I compile a powerpc NT toolchain?
+
+@strong{(Please note: This section has not yet been updated for the latest
+net release.)}
+
+Unfortunately, this will be difficult.  It hasn't been built for
+some time (late 1996) since Microsoft has dropped development of
+powerpc NT.  Exception handling/signals support semantics/args have been
+changed for x86 and not updated for ppc so the ppc specific support would
+have to be rewritten.  We don't know of any other incompatibilities.
+Please send us patches if you do this work!
+
+@subsection How can I compile an Alpha NT toolchain?
+
+@strong{(Please note: This section has not yet been updated for the latest
+net release.)}
+
+We have not ported the tools to Alpha NT and do not have plans to
+do so at the present time.  We would be happy to add support
+for Alpha NT if someone contributes the changes to us.
+
+@subsection How can I adjust the heap/stack size of an application?
+
+@strong{(Please note: This section has not yet been updated for the latest
+net release.)}
+
+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:
+
+@code{gcc -Wl,--heap,1024,--stack,4096 -o foo foo.c}
+
+@subsection How can I find out which dlls are needed by an executable?
+
+@strong{(Please note: This section has not yet been updated for the latest
+net release.)}
+
+objdump -p provides this information.
+
+@subsection How do I build a DLL?
+
+@strong{(Please note: This section has not yet been updated for the latest
+net release.)}
+
+There's documentation that explains the process on the main Cygwin
+project web page (http://sources.redhat.com/cygwin/).
+
+@subsection How can I set a breakpoint at MainCRTStartup?
+
+@strong{(Please note: This section has not yet been updated for the latest
+net release.)}
+
+Set a breakpoint at *0x401000 in gdb and then run the program in
+question.
+
+@subsection How can I build a relocatable dll?
+
+@strong{(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
+@file{http://sources.redhat.com/ml/cygwin/2000-06/msg00688.html} and
+related messages.)}
+
+You must execute the following sequence of five commands, in this
+order:
+
+@example
+$(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
+@end example
+
+In this example, $(LD) is the linker, ld.
+
+$(DLLTOOL) is dlltool.
+
+$(AS) is the assembler, as.
+
+DLLNAME is the name of the DLL you want to create, e.g., tcl80.dll.
+
+OBJS is the list of object files you want to put into the DLL.
+
+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.
+
+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.
+
+BASEFILE is a temporary file that is used during this five stage
+process, e.g., tcl.base.
+
+EXPFILE is another temporary file, e.g., tcl.exp.
+
+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)
+
+This means that the actual symbol name will have an appended @@12, so if
+your entry point really is named @samp{startup}, the string you should
+use for ENTRY in the above examples would be @samp{startup@@12}.
+
+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 @samp{_impure_ptr}, and then initializing it in the
+entry function.  Be careful not to export the global variable
+@samp{_impure_ptr} from your DLL; that is, do not put it in DEFFILE.
+
+@example
+/* 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.  */
+@}
+@end example
+
+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.
+
+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.
+
+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:
+
+$(DLLTOOL) --as=$(AS) --dllname DLLNAME --def DEFFILE --output-lib LIBFILE
+
+$(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.
+
+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.
+
+@subsection How can I debug what's going on?
+
+You can debug your application using @code{gdb}.  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).
+
+@subsection Can I use a system trace mechanism instead?
+
+Yes.  You can use the @code{strace.exe} utility to run other cygwin
+programs with various debug and trace messages enabled.  For information
+on using @code{strace}, see the Cygwin User's Guide or the file
+@code{winsup/utils/utils.sgml}.
+
+Alternatively, you can set the @code{STRACE} environment variable to
+@code{1}, and get a whole load of debug information on your screen
+whenever a Cygwin app runs.  This is an especially useful tool to use
+when tracking bugs down inside the Cygwin library.  @code{STRACE} can be
+set to different values to achieve different amounts of granularity.
+You can set it to @code{0x10} for information about syscalls or
+@code{0x800} for signal/process handling-related info, to name two.  The
+strace mechanism is well documented in the Cygwin library sources in the
+file @code{winsup/cygwin/include/sys/strace.h}.
+
+@subsection Why doesn't gdb handle signals?
+
+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.
+
+@subsection The linker complains that it can't find something.
+
+@strong{(Please note: This section has not yet been updated for the latest
+net release.)}
+
+A common error is to put the library on the command line before
+the thing that needs things from it.
+
+This is wrong @code{gcc -lstdc++ hello.cc}.
+This is right @code{gcc hello.cc -lstdc++}.
+
+@subsection I use a function I know is in the API, but I still get a link error.
+
+@strong{(Please note: This section has not yet been updated for the latest
+net release.)}
+
+The function probably isn't declared in the header files, or
+the UNICODE stuff for it isn't filled in.
+
+@subsection Can you make DLLs that are linked against libc ?
+
+@strong{(Please note: This section has not yet been updated for the latest
+net release.)}
+
+Yes.
+
+@subsection Where is malloc.h?
+
+@strong{(Please note: This section has not yet been updated for the latest
+net release.)}
+
+Include stdlib.h instead of malloc.h.
+
+@subsection Can I use my own malloc?
+
+If you define a function called @code{malloc} in your own code, and link
+with the DLL, the DLL @emph{will} call your @code{malloc}.  Needless to
+say, you will run into serious problems if your malloc is buggy.
+
+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 @code{malloc} @emph{before} your main line is started.
+If you have written your own @code{malloc} to need some initialization
+to occur after @code{main} is called, then this will surely break.
+
+Moreover, there is an outstanding issue with @code{_malloc_r} in
+@code{newlib}.  This re-entrant version of @code{malloc} will be called
+directly from within @code{newlib}, by-passing your custom version, and
+is probably incompatible with it.  But it may not be possible to replace
+@code{_malloc_r} too, because @code{cygwin1.dll} 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.
+
+@subsection Can I mix objects compiled with msvc++ and gcc?
+
+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.
+
+@subsection Can I use the gdb debugger to debug programs built by VC++?
+
+No, not for full (high level source language) debugging.
+The Microsoft compilers generate a different type of debugging
+symbol information, which gdb does not understand.
+
+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.
+
+@subsection Where can I find info on x86 assembly?
+
+CPU reference manuals for Intel's current chips are available in
+downloadable PDF form on Intel's web site:
+
+@file{http://developer.intel.com/design/pro/manuals/}
+
+@subsection Shell scripts aren't running properly from my makefiles?
+
+@strong{(Please note: This section has not yet been updated for the latest
+net release.)}
+
+You need to have . (dot) in your $PATH.  You should NOT need to add
+/bin/sh in front of each and every shell script invoked in your
+Makefiles.
+
+@subsection What preprocessor do I need to know about?
+
+@strong{(Please note: This section has not yet been updated for the latest
+net release.)}
+
+We use _WIN32 to signify access to the Win32 API and __CYGWIN__ for
+access to the Cygwin environment provided by the dll.
+
+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++.
+
+@subsection Where can I get f77 and objc components for B20 EGCS 1.1?
+
+@strong{(Please note: This section has not yet been updated for the latest
+net release.)}
+
+B20-compatible versions of the f77 and objc components are available
+from @file{http://www.xraylith.wisc.edu/~khan/software/gnu-win32/}.
+
+@subsection How should I port my Unix GUI to Windows?
+
+@strong{(Please note: This section has not yet been updated for the latest
+net release.)}
+
+There are two basic strategies for porting Unix GUIs to Windows.
+
+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.
+
+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.
+
+@subsection Why not use DJGPP ?
+
+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.
+
+You can get more info on DJGPP by following
+@file{http://www.delorie.com/}.
diff --git a/winsup/doc/how-resources.texinfo b/winsup/doc/how-resources.texinfo
new file mode 100644
index 000000000..8db4f0d02
--- /dev/null
+++ b/winsup/doc/how-resources.texinfo
@@ -0,0 +1,115 @@
+@section Where can I get more information?
+
+@subsection Where's the documentation?
+
+There are links to quite a lot of it on the main Cygwin project web
+page: @file{http://sources.redhat.com/cygwin/}.  Be sure to at least
+read any 'Release Notes' or 'Readme' or 'read this' links on the main
+web page, if there are any.
+
+There is a comprehensive Cygwin User's Guide at
+@file{http://sources.redhat.com/cygwin/cygwin-ug-net/cygwin-ug-net.html}
+and an API Reference at
+@file{http://sources.redhat.com/cygwin/cygwin-api/cygwin-api.html}.
+
+There is an interesting paper about Cygwin from the 1998 USENIX Windows
+NT Workshop Proceedings at
+@file{http://sources.redhat.com/cygwin/usenix-98/cygwin.html}.
+
+You can find documentation for the individual GNU tools at
+@file{http://www.fsf.org/manual/}.  (You should read GNU manuals from a
+local mirror, check @file{http://www.fsf.org/server/list-mirrors.html}
+for a list of them.)
+
+@subsection What Cygwin mailing lists can I join?
+
+Comprehensive information about the Cygwin mailing lists can be found at
+@file{http://sources.redhat.com/cygwin/lists.html}.
+
+To subscribe to the main list, send a message to
+cygwin-subscribe@@sources.redhat.com.  To unsubscribe from the 
+main list, send a message to cygwin-unsubscribe@@sources.redhat.com.
+In both cases, the subject and body of the message are ignored.
+
+Similarly, to subscribe to the Cygwin annoucements list, send a message
+to cygwin-announce-subscribe@@sources.redhat.com.  To unsubscribe,
+send a message to cygwin-announce-unsubscribe@@sources.redhat.com.
+
+If you are going to help develop the Cygwin library by volunteering for
+the project, you will want to subscribe to the Cygwin developers list,
+called cygwin-developers.  If you are contributing to Cygwin tools &
+applications, rather than the library itself, then you should subscribe
+to cygwin-apps.  The same mechanism as described for the first two lists
+works for these as well.  Both cygwin-developers and cygwin-apps are
+by-approval lists.
+
+There is a searchable archive of the main mailing list at
+@file{http://sources.redhat.com/ml/cygwin/}.  There is an alternate
+archive, also searchable, at @file{http://www.delorie.com/archives/}.
+
+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.
+
+@subsection Posting Guidelines (Or: Why won't you/the mailing list answer my questions?)
+
+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:
+
+@itemize @bullet
+@item Read the User's Guide and the FAQ first.
+@item 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.
+@item 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:
+
+@itemize @bullet
+@item 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 @emph{"it"}?)
+@item Information about your Windows OS ("Win95 OSR2" or "NT4/SP3" or
+"Win2K" or "Win98 SE" or ...).
+@item 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?)
+@item Details about your Cygwin setup, accomplished by @emph{pasting}
+the output of 'cygcheck -s -v -r' into your message.  (Do not send the
+output as a file attachment.)
+@item A valid return address, so that a reply doesn't require manual editing of
+the 'To:' header.
+@end itemize
+
+@item Your message must be relevant to the list.  Messages that are
+@emph{not} directly related to Cygwin are considered off-topic and are
+unwelcome.  For example, the following are off-topic:
+
+@itemize @bullet
+@item General programming language questions
+@item General Windows programming questions
+@item General UNIX shell programming questions
+@item General application usage questions
+@item How to make millions by working at home
+@item Announcements from LaserJet toner cartridge suppliers
+@end itemize
+
+@end itemize
+
+If you do not follow the above guidelines, you may still elicit a
+response, but you may not appreciate it!
+
+Inquiries about support contracts and commercial licensing should go to
+info@@cygnus.com.  If you want to purchase the Cygwin 1.0 CD-ROM, visit
+@file{http://www.cygnus.com/cygwin/} or write to
+cygwin-info@@cygnus.com.  While not strictly @emph{unappreciated} in the
+main cygwin list, you'll get the information you need more quickly if
+you write to the correct address in the first place.
+
+Beyond that, perhaps nobody has time to answer your question.  Perhaps
+nobody knows the answer.
+
diff --git a/winsup/doc/how-using.texinfo b/winsup/doc/how-using.texinfo
new file mode 100644
index 000000000..4997c2de9
--- /dev/null
+++ b/winsup/doc/how-using.texinfo
@@ -0,0 +1,426 @@
+@section Using Cygwin
+
+@subsection How should I set my PATH?
+
+If you look at the "Cygwin 1.1.0" (or similar) shortcut created in the
+"Cygnus Solutions" programs folder, you'll see that it runs
+@code{C:\cygwin\bin\cygwin.bat} (assuming your root is
+@code{C:\cygwin}).  The contents should look something like this:
+
+@example
+	@@echo off
+	SET MAKE_MODE=unix
+	SET PATH=C:\cygwin\bin;C:\cygwin\usr\local\bin;%PATH%
+	bash
+@end example
+
+Effectively, this @strong{prepends} /usr/bin and /usr/local/bin to your
+Windows system path.  If you choose to reset your PATH, say in
+$HOME/.bashrc, then you should follow this rule.  You @strong{must} have
+@code{/usr/bin} in your PATH @strong{before} 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.
+
+If you haven't messed up the default mounts, then @code{/bin} and
+@code{/usr/bin} are the same location, so you only need one of them in
+your PATH.  You should use @code{/usr/local/bin} for installing
+additional Cygwin applications that are not part of the core net
+release.  (That is, anything not found in an ftp mirror of @code{latest}
+and installed by @code{setup.exe}.)
+
+@subsection How do I convert between Windows and UNIX paths?
+
+Use the 'cygpath' utility.  Type '@code{cygpath}' with no arguments to
+get usage information.  For example (on my installation):
+@example
+	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
+@end example
+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 recognised
+as such.
+
+@subsection How do I set /etc up?
+
+@strong{(Please note: This section has not yet been updated for the latest
+net release.)}
+
+If you want a valid /etc set up (so "ls -l" will display correct
+user information for example) and if you are running NT (preferably
+with an NTFS file system), you should just need to create the /etc
+directory on the filesystem mounted as / and then use mkpasswd and
+mkgroup to create /etc/passwd and /etc/group respectively.  Since
+Windows 95/98's Win32 API is less complete, you're out of luck if
+you're running Windows 95/98.
+
+@subsection Why doesn't bash read my .bashrc file on startup?
+
+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.
+
+@subsection How can I get bash filename completion to be case insensitive?
+
+"shopt -s nocaseglob" should do the trick.
+
+@subsection Can I use paths/filenames containing spaces in them?
+
+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.
+
+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:
+@example
+	bash-2.03$ cd '/cygdrive/c/Program Files'
+@end example
+or
+@example
+	bash-2.03$ cd /cygdrive/c/Program\ Files
+@end example
+
+@subsection Why can't I cd into a shortcut to a directory?
+
+Cygwin does not follow MS Windows Explorer Shortcuts (*.lnk files).  It
+sees a shortcut as a regular file and this you cannot "cd" into it.
+
+Some people have suggested replacing the current symbolic link scheme
+with shortcuts.  The major problem with this is that .LNK files would
+then be used to symlink Cygwin paths that may or may not be valid
+under native Win32 non-Cygwin applications such as Explorer.
+
+@subsection I'm having basic problems with find.  Why?
+
+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.
+
+@subsection Why don't cursor keys work under Win95/Win98?
+
+@strong{(Please note: This section has not yet been updated for the latest
+net release.)}
+
+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're 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:
+
+@example
+keyb ru,,C:\WINDOWS\COMMAND\keybrd3.sys
+@end example
+
+(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. exUSSR users are of course knowledgable 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).
+
+@subsection Is it OK to have multiple copies of the DLL?
+
+You should only have one copy of the Cygwin DLL on your system.  If you
+have multiple versions, they will conflict and cause problems.
+
+If you get the error "shared region is corrupted" 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 @emph{all}
+Cygwin apps (including inetd) beforehand.
+
+@subsection Where can I find "more"?
+
+If you are looking for the "more" pager, you should use the "less" pager
+instead.
+
+@subsection Where can I find "which"?
+
+There is no "which" command with Cygwin.  However, you can use the bash
+shell builtin "type" which does something similar.
+
+@subsection How can I access other drives?
+
+You have some flexibility here.
+
+Cygwin has a builtin "cygdrive prefix" for drives that are not mounted.
+You can access any drive, say Z:, as '/cygdrive/z/'.
+
+In some applications (notably bash), you can use the familiar windows
+<drive>:/path/, using posix forward-slashes ('/') instead of 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:
+@example
+	bash-2.03$ cd C:/Windows
+	bash-2.03$ pwd
+        /cygdrive/c/Windows
+@end example
+and
+@example
+	bash-2.03$ cd C:/cygwin
+	bash-2.03$ pwd
+        /
+@end example
+for a default setup.  (You could also use backward-slashes in the
+Windows path, but these would have to be escaped from the shell.)
+
+@strong{Warning:} 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
+behaviour of Cygwin apps will vary depending on the posix path used to
+get there.
+
+You can avoid the ambiguity of Windows paths, and avoid typing
+"/cygdrive", by explicitly mounting drives to posix paths.  For example:
+@example
+	bash$ mkdir /c
+	bash$ mount c:/ /c
+	bash$ ls /c
+@end example
+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).
+
+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.
+
+@subsection How can I copy and paste into Cygwin console windows?
+
+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.
+
+Under Windows 9x, open the properties dialog of the console window.
+Select the Misc tab.  Uncheck Fast Pasting.  Check QuickEdit.
+
+@subsection What does "mount failed: Device or resource busy" mean?
+
+@strong{(Please note: This section has not yet been updated for the latest
+net release.)}
+
+This usually means that you are trying to mount to a location
+already in use by mount.  For example, if c: is mounted as '/'
+and you try to mount d: there as well, you will get this error
+message.  First "umount" the old location, then "mount" the new one and
+you should have better luck.
+
+If you are trying to umount '/' and are getting this message, you may
+need to run @code{regedit.exe} and change the "native" key for the '/'
+mount in one of the mount points kept under
+HKEY_CURRENT_USER/Software/Cygnus Solutions/CYGWIN.DLL setup/<version>
+where <version> is the latest registry version associated with the
+Cygwin library.
+
+@subsection How can I share files between Unix and Windows?
+
+During development, we have both Unix boxes running Samba and
+NT/Windows 95/98 machines.  We often build with cross-compilers
+under Unix 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.
+
+@subsection Are mixed-case filenames possible with Cygwin?
+
+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 @code{Makefile} and
+@code{makefile}.  WIN32 can't tell the difference between files with
+just different case, so the configuration fails.
+
+In releases prior to beta 16, mount had a special mixed case option
+which renamed files in such a way as to allow mixed case filenames.  We
+chose to remove the support when we rewrote the path handling code for
+beta 16.  The standard Windows apps -- explorer.exe,
+cmd.exe/command.com, etc. -- do not distinguish filenames that differed
+only in case, resulting in some (very) undesirable behavior.
+
+Sergey Okhapkin had maintained a mixed-case patch ('coolview') until
+about B20.1, but this has not been updated to recent versions of Cygwin.
+
+@subsection What about DOS special filenames?
+
+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
+@code{aux.sh}.  The perl configuration tries to make sure that
+@code{aux.sh} is there, but an operation on a file with the magic
+letters 'aux' in it will hang.
+
+@subsection When it hangs, how do I get it back?
+
+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.
+
+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.
+
+And, if all else fails, there's always the reset button/power switch.
+This should never be necessary under Windows NT.
+
+@subsection Why the weird directory structure?
+
+Why do /lib and /usr/lib (and /bin, /usr/bin) point to the same thing?
+
+Why use mounts instead of symbolic links?
+
+Can I use a disk root (e.g., C:\) as Cygwin root?  Why is this discouraged?
+
+After a new installation in the default location, your mount points will
+look something like this:
+
+@example
+Device              Directory           Type         Flags
+C:\cygwin\bin       /usr/bin            user         binmode
+C:\cygwin\lib       /usr/lib            user         binmode
+C:\cygwin           /                   user         binmode
+@end example
+
+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 @emph{really} know what you are doing.
+
+Various applications and packages may expect to be installed in /lib or
+/usr/lib (similarly /bin or /usr/bin).  Rather than distinguish 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.
+
+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.
+
+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.  @emph{So don't do this!}
+
+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?)
+
+@subsection How do anti-virus programs like Cygwin?
+
+Users have reported that McAfee (now NAI) VirusScan for NT (and others?) is
+incompatible with Cygwin.  This is because it tries to scan the
+newly loaded shared memory in the cygwin.dll, which can cause fork()s
+to fail, wreaking havoc on many of the tools.
+
+There are also 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.
+
+@subsection Why can't I run bash as a shell under NT Emacs?
+
+@strong{(Please note: This section has not yet been updated for the latest
+net release.)}
+
+Place the following code in your startup file and try again:
+
+@smallexample
+(load "comint")
+(fset 'original-comint-exec-1 (symbol-function 'comint-exec-1))
+(defun comint-exec-1 (name buffer command switches)
+  (let ((binary-process-input t)
+        (binary-process-output nil))
+    (original-comint-exec-1 name buffer command switches)))
+@end smallexample
+
+@subsection info error "dir: No such file or directory"
+
+Cygwin packages install their info documentation in the /usr/info
+directory.  But you need to create a @code{dir} file there before the
+standalone info program (probably @code{/usr/bin/info}) can be used to
+read those info files.  This is how you do it:
+@example
+	bash$ cd /usr/info
+	bash$ for f in *.info ; do install-info $f dir ; done
+@end example
+This may generate warnings:
+@example
+	install-info: warning: no info dir entry in `gzip.info'
+	install-info: warning: no info dir entry in `time.info'
+@end example
+The @code{install-info} command cannot parse these files, so you will
+have to add their entries to @code{/usr/info/dir} by hand.
+
+@subsection Why do I get a message saying Out of Queue slots?
+
+@strong{(Please note: This section has not yet been updated for the latest
+net release.)}
+
+"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).
+
+@subsection Why don't symlinks work on samba-mounted filesystems?
+
+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:
+
+@smallexample
+	map system = yes
+	create mask = 0775
+@end smallexample
+
+Note that the 0775 can be anything as long as the 0010 bit is set.
+
+@subsection Why does df report sizes incorrectly.
+
+@strong{(Please note: This section has not yet been updated for the latest
+net release.)}
+
+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?
+
+@subsection Has the screen program been ported yet?
+
+@strong{(Please note: This section has not yet been updated for the latest
+net release.)}
+
+Screen requires either unix domain sockets or fifoes.  Neither of
+them have been implemented in Cygwin yet.
+