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

1 files changed, 284 insertions, 0 deletions

diff --git a/winsup/doc/how-api.texinfo b/winsup/doc/how-api.texinfo
new file mode 100644
index 0000000..83fb7ce
--- /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.
+