354 lines
16 KiB
XML
354 lines
16 KiB
XML
<!-- 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>
|
|
|