# Cygwin API Questions

How does everything work?

There's a C library which provides a POSIX-style API. The applications are linked with it and voila - they run on Windows.

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.

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.

For a good overview of Cygwin, you may want to read the Cygwin User's Guide.

Are development snapshots for the Cygwin library available?

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 http://cygwin.com/snapshots/.

How is the DOS/Unix CR/LF thing handled?

Let's start with some background.

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.

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.

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.

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.

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 `O_BINARY` to the second argument of an `open` call, or `"b"` to second argument of an `fopen` call. You can also call `setmode (fd, O_BINARY)`. To select text mode add `O_TEXT` to the second argument of an `open` call, or `"t"` to second argument of an `fopen` call, or just call `setmode (fd, O_TEXT)`.

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 `/usr/lib` directory which, when linked to an executable, changes the default open modes of any file opened within the executed process itself. The files are

      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.

Linking against these object files does not 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 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.

Is the Cygwin library multi-thread-safe?

Yes.

There is also extensive support for 'POSIX threads', see the file `cygwin.din` for the list of POSIX thread functions provided.

How is fork() implemented?

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.

Here's how it works:

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.

How does wildcarding (globbing) work?

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 `LS *.EXE` from DOS, it will do what you might expect.

Beware: globbing uses `malloc`. If your application defines `malloc`, that will get used. This may do horrible things to you.

How do symbolic links work?

Cygwin knows of two ways to create symlinks.

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.

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.

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.

Why do some files, which are not executables have the 'x' type.

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.

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.

How secure is Cygwin in a multi-user environment?

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.

How do the net-related functions work?

The network support in Cygwin is supposed to provide the POSIX API, not the Winsock API.

There are differences between the semantics of functions with the same name under the API.

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.

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.

I don't want Unix sockets, how do I use normal Win32 winsock?

You don't. Look for the MingW project to port applications using native Win32/Winsock functions.

What version numbers are associated with Cygwin?

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 `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.7.1-2 is `cygwin1.dll`, major version 7, minor version 1, release 2.

The `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 `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. 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.

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 `/usr/include/cygwin/version.h` file.

Why isn't timezone set correctly?

(Please note: This section has not yet been updated for the latest net release.)

Did you explicitly call tzset() before checking the value of timezone? If not, you must do so.

Is there a mouse interface?

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.