330 lines
15 KiB
XML
330 lines
15 KiB
XML
<?xml version="1.0" encoding='UTF-8'?>
|
|
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
|
|
|
|
<qandadiv id="faq.api">
|
|
<title>Cygwin API Questions</title>
|
|
|
|
<!-- 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 cygutils 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>
|
|
</qandadiv>
|