Update to switch FAQ from texinfo to DocBook.

1 files changed, 348 insertions, 0 deletions

diff --git a/winsup/doc/faq-api.xml b/winsup/doc/faq-api.xml
new file mode 100644
index 000000000..1a9c6c517
--- /dev/null
+++ b/winsup/doc/faq-api.xml
@@ -0,0 +1,348 @@
+<!-- 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
+&lt;earnie_boyd (at) yahoo.com&gt;.
+</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_&lt;name&gt;'.  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-&gt;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>
+