diff options
Diffstat (limited to 'winsup/doc/faq-api.xml')
| -rw-r--r-- | winsup/doc/faq-api.xml | 322 |
1 files changed, 0 insertions, 322 deletions
diff --git a/winsup/doc/faq-api.xml b/winsup/doc/faq-api.xml deleted file mode 100644 index ff6ef2052..000000000 --- a/winsup/doc/faq-api.xml +++ /dev/null @@ -1,322 +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 POSIX-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 (ideally) run on POSIX -systems (Unix/Linux) 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/POSIX translation -layer, providing that DLL changes stay backward-compatible. -</para> -<para>For a good overview of Cygwin, you may want to read the Cygwin -User's Guide. -</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>On POSIX systems, 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, NL) written to the file will prepend a \r -(carriage return, CR) 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 mix Cygwin-ported -POSIX programs with generic Windows programs. As a result, Cygwin allows -to open files in text mode. In the accompanying tools, tools that deal -with binaries (e.g. objdump) operate in POSIX binary mode and many (but -not all) tools that deal with text files (e.g. bash) operate in text mode. -There are also some text tools which operate in a mixed mode. They read -files always in text mode, but write files in binary mode, or they write -in the mode (text or binary) which is specified by the underlying mount -point. For a description of mount points, see the Cygwin User's Guide. -</para> -<para>Actually there's no really good reason to do text mode processing -since it only slows down reading and writing files. Additionally many -Windows applications can deal with POSIX \n line endings just fine -(unfortunate exception: Notepad). So we suggest to use binary mode -as much as possible and only convert files from or to DOS text mode -using tools specifically created to do that job, for instance, d2u and -u2d from the util-linux package. -</para> -<para>It is rather easy for the porter of a Unix package 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>. To select text mode add -<literal>O_TEXT</literal> to the second argument of an <literal>open</literal> -call, or <literal>"t"</literal> to second argument of an -<literal>fopen</literal> call, or just call -<literal>setmode (fd, O_TEXT)</literal>. -</para> -<para>You can also avoid to change the source code at all by linking -an additional object file to your executable. Cygwin provides various -object files in the <filename>/usr/lib</filename> directory which, -when linked to an executable, changes the default open modes of any -file opened within the executed process itself. The files are -<screen> - binmode.o - Open all files in binary mode. - textmode.o - Open all files in text mode. - textreadmode.o - Open all files opened for reading in text mode. - automode.o - Open all files opened for reading in text mode, - all files opened for writing in binary mode. -</screen> -</para> -<para> -<note> - Linking against these object files does <emphasis>not</emphasis> change - the open mode of files propagated to a process by its parent process, - for instance, if the process is part of a shell pipe expression. -</note> -</para> -<para>Note that of the above flags only the "b" fopen flags are defined by -ANSI. They exist under most flavors of Unix. However, using O_BINARY, -O_TEXT, or the "t" flag is non-portable. -</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.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 default method 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 or use the second method to create symlinks. -</para> - -<para>The second method is enabled 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, types of 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 POSIX-style attribute bits on a file stored on -certain filesystems (FAT, FAT32), the library has to fill out some information -not provided by these filesystems. -</para> -<para>It guesses that files ending in .exe and .bat are executable, as are -ones which have a "#!" as their first characters. This guessing doesn't -take place on filesystems providing real permission information (NTFS, NFS), -unless you switch the permission handling off using the mount flag "noacl" -on these filesystems. -</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>The network support in Cygwin is supposed to provide the POSIX 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 POSIX select system call can wait on a standard file handles -and handles to sockets. The select call in Winsock can only wait on -sockets. Because of this, the 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 -porting the application to Cygwin means to port the application to using -the POSIX net functions. You should never mix Cygwin net functions with -direct calls to Winsock functions. If you use Cygwin, use the POSIX API. -</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>You don't. Look for the MingW project to port applications using -native Win32/Winsock functions. -</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.7.1-2 is <literal>cygwin1.dll</literal>, major version 7, minor -version 1, 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. 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>If you're using X then use the X API to handle mouse events. -In a Windows console window you can enable and capture mouse events -using the xterm escape sequences for mouse events. -</para> -</answer></qandaentry> - |