diff options
Diffstat (limited to 'winsup/doc/how-api.texinfo')
| -rw-r--r-- | winsup/doc/how-api.texinfo | 59 |
1 files changed, 34 insertions, 25 deletions
diff --git a/winsup/doc/how-api.texinfo b/winsup/doc/how-api.texinfo index 3ae60bbcb..e95d1a8ef 100644 --- a/winsup/doc/how-api.texinfo +++ b/winsup/doc/how-api.texinfo @@ -11,11 +11,11 @@ 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. +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 +Symposium in August 1998. It is available in HTML format on the project WWW site. @subsection Are development snapshots for the Cygwin library available? @@ -43,14 +43,14 @@ 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 +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. 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 +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. @@ -110,7 +110,7 @@ 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 +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 @@ -167,7 +167,7 @@ the environment variable CYGWIN. @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 +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 @@ -181,7 +181,7 @@ 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. +privilege of another cygwin program running on the machine. This is because cygwin has shared state that is accessible by all processes. @@ -199,9 +199,9 @@ 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 +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 +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 @@ -210,7 +210,7 @@ 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: +exported by the DLL-- check out include/netdb.h: @example ..etc.. @@ -227,7 +227,7 @@ void cygwin_setrpcent (int); 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. +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 @@ -249,15 +249,23 @@ 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. +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 @code{cygwin1.dll} 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 @code{cygwin1.dll}, major version 5, minor version +10, release 2. + +The @code{cygwin1.dll} 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 @code{cygwin1.dll} 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). There are also Cygwin API major and minor numbers. The major number tracks important non-backward-compatible interface changes to the API. @@ -266,13 +274,14 @@ 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 +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 +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. +This has been @code{mounts v2} for a long time. For more exciting Cygwin +version number details, check out the @code{/usr/include/cygwin/version.h} +file. @subsection Why isn't _timezone set correctly? |