Contents|Index|Previous|Next
Windows development with Cygwin: a Win32 porting layer

CygwinTM, a full-featured Win32 porting layer for UNIX applications, is compatible with all Win32 hosts (currently, these are Microsoft’s Windows NT/95/98 systems).

The following documentation discusses porting the GNU development tools to the Win32 host while exploring the development and architecture of the Cygwin library.

Cygwin was invented in 1995 by Cygnus as part of the answer to the question of how to port the GNU development tools to a Win32 host. The Win32-hosted GNUPro compiler tools that use the Cygwin library are available for a variety of embedded processors as well as a native version for writing Win32 applications.
By basing this technology on the GNU tools, Cygnus provides developers with a high-performance, feature-rich 32-bit code development environment, including a graphical source-level debugger, Cygnus InsightTM (see Working with Cygnus Insight, the visual debugger).

Cygwin is a dynamically-linked library (DLL) that provides a large subset of the system calls in common UNIX implementations. The current release includes all POSIX.1/90 calls except for setuid and mkfifo, all ANSI C standard calls, and many common BSD and SVR4 services (including Berkeley sockets). See also Compatibility issues with Cygwin.

When the Free Software Foundation (FSF) first wrote the GNU tools in the mid-1980s, portability among existing and future UNIX operating systems was an important goal. By mid-1995, the tools had been ported to 16-bit DOS using the GO32 32-bit extender by DJ Delorie (maintainer of the DJGPP Project; see http://www.delorie.com/djgpp). However, no one had completed a native 32-bit port for Windows NT and 95/98. It seemed likely that the demand for Win32-hosted native and cross-development tools would soon be large enough to justify the development costs involved. This project’s fulfillment and its ongoing challenges are testaments to the growth that Cygwin provides; for the individuals who have been responsible for creating the Cygwin porting layer; see Acknowledgements for Cygwin.
 
 

Porting UNIX tools to Win32

The first step in porting compiler tools to Win32 was to enhance them so that they could generate and interpret Win32 native object files, using Microsoft’s Portable Executable (PE) format. This proved to be relatively straightforward because of similarities to the Common Object File Format (COFF), which the GNU tools already supported. Most of these changes were confined to the Binary File Descriptor (BFD) library and to the linker.

In order to support the Win32 Application Programming Interface (API), we extended the capabilities of the binary utilities to handle Dynamic-Linked Libraries (DLLs). After creating export lists for the specific Win32 API DLLs that are shipped with Win32 hosts, the tools were able to generate static libraries that executables could use to gain access to Win32 API functions. Because of redistribution restrictions on Microsoft’s Win32 API header files, we wrote our own Win32 header files from scratch on an as-needed basis. Once this work was completed, we were able to build UNIX-hosted cross-compilers capable of generating valid PE executables that ran on Win32 systems. See also Using GCC with Cygwin.

The next task was to port the compiler tools themselves to Win32. Previous experiences using Microsoft Visual C++ to port GDB convinced us to find another means for bootstrapping the full set of tools. In addition to wanting to use our own compiler technology, we wanted a portable build system. The GNU development tools’configuration and build procedures require a large number of additional UNIX utilities not available on Win32 hosts. So we decided to use UNIX-hosted cross-compilers to build our Win32-hosted native and cross-development tools. It made perfect sense to do this since we were successfully using a nearly identical technique to build our DOS-hosted products.

The next obstacle to overcome was the many dependencies on UNIX system calls in the sources, especially in the GNU debugger GDB. While we could have rewritten sizable portions of the source code to work within the context of the Win32 API (as was done for the DOS-hosted tools), this would have been prohibitively time-consuming. Worse, we would have introduced conditionalized code that would have been expensive to maintain in the long run. Instead, Cygnus developers took a substantially different approach by writing Cygwin. See also Debugging Cygwin programs.

Initial goals of Cygwin

The following documentation discusses the work in developing the Cygwin tools.

The original goal of Cygwin was simply to get the development tools working. Completeness with respect to POSIX.12 and other relevant UNIX standards was not a priority. Part of a definition of “working native tools” is having a build environment similar enough to UNIX to support rebuilding the tools themselves on the host system, a process we call self-hosting. The typical configuration procedure for a GNU tool involves running configure, a complex Bourne shell script that determines information about the host system. The script then uses that information to generate the Makefiles used to build the tool on the host in question.

This configuration mechanism is needed under UNIX because of the large number of varying versions of UNIX. If Microsoft continues to produce new variants of the Win32 API as it releases new versions of its operating systems, it may prove to be quite valuable on the Win32 host as well.

The need to support this configuration procedure added the requirement of supporting user tools such as sh, make, file utilities (such as ls and rm), text utilities (such as cat, tr), and shell utilities (such as echo, date, uname, sed, awk, find, xargs, tar, and gzip, among many others). Previously, most of these user tools had only been built natively (on the host on which they would run). As a result, we had to modify their configure scripts to be compatible with cross-compilation.

Other than making the necessary configuration changes, we wanted to avoid Win32-specific changes since the UNIX compatibility was to be provided by Cygwin as much as possible. While we knew this would be a sizable amount of work, there was more to gain than just achieving self-hosting of the tools. Supporting the configuration of the development tools would also provide an excellent method of testing the Cygwin library.

Although we were able to build working Win32-hosted toolchains with cross-compilers relatively soon after the birth of Cygwin, it took much longer than we expected before the tools could reliably rebuild themselves on the Win32 host because of the many complexities involved.

Harnessing the power of the web for Cygwin

Instead of keeping the Cygwin technology proprietary and developing it in-house, Cygnus chose to make it publicly available under the terms of the GNU General Public License (GPL), the traditional license for the GNU tools. Since its inception, we have made a new “GNU-Win32 beta release” available using ftp over the Internet every three or four months. Each release includes binaries of Cygwin and the development tools, coupled with the source code needed to build them. Unlike standard Cygnus products, these free releases come without any assurances of quality or support, although we provide a mailing list that is used for discussion and feedback.

In retrospect, making the technology freely available was a good decision because of the high demand for quality 32-bit native tools in the Win32 arena, as well as significant additional interest in a UNIX portability layer like Cygwin. While far from perfect, the beta releases are good enough for many people. They provide us with tens of thousands of interested developers who are willing to use and test the tools. A few of them are even willing to contribute code fixes and new functionality to the library. As of the last public release, developers on the Net had written or improved a significant portion of the library, including important aspects such as support for UNIX signals and the TTY/PTY calls.
In order to spur as much Net participation as possible, the Cygwin project features an open development model. Cygnus makes weekly source snapshots available to the general public in addition to the periodic full GNU-Win32 releases. A mailing lists for developers facilitates discussion of proposed changes to the library.

In addition to the GPL version of Cygwin, Cygnus provides a commercial license for supported customers of the native Win32 GNUPro tools.

The Cygwin architecture

The following documentation discusses the architecture underlying the Cygwin tools.
 


When a binary linked against the library is executed, the Cygwin DLL is loaded into the application’s text segment. Because we are trying to emulate a UNIX kernel that needs access to all processes running under it, the first Cygwin DLL to run creates shared memory areas that other processes using separate instances of the DLL can access. This is used to keep track of open file descriptors and assist fork and exec, among other purposes. In addition to the shared memory regions, every process also has a per-process structure that contains information such as process ID, user ID, signal masks, and other similar process-specific information.

The DLL is implemented using the Win32 API, allowing it to run on all Win32 hosts. Because processes run under the standard Win32 subsystem, they can access both the UNIX compatibility calls provided by Cygwin as well as any of the Win32 API calls. This gives the programmer complete flexibility in designing the structure of their program in terms of the APIs used. For example, a project might require a Win32-specific GUI using Win32 API calls on top of a UNIX back-end that uses Cygwin.

Early on in the development process, an important design decision was made to overcome the necessity to strictly adhere to existing UNIX standards like POSIX, if it was not possible or if it would significantly diminish the usability of the tools on the Win32 platform (ISO/IEC 9945-1:1996 [ANSI/IEEE Std 1003.1, 1996 Edition]; POSIX Part 1: System Application Program Interface [API/C Language]). In many cases, an environment variable can be set to override the default behavior and force standards compliance.

While Windows 95 and Windows 98 are similar enough to each other that developers can safely ignore the distinction when implementing Cygwin, Windows NT is an extremely different operating system. For this reason, whenever the DLL is loaded, the library checks which operating system is active so that it can act accordingly. In some cases, the Win32 API is only different for historical reasons. In this situation, the same basic functionality is available under 95/98 and NT, although the method used to gain this functionality differs. A trivial example is in our implementation of uname, the library examines the sysinfo.wProcessorLevel structure member to determine the processor type used for Windows 95/98. This field is not supported in NT, which has its own operating system-specific structure member called sysinfo.wProcessorLevel.

Other differences between NT and 95/98 are much more fundamental in nature. The best example is that only NT provides a security model.

Windows NT includes a sophisticated security model based on Access Control Lists (ACLs). Although some modern UNIX operating systems include support for ACLs, Cygwin maps Win32 file ownership and permissions to the more standard, older UNIX model. The chmod call maps UNIX-style permissions back to the Win32 equivalents. Because many programs expect to be able to find the /etc/passwd and /etc/group files, we provide utilities that can be used to construct them from the user and group information provided by the operating system.

Under Windows NT, the administrator is permitted to chown files. There is currently no mechanism to support the setuid concept or API call. Although Cygnus hopes to support this functionality at some point in the future, in practice, the programs that have ported have not needed it.

Under Windows 95/98, the situation is considerably different. Since a security model is not provided, Cygwin fakes file ownership by making all files look like they are owned by a default user and group ID. As under NT, file permissions can still be determined by examining their read/write/execute status. Rather than return an unimplemented error, under Windows 95/98, the chown call succeeds immediately without actually performing any action. This is appropriate since essentially all users jointly own the files when no concept of file ownership exists.

It is important that we discuss the implications of our kernel, using shared memory areas to store information about Cygwin processes. Because these areas are not yet protected in any way, a malicious user could perhaps modify them to cause unexpected behavior in Cygwin processes. While this is not a new problem under Windows 95/98 (because of the lack of operating system security), it does constitute a security hole under Windows NT. This is because one user could affect the Cygwin programs run by another user by changing the shared memory information in ways that they could not in a more typical WinNT program. For this reason, it is not appropriate to use Cygwin in high-security applications. In practice, this will not be a major problem for most uses of the library.

Files and filetypes for Cygwin

Cygwin supports both Win32- and POSIX-style paths, using either forward or back slashes as the directory delimiter. Paths coming into the DLL are translated from Win32 to POSIX as needed. As a result, the library believes that the file system is a POSIX-compliant one, translating paths back to Win32 paths whenever it calls a Win32 API function. UNC pathnames (Universal Naming Conventions, which are paths that start with two slashes) are supported. See also Cygwin’s compatibility with POSIX.1 standards.

The layout of this POSIX view of the Windows file system space is stored in the Windows registry. While the slash (‘/’) directory points to the system partition by default, this is easy to change with the Cygwin mount utility. In addition to selecting the slash partition, it allows mounting arbitrary Win32 paths into the POSIX file system space. Many people use the utility to mount each drive letter under the slash partition (that is, C:\ to /c, D:\ to /d, and so forth).

The library exports several Cygwin-specific functions that can be used by external programs to convert a path or path list from Win32 toPOSIX or vice versa. Shell scripts and Makefiles cannot call these functions directly. Instead, they can do the same path translations by executing the cygpath utility.

Win32 file systems are case preserving but case insensitive. Cygwin does not currently support case distinction because, in practice, few UNIX programs actually rely on it. While we could mangle file names to support case distinction, this would add unnecessary overhead to the library and make it more difficult for non-Cygwin applications to access those files.

Symbolic links are emulated by files containing a magic cookie followed by the path to which the link points. They are marked with the System attribute so that only files with that attribute have to be read to determine whether or not the file is a symbolic link. Hard links are fully supported under Windows NT on NTFS file systems. On a FAT file system, the call falls back to copying the file, a strategy that works in many cases.

The inode number for a file is calculated by hashing its full Win32 path. The inode number generated by the stat call always matches the one returned in d_ino of the dirent structure. It is worth noting that the number produced by this method is not guaranteed to be unique. However, we have not found this to be a significant problem because of the low probability of generating a duplicate inode number.

Text mode and binary bode interoperability with Cygwin

Interoperability with other Win32 programs such as text editors was critical to the success of the port of the development tools. Most Cygnus customers upgrading from the older DOS-hosted toolchains expected the new Win32-hosted ones to continue to work with their old development sources.

Since UNIX and Win32 use different end-of-line terminators in text files, consequently, carriage-return newlines have to be translated by Cygwin into a single newline when reading in text mode. The Ctrl+z character is interpreted as a valid end-of-file character for a similar reason.

This solution addresses the compatibility requirement at the expense of violating the POSIX standard that states that text and binary mode will be identical. Consequently, processes that attempt to lseek through text files can no longer rely on the number of bytes read as an accurate indicator of position in the file. For this reason, an environment variable can be set to override this behavior. See also Cygwin’s compatibility with POSIX.1 standards, Environment variables for Cygwin and Text and binary modes.

ANSI C library for Cygwin

We chose to include Cygnus’ own existing ANSI C library, newlib (ISO/IEC 9899:1990, Programming Languages [C]), as part of the library, rather than write all of the GNU C libraries and math calls from scratch. newlib is a BSD-derived ANSI C library, previously only used by cross-compilers for embedded systems development.

The reuse of existing free implementations of such things as the glob, regexp, and getopt libraries saved considerable effort. In addition, Cygwin uses Doug Lea’s free malloc implementation that successfully balances speed and compactness. The library accesses the malloc calls, using an exported function pointer. This makes it possible for a Cygwin process to provide its own malloc if required.

For more information, see Cygwin’s compatibility with ANSI standards.

Process creation for Cygwin

The following documentation discusses the process in the API with Cygwin tools.
 

The fork call in Cygwin is particularly interesting because it does not map well on top of the Win32 API. This makes it very difficult to implement. Currently, the Cygwin fork is a non-copy-on-write implementation similar to what was present in early versions of UNIX.

The first thing that happens when a parent process forks a child process is that the parent initializes a space in the Cygwin process table for the child. It then creates a suspended child process using the Win32 CreateProcess call. Next, the parent process calls setjmp to save its own context and sets a pointer to this in a Cygwin shared memory area (shared among all Cygwin tasks). It then fills in the child’s .data and .bss sections by copying from its own address space into the suspended child’s address space. After the child’s address space is initialized, the child is run while the parent waits on a mutex. The child discovers it has been forked and longjumps using the saved jump buffer. The child then sets the mutex the parent is waiting on and blocks on another mutex. This is the signal for the parent to copy its stack and heap into the child, after which it releases the mutex the child is waiting on and returns from the fork call. Finally, the child wakes from blocking on the last mutex, recreates any memory-mapped areas passed to it from the shared area, and returns from fork itself.

While we have some ideas as to how to speed up our fork implementation by reducing the number of context switches between the parent and child process, fork will almost certainly always be inefficient under Win32. Fortunately, in most circumstances, the spawn family of calls provided by Cygwin can be substituted for a fork/exec pair with only a little effort. These calls map cleanly on top of the Win32 API. As a result, they are much more efficient. Changing the compiler’s driver program to call spawn instead of fork was a trivial change and increased compilation speeds by 20-30% in our tests.

However, spawn and exec present their own set of difficulties. Because there is no way to do an actual exec under Win32, Cygwin has to invent its own Process IDs (PIDs). As a result, when a process performs multiple exec calls, there will be multiple Windows PIDs associated with a single Cygwin PID. In some cases, stubs of each of these Win32 processes may linger, waiting for their Cygwin process to exit.

Signals with Cygwin

When a Cygwin process starts, the library starts a secondary thread for use in signal handling. This thread waits for Windows events used to pass signals to the process. When a process notices it has a signal, it scans its signal bitmask and handles the signal in the appropriate fashion.

Several complications in the implementation arise from the fact that the signal handler operates in the same address space as the executing program. The immediate consequence is that Cygwin system functions are interruptible unless special care is taken to avoid this. We go to some lengths to prevent the sig_send function that sends signals from being interrupted. In the case of a process sending a signal to another process, we place a mutex around sig_send such that sig_send will not be interrupted until it has completely finished sending the signal.
In the case of a process sending itself a signal, we use a separate semaphore/event pair instead of the mutex. sig_send starts by reset
ting the event and incrementing the semaphore that flags the signal handler to process the signal. After the signal is processed, the signal handler signals the event that it is done. This process keeps intraprocess signals synchronous, as required by POSIX. Most standard UNIX signals are provided. Job control works as expected in shells that support it.

Sockets with Cygwin

Socket-related calls in Cygwin simply call the functions by the same name in Winsock, Microsoft’s implementation of Berkeley sockets. Only a few changes were needed to match the expected UNIX semantics; one of the most troublesome differences was that Winsock must be initialized before the first socket function is called. As a result, Cygwin has to perform this initialization when appropriate. In order to support sockets across fork calls, child processes initialize Winsock if any inherited file descriptor is a socket.

Unfortunately, implicitly loading DLLs at process startup is usually a slow affair. Because many processes do not use sockets, Cygwin explicitly loads the Winsock DLL the first time it calls the Winsock initialization routine. This single change sped up GNU configure times by 30%.

The select function with Cygwin

The UNIX select function is another call that does not map cleanly on top of the Win32 API. Much to our dismay, we discovered that the Win32 select in Winsock only worked on socket handles. Our implementation allows select to function normally when given different types of file descriptors (such as sockets, pipes, handles, and a custom /dev/windows windows messages pseudo-device).

Upon entry into the select function, the first operation is to sort the file descriptors into the different types. There are then two cases to consider.
 

Performance issues with Cygwin

Early on in the development process, correctness was almost the entire emphasis and, as Cygwin became more complete, performance became a much important issue. It was known that the tools ran much more slowly under Win32 than under Linux on the same machine, but it was not clear at all whether to attribute this to differences in the operating systems or to inefficiencies in Cygwin.
The lack of a working profiler has made analyzing Cygwin’s performance particularly difficult. Although the latest version of the library includes real itimer support, we have not yet found a way to implement virtual itimers. This is the most reliable way of obtaining profiling data since concurrently running processes aren’t likely to skew the results. We will soon have a combination of the GCC compiler and the GNU profile analysis tool, gprof, working with real itimer support which will help a great deal in optimizing Cygwin.

Even without a profiler, we knew of several areas inside Cygwin that definitely needed a fresh approach. While we rewrote those sections of code, we used the speed of configuring the tools under Win32 as the primary performance measurement. This choice made sense because we knew process creation speed was especially poor, something that the GNU configure process stresses.

These performance adjustments made it possible to configure completely the development tools under NT with Cygwin in only 10 minutes and complete the build in just under an hour on a dual Pentium Pro 200 system with 128 MB of RAM. This is reasonably competitive with the time taken to complete this task under a typical UNIX operating system running on an identical machine.

Ported software with Cygwin

In addition to being able to configure and build most GNU software, several other significant packages have been successfully ported to the Win32 host using the Cygwin library. Following is a list of some of the more interesting ones (most are not included in the distributions):

Typically, the only necessary source code modification involves specifying binary mode to open calls as appropriate. Because the Win32 compiler always generates executables that end in the standard .exe suffix, it is also often necessary to make minor modifications to makefiles so that make will expect the newly built executables to end with the suffix.

Future work for Cygwin

Standards conformance is becoming a more important focus. Previous work includes getting all POSIX.1/90 calls implemented; except for mkfifo and setuid, they have been. X/Open Release 4 conformance ( see the X/Open Release 4 CAE Specification, System Interfaces and Headers, Issue 4, Vol. 2, X/Open Co, Ltd., 1994) may be a desirable goal, but it is not yet implemented. While the current version of the library passes most of the NIST POSIX test suite (NIST POSIX test suite; see http://www.itl.nist.gov/div897/ctg/posix_form.htm), it performs poorly with respect to mimicking the UNIX security model, so there is still room for improvement. When considering how to implement the setuid functionality, there must be a secure alternative to the library’s usage of the shared memory areas.

Cygwin does not yet support applications that use multiple Windows threads, even though the library itself is multi-threaded. This shortcoming through the use of locks at strategic points in the DLL is desired, as well as creating support for POSIX threads.

Although Cygwin allows the GNU development tools that depend heavily on UNIX semantics to run successfully on Win32 hosts, it is not always desirable to use it. A program using a perfect implementation of the library would still incur a noticeable amount of overhead. As a result, an important future direction involves modifying the compiler so that it can optionally link against the Microsoft DLLs that ship with both Win32 operating systems, instead of Cygwin. This will give developers the ability to choose whether or not to use Cygwin on a per-program basis.

Proprietary alternatives to Cygwin

In developing Cygwin, alternatives to writing a library either did not exist or were not mature enough for the intended purposes.

Today, there are three proprietary alternatives to Cygwin, as the following documentation describes.

The lack of source code, coupled with the licensing fees associated with each of these commercial offerings, might still have required writing a library if there was the same challenge of porting today.

Acknowledgments for Cygwin

There are many individuals who helped create Cygwin: Steve Chamberlain (who wrote the original implementation of the library), Jeremy Allison, Doug Evans, Christopher Faylor, Philippe Giacinti, Tim Newsham, Sergey Okhapkin, Ian Taylor, Eric Bachalo, Chip Chapin, Kathleen Jones, Robert Richardson, Stan Shebs, Sonya Smallets, Ethan Solomita, and Stephan Walli.
 

Compatibility issues with Cygwin

The following documentation discuses the compatibility issues with Cygwin porting layer tools and the Cygwin library and its functionality.

Cygwin’s compatibility with ANSI standards

The following functions are compatible with ANSI standards.

Cygwin’s compatibility with POSIX.1 standards

The following functions are compatible with POSIX.1.
setuid and setgid always return ENOSYS.
link will copy the file if it can’t implement a true symbolic link. Currently, symbolic links work, if at all, only under Windows NT.
chown always returns 0.
fcntl doesn’t support F_GETLK ; it returns -1 and sets errno to ENOSYS.
lseek only works properly on binary files.

Cygwin’s compatibility with other miscellaneous standards

The following functions are compatible with miscellaneous other standards.
Of these networking calls, rexec, rcmd and rresvport are implemented in MS IP stack but may not be implemented in other vendor stacks.
initgroups does nothing.
chroot, mknod, settimeofday, and vhangup always return -1 and sets errno to ENOSYS.
seteuid, setegid , and settimeofday always return 0 and sets errno to ENOSYS .
vfork just calls fork.

Setting up Cygwin

The following documentation discusses setting up the Cygwin tools.
The following packages are included in the native Win32 release of GNUPro.

Installing the binary release for Cygwin

The following procedures help when installing the binaries for the Cygwin tools.
NOTE:
This is not necessary unless your process begins with re-installing the GNUPro tools.
    1.
    Load the GNUPro CD-ROM and run the installer.
The installation process starts by asking for your install location. Once the installation is complete, there will be a new Program Files folder that you can use to obtain a shell from which you can run the tools.
    2.
    Ensure that the ‘temp’ directory is in the proper place.
Type mkdir -p /tmp to ensure that a ‘temp’ directory exists for programs that you expect to find one there.
    3.
    Depending on how you intend to use the tools, various programs may need to be able to find  ‘/bin/sh’ directory path.
Use the ‘mkdir -p /bin’ declaration and put a copy of  ‘sh.exe’ file there, removing the older version, if present. Use the  ‘mount’ utility to specify a drive.
If you should ever want to uninstall the tools, you may do so with “Add/Remove Programs” (accessed from the Start button’s Settings selection for Control Panel).

Directory structure for Cygwin

Cygwin knows how to emulate a standard UNIX directory structure, to some extent. You should make sure that you always have /tmp both with and without the mount table translations, just in case. If you want to emulate the /etc directory (so that the UNIX declaration, ls -l, works), use the following example’s declarations as a guide.
mkdir /etc/
cd /etc
mkpasswd > /etc/passwd
mkgroup > /etc/group
NOTE:
This only works fully under Windows NT. Under Windows 9 x, you may need to edit these files with a text editor. Further changes to your NT registry will not be reflected in /etc/passwd or /etc/group after this implementation, so you may want to regenerate these files periodically. You should also set your home directories to something other than ‘/’ to prevent unexplained delays in various programs.

Environment variables for Cygwin

make uses an environment variable, MAKE_MODE, to decide if it uses Command.com or /bin/sh to run command lines. If you’re getting strange errors from make with the message, /c not found, set MAKE_MODE to UNIX with a declaration like the following example’s form.
C:\> set MAKE_MODE=UNIX
$ export MAKE_MODE=UNIX
The HOME environment variable is used by UNIX shells to determine the location of your home directory. This environment variable is converted from Windows format (that is, C:\home\bob) to UNIX format (that is, /home/bob) when a Cygwin process first starts.
The PATH environment variable is used by Cygwin applications as a list of directories to search for executable files to run. This environment variable is converted from Windows format (that is, C:\WinNT\system32;C:\WinNT) to UNIX format (that is, /WinNT/system32:/WinNT ) when a Cygwin process first starts.
The LD_LIBRARY_PATH environment variable is used by the Cygwin function, dlopen (), as a list of directories to search for .dll files to load. This environment variable is converted from Windows format (that is, C:\WinNT\system32;C:\WinNT) to UNIX format (that is, /WinNT/system32:/WinNT) when a Cygwin process first starts.
The most important environment variable is the CYGWIN variable. It is used to configure many global settings for the Cygwin runtime system. It allows you to express many attributes, using a syntax like the following declaration.

 
set CYGWIN="foo nobar grill=27"
NOTE:
Each option is separated by others with a space. Many options can be turned off by prefixing with “no” (such as “nobar”  or “bar”  options). The following options are available.
Warning:
This may create additional large files on non-NTFS partitions. This option only operates under Windows NT. Off by default.

Mount table

The mount utility controls a mount table that is used to emulate a POSIX view of the Windows file system space. This can be used to change the Windows path used as  ‘/’and mount arbitrary Win32 paths into the POSIX file system space. Many people use the utility to mount each drive letter under the slash partition (such as C:\ to /c or D:\ to /d, and so forth).
Executing mount without any arguments prints the current mount table to the screen. Otherwise, provide the Win32 path you would like to mount as the first argument and the POSIX path as the second argument.
The following example demonstrates using the mount utility to mount the “C:/Cygnus/b20/H-i586-cygwin32/bin” directory to the “/bin” folder. This makes /bin/sh a valid shell, to satisfy make.
C:\cygnus\> ls /bin


ls: /bin: No such file or directory
C:\cygnus\> mkdir /bin
C:\cygnus\> mount
C:/Cygnus/b20/H-i586-cygwin32/bin /bin
C:\cygnus\> mount
Device Directory Type Flags
C: /c native text!=binary
D: /d native text!=binary
\\.\tape1: /dev/st1 native text!=binary
\\.\tape0: /dev/st0 native text!=binary
\\.\b: /dev/fd1 native text!=binary
\\.\a: /dev/fd0 native text!=binary
C:\Cygnus\b20\H-i586-cygwin32\bin /bin native text!=binary
C: / native text!=binary
C:\cygnus\> ls /bin/sh
/bin/sh
C:\cygnus\>

The mount table is stored in the Windows registry (HKEY_CURRENT_USER/Cygnus Solutions/CYGWIN DLL setup/<version>/mounts) where <version> is the latest registry version associated with the Cygwin library.

Using GCC with Cygwin

The following documentation discusses using the GNUPro compiler, GCC, with Cygwin.

Console mode applications

Use GCC to compile, just like under UNIX. See Using GNU CC in the GNUPro Compiler Tools documentation for information on standard usage and options. The following example shows the usage practice for the shell’s console.
C:\cygnus\> gcc hello.c -o hello.exe


C:\cygnus\> hello.exe
Hello, World

C:\cygnus\>

GUI mode applications

Cygwin allows you to build programs with full access to the standard Windows 32-bit API, including the GUI functions as defined in any Microsoft or off-the-shelf publication. However, the process of building those applications is slightly different, as you’ll be using the GNU tools instead of the Microsoft tools.
For the most part, your sources won’t need to change at all. However, you should remove all __export attributes from functions and replace them. The following example’s script shows such implementation.
int foo (int) __attribute__ ((__dllexport__));
int
foo (int i)
For most cases, you can just remove the __export attributes. For convenience sake, you might want to work around a misfeature in Cygwin’s libraries by including the following code fragment; otherwise, you’ll have to add a “-e _mainCRTStartup” declaration to your link line in your Makefile.

 
#ifdef __CYGWIN__
WinMainCRTStartup() { mainCRTStartup(); }
#endif
The Makefile is similar to any other UNIX-like Makefile, and any other Cygwin Makefile. The only difference is that you use a “gcc -mwindows”  declaration to link your program into a GUI application instead of a command-line application. The following example’s script shows such implementation:

 
myapp.exe : myapp.o myapp.res
       gcc -mwindows myapp.o myapp.res -o $@
myapp.res : myapp.rc resource.h
       windres $< -O coff -o $@
NOTE:
The use of windres is for compiling the Windows resources into a COFF-format .res file. That will include all the bitmaps, icons, and other resources you need, into one handy object file. Normally, if you omitted the “-O coff” declaration, it would create a Windows .res format file, but we can only link COFF objects. So, we tell windres to produce a COFF object, but for compatibility with the many examples that assume your linker can handle Windows resource files directly, we maintain the .res naming convention. For more information on windres, see Using binutils in the GNUPro Utilities documentation.

Debugging Cygwin programs

When your programs don’t work properly, they usually have bugs (meaning there’s something wrong with the program itself that is causing unexpected results or crashes). Diagnosing these bugs and fixing them is made easy by special tools called debuggers. In the case of  Cygwin, the debugger is GDB, the GNU debugger, a tool lets you run your program in a controlled environment so that you can investigate the state of your program while it is running or after it crashes.
 
Before you can debug your program, you need to prepare your program for debugging. Add a ‘-g’ declaration to all the other flags you use when compiling your sources to objects. Consider the following example’s declarations.
gcc -g -O2 -c myapp.c
gcc -g myapp.c -o myapp
What this does is add extra information to the objects (making them much bigger), telling the debugger about line numbers, variable names, and other useful things. These extra symbols and debugging data give your program enough information about the original sources so that the debugger can make debugging much easier for you.
GDB is a command-line tool. To invoke it, use the ‘gdb myapp.exe’ declaration (substituting the executable file’s name for myapp ) at the command prompt. Some text then displays about general usage agreements, then the prompt, (gdb), will appear to prompt you to enter commands. Whenever you see this prompt, it means that GDB is waiting for you to type in a command, like run or help. Use the ‘help’ command to get a list of all the commands to use, or see Debugging with GDB in the GNUPro Debugging Tools for a complete description of GDB and how to use it.
If your program crashes and you’re trying to determine why it crashed, the best thing to do is type run and let your program run. After it crashes, you can use the ‘where’ command to determine where it crashed, or ‘info locals’ to see the values of all the local variables. There’s also the ‘print’ declaration that lets you examine individual variables or what pointers point to. If your program is doing something unexpected, you can use the ‘break’ command to tell GDB to stop your program when it gets to a specific function or line number.
(gdb) break my_function
(gdb) break 47
Now, using the ‘run’ command, your program will stop at that breakpoint, and you can use the other GDB commands to look at the state of your program at that point, to modify variables, and to step through your program’s statements one at a time.
NOTE:
Specify additional arguments to the ‘run’ command to provide command-line arguments to your program. These previous example’s case and the next example’s case are the same as far as your program is concerned:
myprog -t foo --queue 47
gdb myprog
(gdb) run -t foo --queue 47

Building and using DLLs with Cygwin

The following documentation discusses building and using dynamically linked libraries (DLLs) with Cygwin.
DLLs are linked into your program at run time instead of build time. There are three parts to a DLL:

Building DLLs

The following documentation provides a simple example of how to build a .dll file, using a single file, myprog.c, for the program, myprog.exe , and a single file, mydll.c, for the contents of the .dll file, mydll.dll, then compiling everything as objects.
gcc -c myprog.c
gcc -c mydll.c
Unfortunately, the process for building a .dll file is rather complicated with five run commands, like the following example’s declaration.

 
ld --dll -o mydll.dll mydll.o -e _mydll_init@12 --base-file mydll.base
dlltool --base-file=mydll.base --def mydll.def --output-exp mydll.exp --dllname                                                                   \mydll.dll
ld --dll -o mydll.dll mydll.o -e _mydll_init@12 --base-file mydll.base mydll.exp
dlltool --base-file=mydll.base --def mydll.def --output-exp mydll.exp --dllname                                                                      \mydll.dll
ld --dll -o mydll.dll mydll.o -e _mydll_init@12 mydll.exp
The extra steps give dlltool the opportunity to generate the extra sections (exports and relocation) that a .dll file needs. After this, you build the import library with the following commands such as the following example’s decalaration.

 
dlltool --def mydll.def --dllname mydll.dll --output-lib mydll.a
Now, when you build your program, you link against the import library, with declaration’s like the following example’s commands.

 
gcc -o myprog myprog.o mydll.a
NOTE:
This usage linked with -e _rdll_init@12, telling the operating system what the DLL’s entry point is, a special function that coordinates bringing the .dll file to life within the operating system. The minimum function looks like the following example’s declaration.
#include <windows.h>
int WINAPI
rdll_init(HANDLE h, DWORD reason, void *foo)
{
   return 1;
}

Linking against DLLs

If you have an existing DLL already, you need to build a Cygwin-compatible import library to link. Unfortunately, there is not yet any tool to do this automatically. However, you can get most of the way by creating a .def file with these commands (use a bash shell for the quoting to work properly with such linking).
echo EXPORTS > foo.def
nm foo.dll | grep’ T _’ | sed’s/.* T _//’ >> foo.def

Once you have the .def file, you can create an import library from it, using a declaration similar to the following example’s form.

 
dlltool --def foo.def --dllname foo.dll --output-lib foo.a

Defining Windows resources for Cygwin

windres reads a Windows resource file (*.rc ) and converts it to a res or coff file. The syntax and semantics of the input file are the same as for any other resource compiler; see any publication describing the Windows resource format for details. Also, see the windres documentation in Using binutils in GNUPro Utilities. The following example shows the usage of windres in a project:
myapp.exe : myapp.o myapp.res
                      gcc -mwindows myapp.o myapp.res -o $@
myapp.res : myapp.rc resource.h
                          windres $< -O coff -o $@
What follows is a quick-reference to the syntax that windres supports.

 
id ACCELERATORS suboptions
BEG
"^C" 12
"Q" 12
65 12
65 12, VIRTKEY ASCII NOINVERT SHIFT CONTROL ALT
65 12, VIRTKEY, ASCII, NOINVERT, SHIFT, CONTROL, ALT
(12 is an acc_id)
END
SHIFT, CONTROL, ALT require VIRTKEY
id BITMAP memflags "filename"
memflags defaults to MOVEABLE
id CURSOR memflags "filename"
memflags defaults to MOVEABLE,DISCARDABLE
id DIALOG memflags exstyle x,y,width,height styles BEG controls END
id DIALOGEX memflags exstyle x,y,width,height styles BEG controls END
id DIALOGEX memflags exstyle x,y,width,height,helpid styles BEG controls END
memflags defaults to MOVEABLE
exstyle may be EXSTYLE=number
styles: CAPTION "string"
        CLASS id
        STYLE FOO | NOT FOO | (12)
        EXSTYLE number
        FONT number, "name"
        FONT number, "name",weight,italic
        MENU id
        CHARACTERISTICS number
        LANGUAGE number,number
        VERSIONK number
controls:
        AUTO3STATE params
        AUTOCHECKBOX params
        AUTORADIOBUTTON params
        BEDIT params
        CHECKBOX params
        COMBOBOX params
        CONTROL ["name",] id, class, style, x,y,w,h [,exstyle] [data]
        CONTROL ["name",] id, class, style, x,y,w,h, exstyle, helpid [data]
         CTEXT params
        DEFPUSHBUTTON params
        EDITTEXT params
        GROUPBOX params
        HEDIT params
        ICON ["name",] id, x,y [data]
        ICON ["name",] id, x,y,w,h, style, exstyle [data]
        ICON ["name",] id, x,y,w,h, style, exstyle, helpid [data]
        IEDIT params
        LISTBOX params
        LTEXT params
        PUSHBOX params
        PUSHBUTTON params
        RADIOBUTTON params
        RTEXT params
        SCROLLBAR params
        STATE3 params
        USERBUTTON "string", id, x,y,w,h, style, exstyle
params:
        ["name",] id, x, y, w, h, [data]
        ["name",] id, x, y, w, h, style [,exstyle] [data]
        ["name",] id, x, y, w, h, style, exstyle, helpid [data]
[data] is optional BEG (string|number) [,(string|number)] (etc) END
id FONT memflags "filename"
memflags defaults to MOVEABLE|DISCARDABLE
id ICON memflags "filename"
memflags defaults to MOVEABLE|DISCARDABLE
LANGUAGE num,num
id MENU options BEG items END
items:
        "string", id, flags:
        SEPARATOR:
        POPUP "string" flags BEG menuitems END
flags::
        CHECKED:
         GRAYED:
         HELP:
         INACTIVE:
         MENUBARBREAK:
         MENUBREAK
id MENUEX suboptions BEG items END
items::
         MENUITEM "string":
         MENUITEM "string", id:
         MENUITEM "string", id, type [,state]:
         POPUP "string" BEG items END:
         POPUP "string", id BEG items END:
         POPUP "string", id, type BEG items END:
         POPUP "string", id, type, state [,helpid] BEG items END
memflags defaults to MOVEABLE
id RCDATA suboptions BEG (string|number) [,(string|number)] (etc) END
STRINGTABLE suboptions BEG strings END
strings::
         id "string":
         id, "string"
(User data)
id id suboptions BEG (string|number) [,(string|number)] (etc) END
id VERSIONINFO stuffs BEG verblocks END
stuffs: FILEVERSION num,num,num,num:
         PRODUCTVERSION num,num,num,num:
         FILEFLAGSMASK num:
         FILEOS num:
         FILETYPE num:
         FILESUBTYPE num:
verblocks::
         BLOCK "StringFileInfo" BEG BLOCK BEG vervals END END:
         BLOCK "VarFileInfo" BEG BLOCK BEG vertrans END END
vervals: VALUE "foo","bar"
vertrans: VALUE num,num
suboptions::
         memflags:
         CHARACTERISTICS num:
         LANGUAGE num,num:
         VERSIONK num
memflags are MOVEABLE/FIXED PURE/IMPURE PRELOAD/LOADONCALL DISCARDABLE

Cygwin utilities

Cygwin comes with a number of command-line utilities for managing the UNIX emulation portion of the Cygwin environment. While many of these reflect their UNIX counterparts, each was written specifically for Cygwin. See the corresponding documentation to the following Cygwin utilities.

Cygwin functions

The following documentation discusses the Cygwin functions.
These functions are specific to Cygwin itself, and probably will not have relations to any other library or standards.

Top|Contents|Index|Previous|Next