diff options
Diffstat (limited to 'winsup/doc/faq-api.xml')
| -rw-r--r-- | winsup/doc/faq-api.xml | 353 |
1 files changed, 0 insertions, 353 deletions
diff --git a/winsup/doc/faq-api.xml b/winsup/doc/faq-api.xml deleted file mode 100644 index ad9ea72e8..000000000 --- a/winsup/doc/faq-api.xml +++ /dev/null @@ -1,353 +0,0 @@ -<!-- faq-api.xml --> -<qandaentry id="faq.api.everything"> -<question><para>How does everything work?</para></question> -<answer> - -<para>There's a C library which provides a Unix-style API. The -applications are linked with it and voila - they run on Windows. -</para> -<para>The aim is to add all the goop necessary to make your apps run on -Windows into the C library. Then your apps should run on Unix and -Windows with no changes at the source level. -</para> -<para>The C library is in a DLL, which makes basic applications quite small. -And it allows relatively easy upgrades to the Win32/Unix translation -layer, providing that DLL changes stay backward-compatible. -</para> -<para>For a good overview of Cygwin, you may want to read the paper on Cygwin -published by the Usenix Association in conjunction with the 2d Usenix NT -Symposium in August 1998. It is available in HTML format on the project -WWW site. -</para> -</answer></qandaentry> - -<qandaentry id="faq.api.snapshots"> -<question><para>Are development snapshots for the Cygwin library available?</para></question> -<answer> - -<para>Yes. They're made whenever anything interesting happens inside the -Cygwin library (usually roughly on a nightly basis, depending on how much -is going on). They are only intended for those people who wish to -contribute code to the project. If you aren't going to be happy -debugging problems in a buggy snapshot, avoid these and wait for a real -release. The snapshots are available from -<ulink url="http://cygwin.com/snapshots/">http://cygwin.com/snapshots/</ulink>. -</para> -</answer></qandaentry> - -<qandaentry id="faq.api.cr-lf"> -<question><para>How is the DOS/Unix CR/LF thing handled?</para></question> -<answer> - -<para>Let's start with some background. -</para> -<para>In UNIX, a file is a file and what the file contains is whatever the -program/programmer/user told it to put into it. In Windows, a file is -also a file and what the file contains depends not only on the -program/programmer/user but also the file processing mode. -</para> -<para>When processing in text mode, certain values of data are treated -specially. A \n (new line) written to the file will prepend a \r -(carriage return) so that if you `printf("Hello\n") you in fact get -"Hello\r\n". Upon reading this combination, the \r is removed and the -number of bytes returned by the read is 1 less than was actually read. -This tends to confuse programs dependent on ftell() and fseek(). A -Ctrl-Z encountered while reading a file sets the End Of File flags even -though it truly isn't the end of file. -</para> -<para>One of Cygwin's goals is to make it possible to easily mix Cygwin-ported -Unix programs with generic Windows programs. As a result, Cygwin opens -files in text mode as is normal under Windows. In the accompanying -tools, tools that deal with binaries (e.g. objdump) operate in Unix -binary mode and tools that deal with text files (e.g. bash) operate in -text mode. -</para> -<para>Some people push the notion of globally setting the default processing -mode to binary via mount point options or by setting the CYGWIN -environment variable. But that creates a different problem. In -binary mode, the program receives all of the data in the file, including -a \r. Since the programs will no longer deal with these properly for -you, you would have to remove the \r from the relevant text files, -especially scripts and startup resource files. This is a porter "cop -out", forcing the user to deal with the \r for the porter. -</para> -<para>It is rather easy for the porter to fix the source code by supplying the -appropriate file processing mode switches to the open/fopen functions. -Treat all text files as text and treat all binary files as binary. To be -specific, you can select binary mode by adding <literal>O_BINARY</literal> to -the second argument of an <literal>open</literal> call, or -<literal>"b"</literal> to second argument of an <literal>fopen</literal> call. -You can also call <literal>setmode (fd, O_BINARY)</literal>. -</para> -<para>Note that because the open/fopen switches are defined by ANSI, they -exist under most flavors of Unix; open/fopen will just ignore the switch -since they have no meaning to UNIX. -</para> -<para>Explanation adapted from mailing list email by Earnie Boyd -<earnie_boyd (at) yahoo.com>. -</para> -</answer></qandaentry> - -<qandaentry id="faq.api.threads"> -<question><para>Is the Cygwin library multi-thread-safe?</para></question> -<answer> - -<para>Yes. -</para> -<para>There is also extensive support for 'POSIX threads', see the file -<literal>cygwin.din</literal> for the list of POSIX thread functions provided. -</para> -</answer></qandaentry> - -<qandaentry id="faq.api.winnt"> -<question><para>Why is some functionality only supported in Windows NT?</para></question> -<answer> - -<para>Windows 9x: n. -32 bit extensions and a graphical shell for a 16 bit patch to an -8 bit operating system originally coded for a 4 bit microprocessor, -written by a 2 bit company that can't stand 1 bit of competition. -</para> -<para>But seriously, Windows 9x lacks most of the security-related calls and -has several other deficiencies with respect to its version of the Win32 -API. See the calls.texinfo document for more information as to what -is not supported in Win 9x. -</para> -</answer></qandaentry> - -<qandaentry id="faq.api.fork"> -<question><para>How is fork() implemented?</para></question> -<answer> - -<para>Cygwin fork() essentially works like a non-copy on write version -of fork() (like old Unix versions used to do). Because of this it -can be a little slow. In most cases, you are better off using the -spawn family of calls if possible. -</para> -<para>Here's how it works: -</para> -<para>Parent initializes a space in the Cygwin process table for child. -Parent creates child suspended using Win32 CreateProcess call, giving -the same path it was invoked with itself. Parent calls setjmp to save -its own context and then sets a pointer to this in the Cygwin shared -memory area (shared among all Cygwin tasks). Parent fills in the child's -.data and .bss subsections by copying from its own address space into -the suspended child's address space. Parent then starts the child. -Parent waits on mutex for child to get to safe point. Child starts and -discovers if has been forked and then longjumps using the saved jump -buffer. Child sets mutex parent is waiting on and then blocks on -another mutex waiting for parent to fill in its stack and heap. Parent -notices child is in safe area, copies stack and heap from itself into -child, releases the mutex the child is waiting on and returns from the -fork call. Child wakes from blocking on mutex, recreates any mmapped -areas passed to it via shared area and then returns from fork itself. -</para> -</answer></qandaentry> - -<qandaentry id="faq.api.globbing"> -<question><para>How does wildcarding (globbing) work?</para></question> -<answer> - -<para>If the DLL thinks it was invoked from a DOS style prompt, it runs a -`globber' over the arguments provided on the command line. This means -that if you type <literal>LS *.EXE</literal> from DOS, it will do what you might -expect. -</para> -<para>Beware: globbing uses <literal>malloc</literal>. If your application defines -<literal>malloc</literal>, that will get used. This may do horrible things to you. -</para> -</answer></qandaentry> - -<qandaentry id="faq.api.symlinks"> -<question><para>How do symbolic links work?</para></question> -<answer> - -<para>Cygwin knows of two ways to create symlinks. -</para> -<para>The old method is the only valid one up to but not including version 1.3.0. -If it's enabled (from 1.3.0 on by setting `nowinsymlinks' in the environment -variable CYGWIN) Cygwin generates link files with a magic header. When you -open a file or directory that is a link to somewhere else, it opens the file -or directory listed in the magic header. Because we don't want to have to -open every referenced file to check symlink status, Cygwin marks symlinks -with the system attribute. Files without the system attribute are not -checked. Because remote samba filesystems do not enable the system -attribute by default, symlinks do not work on network drives unless you -explicitly enable this attribute. -</para> -<para>The new method which is introduced with Cygwin version 1.3.0 is enabled -by default or if `winsymlinks' is set in the environment variable CYGWIN. -Using this method, Cygwin generates symlinks by creating Windows shortcuts. -Cygwin created shortcuts have a special header (which is in that way never -created by Explorer) and the R/O attribute set. A DOS path is stored in -the shortcut as usual and the description entry is used to store the POSIX -path. While the POSIX path is stored as is, the DOS path has perhaps to be -rearranged to result in a valid path. This may result in a divergence -between the DOS and the POSIX path when symlinks are moved crossing mount -points. When a user changes the shortcut, this will be detected by Cygwin -and it will only use the DOS path then. While Cygwin shortcuts are shown -without the ".lnk" suffix in `ls' output, non-Cygwin shortcuts are shown -with the suffix. However, both are treated as symlinks. -</para> -<para>Both, the old and the new symlinks can live peacefully together since Cygwin -treats both as symlinks regardless of the setting of `(no)winsymlinks' in -the environment variable CYGWIN. -</para> -</answer></qandaentry> - -<qandaentry id="faq.api.executables"> -<question><para>Why do some files, which are not executables have the 'x' type.</para></question> -<answer> - -<para>When working out the Unix-style attribute bits on a file, the library -has to fill out some information not provided by the WIN32 API. -</para> -<para>It guesses that files ending in .exe and .bat are executable, as are -ones which have a "#!" as their first characters. -</para> -</answer></qandaentry> - -<qandaentry id="faq.api.secure"> -<question><para>How secure is Cygwin in a multi-user environment?</para></question> -<answer> - -<para>As of version 1.5.13, the Cygwin developers are not aware of any feature -in the cygwin dll that would allow users to gain privileges or to access -objects to which they have no rights under Windows. However there is no -guarantee that Cygwin is as secure as the Windows it runs on. Cygwin -processes share some variables and are thus easier targets of denial of -service type of attacks. -</para> -</answer></qandaentry> - -<qandaentry id="faq.api.net-functions"> -<question><para>How do the net-related functions work?</para></question> -<answer> - -<para><emphasis role='bold'>(Please note: This section has not yet been updated for the latest net release.)</emphasis> -</para> -<para>The network support in Cygwin is supposed to provide the Unix API, not -the Winsock API. -</para> -<para>There are differences between the semantics of functions with the same -name under the API. -</para> -<para>E.g., the select system call on Unix can wait on a standard file handles -and handles to sockets. The select call in Winsock can only wait on -sockets. Because of this, cygwin.dll does a lot of nasty stuff behind -the scenes, trying to persuade various Winsock/win32 functions to do what -a Unix select would do. -</para> -<para>If you are porting an application which already uses Winsock, then -using the net support in Cygwin is wrong. -</para> -<para>But you can still use native Winsock, and use Cygwin. The functions -which cygwin.dll exports are called 'cygwin_<name>'. There -are a load of defines which map the standard Unix names to the names -exported by the DLL-- check out include/netdb.h: -</para> -<screen> -..etc.. -void cygwin_setprotoent (int); -void cygwin_setservent (int); -void cygwin_setrpcent (int); -..etc.. -#ifndef __INSIDE_CYGWIN_NET__ -#define endprotoent cygwin_endprotoent -#define endservent cygwin_endservent -#define endrpcent cygwin_endrpcent -..etc.. -</screen> - -<para>The idea is that you'll get the Unix->Cygwin mapping if you include -the standard Unix header files. If you use this, you won't need to -link with libwinsock.a - all the net stuff is inside the DLL. -</para> -<para>The mywinsock.h file is a standard winsock.h which has been hacked to -remove the bits which conflict with the standard Unix API, or are -defined in other headers. E.g., in mywinsock.h, the definition of -struct hostent is removed. This is because on a Unix box, it lives in -netdb. It isn't a good idea to use it in your applications. -</para> -<para>As of the b19 release, this information may be slightly out of date. -</para> -</answer></qandaentry> - -<qandaentry id="faq.api.winsock"> -<question><para>I don't want Unix sockets, how do I use normal Win32 winsock?</para></question> -<answer> - -<para>To use the vanilla Win32 winsock, you just need to #define __USE_W32_WINSOCK -and #include "windows.h" (or "winsock2.h" at the top of your source file(s). You may -find it easier to add "-D__USE_W32_WINSOCK" to the CFLAGS settings in your makefile, -if you are using one, as this will then apply to all your source files. It is also -worth using "#define WIN32_LEAN_AND_MEAN" before you include the windows header file, -as this will prevent it from pulling in lots of header files for all sorts of unrelated -windows APIs when all you want is the Winsock definitions; again, this could be set -for the entire project in your CFLAGS. -</para><para> -You'll also need to add -lwsock32 to the compiler's command line (or the makefile's -list of link libs) so that 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> - |