text:
This action might not be possible to undo. Are you sure you want to continue?
Cygwin User's Guide
Cygwin User's Guide
Cygwin User's Guide
Copyright © 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Red Hat, Inc.
Cygwin User's Guide
Cygwin Overview 1.1 1.2 1.3 1.4 1.5 1.6 What is it? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Quick Start Guide for those more experienced with Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . Quick Start Guide for those more experienced with UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Are the Cygwin tools free software? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A brief history of the Cygwin project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Highlights of Cygwin Functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.6.1 1.6.2 1.6.3 1.6.4 1.6.5 1.6.6 1.6.7 1.6.8 1.6.9 1.7 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Permissions and Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . File Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Text Mode vs. Binary Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ANSI C Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Process Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sockets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Select . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1 1 1 1 2 2 3 3 3 3 4 5 5 5 6 6 6 6 6 7 7 7 8 8
What's new and what changed in Cygwin 1.7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.7.1 1.7.2 1.7.3 1.7.4 1.7.5 1.7.6 1.7.7 1.7.8 1.7.9 What's new and what changed from 1.7.6 to 1.7.7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What's new and what changed from 1.7.5 to 1.7.6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What's new and what changed from 1.7.3 to 1.7.5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What's new and what changed from 1.7.2 to 1.7.3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What's new and what changed from 1.7.1 to 1.7.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . OS related changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . File Access related changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Network related changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Device related changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
1.7.10 Other POSIX related changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 1.7.11 Security related changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 1.7.12 Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Cygwin User's Guide
Setting Up Cygwin 2.1
Internet Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 2.1.1 2.1.2 2.1.3 2.1.4 2.1.5 2.1.6 2.1.7 2.1.8 2.1.9 Download Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Selecting an Install Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Local Package Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 Connection Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 Choosing Mirrors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 Choosing Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 Download and Installation Progress . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Post-Install Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
2.1.10 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 2.2 Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 2.2.1 2.2.2 2.3 2.4 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Restricted Win32 environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Changing Cygwin's Maximum Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 Internationalization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 2.4.1 2.4.2 2.4.3 2.4.4 2.4.5 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 How to set the locale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 The Windows Console character set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Potential Problems when using Locales . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 List of supported character sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Using Windows security in Cygwin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 2.5.1 2.5.2 2.5.3 2.5.4 2.5.5 2.5.6 2.5.7 2.5.8 2.5.9 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 File permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 Special values of user and group ids . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 The POSIX permission mapping leak . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Switching the user context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 Switching the user context with password authentication . . . . . . . . . . . . . . . . . . . . . . . . . . 28 Switching the user context without password, Method 1: Create a token from scratch . . . . . . . . . . . 29 Switching the user context without password, Method 2: LSA authentication package . . . . . . . . . . . 29 Switching the user context without password, Method 3: With password . . . . . . . . . . . . . . . . . . 30
2.5.10 Switching the user context, how does it all fit together? . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 2.6 Customizing bash . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 The /proc filesystem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1 3. . . . . 41 Filenames with unusual (foreign) characters . . . . . . . . .2 3. . . . . . . . . . . .7.1. . . . . . . . . .10 The @pathnames . . . . . .2. . . . . .1. . . . . . . . . . . . . 36 Using native Win32 paths . . . . . . . . . . . . . . .3 3. . . . . . . . . . . . . . . . . . .6. . . . . . . .9 Special files in /etc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4. . . . . . . . . . . . . . .1. . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 The cygdrive path prefix . . . . . 37 Additional Path-related Information . . . . . . . . . . . .2 3. . . . .6. . . . . . . . .7 3. . . . . . . . . . . . . . 38 Binary or text? . . . . . . . . . . . . . . . . . . . . . . . . . . .2 3. . 56 . . . . . . . . . . . .7. . . . .1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6. . . . . . . . . . . . . . . . . . . . . . . . .2. . . . . . . . . . . . . . . 37 Using the Win32 file API in Cygwin applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 3. . . . . . . . . .5 cygcheck . . . . .1 3. . . . . . . . . . . . . . . . . .5. . . . . . . . . 38 3. . . . . . . . . . .6 Implemented options . . . . . . . . . . . . . . 48 3.exe extension .1 3. . . . . . . . . . . . . . . . . . . . . . . . . . .2 Text and Binary modes . . . . . . . . .1 3. . . .4.7. . . . . . . . . . . . . . . . . . . . . . . . . 47 Cygserver .1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3 3. . . . . . . . . . .3 3. . .2. . . . . 50 cygpath . . . . .7 Cygwin Utilities . . . . . . . . . . . . . . . . . . . . . . .7. . . . . . . . . .4. . . . 55 getfacl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6 3. . 38 3.4. . . . . . . . . . . . 55 kill . . . . . . . . . . . . . . . . . . . . . .3 3. . . . . .4. .7. . . . . . . . . . .4 The Issue . 46 3. . . . . . . . .2 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5 3. . . . . . . . . . . . . . . . . . . . . . . .6 Introduction .4 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 3. . . . . . . . . . . . .3 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 Special filenames . . . . . . . . . . . . . . . . . . . . . 38 The default Cygwin behavior . . . . . . . . .5 The CYGWIN environment variable . 39 Programming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 Forbidden characters in filenames . . 45 3. . . . . . . . . . . . .5 3. . . . . . . . . . . . . 42 POSIX devices . . .1. . . . . . . . . . . .4 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4. . . . . 39 3. . . . . . . . . . . . . . . . . . . . . . .Cygwin User's Guide v 3 Using Cygwin 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2 3. 40 Invalid filenames . . . . . . . . . . . 41 Case sensitive filenames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 3. . . . . . . . . . . . . . 33 The Cygwin Mount Table . . . . . . . . . . . . . . . . . . . . . . . .5. . . . . . . . . . . . . . . . . . . . . . . . . . .1 3. . . . . . . . . . . . . . .4 What is Cygserver? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4. . . . . . . . . . . . . . . . . . . . . . . . . . .6. . . . . . . . . . . . . . . . . .8 3. . . . . . . . . . . . . . . . . . 50 3. . . . . . . . . 50 The Cygserver configuration file . . . . . . .4 File permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 3. . . . . . . . . .3 3. . 46 Obsolete options . . . . . . . . . . . .1 3. . . . 48 Cygserver command line options . . . . . . . . . .2. . . . . . . . . . . . .2 3. . . . . . . . . .4 3. .1 33 Mapping path names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 dumper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4. . .4. . . . . . . . . . . . . . . . . . . . . . . . . . . 42 The . . . . . . . . . . . . . . . . . . 48 How to start Cygserver . . . . . . . . . . . . 45 The /proc/registry filesystem . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . .3. . . . . . . . . . . .7. . . . . . . . . . . . . . . . . . . . . . . . . . 75 4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7. . .9 locale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 Building and Using DLLs . 63 Limitations . . . . . . . . . . . . . . . . . . 73 Console Programs . . . . . . . . . . . . . . . . . . . . . . . . .3. . . . . . . . . . . 61 3. .3 Debugging Cygwin Programs . . . 78 Linking Against DLLs . . . . . . . . . . . . . . . . . . . . . .7. . . . . . . . . . . . . . . . . . . .8. . . . . . . . .4 3. . . .1. . . . . . . . . . . . . . . . . . . . 74 Creating shortcuts with cygutils . . . . . . . . . . . .Cygwin User's Guide vi 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2 Console Mode Applications . . . . .11 ps . . . . . . . . . . . . .2 4. . . . . .7. . . . 74 Printing with cygutils . . . . . . . . . . . . . . . . . . . . . . . .6 4 Pathnames . . . . . . . . . .7. . . . . . . . . . . . 64 3. . . . . . . . . . . . . .7. . . . 73 Cygwin and Windows Networking . . . . . . . . . . . . . . . . . . . . . . . . . . .7. . . . . . . . . . 75 GUI Mode Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 3. . . . 64 3. . . . . . . . . 79 4. . . . . . . . . . . . . . . . .8. . . . . . . . . . . . .1 4. . . . . . . . . . . . . . . . . . . . . . . .2 3. . . . . . . . . . . . . . . . . . .8 Using Cygwin effectively with Windows . .2 Building DLLs . . . . .14 ssp . .7. . . . . . . .1 3. . . . . 72 3. . . . . . . . . .8 3. . . . . . . . . . . . . . . . . . . . . . . . . . .9. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8. . . . . . . . . . .4 Defining Windows Resources . . 73 The cygutils package . . . . . . . . . . . 72 3. . . . .12 regtool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1. . . . . . . . .1 3. . . . . . . . . . . . . . 74 75 Programming with Cygwin 4. . . . . . . . . . . . . . . . . . . 62 Cygdrive mount points . . . . . . . . . . . . .8. 68 3. . . . . . . . . . . . . . . . . .7. .9. .8. . . . .13 setfacl . . . . . . . . . . .10 passwd . . . . . . . . . . . . . . . . . . . . . 78 4. . . . . . . . . .2 3. . . . . . . . . . . . . . 60 mount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8. . . . . . . . . . . . . . . . . . . 80 . . . . . . . . . . . . . . . . . 75 4. . . . . . . . . . . . . . . . . . . . . .7. . . . . . . . . . . . . . . . . . . . . . . . . . .3 Using mount . . . . . . . . . . . . . .7. . . 57 mkgroup . . . . . . .16 umount . . . . . . . . . . . . . . . .7 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9. . . . . . . . . . . . . . . . . . . . . . . . . .7. 69 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 mkpasswd . . . . . . . . . . .1 4. . . . . . . . . . . . . .3 3. . . . . . . .1 Using GCC with Cygwin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 3. . . . . . . . . . . . . . .5 3. . . . . . . .15 strace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 3. . . . . . . . . . . . . . . . . . .6 3. . . . . .
Use setup. For example. which acts as an emulation layer providing substantial POSIX (Portable Operating System Interface) system call functionality. After installation. The resource compiler windres is also provided.3 Quick Start Guide for those more experienced with UNIX If you are an experienced UNIX user who misses a powerful command-line environment. which provide a Linux look and feel. The best plan is probably to click on individual categories and install either entire categories or packages from the categories themselves. you may find it difficult to understand at first.exe. you will enjoy Cygwin. If you are installing Cygwin for a specific purpose. If you want to know more about what each option means.dll). run the setup. Developers coming from a Windows background will be able to write console or GUI executables that rely on the Microsoft Win32 API instead of Cygwin using the -mno-cygwin option to GCC. 1. Another option is to install everything by clicking on the Default field next to the All category. However. When running setup. This guide is not meant to be comprehensive. To install a basic Cygwin environment. 1. As a result. With Cygwin installed. including a working UNIX shell. The major differences between Cygwin and Linux is the C library (newlib instead of glibc). be advised that this will download and install several hundreds of megabytes of software to your computer. The default settings are correct for most users. and then Linux practice. The Cygwin DLL works with all x86 and AMD64 versions of Windows NT since Windows NT 4. if you want to compile C++ programs. They can be used from one of the provided shells such as bash or from the Windows Command Prompt. programmers may write Win32 console or GUI applications that make use of the standard Microsoft Win32 API and/or the Cygwin API. It consists of a DLL (cygwin1. it is possible to easily port many significant UNIX programs without the need for extensive changes to the source code. This includes configuring and building most of the available GNU software (including the development tools included with the Cygwin distribution).exe program and click Next at each page. The -shared option allows to write Windows Dynamically Linked Libraries (DLLs). clicking on categories and packages in the package installation screen will provide you with the ability to control what is installed or updated. Developers coming from a UNIX background will find a set of utilities they are already comfortable using. use it to install the tools that you need. users have access to many standard UNIX utilities. . and a collection of tools. see Section 2.exe any time you want to update or install a Cygwin package.1.Cygwin User's Guide 1 / 82 Chapter 1 Cygwin Overview 1.2 Quick Start Guide for those more experienced with Windows If you are new to the world of UNIX. so we recommend that you use the many available Internet resources to become acquainted with UNIX basics (search for "UNIX basics" or "UNIX tutorial"). The API follows the Single Unix Specification as much as possible. you can find Cygwin-specific documentation in the /usr/share/doc/Cygwin/ directory. Additionally. you need the gcc-g++ package and probably a text editor like nano.1 What is it? Cygwin is a Linux-like environment for Windows.
But this would have meant spending a huge amount of time on each and every tool. gdb. Since then.exe to install and upgrade each package separately.4 Are the Cygwin tools free software? Yes. The first thing done was to enhance the development tools (gcc. some of it is public domain. textutils. etc. only ported to the Windows host. Customers of the native Win32 GNUPro should feel free to submit bug reports and ask questions through Red Hat channels. Add any other packages by clicking on the + next to the Category name and selecting the package from the displayed list..) so that they could generate and interpret Win32 native object files. You may search for specfic tools by using the Setup Package Search at the Cygwin web site. gas. Inc. "Cygwin32: A Free Win32 Porting Layer for UNIX® Applications" which can be found at the 2nd USENIX Windows NT Symposium Online Proceedings. Many of these tools were previously only built natively so we had to modify their configure scripts to be compatible with cross-compilation. For more information about the proprietary-use license.). Windows 9x and NT looked like a flavor of UNIX from the perspective of the GNU configure mechanism. We could have done this by rewriting large portions of the source to work within the context of the Win32 API. etc. it was possible to build working Win32 tools using UNIX-hosted cross-compilers. etc. etc.com. select.Cygwin User's Guide 2 / 82 The compiler tools are the standard GNU compilers most people will have previously used under UNIX.exe means. 1. the project announced a New Cygwin Net Release which provided the native non-Cygwin Win32 program setup. parts are covered by the standard X11 license. The entire Cygwin toolset was available as a monolithic install. Noer's 1998 paper.1.). be advised that this will download and install several hundreds of megabytes of software to your computer. . You don't have to pay anyone to use it but you should be sure to read the copyright section of the FAQ for more information on how the GNU GPL may affect your use of these tools. we took a substantially different approach by writing a shared library (the Cygwin DLL) that adds the necessary UNIX-like functionality missing from the Win32 API (fork. you can find Cygwin-specific documentation in the /usr/share/doc/Cygwin/ directory. We call this new interface the Cygwin API. linking against this library.). Self hosting was achieved as of the beta 17. Parts are GNU software (gcc. Programmers wishing to port UNIX software to Windows NT will find that the Cygwin library provides an easy way to port many UNIX packages. you may want the Cygwin proprietary-use license. very few source-level changes had to be made since Cygwin provided a UNIX-like API. these are described in more detail in Section 3. Another option is to install everything by clicking on the Default field next to the All category.5 A brief history of the Cygwin project Note A historical look into the first years of Cygwin development is Geoffrey J. see Section 2. All other questions should be sent to the project mailing list cygwin@cygwin. None of it is shareware. with only minimal source code changes. Once written. In April 2000. The next task was to port the tools to Win NT/9x. signals. However.8. From this point. Note that there are some workarounds that cause Cygwin to behave differently than most UNIX-like operating systems.). Running bash with the development tools and user tools in place. ld..redhat. 1. This program must be run manually every time you want to check for updated packages since Cygwin does not currently include a mechanism for automatically detecting package updates. The best plan is probably to click on individual categories and install either entire categories or packages from the categories themselves.com/services/custom/cygwin/. the Cygwin DLL and setup. please go to http://www. Cygwin began development in 1995 at Cygnus Solutions (now part of Red Hat. bash. For more information about what each option in setup. gas. spawn.exe only installs a minimal subset of packages.exe have seen continuous development. After installation. Instead. setup. Other than the configuration changes. If you intend to port a proprietary application using the Cygwin library. Since neither OS ships with standard UNIX user tools (fileutils. we had to get the GNU equivalents working with the Cygwin API. some of it was written by Red Hat and placed under the GNU General Public License (GPL). Use the graphical command setup.exe any time you want to update or install a Cygwin package. we pursued the goal of producing Windows-hosted tools capable of rebuilding themselves under Windows 9x and NT (this is often called self-hosting). sockets. By default.1 release in October 1996.
The chmod call maps UNIX-style permissions back to the Win32 equivalents. IPv6 support and much more. user id. Since version 1. the layout of this POSIX view of the Windows file system space is stored in the /etc/fstab file. Actually.6 1. as well as Section 3. 1.2. on file systems supporting them (usually NTFS). we provide utilities that can be used to construct them from the user and group information provided by the operating system. UNC pathnames (starting with two slashes) are supported for network paths. see Section 2.7 release in 2009.3 Cygwin introduced a mechanism for setting real and effective UIDs. This is described in Section 2.13.7. The implementation details are safely hidden in the Cygwin DLL.6. Because many programs expect to be able to find the /etc/passwd and /etc/group files. they could write a Win32-specific GUI using Win32 API calls on top of a UNIX back-end that uses Cygwin. Users with Administrator rights are permitted to chown files. the Cygwin DLL is loaded into the application's text segment. 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.5.d/${USER}. it's not always possible to strictly adhere to existing UNIX standards like POSIX. among other purposes. It adds a lot of new features like case-sensitive filenames. Cygwin maps Win32 file ownership and permissions to ACLs by default.3 File Access Cygwin supports both POSIX.and Win32-style paths.1. As of version 1.5. From the application perspective.Cygwin User's Guide 3 / 82 The latest major improvement in this development is the 1.2 Permissions and Security Windows NT includes a sophisticated security model based on Access Control Lists (ACLs). 1. the file system is a POSIX-compliant one. This gives the programmer some flexibility in designing the structure of their program in terms of the APIs used. where appropriate. For details. Due to some restrictions in Windows. 1. they can access both the UNIX compatibility calls provided by Cygwin as well as any of the Win32 API calls. This is used to keep track of open file descriptors and to assist fork and exec. there is a system-wide /etc/fstab file as well as a user-specific fstab file /etc/fstab. Cygwin processes share some variables and are thus easier targets of denial of service type of attacks. the first Cygwin DLL to run creates shared memory areas and global synchronization objects that other processes using separate instances of the DLL can access. Because we are trying to emulate a UNIX kernel which needs access to all processes running under it.6. Because processes run under the standard Win32 subsystem. which dropped Windows 95/98/Me support in favor of using Windows NT features more extensively.1 Highlights of Cygwin Functionality Introduction When a binary linked against the library is executed.1. Fortunately these are mostely border cases. but are hidden to the Win32 API. Every process also has a per_process structure that contains information such as process id. as well as to access NT capabilities which are useful to implement certain POSIX features. For example. Under the hood it's using the Win32 API.0. Paths coming into the DLL are translated from POSIX to native NT as needed. and other similar process-specific information.6. as well as the native NT API.5. NFS interoperability. Solaris style ACLs and accompanying function calls are also supported.2. signal masks. With version 1. Note Some restrictions apply for calls to the Win32 API. using either forward or back slashes as the directory delimiter.1. However there is no guarantee that Cygwin is as secure as the Windows it runs on. The DLL is implemented as a standard DLL in the Win32 subsystem. The native NT API is used mainly for speed. .
On FAT and other file systems which don't support hardlinks. to better support internationalization. This allows Linux-compatible EA operations and keeps tools like attr.foo" within Cygwin. UNIX and Win32 have different end-of-line conventions in text files. just like on other POSIX systems. the chroot call isn't a privileged call.7.. Starting with Cygwin 1. On file systems which don't support unique persistent file IDs (FAT. the mount points point to Win32 paths. This solution addresses the newline interoperability concern at the expense of violating the POSIX requirement that text and binary mode be identical. or setfattr happy. Just instead of block devices.4. However. Given that.7 and later supports Extended Attributes (EAs) via the linux-specific function calls getxattr. Second. older Samba shares) the inode number for a file is calculated by hashing its full Win32 path. 1.dll. setxattr.. Any user may call it. The library exports several Cygwin-specific functions that can be used by external programs to convert a path or path list from Win32 to POSIX or vice versa. The layout of this file is very similar to the layout of the fstab file on Linux.exe installs a fstab file by default. /cygdrive/d. Symbolic links are potentially created in two different ways. but does not create them. Consequently. However. It is worth noting that the number produced by this method is not guaranteed to be unique. The fstab file allows mounting arbitrary Win32 paths into the POSIX file system space. the chroot environment isn't safe against native windows processes. Win32 applications handle filenames in a case preserving. symbolic links are using UTF-16 to encode the filename of the target file. For that reason the usage of chroot is discouraged. The cygdrive prefix can be set to some other value (/mnt for instance) in the fstab file(s). but case insensitive manner. they can do the same path translations by executing the cygpath utility program that we provide with Cygwin. A UNIX text file will have a single newline character (LF) whereas a Win32 text file will instead use a two character sequence (CR+LF). however. Symbolic links are not present and supported on Windows up to and including Windows Server 2003 R2. The file style symlinks are files containing a magic cookie followed by the path to which the link points.1. listxattr. First of all. it's transformed into "user. the call returns with an error. It's the path under which every available drive in the system is mounted under its drive letter. The mechanism used for this is simple. the two character sequence must be translated on the fly by Cygwin into a single character newline when reading in text mode. which can easily be changed using the editor of your choice. Please note that this new UTF-16 style of symlinks is not compatible with older Cygwin release.6.3. so you can access the drives as /cygdrive/c. The default value is /cygdrive. However. All EAs on Samba or NTFS are treated as user EAs. the OS only supports case sensitivity when a specific registry value is changed. and removexattr. Cygwin recognizes native symlinks. they are not useful in a POSIX emulation layer. we have not found this to be a significant problem because of the low probability of generating a duplicate inode number. An installation with setup. Native symlinks are available starting with Windows Vista. chroot in Cygwin is only a hack which pretends security where there is none. Consequently. Since Windows XP. Due to their strange implementation. A special case is the so-called cygdrive prefix. Binary Mode It is often important that files created by native Windows applications be interoperable with Cygwin applications. So it looks for the fstab file in C:\Cygwin\etc\fstab. For example. case sensitivity is not usually the default.Cygwin User's Guide 4 / 82 At startup the DLL has to find out where it can find the /etc/fstab file. chroot is supported since Cygwin 1. Instead. which can't read the target filename correctly. Unfortunately.4 Text Mode vs. a file created by a native Windows text editor should be readable by a Cygwin application. First it retrieves it's own path. Hard links are fully supported on NTFS and NFS file systems. Cygwin 1. for instance C:\Cygwin\bin\cygwin1. Shell scripts and Makefiles cannot call these functions directly. Symlinks created by older Cygwin releases can be read just fine. if the name of an EA is "foo" from the Windows perspective. The inode number generated by the stat call always matches the one returned in d_ino of the dirent structure. This implies some serious restrictions. The advantage of file symlinks is speed. processes that attempt to lseek through text files can no longer rely on the number of . and vice versa. chroot is not a concept known by Windows. Therefore. etc. you could run into problems with them if you're now using another character set than the one you used when creating these symlinks (see Section 2. From there it deduces that the root path is C: \Cygwin.4. The shortcut style symlinks are Windows shortcut files with a special header and the Readonly DOS attribute set. the advantage of shortcut symlinks is the fact that they can be utilized by non-Cygwin Win32 tools as well. They are marked with the System DOS attribute so that only files with that attribute have to be read to determine whether or not the file is a symbolic link. so. Cygwin supports case sensitivity on file systems supporting that.
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. the signal handler signals the event that it is done. This process keeps intraprocess signals synchronous. We go to some lengths to prevent the sig_send function that sends signals from being interrupted. Cygwin allows you to choose the mode in which a file is read in several ways. it scans its signal bitmask and handles the signal in the appropriate fashion. Cygwin uses Doug Lea's free malloc implementation that successfully balances speed and compactness. when a process performs multiple exec calls. the library starts a secondary thread for use in signal handling. Changing the compiler's driver program to call spawn instead of fork was a trivial change and increased compilation speeds by twenty to thirty percent in our tests. there will be multiple Windows PIDs associated with a single Cygwin PID.data and .Cygwin User's Guide 5 / 82 bytes read to be an accurate indicator of position within the file. In the case of a process sending a signal to another process. the child wakes from blocking on the last mutex. The immediate consequence is that Cygwin system functions are interruptible unless special care is taken to avoid this. we use a separate semaphore/event pair instead of the mutex. in most circumstances the spawn family of calls provided by Cygwin can be substituted for a fork/exec pair with only a little effort. In the case of a process sending itself a signal. 1. which are not supported by newlib have been added to the Cygwin sources using BSD implementations as much as possible. These calls map cleanly on top of the Win32 API. For this reason.6. recreates any memory-mapped areas passed to it via the shared area. When a process notices it has a signal. spawn and exec present their own set of difficulties. waiting for their exec'd Cygwin process to exit. Other functions. The child then sets the mutex the parent is waiting on and blocks on another mutex. 1.bss sections by copying from its own address space into the suspended child's address space. Job control works as expected in shells that support it. This makes it very difficult to implement correctly. The reuse of existing free implementations of such things as the glob. However.6 Process Creation The fork call in Cygwin is particularly interesting because it does not map well on top of the Win32 API. It then fills in the child's . sig_send starts by resetting the event and incrementing the semaphore that flags the signal handler to process the signal. the child is run while the parent waits on a mutex. 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). 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. rather than write all of the lib C and math calls from scratch. regexp. stubs of each of these Win32 processes may linger. Several complications in the implementation arise from the fact that the signal handler operates in the same address space as the executing program. Finally. This makes it possible for a Cygwin process to provide its own malloc if it so desires. the Cygwin fork is a non-copy-on-write implementation similar to what was present in early flavors of UNIX. As a result. and returns from fork itself.7 Signals When a Cygwin process starts. Cygwin has to invent its own Process IDs (PIDs).6. As a result. Next. they are much more efficient. It then creates a suspended child process using the Win32 CreateProcess call. This is the signal for the parent to copy its stack and heap into the child. In addition. Most standard UNIX signals are provided.5 ANSI C Library We chose to include Red Hat's own existing ANSI C library "newlib" as part of the library. After the child's address space is initialized. as required by POSIX. The library accesses the malloc calls via an exported function pointer. . 1. Because there is no way to do an actual exec under Win32.6. we place a mutex around sig_send such that sig_send will not be interrupted until it has completely finished sending the signal. This thread waits for Windows events used to pass signals to the process. The child discovers it has been forked and longjumps using the saved jump buffer. After the signal is processed. and getopt libraries saved us considerable effort. Fortunately. previously only used by cross-compilers for embedded systems development. Currently. In some cases. fork will almost certainly always be inefficient under Win32. Newlib is a BSD-derived ANSI C library. after which it releases the mutex the child is waiting on and returns from the fork call.
Each thread polls the file descriptors of its respective type with the appropriate Win32 API call. Cygwin has to perform this initialization on the fly.0 adds replacement functions which implement the full functionality for IPv4. since it breaks backward compatibility too much. Cygwin's implementation also supports the getpeereid BSD extension. Some socket-related functions are not implemented at all in Winsock.7. An especially troublesome feature of Winsock is that it must be initialized before the first socket function is called. .6 change to set the Win32 current working directory (CWD) always to an invalid directory.7.o. Microsoft's implementation of Berkeley sockets. on the availability of the Windows IPv6 stack.7 1.7.1 What's new and what changed in Cygwin 1.6. -ltextreadmode and -lautomode. • Allow to link against -lbinmode instead of /lib/binmode.6 • Add new mount options "dos" and "ihash" to allow overriding Cygwin default behaviour on broken filesystems not recognized by Cygwin. child processes initialize Winsock if any inherited file descriptor is a socket. unless the Cygwin CWD is not usable as Win32 CWD. However. not feature complete in Windows 2003 and earlier. See Section 3.6. The more complex case involves waiting for socket or pipe file descriptors to be ready. There are then two cases to consider.7. So select returns. rexec(3) and rresvport(3). In that case. that thread signals the main thread to wake up.7.5 for details.8 Sockets Socket-related calls in Cygwin basically call the functions by the same name in Winsock. after polling all of the file descriptors one last time.7. 1. socketpair. as. • Make sure to follow the Microsoft security advisory concerning DLL hijacking. however.e. Cygwin does not depend on the underlying OS for the (newly implemented) getaddrinfo and getnameinfo functions. pipes. As a result. for example. Additional bookkeeping is necessary to implement correct socket sharing POSIX semantics and especially for the select call. In order to support sockets across fork calls. 1.0. Upon entry into the select function. but with lots of tweaks. we discovered that the Win32 select in Winsock only worked on socket handles.5 to 1. handles. The simple case is when at least one file descriptor is a type that is always known to be ready (such as a disk file). Microsoft removed the legacy calls rcmd(3). This case is now the same as the first one since we know at least one descriptor is ready.Cygwin User's Guide 6 / 82 1. As soon as a thread identifies a ready descriptor.7. This support is dependent. All sockets are non-blocking under the hood to allow to interrupt blocking calls by POSIX signals. The IPv6 stack was "experimental".1. Starting with Windows Vista. See the reworked Section 3. i. as soon as the first socket-related function is called by the application.7 • Partially revert the 1. Same for -ltextmode. This is completely transparent to the application. after starting one thread for each type of file descriptor present. Our implementation allows select to function normally when given different types of file descriptors (sockets.2 What's new and what changed from 1.7 What's new and what changed from 1. Cygwin does not yet support descriptor passing. The Cygwin CWD and the Win32 CWD are now kept in sync again. select returns immediately as soon as it has polled each of the other types to see if they are ready.2. Recent versions of Cygwin now implement all these calls internally. AF_UNIX (AF_LOCAL) sockets are not available in Winsock.4 for details. 1. and a custom /dev/windows Windows messages pseudo-device).7. They are implemented in Cygwin by using local AF_INET sockets instead. See the Microsoft Security Advisory (2269637) "Insecure Library Loading Could Allow Remote Code Execution" for details. Full IPv6 support became available starting with Windows Vista and Windows Server 2008.9 Select The UNIX select function is another call that does not map cleanly on top of the Win32 API. Much to our dismay.7. Cygwin 1.6 to 1. IPv6 is supported beginning with Cygwin release 1. the first operation is to sort the file descriptors into the different types. This is accomplished by the main thread suspending itself.
PT154. • Modification and access timestamps of devices reflect the current time. – New tool "locale" to fetch locale information and default locales based on the Windows default settings as well as lists of all supported locales and character sets. zh_TW -> Big5. The locale must exist in Windows to be recognized. – Default charset in the "C" or "POSIX" locale has been changed back from UTF-8 to ASCII.7.alias are also allowed.7.] 1.7. LC_MESSAGES is enabled via a big table with localized strings.7. and LC_TIME localization is enabled via Windows locale support. – LC_COLLATE. – Support for the various locale modifiers to switch charsets as on Linux. [. ja_JP -> EUC-JP.5 What's new and what changed from 1. These charsets are implemented as aliases to GBK. Locale aliases from the file /usr/share/locale/locale.7. – Cygwin now handles locales using the underlying Windows locale support. The Win32 current working directory is set to an invalid path to be out of the way. chmod and chown now work on ttys/ptys.2 • Localization support has been much improved. and TIS-620. – Default charset for locales without explicit charset is now chosen from a list of Linux-compatible charsets. LC_MONETARY...3 What's new and what changed from 1. • Locale categories contain all localization strings additionally as wide-char strings. just as on Linux. which does not require to use Cygserver. • Ttys and ptys are handled as securable objects using file-like permissions and owner/group information.7. LC_NUMERIC. . This allows shells to disable creating stackdump files in child processes via ulimit -c 0 in bash or limit coredumpsize 0 in tcsh. • DEPRECATED with 1.1 to 1. nl_langinfo(3) allows to fetch them.3 to 1.7. • Pass on coresize settings made with setrlimit(2).7. 1. 1. • New interfaces mkostemp(3) and mkostemps(3) are added. locale(1) prints these values just as on Linux.7: Cygwin handles the current working directory entirely on its own.3 • Support for GB2312/EUC-CN.Cygwin User's Guide 7 / 82 • Add new mount option "bind" to allow remounting parts of the POSIX file hirarchy somewhere else. • clock_gettime(3) and clock_getres(3) accept CLOCK_MONOTONIC.7. For instance: en_US -> ISO-8859-1. – Added support for the charsets GEORGIAN-PS. A new mechanism is used to propagate pty handles safely to other processes.4 What's new and what changed from 1.7.5 • Support for DEC Backarrow Key Mode escape sequences (ESC [ ? 67 h. to avoid problems with applications expecting a singlebyte charset in the "C"/"POSIX" locale. • New virtual file /proc/filesystems. Still use UTF-8 internally for filename conversion in this case. ESC [ ? 67 l) in Windows console.2 to 1. GB2312 is now the default charset name for the locales zh_CN and zh_SG. as long as their replacement is supported by the underlying Windows.
wcsftime(3). per POSIX-1. The integer portion of the result of a decimal conversion (%i.6 OS related changes • Windows 95. Mount points created with mount(1) are only local to the current session and disappear when the last Cygwin process in the session exits.bat like this: . – Support of combining Alt and AltGr modifiers in console window (compatible with xterm and mintty). 1832. Additionally these functions now also support the padding modifiers '0' and '+'. – New strfmon(3) call. • Support open(2) flags O_CLOEXEC and O_TTY_INIT flags. Add mouse reporting mode 1002 to report mouse drag movement. not invisible (28). – printf(3). Add mouse reporting mode 1003 to report any mouse movement. 98 and Me are not supported anymore. or $LC_CTYPE to a valid POSIX value. as defined by RFCs 1014. as well as a field width per POSIX-1. Add new Linux-compatible API calls accept4(2). %G) will be formatted with thousands' grouping characters. regcomp(3). • If a filename cannot be represented in the current character set. The new Cygwin 1.2008. • Handle native DOS paths always as if mounted with "posix=0. wprintf(3) families of functions now handle the grouping flag. and 4506. regexec(3) calls are now multibyte-aware. The XDR protocol and functions are useful for cross-platfrom data exchange. and /usr/lib automatically from it's own position on the disk. • New support for eXtensible Data Record (XDR) encoding and decoding.d/$USER instead. • Recognize NWFS filesystem and workaround broken OS call. Add focus event reporting (mode 1004). Alt-@ sends ESC @ also on keyboards where @ is mapped to an AltGr combination. – The console's backspace keycode can be changed using 'stty erase'.7. assumedly due to driver interworking issues). This allows to access all files. Support the signal SIGPWR. They don't have to be specified in /etc/fstab. In other words. Support fcntl flag F_DUPFD_CLOEXEC. compatible with xterm and mintty.g. • Cygwin creates the mount points for /. xterm-style. even those not having a valid representation of their filename in the current character set. Support socket flags SOCK_CLOEXEC and SOCK_NONBLOCK. – strftime(3). $LC_ALL. /usr/bin. the apostrophe '. 1.noacl". %u. • Add support for Windows 7 and Windows Server 2008 R2. and are commonly used as the core data interchange format for Remote Procedure Call (RPC) and NFS. and strptime(3) now handle the E and O format modifiers to print/scan alternative date and time representations or to use alternative digits in locales which support this. for instance in Cygwin.2008.7. – Support VT100 line drawing graphics mode in console window (compatible with xterm and mintty). – Function keys send distinguished escape sequences compatible with rxvt. • Handle UNC paths starting with slashes identical to /cygdrive paths. Keypad keys send distinguished escape sequences. %g. %F. 1. %d. use the UTF-8 charset by setting the environment variable $LANG. dup3(2).7 File Access related changes • Mount points are no longer stored in the registry. • Enhanced Windows console support. Use /etc/fstab and /etc/fstab. use the /cygdrive mount flags for these paths as well.7 DLL will not run on any of these systems.Cygwin User's Guide 8 / 82 – fnmatch(3). To always have a valid string. %f. not blinking (25) (compatible with xterm and mintty). – Add escape sequences for not bold (22). and pipe2(2). the character will be converted to a sequence Ctrl-X + UTF-8 representation of the character. – Report mouse wheel scroll events in mouse reporting mode 1000 (note: this doesn't seem to work on all systems. so that e.
FAT32. • Implement atomic O_APPEND mode. Only create Windows shortcut style symlinks if CYGWIN=winsymlinks is set in the environment. . Get correct stat(2) information and set real mode bits on open(2). Recognize and create real symlinks on NFS shares. • The CYGWIN environment variable option "ntea" has been removed without substitute. Cygwin 1. '<'. • unlink(2) and rmdir(2) try very hard to remove files/directories even if they are currently accessed or locked. • Recognize Samba version beginning with Samba 3.posix=0 mount flags. • Creating filenames with special DOS characters '"'. as required by POSIX. '|' is supported. • Recognize MVFS and workaround problems manipulating metadata and handling DOS attributes. • Recognize Netapp DataOnTap drives and fix inode number handling. ':'. • Handle NTFS native symlinks available since Vista/2008 as symlinks (but don't create Vista/2008 symlinks due to unfortunate OS restrictions). • Add st_birthtim member to struct stat. • The CYGWIN environment variable option "check_case" has been removed in favor of real case-sensitivity on file systems supporting it. filled out with DT_REG or DT_DIR. All other file types return as DT_UNKNOWN for performance reasons. • Recognize NFS shares and handle them using native mechanisms.0. • Make the "plain file with SYSTEM attribute set" style symlink default again when creating symlinks. • The CYGWIN environment variable options "ntsec" and "smbntsec" have been replaced by the per-mount option "acl"/"noacl".Cygwin User's Guide 9 / 82 set LC_CTYPE=en_US. • File names are case sensitive if the OS and the underlying file system supports it. This is done by utilizing the hidden recycle bin directories and marking the files for deletion. etc. • New open(2) flags O_DIRECTORY. • Creating files with special DOS device filename components ("aux". path names can be as long as the underlying OS can handle (32K). • Symlinks now use UTF-16 encoding for the target filename for better internationalization support. Just return an error instead.UTF-8 • PATH_MAX is now 4096. mkdir(2) and chmod(2). managed mounts have been removed. Does not work on FAT and Samba shares. "nul".28a using the new extended version information negotiated with the Samba developers. • Due to the above changes. not mandatory anymore. • access(2) now performs checks using the real user ID. • Incoming DOS paths are always handled case-insensitive and get no POSIX permission. • struct dirent now supports d_type. the old behavior of querying based on effective user ID is available through the new faccessat(2) and euidaccess(2) APIs.7 can read all old style symlinks. the flock(2) API creates and maintains locks with BSD semantics. but the new style is not compatible with older Cygwin releases. The fcntl(2) and the new lockf(2) APIs create and maintain locks with POSIX semantics. '*'.). Works on NTFS and NFS. • Stop faking hardlinks by copying the file on filesystems which don't support hardlinks natively (FAT. • rename(2) rewritten to be more POSIX conformant. Can be switched off on a per-mount basis. just like Linux. • File locking is now advisory. O_EXEC and O_SEARCH. as if they are mounted with noacl. "prn") is supported. '>'. Requires to change a registry key (see the User's Guide). Internally. POSIX and BSD locks are independent of each other.
replacement functions are available for IPv4. canonicalize_file_name. funopen. • Resolver functions (res_init. fchownat. renameat. Control-Space now emits an ASCII NUL (0x0) character. • Define multicast structures in netinet/in. same as the Linux console and xterm. Alt-Backspace emits ESC-DEL (0x1b. • New file conversion API for conversion from Win32 to POSIX path and vice versa (cygwin_conv_path. fchmodat. freeaddrinfo. if_nametoindex. • Detect when a stdin/stdout which looks like a pipe is really a tty. the underlying WinSock functions are used. • send/sendto/sendmsg now send data in 64K chunks to circumvent an internal buffer problem in WinSock (KB 201213). mknodat. this *is* the former libminires. • Support UTF-8 in console window.9 Device related changes • Reworked pipe implementation which uses overlapped IO to create more reliable interruptible pipes and fifos. Support real interface flags on systems supporting them. posix_fallocate. in6addr_any. • Other new APIs: bindresvport. • Improved fifo handling by using native Windows named pipes. Note that fully conformant multicast support is only available beginning with Vista/2008. cygwin_conv_path_list). [fl]setxattr. 1. Applications don't have to link against minires anymore. open_memstream. Support SIOCGIFINDEX.8 Network related changes • New implementation for blocking sockets and select on sockets which is supposed to allow POSIX-compatible sharing of sockets between threads and processes. • Other new APIs: posix_fadvise. fdopendir. this allows a debugged application to recognize that it is using the same tty as the debugger. rresvport_af. fpurge. res_search. • The CYGWIN environment variable option "binmode" has been removed. if_freenameindex. [fl]removexattr). unlinkat. dn_expand) are now part of Cygwin. eaccess. res_querydomain. iruserok_sa. • Add /proc/net/if_inet6. On systems with IPv6 enabled. faccessat. fstatat. mkdirat. fmemopen. res_mkquery. execvpe. in6addr_loopback. if_nameindex. keep in mind that a *fully* conformant implementation of getaddrinfo and other stuff is only available starting with Windows Vista/2008. linkat. New APIs getaddrinfo. . This allows rsh(1) usage on Vista/2008 and later. Redefine struct ifreq and subsequent datastructures to be able to keep more information. • New send/recv option MSG_DONTWAIT. fopencookie. instead of calling the WinSock function. • rcmd is now implemented inside of Cygwin. mkfifoat. fexecve. cygwin_create_path. bindresvport_sa. getifaddrs.Cygwin User's Guide 10 / 82 • List servers of all accessible domains and workgroups in // instead of just the servers in the own domain/workgroup. On IPv6-less systems. if_indextoname. futimesat. euidaccess. readlinkat. Among other things. While I tried hard to get the functionality as POSIXy as possible. • In the console window the backspace key now emits DEL (0x7f) instead of BS (0x08). res_send.7. [fl]listxattr. • Support Linux-like extended attributes ([fl]getxattr. mkstemps. • New openat family of functions: openat. 1.a. res_query.7. SIOCGIFDSTADDR and the Cygwin specific SIOCGIFFRNDLYNAM. gethostbyname2. getnameinfo. which dropped this function from WinSock. symlinkat. dn_comp. gai_strerror.0x7f) instead of DEL (0x7f). • IPv6 support. Actually. • Improve get_ifconf. rcmd_af. freeifaddrs. open_wmemstream.h.
vfwscanf. get_phys_pages. putwchar. • Implement pthread_kill(thread. • Allow multiple concurrent read locks per thread for pthread_rwlock_t. 850. vfwprintf. • New options have been added to the mkpasswd and mkgroup tools to ease use in multi-machine and multi-domain environments.html • Cygwin now allows storage and use of user passwords in a hidden area of the registry. 0) as per POSIX. • Support for WCONTINUED. wprintf. ungetwc. This must be manually installed by a privileged user using the /bin/cyglsa-config script. wcstod. • New API: cfmakeraw. "UTF-8". shm_unlink. For instance. insque. • New APIs: _Exit. . rint. confstr. "eucKR".a. "KOI8-R". wcstok. except 12. fgetwc. fwscanf. libresolv. The default locale in the absence of one of the aforementioned environment variables is "C. rintl. similar to Linux. mq_getattr.ISO-8859-15" before starting a Cygwin session will use the ISO-8859-15 character set in the entire session./dev/ttyS63. 1258). wcstoumax. 862. 866./dev/sddx. wcstof. rintf. fputwc. mq_close. with xxx in (437. • Fallout from the long path names: If the current working directory is longer than 260 bytes. 874. stpncpy. putwc. swprintf. 1257. "SJIS".h>. 1. The existing options have a slightly changed behaviour. wcsncasecmp. 1255. pow10f. mq_send. setting $LANG to "de_DE. exp10.UTF-8". mq_unlink. wcsftime. get_nprocs_conf. • Support up to 128 raw disk drives /dev/sda . wcstoimax. vwprintf. mq_receive. sem_close. 737. 1250. remque. 1253. swscanf. 1256.7. wcstoull. reallocf. pow10. vswscanf. $LC_ALL or $LC_CTYPE will be used. mbsnrtowcs. librt.com/ml/cygwin-developers/200611/msg00000. • New API for POSIX IPC: Named semaphores: sem_open. wcsnrtombs. llrintf. The advantages and disadvantages are noted in http://cygwin. lrintl. wcsnlen. The setting of the environment variables $LANG. /cygdrive. mq_notify. llrintl. 1125.12 Miscellaneous • New ldd utility.Cygwin User's Guide 11 / 82 • Support up to 64 serial interfaces using /dev/ttyS0 . 1251. mq_timedreceive. wcstoul. Message queues: mq_open. for instance. • Cygwin now comes with a real LSA authentication package. dprintf. lrint. WIFCONTINUED() added to waitpid and wait4. fwide. • Only declare expected functions in <strings. 857. 1254. • New link libraries libdl. 720. //server). get_nprocs. sem_unlink. wcsxfrm. llrint. "ISO-8859-x" with x in 1-16. 1.7. vdprintf. 1252. posix_openpt. strcasestr.7. ssh public key sessions with full network credentials to access shares on other machines. vwscanf. vasnprintf. asnprintf. This allows.10 Other POSIX related changes • A lot of character sets are supported now via a call to setlocale(). don't include <string. wcpncpy. fputws. "GBK". wcstol. 858. getwchar. don't call native Win32 programs since they don't understand these paths. exp10f. Windows codepages "CPxxx". sys_sigabbrev. fwprintf. posix_memalign. wcscasecmp. The full list of supported character sets: "ASCII". 852.h> from here. wcpcpy. stpcpy. mq_timedsend.11 Security related changes • Getting a domain user's groups is hopefully more bulletproof now. and "Big5". wcstoll. or if the current working directory is a virtual path (like /proc. posix_madvise.a. This is tried first when Cygwin is called by privileged processes to switch the user context. vswprintf. get_avphys_pages. Shared memory: shm_open. 775. mq_setattr. wscanf. "eucJP". 1.a. lrintf. getwc. fgetws. 855. "KOI8-U".
\\foo\bar). This warning may be disabled via the new CYGWIN=nodosfilewarning setting. • Each Cygwin DLL stores its path and installation key in the registry. Switch back to old behaviour with the new CYGWIN=upcaseenv setting. • Detect and report a missing DLL on process startup. • Add the ability to distinguish registry keys and registry values with the same name in the same registry subtree. • Don't force uppercase environment when started from a non-Cygwin process. • Add /proc/$PID/mounts entries and a symlink /proc/mounts pointing to /proc/self/mounts as on Linux.Cygwin User's Guide 12 / 82 • On the first usage of a DOS path (C:\foo. Cygwin automatically uses cygserver if it's available. The key is called "foo" and the value will be called "foo%val" in this case. • The CYGWIN environment variable option "server" has been removed. • Allow environment of arbitrary size instead of a maximum of 32K. the Cygwin DLL emits a scary warning that DOS paths shouldn't be used. . • Optimized strstr and memmem implementation. to support the toolchain in implementing full C++ standards conformance when working with shared libraries. Except for certain Windows and POSIX variables which are always uppercased. (Some *very* old programs which use signal masks may no longer work correctly). • Remove backwards compatibility with old signal masks. This allows troubleshooting of problems which could be a result of having multiple concurrent Cygwin installations. • Different Cygwin installations in different paths can be run in parallel without knowing of each other. • Cygwin now exports wrapper functions for libstdc++ operators new and delete. preserve environment case. The path of the Cygwin DLL used in a process is a key used when creating IPC objects. • Add /proc/registry32 and /proc/registry64 paths to access 32 bit and 64 bit registry on 64 bit systems. • Align /proc/cpuinfo more closly to Linux content. So different Cygwin DLLs are running in different namespaces.
unless you do not have write access to HKEY_LOCAL_MACHINE in the registry or the All Users Start Menu.1. search the list for mkcygwget for ideas.exe installation. The only exception to this is choosing a Cygwin mirror.exe installer is designed to be easy for new users to understand while remaining flexible for the experienced.exe in it. It may already be present in the CVS version! Since the default value for each option is the logical choice for most installations. which you can choose by experimenting with those listed at http://cygwin. setup. you might create a C:\cache\ directory and place setup. If you are new to Unix.exe which can be run to download a complete cygwin installation via the internet. The volunteer development team is constantly working on setup. Please note that this guide assumes that you have a basic understanding of Unix (or a Unix-like OS). check the wishlist in the CVS README . The Download from Internet option is mainly for creating a base Cygwin package tree on one computer for installation on several machines with Install from Local Directory.exe to Install from Internet or Download from Internet.com/mirrors.1 Download Source Cygwin uses packages to manage installing various software. read on below. This will download a GUI installer called setup. 2. Run setup. Follow the instructions on each screen to install Cygwin. When the default Install from Internet option is chosen.2 Selecting an Install Directory The Root Directory for Cygwin (default C:\cygwin) will become / within your Cygwin installation. You must have write access to the parent directory.exe.1 Internet Setup To install the Cygwin net release. Though this provides some basic mirroring functionality. Download from Internet performs only the first part (storing the packages locally). to keep up to date we recommend using a mirroring tool such as wget. you can get a working minimal Cygwin environment installed by simply clicking the Next button at each page. go to http://cygwin. copy the entire local package tree to another machine with the directory tree intact. if you are managing a large Cygwin installation. you will also want to make use of other resources. This is true even if you are the only . and any ACLs on the parent directory will determine access to installed files.1. 2. while Install from Local Directory performs only the second (installing the contents of the packages). then copy the whole C:\cache\ to each machine and instead choose Install from Local Directory.html .Cygwin User's Guide 13 / 82 Chapter 2 Setting Up Cygwin 2. A helpful user on the Cygwin mailing list created a simple demonstration script to accomplish this. The Install For options of All Users or Just Me should always be left on the default All Users. before requesting a new feature. The setup.com/ and click on "Install Cygwin Now!". For example. For more details about each of page of the setup.exe creates a local directory to store the packages before actually installing the contents.
check the list at http://cygwin.html to find one near you. and Pending (only packages to be installed. Within the cache.6 Choosing Packages For each selected mirror site. removed or upgraded).1. the cache is no longer necessary. use the Pending view to see which packages have been marked for upgrading. see the setup. Unfortunately.Cygwin User's Guide 14 / 82 user planning to use Cygwin on the machine. or in case you need to reinstall a package. if setup. 2. you can manually type it into the Use Proxy section. click on Keep to toggle it.exe does not currently support password authorization for proxy servers. the setup. Cygwin mirrors are geographically distributed around the world. By default. Also. setup. but you may want to retain the packages as backups.1. If you have a proxy server. it will automatically mark it to be upgraded. After installing Cygwin.exe's view style. In particular.exe automatically selects dependencies.exe will install only the packages in the Base category and their dependencies. You can select multiple mirrors by holding down CTRL and clicking on each one. Full (all packages). If your organisation uses a proxy server or auto-configuration scripts. Information on installed packages is kept in the /etc/setup/ directory of your Cygwin installation. but still want to use these programs.exe begins to install the upgraded package. . For details about the format of this file.exe stores the packages before they are installed. Selecting Just Me will cause problems for programs such as crond and sshd.exe finds a newer version of an installed package available. while the IE5 method will leverage your IE5 cache for performance. setup. which allows setup.exe to use multiple mirrors and custom packages. be careful not to unselect any required packages. Reinstall. the IE5 method also uses these settings.com/mirrors. to avoid the need to reboot after upgrading.5 Choosing Mirrors Since there is no way of knowing from where you will be downloading Cygwin. \r\n). To avoid unintentionally upgrading. consult the Cygwin mailing list archives about others' experiences. If you have the URL of an unlisted mirror (for example.exe downloads a small text file called setup. If you don't want to upgrade a package. for installing Cygwin to another system. Each package can be found under any of those categories in the heirarchial chooser view.4 Connection Method The Direct Connection method of downloading will directly download the packages.exe. 2. or get the Source for an existing package. setup.bz2 that contains a list of packages available from that site along with some basic information about each package which setup. To Uninstall. if your organization has an internal Cygwin mirror) you can add it. 2. resulting in a minimal Cygwin installation. 2. click on the new version number to toggle it until it says Keep. The chooser is the most complex part of setup. and one package may belong to multiple categories (assigned by the volunteer package maintainer). If you are familiar with Unix. However. Click on the View button and it will rotate between Category (the default).1. make sure to close all Cygwin windows and stop all Cygwin processes before setup. you will probably want to at least glance through the Full listing for your favorite tools. Packages are grouped into categories.3 Local Package Directory The Local Package Directory is the cache where setup. \n) unless you have a very good reason to switch it to DOS (that is. this will not include many commonly used tools such as gcc (which you will find in the Devel category). which is helpful if you know the name of a package you want to install but not which category it is in. If you do not have the necessary permissions. you need to choose at least one mirror site. everything in the Base category is required.exe homepage.exe cannot find this directory it will act as if you have no Cygwin installation. The Default Text File Type should be left on Unix (that is. Once you have an existing Cygwin installation.exe parses and uses to create the chooser window. a separate directory is created for each Cygwin mirror.1. You can change setup. If setup.exe chooser is also used to manage your Cygwin installation. Since setup. The cache must not be the same folder as the Cygwin root.
1. 2.exe it will try to replace old or experimental versions with the current stable version.bat to your liking or create your own .full.7. 2. 2.. so try a different mirror and/or a different protocol (i.bat and is created in the Cygwin root directory that you specified during setup.exe will run any post-install scripts to finish correctly setting up installed packages.) using a syntax like this in the DOS shell. The PATH environment variable is used by Cygwin applications as a list of directories to search for executable files to run. Note that the "Cygwin" option of the Start Menu points to Cygwin. setup. several windows may pop up. for instance). Make a backup of this file before running setup. all of them are honored and have a meaning.1. The CYGWIN variable is used to configure many global settings for the Cygwin runtime system. HTTP instead of FTP). 2. Some of these settings need to be in effect prior to launching the initial Cygwin session (before starting your bash shell. you can use these shortcuts as a guide to creating your own. Such settings can be placed in a .2. you can check the setup.html When the last post-install script is completed.1 Environment Variables Overview You may wish to specify settings of several important environment variables that affect Cygwin's operation.4. see Section 3. Since Cygwin 1. During the download and installation. They should therefore be set in the Windows environment. it may be network congestion. This environment variable is converted from Windows format (e. For a more detailed description see Section 2. setup. setup.exe will download all selected packages to the local directory chosen earlier. that the next time you run setup.2 2. If you prefer to use a different shell or terminal emulator such as mintty or xterm. A few packages. require some manual site-specific configuration.7 Download and Installation Progress First.bat file.com/setup. By default the chooser shows only the current version of each package. Initially you can leave CYGWIN unset or set it to tty (e.exe log file at /var/log/setup.exe again.Cygwin User's Guide 15 / 82 The final feature of the setup.log.exe performs a checksum on each package. If you notice something is not working after running setup. though mirrors have at least one previous version and occasionally there is a testing or beta version of a package available. click on the Prev or Exp radio button. to support job control with ˆZ etc.2.e. An initial file is named Cygwin.bat. Locale support is controlled by the LANG and LC_xxx environment variables. To see these package. such as the OpenSSH server. Before installing.exe will display a box announcing the completion. setup.1. see the Cygwin Package Contributor's Guide at http://cygwin. and follow the steps for Reporting Problems with Cygwin. If you are interested in what is being done.8 Icons You may choose to install shortcuts on the Desktop and/or Start Menu to start a bash shell. Edit Cygwin.9 Post-Install Scripts Last of all. setup. Relevant documentation can be found in the /usr/doc/Cygwin/ or /usr/share/doc/Cygwin/ directory.5..g. the complex setup process means that odd problems can occur. C:\Windows\system32. all Windows environment variables are imported when Cygwin starts.bat files to start Cygwin processes. before launching bash. C:\> set CYGWIN=tty notitle glob For all possible settings of the CYGWIN environment variable.exe shows progress bars for the current task and total remaining disk space. Since each script is run separately. If you're having trouble downloading packages.1. however. If the local directory is a slow medium (such as a network drive) this can take a long time.exe chooser is for Previous and Experimental packages.C:\Windows) to UNIX format .10 Troubleshooting Unfortunately. Be warned. 2..g.
Cygwin User's Guide 16 / 82 (e. Add the DWORD value heap_chunk_in_mb and set it to the desired memory limit in decimal MB. are converted to UNIX format: TMPDIR.dll files to load. (For more information about regtool or the other Cygwin utilities. Most Cygwin applications do not make use of the dlopen () call and do not need this variable. In these cases. The LD_LIBRARY_PATH environment variable is used by the Cygwin function dlopen () as a list of directories to search for . and they point to the default Windows temporary directory. The TERM environment variable specifies your terminal type. see Section 3. If set. The Win32 environment is usually stripped to a bare minimum and not at all kept in sync with the Cygwin POSIX environment. possibly with unexpected results. if they exist in the Windows environment. For example: export TMP=/tmp export TEMP=/tmp 2.h> cygwin_internal (CW_SYNC_WINENV). However. you could set TMP and TEMP to point to /tmp or to any other temporary directory of your choice.g. to synchronize the Win32 environment with the Cygwin environment. This environment variable is converted from Windows format to UNIX format when a Cygwin process first starts. Alternatively. Note that this only synchronizes the Win32 environment once with the Cygwin environment. 2. This environment variable is also converted from Windows format when a Cygwin process first starts. Later changes using the setenv or putenv calls are not reflected in the Win32 environment. In addition to PATH. You may therefore want to unset them by adding the following two lines to your ~/. It's usually set in the shell profile scripts in the /etc directory. this problem can be solved by adding an entry in the either the HKEY_LOCAL_MACHINE (to change the limit for all users) or HKEY_CURRENT_USER (for just the current user) section of the registry. there are three other environment variables which. you have to call the aforementioned cygwin_internal call again.2..bashrc file.bashrc file: unset TMP unset TEMP This is done in the default ~/.3 Changing Cygwin's Maximum Memory Cygwin's heap is extensible.7 or use the --help option of each util. It is automatically set to cygwin if you have not set it to something else. /cygdrive/c/Windows/system32:/cygdrive/c/Windows) when a Cygwin process first starts. The HOME environment variable is used by many programs to determine the location of your home directory and we recommend that it be defined. If you need the full Win32 environment set up in a Cygwin process. HOME.) You should always be careful when using regtool since damaging your system registry can result in an unusable system. This example sets memory limit to 1024 MB: . In some cases. these variables will be used by some Cygwin applications. you have to call #include <sys/cygwin. it does start out at a fixed size and attempts to extend it may run into memory which has been previously allocated by Windows. Cygwin maintains its own environment in POSIX style. and TEMP. TMP. Set it so that it contains at least the x:\cygwin\bin directory where "x:\cygwin is the "root" of your cygwin installation if you wish to use cygwin tools outside of bash. The first is not set by default in the Windows environment but the other two are. and LD_LIBRARY_PATH. It is preferred to do this in Cygwin using the regtool program included in the Cygwin package.2 Restricted Win32 environment There is a restriction when calling Win32 API functions which require a fully set up application environment. This is usually done by the batch file you're starting your shell with.
you can find it in the online publication of the POSIX manual pages on the homepage of the Open Group. sum. If so. The content of these variables should follow the POSIX standard for a locale specifier.UTF-8" language = french. or. if there is no ISO 639-1 code for the language (for instance.eucKR" language = korean.c -o max_memory.4 2. given the default content of the /usr/share/locale/locale.0). } You can compile this program using: gcc max_memory. char *x. sum=0. "Lower Sorbian"). in this order. charset = UTF-8 "ko_KR. the below examples would be valid locale specifiers as well.0/1024. territory = Switzerland. Cygwin checks if the locale is one of the locale aliases defined in the file /usr/share/locale/locale.1 Internationalization Overview Internationalization support is controlled by the LANG and LC_xxx environment variables. The system swap should be at least as large as the physically installed RAM and can be modified under the System category of the Control Panel. return 0.4. the locale is accepted. . charset is one of a list of supported character sets. So. Here is a small program written by DJ Delorie that tests the memory allocation limit on your system: main() { unsigned int bit=0x40000000. default charset If the locale specifier does not follow the above form. Memory can be allocated up to the size of the system swap space minus any the size of any running processes. too. LC_CTYPE. "TERRITORY" is an uppercase two character string per ISO 3166. a three character string per ISO 639-3. Typical locale specifiers are "de_CH" language = German. default charset "fr_FR. if (x) sum += bit. while (bit > 4096) { x = malloc(bit). territory = South Korea. territory = France. sum/1024.alias. and LANG.charset][@modifier]] "language" is a lowercase two character string per ISO 639-1.1fMb)\n". according to the POSIX standard.alias file. territory = Syria. see below). 2. The correct form of a locale specifier is language[[_TERRITORY][. If you're interested in the exact description. bit >>= 1. } printf("%08x bytes (%.Cygwin User's Guide 17 / 82 regtool -i set /HKLM/Software/Cygwin/heap_chunk_in_mb 1024 regtool -v list /HKLM/Software/Cygwin Exit all running Cygwin processes and restart them. and if the replacement localename is supported by the underlying Windows. charset = eucKR "syr_SY" language = Syriac. You can set all of them but Cygwin itself only honors the variables LC_ALL. The modifier doesn't matter here (though some are recognized.exe Run the program and it will output the maximum amount of allocatable memory.
charset". • The default script used for all Serbian language locales (sr_BA. typically by using the call setlocale (LC_ALL. but not within the same process. the setlocale function fails. even if one of the locale environment variables is set to some other value than "C". the application's locale is set to the default "C" or "POSIX" locale. this locale defaults to the ASCII character set on the application level.UTF-8" default locale) for converting filenames etc.2 and later. the locale is set to the default locale. the language and territory are used to fetch locale-dependent information from Windows. This allows for easier interoperability with applications running in the default "C.ISO-8859-1" in locale.2. The setting of the locale environment variables at process startup is effective for Cygwin's internal conversions to and from the Windows UTF-16 object names for the entire lifetime of the current process. Cygwin will still use UTF-8 under the hood to translate filenames. When the locale in the environment specifies an ASCII charset. which includes a character for the "Euro" currency sign. and there is none of the important locale variables set in the environment. sr_ME. • The default charset of the "uz_UZ" locale (Uzbek/Uzbekistan) is ISO-8859-1. you can define this by setting one of the locale environment variables to "C. early in the application code. As the POSIX standard requires. This is especially important with filenames. it's the application's responsibility to activate that locale for its own purposes. will nevertheless use the locale set in the environment (or the "C. the modifier "@euro" can be added to enforce usage of the ISO-8859-15 character set. At application startup.alias is provided by the gettext package under Cygwin. so that this doesn't get lost: If the application calls setlocale as above. they are running in the "C" or "POSIX" locale. • For locales which use the Euro (EUR) as currency.alias defined as "tr_TR. With the "@cyrillic" modifier it's UTF-8. For instance "C. Any other modifier is simply ignored for now. However. and LANG. and the deprecated sr_CS and sr_SP) is cyrillic. for example "C" or "en_US. The following modifiers are recognized. The Cygwin DLL itself. LC_CTYPE. • The default charset of the "be_BY" locale (Belarusian/Belarus) is CP1251.alias defined as "ja_JP. however. which is "C.ISO-8859-9" in locale. Starting with Cygwin 1. Changing the environment variables to another value changes the way filenames are converted in subsequently started child processes.UTF-8" locale.7. . sr_RS.ASCII".UTF-8".UTF-8". to determine how to convert Windows filenames from their UTF-16 representation to the singlebyte or multibyte character set used by Cygwin. Again. With the "@iqtelif" modifier it's UTF-8. ""). this does only affect how Cygwin itself converts filenames.ISO-8859-1" Note The default locale in the absence of the aforementioned locale environment variables is "C.7. Windows uses the UTF-16 charset exclusively to store the names of any object used by the Operating System. • The default charset of the "tt_RU" locale (Tatar/Russia) is ISO-8859-5. which implies the ASCII charset.eucJP" in locale. If the language and territory are not known to Windows. Cygwin uses the setting of the locale environment variables LC_ALL. But what about applications which are not locale-aware? Per POSIX. With the "@latin" modifier it's UTF-8. With the "@latin" modifier it gets switched to the latin script with the respective collation behaviour. If you want to stick to the "C" locale and only change to another charset.Cygwin User's Guide 18 / 82 "catalan" "japanese" "turkish" defined as "ca_ES. Under Cygwin 1.alias The file /usr/share/locale/locale.
4). Assume further that you're living in Japan.bat file which is the batch file to start a Cygwin session from the "Cygwin" desktop shortcut. In these languages wcwidth and wcswidth return 2 for these characters. except if the language is specifed as "ja" (Japanese). For these characters the width returned by the wcwidth/wcswidth function is usually 1.i UTF-8 is the only multibyte character set which can represent every Unicode character. . For instance. This is often a problem in East-Asian languages.7.2 How to set the locale • Assume that you've set one of the aforementioned environment variables to some valid POSIX locale value. which historically use character sets in which these characters have a width of 2. While Cygwin has a workaround to access files with unusual characters (see Section 3. other than "C" and "POSIX".4. set LANG=es_MX. 2.UTF-8 For a description of the Unicode standard. is to set the LANG variable in the C:\cygwin\Cygwin. Cygwin uses a character set which is the typical Unix-equivalent to the Windows ANSI codepage. say. use the new >locale -a command. which modifies the behaviour of wcwidth/wcswidth to return 1 for the ambiguous width characters. which is part of the Cygwin package. the wcwidth/wcswidth functions return 1 as the width of these characters.5 • Last. This is not correct in all circumstances. Not all characters from the Unicode character set are available in a singlebyte or doublebyte charset. so what will Cygwin use now? Starting with Cygwin 1. so the user of one of these languages can specify the modifier "@cjknarrow". called the "CJK Ambiguous Width Character set".7. but not least. By default. LANG to "ja_JP".4. thus setting. What you can do. For a description see Section 3. Windows filesystems use the Unicode character set in the UTF-16 encoding to store filename information.2. @echo off C: chdir C:\cygwin\bin set LANG=ja_JP. but the Windows default charset SJIS.6 Note For a list of supported character sets. "ko" (Korean). You might want to use the language code "ja" and the territory "JP".4. You didn't set a character set. a better workaround is to use always the UTF-8 character set. the default character set is determined by the default Windows ANSI codepage for this language and territory.Cygwin User's Guide 19 / 82 • There's a class of characters in the Unicode character set. or "zh" (Chinese). For instance: "en_US" ISO-8859-1 "el_GR" ISO-8859-7 "pl_PL" ISO-8859-2 "pl_PL@euro" ISO-8859-15 "ja_JP" EUCJP "ko_KR" EUCKR "te_IN" UTF-8 • You don't want to use the default character set? In that case you have to specify the charset explicitly. most singlebyte or doublebyte charsets have a big disadvantage. see the homepage of the Unicode Consortium. for instance. see Section 2. assume you're from Japan and don't want to use the japanese default charset EUC-JP.SJIS bash --login -i Note For a list of locales supported by your Windows machine.
but also in your Cygwin shell on the fly. what if a non-localized application calls a remote application which itself is localized? This can happen with ssh or rlogin. the target filename of the symlink is now potentially an invalid character sequence in the new character set. this is no problem at all. or running the Cygwin. the current ANSI or OEM character set had been used to store the target filename. you can open the "Regional and Language Options" portion of the Control Panel. If you are running Windows XP or older.exe. as you would use it in the internationalization environment variables as outlined above. 20932/EUC-JP. However.2. the name of an environment variable should only consist of valid ASCII characters. and you're planning to use. As long as the environment only contains ASCII characters.Cygwin User's Guide 20 / 82 2.4. The environment is another of the system objects stored in UTF-16 in Windows. here's a problem. may pose a problem when switching charsets on the fly. too. When a Cygwin process is started in a Windows console (either explicitly from cmd. 2. If the target filename contains non-ASCII characters and you use another character set than your default ANSI/OEM charset. and the underscore for maximum portablilty.2.4. here's the list of currently supported character sets. Symbolic links. or implicitly by. While terminal emulations like xterm or mintty have a distinct way to set the character set used for in. the Windows environment is converted from UTF-16 to UTF-8. even switch to yet another character set.bat file).and output. This problem is solved in Cygwin as follows. the Console character set is determined by the setting of the aforementioned internationalization environment variables. In bash for instance: bash$ export LC_CTYPE="nl_BE. Setting one of the internationalization environment variable to the same charset as the remote machine before starting ssh or rlogin fixes that problem.4. the Windows console hasn't such a way. At the start of the first Cygwin process in a session. Note that charset specifiers are case-insensitive. dependent on the old CYGWIN environment variable setting codepage (see Section 3. This behaviour is not different from the behaviour in other Operating Systems. 949/EUC-KR. if you suddenly can't access a symlink anymore which worked all these years before. A symbolic link contains the filename of the target file the symlink points to. The left-hand expression is the name of the charset. Cygwin converts the PATH environment variable to the charset set in the environment. This would be especially a problem in variables like PATH. select the "Advanced" tab. 950/Big5. But if it contains native characters. clicking on the Cygwin desktop icon.4 Potential Problems when using Locales You can set the above internationalization variables not only in Cygwin.5 List of supported character sets Last but not least.3 The Windows Console character set Most of the time the Windows console is used to run Cygwin applications. the same way as described in Section 2. When a symlink had been created with older versions of Cygwin. 2. digits. the application knows if it uses localization or not. 936/GBK. To circumvent the worst problems. since it's not an application in its own right. maybe it's because you switched to another character set. if it's different from the UTF-8 charset. EUCJP is equivalent to eucJP or eUcJp. Both commands don't have and don't need localization and they never call setlocale. for instance. say.7 or later. and yet another. This doesn't occur with symlinks created with Cygwin 1. . GBK. the environment will result in invalid characters in the GBK charset. and only of uppercase letters.UTF-8" However. Another problem you might encounter is that older versions of Windows did not install all charsets by default. Note Per POSIX. Writing the charset in the exact case as given in the list below is a good convention. So. What is that good for? Why not switch the console character set with the applications requirements? After all.bat or in the Windows environment.5.4. The following entries are useful to cygwin: 932/SJIS. and select entries from the "Code page conversion tables" list. though.
Central European) (OEM Cyrillic) (OEM Turkish) (OEM Latin 1 + Euro Symbol) (OEM Hebrew) (OEM Russian) (ANSI/OEM Thai) not exactly identical to SJIS) (OEM Ukraine) (ANSI Central European) (ANSI Cyrillic) (ANSI Latin 1. always use them with the trailing "CP".437 You can find a full list of Windows codepages on the Microsoft MSDN page Code Page Identifiers. Especially in case of the "CPxxx" style charsets. Western European) (ANSI Greek) (ANSI Turkish) (ANSI Hebrew) (ANSI Arabic) (ANSI Baltic) (ANSI/OEM Vietnamese) (ISO-8859-1) (ISO-8859-2) (ISO-8859-3) (ISO-8859-4) (ISO-8859-5) (ISO-8859-6) (ISO-8859-7) (ISO-8859-8) (ISO-8859-9) (not available) (not available) (ISO-8859-13) (not available) (ISO-8859-15) (not available) 437 720 737 775 850 852 855 857 858 862 866 874 932 (Shift_JIS. They are only noted here for reference.CP437 This does not work: set LC_ALL=en_US. 1125 1250 1251 1252 1253 1254 1255 1256 1257 1258 28591 28592 28593 28594 28595 28596 28597 28598 28599 28603 28605 - 950 (ANSI/OEM Traditional Chinese) 936 (ANSI/OEM Simplified Chinese) 20932 (EUC Japanese) . unless they happen to be identical with the left-hand side. Don't try to use the bare codepage number or the Windows name of the codepage as charset in locale specifiers. Charset ------------------ASCII CP437 CP720 CP737 CP775 CP850 CP852 CP855 CP857 CP858 CP862 CP866 CP874 CP932 CP1125 CP1250 CP1251 CP1252 CP1253 CP1254 CP1255 CP1256 CP1257 CP1258 ISO-8859-1 ISO-8859-2 ISO-8859-3 ISO-8859-4 ISO-8859-5 ISO-8859-6 ISO-8859-7 ISO-8859-8 ISO-8859-9 ISO-8859-10 ISO-8859-11 ISO-8859-13 ISO-8859-14 ISO-8859-15 ISO-8859-16 Big5 EUCCN or euc-CN EUCJP or euc-JP Codepage ------------------------------------------20127 (US_ASCII) (OEM United States) (DOS Arabic) (OEM Greek) (OEM Baltic) (OEM Latin 1.Cygwin User's Guide 21 / 82 The right-hand side is the number of the equivalent Windows codepage as well as the Windows name of the codepage. This works: set LC_ALL=en_US. Western European) (OEM Latin 2.
called the "Discretionary Access Control List" (DACL). Let's talk about the SID first. 2. We start with a short overview. called the "Security Access Control List" (SACL). but are more complicated because they are unique across multiple machines or domains. but not exactly CP932) (ANSI/OEM Thai) 65001 (UTF-8) 2. There's a convenient convention to type SIDs. which doesn't matter for our purpose. but assumed to be understood by the reader. If you want to learn more about the Windows security model. POSIX concepts and specificially the POSIX security model are not discussed here. as well as how the Windows authentication model is used to allow cygwin applications to switch users in a POSIX-like fashion. This is not discussed here. The SD of an object consists of five parts: • Flags which control several aspects of this SD. • The SID of the object owner group.5 Using Windows security in Cygwin This section discusses how the Windows security model is utilized in Cygwin to implement POSIX-like permissions. If you don't know the POSIX security model. see the Access Control article in MSDN documentation. We ignore it here. and to determine what they are allowed to do to or with it. computers and Active Directory (AD) domains. semaphores.5. • A list of "Access Control Entries" (ACE). threads. Every ACE contains a so-called "Security IDentifier" (SID) and other stuff which is explained a bit later. The SD contains all information necessary to control who can access an object. almost. • Another list of ACEs. groups. Here's an example: SID of a machine "foo": S-1-5-21-165875785-1005667432-441284377 SID of a user "johndoe" of the system "foo": S-1-5-21-165875785-1005667432-441284377-1023 . A SID is a structure of multiple numerical values. almost any "object" is securable. "Objects" are files.1 Overview In the Windows security model. • The SID of the object owner. Note that this overview must be necessarily short. called a "security descriptor" (SD). search the web for beginner documentation. SIDs are basically comparable to POSIX user ids (UIDs) and group ids (GIDs). as a string of numerical fields separated by hyphen characters. A SID is a unique identifier for users. processes.Cygwin User's Guide 22 / 82 EUCKR or euc-KR GB2312 GBK GEORGIAN-PS KOI8-R KOI8-U PT154 SJIS TIS620 or TIS-620 UTF-8 or utf8 949 936 936 20866 21866 874 (EUC Korean) (ANSI/OEM Simplified Chinese) (ANSI/OEM Simplified Chinese) (not available) (KOI8-R Russian Cyrillic) (KOI8-U Ukrainian Cyrillic) (not available) (not available. etc. The setting of POSIX-like file and directory permissions is controlled by the mount option (no)acl which is set to acl by default. Every object has a data structure attached.
the "Everyone" SID. The last part of the SID. Here are a few examples for well-known SIDs: Everyone Batch S-1-1-0 Simply everyone. one account created on the machine "foo". The Cygwin package called "csih" provides a tool. consider you created a new domain "bar" on some new domain controller and you would like to create a domain account "johndoe": SID of a domain "bar. It's a bit different in domains. except for an additional part. Both have different SIDs and not even the RID is the same.. Windows has a SID for these poor souls. One is "FOO\johndoe". For example. represent the unique 96 bit identifier of the computer system. They have the same meaning across the Windows network.. As you can see in the above example. For a full list please refer to the MSDN document Well-known SIDs. the name is the same.. but in practice it's sufficient if the computer SIDs are unique within a single Windows network.local": S-1-5-21-186985262-1144665072-740312968 SID of a user "johndoe" in the domain "bar. which can be used to print the (possibly localized) name for the various well-known SIDS. the other one is "BAR\johndoe" or "johndoe@bar. different account.local". All machines on the network will treat these SIDs as identifying two separate accounts. Anonymously accessing users are not incuded here. Domain user SIDs look exactly like the computer user SIDs. well-known SIDs are the same on each machine. the leading part is just the domain SID and the RID is created when the user is created.. one created in the domain "bar. so they are not unique to a machine or domain. How do the systems know it's the same account? After all. right? The answer is. So far there exists only one version of SIDs. Authenticated Users S-1-5-11 Users which have gone through the authentication process and survived. Naturally. sort of an uber-root account. POSIX has no GID for the group of "all users" or "world" or "others". Interactive S-1-5-4 Only processes of users which are logged in via an interactive session are members here. So the SID of a user is always uniquely attached to the system on which the account has been generated. so this field is always 1. all 32 bit values. S-1-5-3 Processes started via the task scheduler are member of this group. and that SID is identical to the SID of the first domain controller.local". However. /usr/lib/csih/getAccountName. these accounts are not identical. the so-called "relative identifier" (RID). on which the domain is created. rather than actual users or groups. . This is a hopefully unique value all over the world.local": S-1-5-21-186985262-1144665072-740312968-1207 So you now have two accounts called johndoe. Other well-known SIDs represent circumstances under which a process is running. Domain account UIDs and GIDs are offset by 10000 by default which might be a bit low for very big organizations. The third and fourth fields represent the "authority" which can be thought of as a type or category of SIDs. SYSTEM S-1-5-18 A special account which has all kinds of dangerous rights. SIDs of users (and groups) are identical to the computer SID. the so called "Relative IDentifier" (RID). is by default used as UID and/or GID under Cygwin when you create the /etc/passwd and /etc/group files using the mkpasswd and mkgroup tools.Cygwin User's Guide 23 / 82 The first field is always "S". The domain has its own SID. computer and domain SIDs always start with "S-1-5-21".exe. Different SID. The next three fields. which is just a notational convention to show that this is a SID. Do you still remember the SIDs with special meaning? In offical notation they are called "well-known SIDs". Full stop. Ok. The last three rwx bits in a unix-style permission value just represent the permissions for "everyone who is not the owner or is member of the owning group". There are a couple of builtin accounts and accounts with very special meaning which have certain well known values in these third and fourth fields. Fortunately there's an option in both tools to change the offset. The second field is the version number of the SID structure.
and even changing object data can be separated into different permission bits for different kind of data. the group and for "Everyone". It's required that the SID is the last entry of the pw_gecos field. every account is usually member in the "Users" group.Cygwin User's Guide 24 / 82 Additionally.5.local". See Section 2. which represents what POSIX calls "others".. every domain user and every domain group can be a member of these well known groups. In a domain environment it's a bit more tricky. Newer operating systems and file systems on POSIX systems also provide access control lists. Two different APIs exist for accessing these ACLs. the Cygwin implementation of the Solaris API isn't quite up to speed. the permission to delete an object is different from the permission to change object data. If you stick the user "BAR\johndoe" into the group "Domain Admins". Online man pages for the Solaris ACL API can be found on http://docs. it doesn't handle access denied ACEs gracefully. This group is by default in the "Administrators" group. At the time of writing this document. Every member is an ACE. To use Windows security correctly.4.com. For instance. assuming that the entries in pw_gecos are comma-separated. These files define the translation between the Cygwin uid/gid and the Windows SID. • The SID for which the permissions are allowed or denied. 2. But there's a problem with the definition of a "correct" ACL which disallows mapping of certain POSIX permissions cleanly. POSIX is able to create only three different permissions? Not quite. In contrast the Windows ACL has a potentially infinite number of members.. S-1-5-32-544 S-1-5-32-545 S-1-5-32-546 For instance. Let's assume the above computer called "foo" is a member machine of the domain "bar. 32 of them. the Solaris API and the POSIX API. For example. the deny ACE results in denying the specific permission bits.sun.. Consider the domain group "Domain Admins". The commands mkpasswd and mkgroup usually do this for you. Neat. The two (for us) important types of ACEs are the "access allowed ACE" and the "access denied ACE". Cygwin depends on the files /etc/passwd and /etc/group. Since these SIDs are not unique to a machine. Cygwin implements the Solaris API to access Windows ACLs in a Unixy way. • Permission bits. It takes the form "U-domain\username" and is sometimes used by services to authenticate a user.. All administrator accounts are member of the "Administrators" group. there are some rules for the layout. Another interesting entry in the pw_gecos field (which is also usually created by running mkpasswd) is the Windows user name entry. Logging in through telnet is a common scenario. So. POSIX is able to create three different permissions. Since the pw_gecos field can contain more information than just a SID. and in the gr_passwd field in /etc/group. for the group and for the world. as long as they fit into 64K. use with care. A typical snippet from /etc/passwd: . Cygwin sets file permissions as in POSIX. That's all about it as far as single machines are involved. The possible permissions on objects are more detailed than in POSIX. this guy will automatically be a member of the administrators group on "foo" when logging on to "foo". there are a couple of well-known builtin groups. Basically this is done by defining a SD with the matching owner and group SIDs.5. The SID is stored in the pw_gecos field in /etc/passwd. ACE consist of three parts: • The type of the ACE (allow ACE or deny ACE). isn't it? Back to ACE and ACL. As the names imply. which have the same SID on every machine and which have certain user rights by default: administrators users guests . and a DACL which contains ACEs for the owner.2 File permissions On NTFS and if the noacl mount option is not specified for a mount point. the permissions for the owner. the allow ACE tells the system to allow the given permissions to the SID.
S ← -1-5-21-2913048732-1697188782-3448811101-1001:/home/corinna:/bin/tcsh The above /etc/passwd will still work fine. we're on the safe side: Example 2.) Especially. Windows doesn't care if the owner of a file is a user or a group. for instance.S-1-5-21-790525478-115176313-839522115-500:/home/ ← Administrator:/bin/bash thursday_next:unused:11001:11125:U-BAR\corinna. don't change the UID or the name of the user SYSTEM. This has changed. . just set the user's primary group in /etc/passwd to the Cygwin uid of "Users" (see in /etc/group. The Administrators entry (Huh? A group in /etc/passwd?) is only here to allow ls and similar commands to print some file ownerships correctly. Having this complete information allows us to choose a Cygwin user name and uid which doesn't have to match the Windows account at all.S ← -1-5-21-790525478-115176313-839522115-500:/home/Administrator:/bin/bash corinna:unused:11001:11125:U-BAR\corinna. For instance. Otherwise. all is well. normal users in a domain environment are members in the group "Domain Users". You can now login via ssh as the user "root". and to have a two way translation. do so only if you feel comfortable with the concepts. This allows you to. but you can still switch to this setting on newer systems. do not be surprised if things break in either subtle or surprising ways! If you do screw things up. So. Do I have to mention that you can also rename groups in /etc/group? As long as the SID is present and correct. but will wake up sooner or later finding out she's still actually the domain user BAR\corinna. default 545) and let the user create files with a default group ownership of "Users". Files created as root will be owned by FOO\Administrator. The Administrator entry is for the local administrator. Note If you wish to make these kind of changes to /etc/passwd and /etc/group.Cygwin User's Guide 25 / 82 Example 2. tweaked: root:unused:0:513:U-FOO\Administrator.. The information given in the pw_gecos field are all we need to exactly identify an account. So it's convenient to have the Administrators group in /etc/passwd..2 /etc/passwd. And the domain user BAR\corinna can now happily pretend to be Thursday Next. rename the "Administrators" group to "root" as well: Example 2. you can also change the primary group of a user in /etc/passwd.S-1-5-21-2913048732-1697188782-3448811101-1001:/ ← home/corinna:/bin/tcsh The SYSTEM entry is usually needed by services. the corinna entry matches the corinna account in the domain BAR. which in turn belongs to the well-known group "Users". if it's more convenient in your environment for the user's primary group to be "Users". All you do you're actually doing as Administrator.1 /etc/passwd: SYSTEM:*:18:544:. but some Cygwin applications running as a local service under that account could suddenly start behaving strangely. tweaked: root:S-1-5-32-544:544: Last but not least. revert to copies of /etc/passwd and /etc/group files created by mkpasswd and mkgroup. In older versions of Windows NT the default ownership for files created by an administrator account was set to the group Administrators instead of to the creating user account.3 /etc/group.S-1-5-18:: Administrators:*:544:544:. As long as the pw_gecos information is available. The only requirement is that the user is actually a member of the new primary group in Windows. The really interesting entries are the next two. from Windows account name/SID to Cygwin account name uid and vice versa.S-1-5-32-544:: Administrator:unused:500:513:U-FOO\Administrator. (Make backup copies of these files before modifying them. It may mostly work. and Cygwin dutifully translates "root" into the Windows user "FOO\Administrator" and files owned by FOO\Administrator are shown to have the uid 0 when calling ls -ln.
If another user (or a Windows group. treated as a user) is not present in /etc/passwd. The second rule is not modified to get the ACEs in the preferred order. it will be named 'mkgroup'. that user's login gid is set to a special value of 401. here's the problem when trying to map the POSIX permission model onto the Windows permission model. The official documentation explains in short the following: • The requested permissions are checked against all ACEs of the user as well as all groups the user is member of. The gid 401 is shown as 'mkpasswd'.5. Canonical ACLs are unable to reflect each possible combination of POSIX permissions. Thank God. This should be noted and corrected. with PPP being the gid as noted in /etc/passwd and GGG the gid as noted in /etc/group. The permissions given in these user and groups access allowed ACEs are accumulated and the resulting set is the set of permissions of that user given for that object. Example: . but that user's login group is not present in /etc/group. • All access denied ACEs should precede any access allowed ACE. the sort order remains unchanged if one presses the Cancel button. again indicating the appropriate command. Reading stops when this condition is met.5. • Otherwise. The user name shown in this case will be '????????'.3 Special values of user and group ids If the current user is not present in /etc/passwd. it's group will be named 'mkpasswd'. nothing prevents you from actually having a user named 'mkpasswd' in /etc/passwd (or a group named 'mkgroup' in /etc/group).4 The POSIX permission mapping leak As promised earlier. be aware of the possible confusion. the group name will be shown as 'mkgroup'. but that user's group is not in /etc/group and is not the login group of that user. however.Cygwin User's Guide 26 / 82 2. Note that. If the current user is not present in /etc/passwd. If the current user is present in /etc/passwd. If another user is not present in /etc/passwd. But don't even think of pressing OK. indicating the command that should be run to alleviate the situation. The group name printed in this case is 'passwd/group_GID_clash(PPP/GGG)'. the uid of that user will have a special value of -1 (which would be shown by ls as 65535). since the special user and group names are just indicators. the gid is set to a special value of -1. the group name is shown as 'passwd/group_GID_clash(PPP/GGG)' with PPP and GGG being the different group ids. if the login group of the current user isn't in /etc/group. To summarize: • If the current user doesn't show up in /etc/passwd. There's a leak in the definition of a "correct" ACL which disallows a certain POSIX permission setting. that user's uid is set to a special value of 400. The name of this group (id -1) will be shown as '????????'. • Otherwise a group not in /etc/group will be shown as '????????' and a user not in /etc/passwd will be shown as "????????". A special case is if the current user's primary group SID is noted in the user's /etc/passwd entry using another group id than the group entry of the same group SID in /etc/group. It's not an absolute requirement.. The user name for the current user will always be shown correctly. All Windows kernels will correctly deal with the ACL regardless of the order of allow and deny ACEs. • The order of ACEs is important. 2. • If different group ids are used for a group with the same SID. If you do that. Later ACEs are not taken into account.. Unfortunately the security tab in the file properties dialog of the Windows NT4 explorer is completely unable to deal with access denied ACEs while the Windows 2000 and later properties dialog rearranges the order of the ACEs to canonical order before you can read them. ACLs following this rule are called "canonical" Note that the last rule is a preference or a definition of correctness. If the user is present in /etc/passwd. The system reads them in sequence until either any single requested permission is denied or all requested permissions are granted. that user's login gid is set to a special value of -1.
which allows. The only chance: UserDeny: UserAllow: GroupDeny: GroupAllow: OthersAllow: 001 010 010 001 110 Again: This works on all existing versions of Windows NT. this operation can be performed by processes running under the privileged user accounts (usually the "root" user account) on a per-process basis. because of the accumulation of allow rights the user may execute because the group may execute. . which switches the entire desktop to another user while leaving the original user's desktop "suspended". either. 2. Another Windows feature (since Windows 2000) is the "Run as. Windows users have been accustomed to the "Switch User" feature.Cygwin User's Guide 27 / 82 rw-r-xrw- Ok. How should this problem be solved? According to the canonical order a UserAllow has to follow the GroupDeny but it's easy to see that this can never be solved that way. which allows you to start an application using another user account when right-clicking on applications and shortcuts.. Third try: UserDeny: GroupDeny: GroupAllow: OthersAllow: 001 010 001 110 Now the group may not write as intended but unfortunately the user may not write anymore. On POSIX systems. Every new process within a session inherits the access token from its parent process. While this sort of feature is available on Windows as well. as their POSIX counterpart: UserAllow: 110 GroupAllow: 101 OthersAllow: 110 Hmm. Second try: UserDeny: 001 GroupAllow: 101 OthersAllow: 110 Now the user may read and write but not execute. Usually the access token is created at logon time and then it's attached to the starting process. Switching the user context in Windows is generally a tricky process with lots of "behind the scenes" magic involved. Windows uses so-called 'access tokens' to identify a user and its permissions. and is performed using the POSIX setuid and seteuid system calls. at the time of writing from at least NT4 up to Server 2008. Better? No! Unfortunately the group may write now because others may write.. This is called "switching the user context" for that process. for instance.5 Switching the user context Since Windows XP.5. Every thread can get its own access token." context menu entry. Only the GUIs aren't able (or willing) to deal with that order. assuming the Windows permissions only have three bits. Windows does not support the concept of these calls in a simple fashion. so here's the first try to create a matching ACL. to define threads with restricted permissions.
. to switch to that user context by setuid or seteuid calls. If the user exists and the password was specified correctly.. . /* Cygwin is now able.] struct passwd *user_pwd_entry = getpwnam (username).h> #include <sys/cygwin. */ { HANDLE token. Two Cygwin functions have been introduced to support porting setuid applications which only require login with passwords..5. /* Inform Cygwin about the new impersonation token..h> #endif [.. */ cygwin_set_impersonation_token (token). */ hashed_password = crypt (cleartext_password.. Back to this logon with password. if (!user_pwd_entry || strcmp (hashed_password. You only give Cygwin the right access token and then you can call seteuid or setuid as usual in POSIX applications. user_pwd_entry->pw_password)) error_exit. . the access token is returned and either used in ImpersonateLoggedOnUser to change the user context of the current thread. */ token = cygwin_logon_user (user_pwd_entry. salt). Porting such a setuid application is illustrated by a short example: /* First include all needed cygwin stuff. the process has to request such an access token for the new user. none of these extensions to the original concept are important for this documentation. /* Try to get the access token from Windows. This is typically done by calling the Win32 API function LogonUser with the user name and the user's cleartext password as arguments. */ } #else /* Use standard method on non-Cygwin systems. seteuid (user_pwd_entry->pw_uid).] /* Everything else remains the same! */ setegid (user_pwd_entry->pw_gid). cleartext_password).. */ #ifdef __CYGWIN__ #include <windows.6 Switching the user context with password authentication To switch the user context. Later versions of Windows define new functions in this context and there are also functions to manipulate existing access tokens (usually only to restrict them). it requires modification of the calling application.). how can this be used to implement set(e)uid? Well.Cygwin User's Guide 28 / 82 2. #endif /* CYGWIN */ [.] #ifdef __CYGWIN__ /* Patch the typical password test.. However. char *cleartext_password = getpass ("Password:"). execl ("/bin/sh". Windows Vista also adds subtokens which are attached to other access tokens which plays an important role in the UAC (User Access Control) facility of Vista and later. or in CreateProcessAsUser to change the user context of a spawned child process. if (token == INVALID_HANDLE_VALUE) error_exit. [.
But there are other ways to get new user tokens. when starting services under that account. This is accomplished by using an (officially undocumented) function on the NT function level. you don't have the usual comfortable access to network shares. A process running under this new access token might want to know under which user account it's running.5. Consider a service started under the SYSTEM account (up to Windows XP) switches the user context to DOMAIN\my_user using a token created directly by calling the NtCreateToken function.) as Windows services under the SYSTEM (or LocalSystem in the GUI) account and everything just works. You might ask "So what?" After all. Another technique is to create an LSA authentication package. groups. A more important problem is that using NtCreateToken is not sufficient to create a new logon session for the new user.Cygwin User's Guide 29 / 82 2. if the same process asks the OS for the user name of this SID something wierd happens. allows you to specify user.. Unfortunately that's too simple. This has the following unfortunate consequence. non-Cygwin Windows applications will misbehave badly in this situation. We're looking for another way to switch the user context without having to provide the password. that Windows functions identify the user domain and user name not by the SID of the access token owner. We just start the servers which have to switch the user context (sshd. Last but not least. the LookupAccountSid function will not return "DOMAIN\my_user". But that's a minor problem. permissions and almost everything you need to create a user token. inetd. A well-known example are certain versions of Visual-C++. you can't even define a drive letter to access the share. and which is considered the most dangerous right a user can have on Windows systems. but "NT AUTHORITY\SYSTEM" as the user name. Windows NT4 users have to use one of the other methods described in this document. The only restriction for using this function is that the calling process needs the "Create a token object" user right. this only looks bad. For instance. or the cron application which. Some native. Method 2: LSA authentication package Caveat: The method described in this chapter only works starting with Windows 2000. The NT function level is used to implement the Win32 level.7 Switching the user context without password. the permission "Create a token object" gets explicitly removed from the SYSTEM user's access token. without the need to specify the user password. The function of interest. The password are your credentials necessary for network access. Applications such as sshd wishing to switch the user context after a successful public key authentication. cron. Therefore it's better to get used to accessing these shares using the UNC path as in bash$ grep foo //server/share/foofile 2. wants to switch the user without any authentication are stuck here. as such is closer to the kernel than the Win32 level. if you logon with a password. beginning with Windows Server 2003. but functionality and permission-wise everything should be ok. but only by the logon session the process is running under. First of all. NtCreateToken. LSA is an acronym for "Local Security Authority" which is a protected part of the operating . for instance S-1-5-21-1234-5678-9012-77777. and under some circumstances the drive letter you choose collides with a drive letter already used in another session. which only the SYSTEM user account has by default. One way is just to create a user token from scratch. That sounds good. the password is stored hidden as "token credentials" within the access token and used as default logon to access network resources. on the command line for instance: bash$ net use '\\server\share' /user:DOMAIN\my_user my_users_password Note that. Unfortunately this is more complicated. . One of these attributes is the fact. The corresponding SID is returned correctly. What does that mean? Every logon usually creates a new logon session.5. That requires us to create a new account with this specific permission just to run this kind of services. Using NtCreateToken has a few drawbacks. A logon session has a couple of attributes which are unique to the session. again. you only can access network shares from the new user's process tree by using explicit authentication. Method 1: Create a token from scratch An unfortunate aspect of the implementation of set(e)uid is the fact that the calling process requires the password of the user to which to switch. on some systems.8 Switching the user context without password. And Cygwin knows about this shortcoming so it will return the correct Cygwin username when asked. and. However.. Thus. The reason is that the token has been created without knowing the password. Since these credentials are missing from the token created with NtCreateToken.
the password is two-way encrypted in a hidden. Method 3: With password Ok. LogonUser returns an access token with all credentials necessary for network access. Nevertheless. This is done by tweaking a special registry key. Hmm. every administrator can access the password of all keys stored this way in the registry. Cygwin provides such an authentication package. Other privileged user rights are still necessary. Second. The Cygwin command passwd -R allows a user to specify his/her password for storage in this registry area. If cygserver is started as a service running under the SYSTEM account (which is the default way to run cygserver) you can use passwd -R as normal. you can't examine this area with regedit. as aforementioned. For good measure. how does it work? The title of this section says it all. Back on earth. the LSA authentication package is used by Cygwin when set(e)uid is called by an application. So what we do is to utilize this registry area for the purpose of set(e)uid. and since this way to implement set(e)uid is not only used by Cygwin but also by Microsoft's SFU (Services for Unix). one of the protected LSA processes died). there still hasn't been any password authentication involved. isn't it? 2. but it has its own drawbacks. so. what about the drawbacks? First.9 Switching the user context without password. adding a password to the LSA private registry area requires administrative access. Fortunately there is a solution. When this user tries to login using ssh with public key authentication. Instead of trying to logon without password. this is Windows. After running /usr/bin/cyglsa-config and rebooting the system. but that's just business as usual. It has to be installed and the machine has to be rebooted to activate it. Cygwin's set(e)uid examines the LSA private registry area and searches for a Cygwin specific key which contains the password. We got it. for instance. sure. first things first. except for the network access problem.5. using this password. The requirement to reboot after every installation or deinstallation of the cygwin LSA authentication DLL is just a minor inconvenience compared to that. Disadvantages? Yes. The created access token using this method has its own logon session. LSA is the part of the OS which cares for the user logons and which also creates logon sessions. This is the job of the shell script /usr/bin/cyglsa-config which is part of the Cygwin package. Every administrator can start regedit as SYSTEM user: bash$ date Tue Dec 2 16:28:03 CET 2008 bash$ at 16:29 /interactive regedit. obfuscated area of the registry. So calling passwd -R as a normal user will fail! Cygwin provides a workaround for this.exe Additionally.. it calls LogonUser under the hood. we also look for a key stored by SFU (using the SFU command regpwd) and use that if it's available. After all.. A full access token with its own logon session. If that works. it triggers a system reboot. that's heaven. even as an administrator. even by delicate native applications which choke on that using the NtCreateToken method. Also. non-privileged user as well. . The user is correctly identified. if an administrator knows under which name the private key is stored (which is well-known since the algorithms used to create the Cygwin and SFU keys are no secret). as soon as the LSA encounters serious problems (for instance. The very special and very dangerous "Create a token object" user right is not required by a user using this method..Cygwin User's Guide 30 / 82 system which only allows changes to become active when rebooting the system after the change. especially the "Act as part of the operating system" right. the passwords of the Windows services which run under some non-default user account. Not being able to access network shares without having to specify a cleartext password on the command line or in a script is a harsh problem for automated logons for testing purposes and similar stuff. with all network credentials. so we have solved almost any problem. obfuscated registry area.. The access token created using LSA authentication still lacks the credentials for network access. An LSA authentication package is a DLL which has to be installed as part of the LSA. Right? No. This part of the registry contains. If it finds it. this is already a lot better than what we get by using NtCreateToken. This method has two advantages over the NtCreateToken method. But. Only SYSTEM has access to this area for listing purposes. we just logon with password. The password gets stored two-way encrypted in a hidden. the LSA private registry area.
Cygwin User's Guide
31 / 82
Conclusion: If your system is used exclusively by you, and if you're also the only administrator of your system, and if your system is adequately locked down to prevent malicious access, you can safely use this method. If your machine is part of a network which has dedicated administrators, and you're not one of these administrators, but you (think you) can trust your administrators, you can probably safely use this method. In all other cases, don't use this method. You have been warned.
Switching the user context, how does it all fit together?
Now we learned about four different ways to switch the user context using the set(e)uid system call, but how does set(e)uid really work? Which method does it use now? The answer is, all four of them. So here's a brief overview what set(e)uid does under the hood: • When set(e)uid is called, it tests if the user context had been switched by an earlier call already, and if the new user account is the privileged user account under which the process had been started originally. If so, it just switches to the original access token of the process it had been started with. • Next, it tests if an access token has been stored by an earlier call to cygwin_set_impersonation_token. If so, it tests if that token matches the requested user account. If so, the stored token is used for the user context switch. If not, there's no predefined token which can just be used for the user context switch, so we have to create a new token. The order is as follows. • Check if the user has stored the logon password in the LSA private registry area, either under a Cygwin key, or under a SFU key. If so, use this to call LogonUser. If this succeeds, we use the resulting token for the user context switch. • Otherwise, check if the Cygwin-specifc LSA authentication package has been installed and is functional. If so, use the appropriate LSA calls to communicate with the Cygwin LSA authentication package and use the returned token. • Last chance, try to use the NtCreateToken call to create a token. If that works, use this token. • If all of the above fails, our process has insufficient privileges to switch the user context at all, so set(e)uid fails and returns -1, setting errno to EPERM.
Customizing bash
To set up bash so that cut and paste work properly, click on the "Properties" button of the window, then on the "Misc" tab. Make sure that "QuickEdit mode" and "Insert mode" are checked. These settings will be remembered next time you run bash from that shortcut. Similarly you can set the working directory inside the "Program" tab. The entry "%HOME%" is valid, but requires that you set HOME in the Windows environment. Your home directory should contain three initialization files that control the behavior of bash. They are .profile, .bashrc and .inputrc. The Cygwin base installation creates stub files when you start bash for the first time. .profile (other names are also valid, see the bash man page) contains bash commands. It is executed when bash is started as login shell, e.g. from the command bash --login. This is a useful place to define and export environment variables and bash functions that will be used by bash and the programs invoked by bash. It is a good place to redefine PATH if needed. We recommend adding a ":." to the end of PATH to also search the current working directory (contrary to DOS, the local directory is not searched by default). Also to avoid delays you should either unset MAILCHECK or define MAILPATH to point to your existing mail inbox. .bashrc is similar to .profile but is executed each time an interactive bash shell is launched. It serves to define elements that are not inherited through the environment, such as aliases. If you do not use login shells, you may want to put the contents of .profile as discussed above in this file instead.
shopt -s nocaseglob
Cygwin User's Guide
32 / 82
will allow bash to glob filenames in a case-insensitive manner. Note that .bashrc is not called automatically for login shells. You can source it from .profile. .inputrc controls how programs using the readline library (including bash) behave. It is loaded automatically. For full details see the Function and Variable Index section of the GNU readline manual. Consider the following settings:
# Ignore case while completing set completion-ignore-case on # Make Bash 8bit clean set meta-flag on set convert-meta off set output-meta on
The first command makes filename completion case insensitive, which can be convenient in a Windows environment. The next three commands allow bash to display 8-bit characters, useful for languages with accented characters. Note that tools that do not use readline for display, such as less and ls, require additional settings, which could be put in your .bashrc:
alias less='/bin/less -r' alias ls='/bin/ls -F --color=tty --show-control-chars'
Cygwin User's Guide
33 / 82
Chapter 3
Using Cygwin
This chapter explains some key differences between the Cygwin environment and traditional UNIX systems. It assumes a working knowledge of standard UNIX commands.
Mapping path names
Cygwin supports both Win32- and POSIX-style paths. Directory delimiters may be either forward slashes or backslashes. Paths using backslashes are always handled as Win32 paths. POSIX paths must only use forward slashes as delimiter, otherwise they are treated as Win32 paths and file access might fail in surprising ways. UNC pathnames (starting with two slashes and a network name) are also supported.
Note The usage of Win32 paths, though possible, is deprecated, since it circumvents important internal path handling mechanisms. See Section 3.1.4 and Section 3.1.5 for more information.
POSIX operating systems (such as Linux) do not have the concept of drive letters. Instead, all absolute paths begin with a slash (instead of a drive letter such as "c:") and all file systems appear as subdirectories (for example, you might buy a new disk and make it be the /disk2 directory). Because many programs written to run on UNIX systems assume the existance of a single unified POSIX file system structure, Cygwin maintains a special internal POSIX view of the Win32 file system that allows these programs to successfully run under Windows. Cygwin uses this mapping to translate from POSIX to Win32 paths as necessary.
The Cygwin Mount Table
The /etc/fstab file is used to map Win32 drives and network shares into Cygwin's internal POSIX directory tree. This is a similar concept to the typical UNIX fstab file. The mount points stored in /etc/fstab are globally set for all users. Sometimes there's a requirement to have user specific mount points. The Cygwin DLL supports user specific fstab files. These are stored in the directory /etc/fstab.d and the name of the file is the Cygwin username of the user, as it's stored in the /etc/passwd file. The structure of the user specific file is identical to the system-wide fstab file. The file fstab contains descriptive information about the various file systems. fstab is only read by programs, and not written; it is the duty of the system administrator to properly create and maintain this file. Each filesystem is described on a separate line; fields on each line are separated by tabs or spaces. Lines starting with '#' are comments. The first field describes the block special device or remote filesystem to be mounted. On Cygwin, this is the native Windows path which the mount point links in. As path separator you MUST use a slash. Usage of a backslash might lead to unexpected results. UNC paths (using slashes, not backslashes) are allowed. If the path contains spaces these can be escaped as '\040'.
Cygwin User's Guide
34 / 82
The second field describes the mount point for the filesystem. If the name of the mount point contains spaces these can be escaped as '\040'. The third field describes the type of the filesystem. Cygwin supports any string here, since the file system type is usually not evaluated. The notable exception is the file system type cygdrive. This type is used to set the cygdrive prefix. The fourth field describes the mount options associated with the filesystem. It is formatted as a comma separated list of options. It contains at least the type of mount (binary or text) plus any additional options appropriate to the filesystem type. Recognized options are binary, text, nouser, user, exec, notexec, cygexec, nosuid, posix=[0|1]. The meaning of the options is as follows.
acl - Cygwin uses the filesystem's access control lists (ACLs) to implement real POSIX permissions (default). This flag only affects filesystems supporting ACLs (NTFS) and is ignored otherwise. auto - Ignored. binary - Files default to binary mode (default). bind - Allows to remount part of the file hierarchy somewhere else. In contrast to other entries, the first field in the fstab line specifies an absolute POSIX path. This path is remounted to the POSIX path specified as the second path. The conversion to a Win32 path is done on the fly. Only the root path and paths preceding the bind entry in the fstab file are used to convert the POSIX path in the first field to an absolute Win32 path. Note that symlinks are ignored while performing this path conversion. cygexec - Treat all files below mount point as cygwin executables. dos - Always convert leading spaces and trailing dots and spaces to characters in the UNICODE private use area. This allows to use broken filesystems which only allow DOS filenames, even if they are not recognized as such by Cygwin. exec - Treat all files below mount point as executable. ihash - Always fake inode numbers rather than using the ones returned by the filesystem. This allows to use broken filesystems which don't return unambiguous inode numbers, even if they are not recognized as such by Cygwin. noacl - Cygwin ignores filesystem ACLs and only fakes a subset of permission bits based on the DOS readonly attribute. This behaviour is the default on FAT and FAT32. The flag is ignored on NFS filesystems. nosuid - No suid files are allowed (currently unimplemented). notexec - Treat all files below mount point as not executable. nouser - Mount is a system-wide mount. override - Force the override of an immutable mount point (currently "/"). posix=0 - Switch off case sensitivity for paths under this mount point (default for the cygdrive prefix). posix=1 - Switch on case sensitivity for paths under this mount point (default for all other mount points). text - Files default to CRLF text mode line endings. user - Mount is a user mount.
While normally the execute permission bits are used to evaluate executability, this is not possible on filesystems which don't support permissions at all (like FAT/FAT32), or if ACLs are ignored on filesystems supporting them (see the aforementioned acl mount option). In these cases, the following heuristic is used to evaluate if a file is executable: Files ending in certain extensions (.exe, .com, .bat, .btm, .cmd) are assumed to be executable. Files whose first two characters begin with '#!' are also considered to be executable. The exec option is used to instruct Cygwin that the mounted file is "executable". If the exec option is used with a directory then all files in the directory are executable. This option allows other files to be marked as executable and avoids the overhead of opening each file to check for a '#!'. The cygexec option is very similar to exec, but also prevents Cygwin from setting up commands and environment variables for a normal Windows program, adding another small performance gain. The opposite of these options is the notexec option, which means that no files should be marked as executable under that mount point. A correct root directory is quite essential to the operation of Cygwin. A default root directory is evaluated at startup so a fstab
if C: is mounted as /c and also as /..4. The fifth and sixth field are ignored. Therefore. Otherwise. Whenever Cygwin generates a Win32 path from a POSIX one. They are so far only specified to keep a Linux-like fstab file layout.Cygwin User's Guide 35 / 82 entry for the root directory is not necessary. This translation is normally only used when trying to derive the POSIX equivalent current directory.noacl 0 0 • This is just a comment: # This is just a comment • Set the cygdrive prefix to /mnt: none /mnt cygdrive binary 0 0 • Remount /var to /usr/var: /var /usr/var none bind Assuming /var points to C:/cygwin/var. as text mount). Note that you don't have to specify an fstab entry for the root dir. If you want to see the current set of mount points valid in your session. /usr/bin and /usr/lib are by default also automatic mount points generated by the Cygwin DLL similar to the way the root directory is evaluated. do so at your own risk. nouser mount points are not overridable by a later call to mount. This is equivalent to the Linux bind option available since Linux 2. you can invoking the Cygwin tool mount without arguments: . Since this is a dangerous thing to do. An fstab entry for them is not required. it uses the longest matching prefix in the mount table. Example entries: • Just a normal mount point: c:/foo /bar fat32 binary 0 0 • A mount point for a textmode mount with case sensitivity switched off: C:/foo /bar/baz ntfs text. unless you specify the option user. /usr/lib is supposed to point to the /lib directory. /usr/bin points to the directory the Cygwin DLL is installed in. unless you think you really know what you're doing.. If it's wrong. Thus. In this case. the root directory evaluated by Cygwin itself is treated as an immutable mount point and can't be overridden in /etc/fstab. This allows the administrator to set certain paths so that they are not overridable by users. /usr/var now also points to C:/cygwin/var.0. Mount points given in /etc/fstab are by default nouser mount points. unless you want to have the root dir pointing to somewhere entirely different (hopefully you know what you're doing). This choice is safe and usually shouldn't be changed. all mount points in the user specific fstab file are user mount points. then Cygwin would translate C:/foo/bar to /c/foo/bar. nothing will work as expected. or if you want to mount the root dir with special options (for instance. In contrast. the handling of MS-DOS filenames bypasses the mount table. use the override flag in the options field in the /etc/fstab file.posix=0 0 0 • A mount point for a Windows directory with spaces in it: C:/Documents\040and\040Settings /docs ext3 binary 0 0 • A mount point for a remote directory without ACL support: //server/share/subdir /srv/subdir smbfs binary.
acl 0 0 none /cygdrive cygdrive posix=0. See Section 3. Stop all your Cygwin processes and restart them. and /usr/lib are never generated.noumount. like this: bash$ ls -l /cygdrive/f/somedir This lists the content of the directory F:\somedir.acl of the /mysrv mount point are used.6. If you want to create a user specific /etc/fstab. you can access arbitary drives on your system by using the cygdrive path prefix. /usr/bin.user.noacl are used. and you can simply use your old user mount points as before.7. these mount points will disappear as soon as your last Cygwin process ends.posix=0. For instance. The old user mount points in your HKEY_CURRENT_USER branch of the registry are not used to generate /etc/fstab. and the umount to delete them.4. The cygdrive prefix is a virtual directory under which all drives on a system are subsumed. Please note that you must not use the cygdrive prefix for any other mount point. Note When you upgrade an existing older Cygwin installation to Cygwin 1.user. unless they are accessed through a mount point.3. and a path to any drive can be constructed by using the cygdrive prefix and appending the drive letter as subdirectory.noacl 0 0 Assume there's a file \\server\share\foo on the share. When accessing it as /mysrv/foo. Note This only applies to UNC paths using forward slashes. The cygdrive prefix flags are also used for all UNC paths starting with two slashes.posix=0. since they are only noted in memory.3 The cygdrive path prefix As already outlined in Section 1.auto) f:/cygwin/lib on /usr/lib type system (binary. For instance this: .7.posix=0.auto) e: on /cygdrive/e type user (binary. The mount options of the cygdrive prefix is used for all file access through the cygdrive prefixed drives. For instance. then the flags posix=1. When accessing it as //server/share/foo. then the flags for the cygdrive prefix.auto) f:/cygwin on / type system (binary.noumount. The default value for this prefix is /cygdrive.d/${USER} file from your old entries.1 Displaying the current set of mount points bash$ mount f:/cygwin/bin on /usr/bin type system (binary.auto) You can also use the mount command to add new mount points. Note that entries for /. 3.9 and Section 3. See Section 3. posix=0. However. your old system mount points (stored in the HKEY_LOCAL_MACHINE branch of your registry) are read by a script and the /etc/fstab file is generated from these entries. assuming the cygdrive mount options are binary.7. and the case of the filename doesn't matter (mount option posix=0. The cygdrive prefix may be changed in the fstab file as outlined above. consider these /etc/fstab entries: //server/share /mysrv ntfs posix=1. When using backslashes the flags for native paths are used. /bin/copy-user-registry-fstab.Cygwin User's Guide 36 / 82 Example 3.1.auto) e:/src on /usr/src type system (binary) c: on /cygdrive/c type user (binary.1. there's a script available which does exactly that for you. Just start the script and it will create your user specific fstab file. then any file /cygdrive/x/file will be opened in binary mode by default (mount option binary.16 for more information.
All paths using DOS notation will be treated as caseinsensitive. If you want to mount any drive explicitly in another mode than the cygdrive prefix. and permissions are just faked as if the underlying drive is a FAT drive. In the worst case. • SetCurrentDirectory does not support case-sensitive filenames. As long as the Cygwin CWD is usable as Windows CWD. The following paths are treated as native Win32 paths in Cygwin: • All paths starting with a drive specifier C:\foo C:/foo • All paths containing at least one backslash as path component C:/foo/bar\baz/. at least not as long as they use the POSIX API (chdir. This restriction doesn't apply for Cygwin processes. the wrong files are deleted. 3.5 Using the Win32 file API in Cygwin applications Special care must be taken if your application uses Win32 file API functions like CreateFile to access files using relative pathnames. fails for directories for which the user has no permissions. This means.. even if the user is an administrator. if they are running under an administrator account. This restriction doesn't apply for Cygwin processes. Cygwin uses a default setting for the mount flags. This also applies to NTFS and other filesystems which usually are capable of casesensitivity and storing permissions.. Those paths circumvent all internal integrity checking and bypass the information given in the Cygwin mount table. • The Win32 API call to set the current directory. When accessing files using native Win32 paths as above. If the process uses the Win32 API to access a file using a relative pathname. but not least. the Windows idea of the current working directory (CWD) is not necessarily the same as the Cygwin CWD.. the Cygwin CWD and the Windows CWD differ.1. if the Cygwin process changes its working directory into one of the directories which are unusable as Windows CWD. while possible. or if your application uses functions like CreateProcess or ShellExecute to start other applications. if a Cygwin process has a CWD using an absolute path longer than 258 characters.Cygwin User's Guide 37 / 82 none /cygdrive cygdrive binary 0 0 D: /cygdrive/d somefs text 0 0 will not make file access using the /mnt/d path prefix suddenly using textmode. which disallow certain directories as Win32 CWD: • The Windows subsystem only supports CWD paths of up to 258 chars. we're in trouble. SetCurrentDirectory.1. getcwd).4 Using native Win32 paths Using native Win32 paths in Cygwin. the Cygwin and Windows CWDs are in sync within a process. SetCurrentDirectory can't work on virtual Cygwin paths like /proc or /cygdrive. When a Cygwin application is started. These paths only exists in the Cygwin realm so they have no meaning to a native Win32 process. . the resulting absolute path would not match the expectations of the process. • Last. There are a couple of restrictions in the Win32 API. However. • UNC paths using backslashes \\server\share\.. is generally inadvisable. use a distinct path prefix: none /cygdrive cygdrive binary 0 0 D: /mnt/d somefs text 0 0 3.
a.. Many do not do so by default (the Unix Samba server does not by default. sockets and non-file devices are opened in binary mode. PATH. the deliberate effect is that a call to. the command ln -s //pollux/home/joe/data /data would have about the same effect as creating a mount point from //pollux/home/joe/data to /data using mount. . this section gives the design goals. from c:/cygwin\bin to /bin. cmp. will fail. Since it's not a real filesystem. The mode can be specified explicitly as explained in the Programming section below.2 3.2. make. The situation is different in the DOS/Windows world where a file can be opened in one of two modes.. don't use the Win32 file API in Cygwin applications. However on writing in text mode.. 3. when an application reads from a file it gets exactly what's in the file on disk and the converse is true for writing. you can simply specify text or binary mode just like in calls to fopen(). 3. All other programs (such as cat.2 The default Cygwin behavior The Cygwin system gives us some flexibility in deciding how files are to be opened when the mode is not specified explicitly. The rules are evolving. if there was a mount from that Win32 path to that POSIX path) when a Cygwin process first starts. c. Most other programs (such as sed. you have to make sure that the Cygwin CWD is set to some directory which is valid as Win32 CWD. If the file is a symbolic link. 3.1 Text and Binary modes The Issue On a UNIX system. tr . then the default is specified by the mount flag. programs that deal explicitly with object files specify binary mode (this is the case of od. Cygwin sets the Windows CWD to a special directory in this case. for example). Other differences are that the mapping is distributed throughout the file system and proceeds by iteratively walking the directory tree instead of matching the longest prefix in a kernel table. for instance.2. ˆM) NL.4 to switch to textmode. For pipes opened through the pipe() system call you can use the setmode() function (see Section 3.6 Additional Path-related Information The cygpath program provides the ability to translate between Win32 and POSIX pathnames in shell scripts.Cygwin User's Guide 38 / 82 To workaround this problem. cmp. The HOME. In an ideal DOS/Windows world.1.. binary or text.2.7. This special directory points to a virtual filesystem within the native NT namespace (\??\PIPE\). For pipes opened through popen(). which is helpful to diagnose CR problems). rather than the POSIX exec(3) family of functions. or if you really have to use CreateProcess to start applications.) would open files (and change the mode of their standard input and output) as text..). If the filename is specified as a POSIX path and it appears to reside on a file system that is mounted (i. ˆJ) is transformed into the sequence CR (\r. a NL (\n. So. For example. Pipes. This can wreak havoc with the seek/fseek calls since the number of bytes actually in the file may differ from that seen by the application. the mode of the target file system applies. b.g. CreateFile ("foo". and LD_LIBRARY_PATH environment variables are automatically converted from Win32 format to POSIX format (e. as long as the processes CWD doesn't work as Windows CWD. tr) use the default mode. Symbolic links can also be used to map Win32 pathnames to POSIX. if its pathname starts with a directory displayed by mount). all programs using lines as records (such as bash. in general. If you really need to access files using the Win32 API.2 for the details. See Section 3. sed .. except that symbolic links cannot set the default file access mode.) would use binary mode.e. the default is binary. In the binary mode the system behaves exactly as in UNIX. it contains a backslash or a colon).e.. Note that symbolic links will only work on network drives that are properly configured to support the "system" file attribute. . If the file is specified via a MS-DOS pathname (i. In practice with Cygwin.
2. In the fopen() and popen() function calls.o -o my_tiny_app Starting with Cygwin 1. binary mode can be specified with the flag O_BINARY and text mode with O_TEXT.2.mode) where fd is a file descriptor (an integer) and mode is O_BINARY or O_TEXT.4 Programming In the open() function call.c -lbinmode -o my_tiny_app This adds code which sets the default open mode for all files opened by my_tiny_app to binary for reading and writing. The function returns O_BINARY or O_TEXT depending on the mode before the call. It makes most sense to keep the Cygwin distribution and your Cygwin home directory in binmode and generate text files in binmode (with UNIX LF lineendings).o to the link stage of the application in your project. Use mkostemp() or mkostemps() with the same flags as open() for more control on temporary files.7. if you want to make sure that all files are always opened in binary mode by an application. d2u removes CR's.a /lib/automode. As application programmer you can decide on a file by file base. Most programs included in the official Cygwin distributions should work well in the default mode. which handles UNIX lineendings incorrectly and only produces output files with DOS CRLF lineendings. With non-Cygwin shells the commands cat filename | program and program < filename are not equivalent when filename is on a text-mounted partition. the Cygwin shells uses rules (a-d). Sockets and other non-file devices are always opened in binary mode. A notable exception is the mini-editor Notepad. Text mode is specified by adding a t to the mode string. The mode of a file can be changed by the call setmode(fd. Use the --help option to these commands for more information. just add the file /lib/binmode. Cygwin provides the following libraries and object files to set the default open mode just by linking an application against them: • /lib/libautomode.3 Binary or text? UNIX programs that have been written for maximum portability will know the difference between text and binary files and act appropriately under Cygwin. When redirecting. you can use the even simpler: $ gcc my_tiny_app. u2d add's CR's before a NL. You can also specify a directory in the mount table to be mounted in textmode so you can use that directory for exchange purposes. unless you want to exchange files with native Win32 applications. 3. binary mode can be specified by adding a b to the mode string. like this: $ gcc my_tiny_app. open files for writing in binary mode .Cygwin User's Guide 39 / 82 d.7. Binmode is the best choice usually since it's faster and easier to handle.c /lib/binmode. You can convert files between CRLF and LF lineendings by using certain tools in the Cygwin distribution like d2u and u2d from the cygutils package.o Open files for reading in textmode. or you can specify default open modes depending on the purpose for which the application open files. Non-Cygwin shells always pipe and redirect with binary mode. Most Windows applications can handle binmode files just fine. See the next section for a description of your choices. These symbols are defined in fcntl. The programs u2d and d2u can be used to add or remove CR's from a file. The mkstemp() and mkstemps() calls force binary mode. There's also a convenient way to set the default open modes used in an application by just linking against various object files provided by Cygwin. For instance. e. 3.h. regardless of the mode of the underlying mount point. and EOF on error.
see Section 2.o - Open files for reading and writing in binary mode • /lib/libtextmode.1 Special filenames Special files in /etc Certain files in Cygwin's /etc directory are read by Cygwin before the mount table has been established.5. Files are considered to be executable if the filename ends with .dll exists and /etc must not be a Cygwin symlink pointing to another directory.com or .d is allowed to be a Cygwin symlink either. which only have to be readable by the $USER user account itself. The list of files is /etc/fstab /etc/fstab.o - Open files for reading and writing in textmode • /lib/libtextreadmode. file permissions are evaluated using the Access Control Lists (ACLs) attached to a file.a /lib/binmode. native NTFS symlinks and reparse points are transparent when accessing the above files so all these files as well as /etc itself may be NTFS symlinks or reparse points. This can be switched off by using the "noacl" option to the respective mount point in the /etc/fstab or /etc/fstab. Last but not least. Every process of any user account has to read these files potentially. .d/$USER file.d/$USER. For that reason there are a few requirements as far as /etc is concerned. It can thus be relatively slow.o - Open files for reading in textmode.a /lib/textreadmode. For more information on file permissions.4 3. if the NFS client is the one from Microsoft's "Services For Unix".a /lib/textmode. Consequently chmod can only affect the "w" mode. Then "etc" and the filename to look for is attached: C:\cygwin\etc\fstab. On NFS shares. 3. On NTFS. The only exception are the user specific files /etc/fstab. To access these files. or the one built into Windows Vista or later. So the /etc directory must be parallel to the directory in which the cygwin1. However. including the directory /etc/fstab. strips off the innermost directory component and adds "\etc". so world-readability is essential. file permissions are exactly the POSIX permissions transmitted from the server using the NFSv3 protocol. Let's assume the Cygwin DLL is installed as C:\cygwin\bin\cygwin1. and Cygwin uses the DOS read-only attribute to determine if they are writable. .d/$USER /etc/passwd /etc/group These file are read using native Windows NT functions which have no notion of Cygwin symlinks or POSIX paths. Consequentially none of the files from the above list. or if its content starts with #!. First the DLL name as well as the innermost directory (bin) is stripped off: C:\cygwin\. keep default behaviour for writing. make sure that these files are world-readable.4.dll. files are always readable. it silently ignores actions involving the other modes. Only the user and group ownership is not necessarily correct. the Cygwin DLL evaluates it's own full Windows path. 3.3 File permissions On FAT or FAT32 filesystems.Cygwin User's Guide 40 / 82 • /lib/libbinmode.bat. This means that ls -l needs to open and read files.exe.
but it has a method to workaround this restriction.2 Invalid filenames Filenames invalid under Win32 are not necessarily invalid under Cygwin since release 1. Cygwin replaces the non-convertible character with a special character sequence. All of the above characters.txt or foo. If that occurs. The backslash has to be exempt from this conversion.4.Cygwin User's Guide 41 / 82 3. An exception from this rule are some network filesystems (NetApp. you will nevertheless be able to access the file. because Cygwin knows how to convert this filename back to UTF-16. equivalent Control-X). The result is a filename containing some ugly looking characters. but again might impose problems when switching to a non-"C" or non-"UTF-8" charset. When trying to create files with trailing dots or spaces.7.4 Filenames with unusual (foreign) characters Windows filesystems use Unicode encoded as UTF-16 to store filename information. There are a few rules which apply to Windows filenames. Most notably.3 Forbidden characters in filenames Some characters are disallowed in filenames on Windows filesystems. This will always result in some valid filename by default.aux are invalid filenames for native Win32 applications. Cygwin can create and access files with such names just fine.4. However. Just don't try to use these files with native Win32 applications. always use UTF-8 as the character set. Note To avoid this scenario altogether. These forbidden characters are the ASCII control characters from ASCII value 1 to 31.6.7. are converted to special UNICODE characters in the range 0xf000 to 0xf0ff (the "Private use area") when creating or accessing files. NWFS) which choke on these filenames. If you don't use the UTF-8 character set (see Section 2. Cygwin creates filenames using the UTF-8 charset. Thus. They return with an error like "No such file or directory" when trying to create such files. 3. Starting with Cygwin 1. How does that work? When Cygwin converts the filename from UTF-16 to your character set. except for the backslash. Leading spaces and trailing dots and spaces will be converted to UNICODE characters in the private use area. LPT1 or PRN (to name a few) cannot be used as filename or extension in a native Win32 application. The sequence starts with an ASCII CAN character (hex code 0x18.4) then there's a chance that a filename is using one or more characters which have no representation in the character set you're using. COM1. Converting backslashes using the above method would make this impossible. Cygwin applications can create and access files with trailing dots and spaces without problems. DOS device names like AUX. plus the following characters which have a special meaning in the Win32 API: " * : < > ? | \ Cygwin can't fix this. So filenames like prn. all of them are removed before the file is created. Cygwin recognizes these filesystems and works around this problem by applying the same rule as for the other forbidden characters. it is nice. If you don't want or can't use UTF-8 as character set for whatever reason. This behaviour can be switched on explicitely for a filesystem or a directory tree by using the mount option dos. 3. This restriction only affects native Win32 applications. Note In the default "C" locale.4. because Cygwin accepts Win32 filenames including backslashes as path separators on input. While it doesn't look nice. This restriction doesn't apply to Cygwin applications. it skips over the ASCII CAN and handles the following bytes as a UTF-8 character.0. followed by the UTF-8 representation of the character. . The filename will be converted using your usual character set. when Cygwin recognizes an ASCII CAN character. Additionally Win32 filenames can't contain trailing dots and spaces for DOS backward compatibility. the filename is symmetrically converted back to UTF-16 and you can access the file. it recognizes characters which can't be converted.
Note When installing Microsoft's Services For Unix (SFU). Rather. if you have SFU installed. your shell might claim that it can't find Windows commands like attrib or net.exe can be created and accessed like other files. You have been warned! Even if you use case-sensitivity. which usually both don't know this registry key.exe and aBc. 3. Only by using the UTF-8 charset you can avoid this problem safely. You can't access two files in the same directory which only differ by case. too. These devices cannot be seen with the command ls /dev/ although commands such as ls /dev/tty work fine.d/$USER to switch it to case-sensitivity. Also. case-sensitivity can not be supported by Cygwin. Read on for more information. If you want case-sensitivity on these systems. by using the "posix=0" mount option in /etc/fstab. However. For least surprise. /proc/registry32 and /proc/registry64. or your /etc/fstab. If you really want case-sensitivity in Cygwin. the /cygdrive path is case-insensitive by default and you have to use the "posix=1" setting explicitly in /etc/fstab or /etc/fstab.d/$USER file.Cygwin User's Guide 42 / 82 Note Please be aware that this method is not entirely foolproof. After you set this registry value to 0. To ease the pain. the installer will change the aforementioned registry value to 0. there's some chance that the registry value is already set to case sensitivity. 3. So. starting applications is still case-insensitive due to Windows limitations and so the program you try to launch may not be the one actually started. there are limitations: while two programs Abc. You can do this on a per-mount point base. /cygdrive paths are case-insensitive by default.4. Registry access is always caseinsensitive.4. For that reason. If you want to be able to see all well-known devices in /dev/.5 Case sensitive filenames In the Win32 subsystem filenames are only case-preserved. Cygwin supports the following character devices commonly found on POSIX systems: . Cygwin will be case-sensitive by default on NTFS and NFS filesystems. you can use Igor Pechtchanski's create_devices. it's not necessary to see an existing device in /dev to access it. The script is just for the fun of it.6 POSIX devices There is no need to create a POSIX /dev directory as Cygwin automatically simulates it internally. it might be feasible to switch to case-insensitivity for certain paths for better interoperability with native Win32 applications (even if it's just Windows Explorer). In some character set combinations it might not work for certain native characters. the NT kernel starting with Windows XP does not support it by default.sh script. While NTFS (and some remote filesystems) support case-sensitivity. Again. rather stopping all Cygwin processes and then restarting them is sufficient. if you use case-sensitivity on the /cygdrive prefix. Note that mount points as well as device names and virtual paths like /proc are always case-sensitive! The only exception are the subdirectories and filenames under /proc/registry. you're asked if you want to use case-sensitive filenames. This script does not add the raw disk devices. If you answer "yes" at this point. be aware that using two filenames which only differ by case might result in some weird interoperability issues with native Win32 applications. As a result. or you have to make sure that the native Win32 %PATH% environment variable is using the correct case for all paths throughout. you have to tweak a registry setting and reboot. You're using case-sensitivity at your own risk. though. create that registry value and set it to 0. On these systems (and only on these systems) you don't have to reboot to bring it into effect. you can switch it on by setting the registry value HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\kernel\obcaseinsensitive to 0 and reboot the machine. Cygwin expects this registry value also on Windows NT4 and Windows 2000. The reason is that the native Windows %PATH% environment variable is not always using the correct case for all paths in it. unless you change that registry value. like Abc and aBc. but not case-sensitive.
text only /dev/windows The Windows message queue.. For external disks (USB-drives. etc. If you match the information between /proc/partitions and the df output. tapes have a "Tape Symbolic Name". /dev/ptmx Pseudo tty master device.exe. the Windows "Disk Management" utility (part of the "Computer Management" console) shows that the mapping of "Disk 0" is \device\harddisk0..Cygwin User's Guide 43 / 82 /dev/null /dev/zero /dev/full /dev/console Pseudo device name for the standard console window created by Windows. The mapping from physical device to the name of the device in the internal NT namespace can be found in various places. the places where this information is found is not very well-defined. Every one of them has this name. These POSIX device names are generated using a direct conversion from the POSIX namespace to the internal NT namespace. /dev/clipboard The Windows clipboard... . Disks have a "Location" number. for usage with sys logger services. /dev/com2 Please use /dev/ttySx instead. Another place to find this mapping is the "Device Management" console. you can't access physical memory from user space. Note that access to the /dev/port physical memory has been restricted with Windows Server 2003. E. /dev/tty The current tty of a session running in a pseudo tty. .. The df command shows a list of drives and their respective sizes. /dev/conin Same as Windows CONIN$. The first floppy in the system is \device\floppy0. Cygwin also has several Windows-specific devices: /dev/com1 The serial ports. /dev/urandom /dev/dsp Default sound device of the system. Serial communication devices. starting with COM1 which is the same as ttyS0. /dev/random Random number generator. For hard disks and CD/DVD drives. Unfortunately. the first harddisk is the NT internal device \device\harddisk0\partition0 or the first partition on the third harddisk is \device\harddisk2\partition1. etc) you can use Cygwin to show the mapping. "CD-ROM 2" is \device\cdrom2. you should be able to figure out which external drive corresponds to which raw disk device name. ttyS0 == Win32 COM1. ttyS1 == COM2.g. etc. /dev/ttym /dev/tty0 Pseudo ttys are numbered from /dev/tty0 upwards as they are /dev/tty1 requested. /dev/conout Same as Windows CONOUT$. Block devices are accessible by Cygwin processes using fixed POSIX device names.. It's not quite comparable with the console device on UNIX machines. /dev/kmsg Kernel message pipe. . CF-cards in a cardreader. /dev/ttyS0 /dev/ttyS1 . Same as the one used for cmd. /dev/kmem Since this OS. the first CD-ROM is \device\cdrom0 and the first tape drive is \device\tape0. /proc/partitions contains a list of raw drives known to Cygwin. /dev/pipe /dev/fifo /dev/mem The physical memory of the machine.
. no-rewind \device\tape1 \device\tape1 \device\floppy0 \device\floppy1 \device\cdrom0 \device\cdrom1 \device\cdrom0 \device\cdrom1 \device\harddisk0\partition0 \device\harddisk0\partition1 (whole disk) (first partition) \device\harddisk0\partition15 (fifteenth partition) \device\harddisk1\partition0 \device\harddisk1\partition1 if you don't like these device names.bat and . 3.. so that traditional UNIX names can be used.. for the device.exe extension Win32 executable filenames end with . So.exe need not be included in the command.. feel free to create symbolic links as they are created on Linux systems for convenience: ln -s /dev/sr0 /dev/cdrom ln -s /dev/nst0 /dev/tape . Last but not least. /dev/sda15 /dev/sdb /dev/sdb1 [up to] /dev/sddx /dev/sddx1 .. you cannot omit the extension.com.7 The . the mapping from POSIX /dev namespace to internal NT namespace is as follows: POSIX device name /dev/st0 /dev/nst0 /dev/st1 /dev/nst1 . You have been warned. and for you. /dev/st15 /dev/nst15 /dev/fd0 /dev/fd1 . /dev/scd15 /dev/sda /dev/sda1 . rewind \device\tape0.exe but the ...4.. /dev/fd15 /dev/sr0 /dev/sr1 . .... for programs that end in . please.. handle this ability with care. Writing to a raw mass storage device you should only do if you really know what you're doing and are aware of the fact that any mistake can destroy important information. However. /dev/sr15 /dev/scd0 /dev/scd1 . accessing mass storage devices raw is something you should only do if you know what you're doing and know how to handle the information... /dev/sddx15 \device\harddisk127\partition0 \device\harddisk127\partition1 \device\harddisk127\partition15 Internal NT device name \device\tape0.Cygwin User's Guide 44 / 82 Note Apart from tape devices which are not block devices and are by default accessed directly.
) gives information about filename.exe If a shell script myprog and a program myprog.. Reserved characters ('/'. but it provides significant capabilities. Cygwin displays the subkey as foo and the value as foo%val. and . It displays each KEY as a directory and each VALUE as a file. There are additionally subdirectories called /proc/registry32 and /proc/registry64. use caution since changes may result in an unstable or broken system.. see next section. -r--r----.exe when asked to produce filename. In the same situation the function call stat("filename"..exe if filename. They are identical to /proc/registry on 32 bit host OSes.. It has been changed for consistency with the rest of Cygwin..exe. This allows many makefiles written for UNIX systems to work well under Cygwin.exe 432961010 b 432961010 b...exe 445885548 a 435996602 a. The two files can be distinguished by examining their inodes.exe bash$ ls -i a a.exe b.exe bash$ ls -i b b. The gcc compiler produces an executable named filename. \DosDevices\C: (REG_BINARY) = cf a8 97 e8 00 08 fe f7 ..19. The files in this directory are representations of various aspects of your system.Cygwin User's Guide 45 / 82 As a side effect. If a registry key contains a subkey and a value with the same name foo. The Cygwin /proc is not as complete as the one in Linux. The procps package contains several utilities that use it. On 64 bit host OSes. . Note that this was quite the reverse up to Cygwin 1. 3.. the ls filename gives information about filename. '\'. bash$ od -t x1 MountedDevices/%5CDosDevices%5CC%3A 0000000 cf a8 97 e8 00 08 fe f7 01 00 00 00 The unnamed (default) value of a key can be accessed using the filename @. bash$ ls * a a. as demonstrated below.8 The /proc filesystem Cygwin. bash$ cd /proc/registry/HKEY_LOCAL_MACHINE/SYSTEM bash$ ls -l MountedDevices .9 The /proc/registry filesystem The /proc/registry filesystem provides read-only access to the Windows registry. and '%') or reserved names (. supports the /proc virtual filesystem.4... the shell script has precedence and is selected for execution of myprog. One unique aspect of the Cygwin /proc filesystem is /proc/registry. As anytime you deal with the Windows registry.1 Admin SYSTEM 12 Dec 10 11:20 %5CDosDevices%5CC%3A .5. while /proc/registry64 opens the 64 bit processes view. /proc/registry32 opens the 32 bit processes view on the registry. ':'. for example the command cat /proc/cpuinfo displays information such as what model and speed processor you have.) are converted by percent-encoding: bash$ regtool list -v '\HKEY_LOCAL_MACHINE\SYSTEM\MountedDevices' .4.exe coexist in a directory.exe exists and filename does not. like Linux and other similar operating systems. 3.
as the cache is not invalidated and may contain values that depend on the previous mount table contents. runs Win32filepath when cygwin encounters a fatal error.if set. • (no)glob[:ignorecase] . Win32filepath is usually set to the path to gdb or dumper. This option also accepts an optional [no]ignorecase modifer.1 The CYGWIN environment variable Implemented options The CYGWIN environment variable is used to configure many global settings for the Cygwin runtime system. Cygwin will warn the first time a user uses an "MS-DOS" style path name rather than a POSIX-style path name. There is no default set. Default is set.10 The @pathnames To circumvent the limitations on shell line length in the native Windows command shells. Default is not set. Defaults to set. It contains the options listed below. This is applicable only to programs running from a DOS command line prompt.4. which is useful for debugging. If a file pathname exists. • (no)export . Defaults to set. wildcard matching is case insensitive. Note that this may cause problems if the mount table changes.5. The default is noignorecase • (no)reset_com .2 Using @pathname bash$ echo 'This is "a long" bash$ echo @mylist @mylist bash$ cmd c:\> c:\cygwin\bin\echo @mylist This is a long line line' > mylist 3.causes fork() and exec*() to retry n times when a child process fails due to certain windows-specific errors.If set.5 3.If set. Cygwin programs expand their arguments starting with "@" in a special way. • forkchunk:32768 . Double quotes can be used inside the file to delimit strings containing blank space. . These errors usually occur when processes are being started while a user is logging off. • proc_retry:n . question mark. the final values of these settings are re-exported to the environment as CYGWIN again. in the above example 32768 bytes (32Kb) at a time.if set. • (no)title . • (no)envcache . • (no)strip_title . • error_start:Win32filepath . environment variable conversions (between Win32 and POSIX) are cached.if set. for example C:\cygwin\bin\gdb. Many options can be turned off by prefixing with no.causes fork() to copy memory some number of bytes at a time. The default is to copy as many bytes as possible. If supplied. if any. In the following example compare the behaviors of the bash built-in echo and of the program /bin/echo. This is done at open time and when handles are inherited. serial ports are reset to 9600-8-N-1 with no flow control when used. the title bar reflects the name of the program currently running. separated by blank characters. Default is not set.if set. the argument @pathname expands recursively to the content of pathname. Defaults to set. command line arguments containing UNIX-style file wildcard characters (brackets. asterisk.exe.If set.Cygwin User's Guide 46 / 82 3.if set. strips the directory part off the window title. escaped with \) are expanded into lists of files that match those wildcards. which is preferable in most cases but may slow some older systems down. Embedded double quotes must be repeated. Example 3. • (no)dosfilewarning . Defaults to off.
• codepage:[ansi|oem] . termios) for UNIX-like ttys in the Windows console. • check_case .if set.Cygwin User's Guide 47 / 82 • (no)tty . . or $LC_CTYPE. unless the open mode has been specified explicitly in the open(2) call. The current list of always uppercased variables is: ALLUSERSPROFILE COMMONPROGRAMFILES COMPUTERNAME COMSPEC HOME HOMEDRIVE HOMEPATH NUMBER_OF_PROCESSORS OS PATH PATHEXT PROCESSOR_ARCHITECTURE PROCESSOR_IDENTIFIER PROCESSOR_LEVEL PROCESSOR_REVISION PROGRAMFILES SYSTEMDRIVE SYSTEMROOT TEMP TERM TMP TMPDIR WINDIR Defaults to not set. Defaults to not set. when a Cygwin process is started from a non-Cygwin native Windows process.. and is settable via stty.e. this setting became superfluous. If not set.This option has been removed since it only fakes security which is considered dangerous and useless.7.7 or later are not readable by older Cygwin releases because the new symlinks use UTF-16 to encode the target filename. Cygwin does not change the case of environment variables.2 Obsolete options Certain CYGWIN options available in past releases have been removed in Cygwin 1. except for a restricted set to maintain minimal backward compatibility and for correct handling of certain essential variables. Cygwin converts all environment variables to all-uppercase.This option has been removed in favor of real case sensitivity and the per-mount option "posix=[0|1]". depending on the application call to the setlocale() function. For more information. If not set. • (no)upcaseenv .This option has been removed because all file opens default to binary mode.. • (no)binmode . Cygwin enables extra support (i. Defaults to not set since plain file symlinks are faster to write and faster to read. It also created an uncontrollably large file on FAT and was entirely useless on FAT32. read the documentation in Section 3. It should not be set when using other terminals (i. These obsolete options are listed below. It is not compatible with some Windows programs.e. Note that this has been changed such that ˆD works as expected instead of ˆZ.if set. Cygwin creates symlinks as Windows shortcuts with a special header and the R/O attribute set. Since Cygwin is now doing all character conversion by itself. while the old symlinks used the current ANSI or OEM charset. Please note that symlinks created under Cygwin 1. a path and the system attribute set. This option must be specified before starting a Cygwin shell and it cannot be changed in the shell.This option controled which character set is used for file and console operations. mintty or xterm). • (no)ntea . $LC_ALL. in which case the tty is opened in text mode.1. This was the default behavior in releases prior to Cygwin 1. • (no)winsymlinks .2 and Section 3. and in turn by the setting of the environment variables $LANG.5.5.7 for one reason or another.if set.4. Cygwin creates symlinks as plain files with a magic number. 3.
For more information. • (no)server . but the interface is still available: Control slave tty/pty handle dispersal from tty owner to other processes without compromising the owner processes' security. read the documentation in Section 3.1. The one-character options are prepended by a single dash.Originally this option had to be enabled on the client side to use features only available when running cygserver. For more information.5. This service is used by passwd -R.This option has been removed because the behaviour it switched on is now the standard behaviour in Cygwin.This option has been removed because traverse checking is not quite correctly implemented by Microsoft and it's behaviour has been getting worse with each new OS version. for obvious reasons. Using the stored passwords in set(e)uid does not require running Cygserver. 3.7. • (no)smbntsec . read the documentation in Section 3. The implemented services so far are: • XSI IPC Message Queues. • (no)transparent_exe . Arguments to options are marked in angle brackets below.5. This complicates its usage so the option has been removed for now. see Section 2. • Allows non-privileged users to store obfuscated passwords in the registry to be used by setuid and seteuid calls to create user tokens with network credentials. For more information. .2. This option has been removed because Cygwin now always tries to contact cygserver if a function is called which requires cygserver being available.6.6. The default configuration file is /etc/cygserver.2.6 another safe mechanism to share tty/pty handles is used. Nearly all options have a counterpart in the configuration file (see below) so setting them on the command line isn't really necessary.6.6.1 Cygserver What is Cygserver? Cygserver is a program which is designed to run as a background service. Command line options override settings from the Cygserver configuration file. This option has no counterpart in the configuration file.6 3.This option has been removed in favor of the per-mount option "acl"/"noacl". --config-file <file> Use <file> as configuration file instead of the default configuration line. 3. The --help and --version options will print the default configuration pathname.2 Cygserver command line options Options to Cygserver take the normal UNIX-style '-X' or '--longoption' form.This option has been removed in favor of the per-mount option "acl"/"noacl".7. These are not part of the actual syntax but are used only to denote the arguments.1. Cygserver has no options with optional arguments. It provides Cygwin applications with services which require security arbitration or which need to persist while no other cygwin application is running.conf. • XSI IPC Shared Memory. • (no)traverse .Cygwin User's Guide 48 / 82 • (no)ntsec . Note that all arguments are required. • XSI IPC Semaphores. Starting with Cygwin 1. the long variants are prepended with two dashes. • This functionality is no longer used since Cygwin 1. For details. read the documentation in Section 3. The recognized options are: • -f.
The default level is 6. Configuration file option: kern. -Y options (or the appropriate settings in the configuration file). g. • -v. --help Output usage information and exit. which is relatively chatty. --request-threads <num> Number of threads started to serve application requests. If you set it to 1.srv. • -e. Configuration file option: kern.srv. This is the default if stderr is connected to a tty. Configuration file option: kern.log. --log-level <level> Set the verbosity level of the logging output.stderr • -E. redirected to a file.Cygwin User's Guide 49 / 82 • -c.srv. --cleanup-threads <num> Number of threads started to perform cleanup tasks. calling 'net stop cygserver' or 'cygrunsrv -E cygserver'. .msgqueues • -s. -y. --no-semaphores Don't start XSI IPC Semaphores.log.level • -m. --debug Log debug messages to stderr. The -c and -r options can be used to play with Cygserver's performance under heavy load conditions or on slow machines.srv.syslog • -Y. • -h. you will get only messages which are printed under severe conditions. --stderr Force logging to stderr. if running as service. These will clutter your stderr output with a lot of information.semaphores • -S. Configuration file option: kern.log. Configuration file option: kern. you can explicitly set the logging output as you like. Other methods are sending a SIGHUP to the Cygserver PID or. Configuration file option: kern.stderr • -y.srv. --no-sharedmem Don't start XSI IPC Shared Memory support.cleanup_threads • -r. Valid values are between 1 and 7. you can switch it off here. the default is logging to the system log. Configuration file option: kern. even to both. --version Output version information and exit. if stderr is not connected to a tty. which will result in stopping Cygserver itself.log. By using the -e. If you don't need XSI IPC Shared Memory support. --shutdown Shutdown a running daemon and exit. stderr and syslog. Default is 10. --no-msgqueues Don't start XSI IPC Message Queues. Configuration file option: kern. Configuration file option: kern. e.request_threads • -d.log. Configuration file option: kern. typically only useful to developers.sharedmem • -q. This is the default. --syslog Force logging to the system log.syslog • -l. Default is 2. Otherwise. --no-syslog Don't log to syslog. --no-stderr Don't log to stderr. -E.
Due to the wide configurability by changing the configuration file.1 cygcheck Usage: cygcheck [-v] [-h] PROGRAM cygcheck -c [-d] [PACKAGE] cygcheck -s [-r] [-v] [-h] cygcheck -k cygcheck -f FILE [FILE]. The script only performs a default install. Therefore. it's also considered good practice to keep all other comments in the file.4 The Cygserver configuration file Cygserver has many options.6. You should always run Cygserver as a service under LocalSystem account. since it will not be overwritten by a later update installation. Customization is accomplished by editing the configuration file. or query package database. 3. At least one command option or a PROGRAM is required. you should run the /usr/bin/cygserver-config script once. Since reading the options file on Cygserver startup doesn't take much time. This is the way it is installed for you by the /usr/bin/cygserver-config script. installs Cygserver as service. which is by default /etc/cygserver. This keeps you from searching for clues in other sources. cygcheck -p REGEXP cygcheck --delete-orphaned-installation-keys cygcheck --enable-unique-object-names Cygwin-DLL cygcheck --disable-unique-object-names Cygwin-DLL cygcheck --show-unique-object-names Cygwin-DLL cygcheck -h List system information. for example.7.Cygwin User's Guide 50 / 82 3. giving you the option to overwrite an already existing file or to leave it alone. The default configuration file contains many comments which describe everything needed to understand the settings. upon request. cygcheck -l [PACKAGE]. check installed packages. A comment at the start of the file describes the syntax rules for the file. The default configuration file delivered with Cygserver is installed to /etc/defaults/etc. PROGRAM -c. All of the Cygwin command-line utilities support the --help and --version options.3 How to start Cygserver Before you run Cygserver for the first time. While many of these reflect their UNIX counterparts. There are options which set the number of threads running in parallel. --check-setup list library (DLL) dependencies of PROGRAM show installed version of PACKAGE and verify integrity (or for all installed packages if none specified) . sending a signal to Cygserver. You may use the long or short option names interchangeably. 3. The /usr/bin/cygserver-config script copies it to /etc. with no further options given to Cygserver when running as service. as shown above. It creates the default configuration file and.. --help and -h function identically.. There's no option to re-read the file at runtime by. each was written specifically for Cygwin.conf. The configuration file determines how Cygserver operates.. the /etc file is safe to be changed by you. say. This file is only read once.6. 3. options for setting how and what to log and options to set various maximum values for the IPC services. It is generally a good idea to uncomment only options which you intend to change from the default values. at startup of Cygserver. which allow you to customize the server to your needs.7 Cygwin Utilities Cygwin comes with a number of command-line utilities that are used to manage the UNIX emulation portion of the Cygwin environment. that's typically not necessary.. The default options are shown in the file but are commented out.
cygcheck will give general system information. For example.Cygwin User's Guide 51 / 82 -d. otherwise print this help -V. If you do not need to know the status of each package and want cygcheck to run faster. -f. The -p REGEXP matches package names. cygcheck will report on both.) The -c option checks the version and status of installed Cygwin packages. do not verify (with -c) produce diagnostic system information (implies -c -d) also scan registry for Cygwin settings (with -s) perform a keyboard check session (must be run from a plain console only. --verbose produce more verbose output -h.exe. add the -d option and cygcheck will only output the name and version for each package. just list packages. A package will be marked Incomplete if files originally installed are no longer present. and -l lists all files in a package. The DLL path must be given as valid Windows(!) path. -k. and -l only report on packages that are currently installed.1 /usr/man/man1/lesskey. or with no arguments it lists all packages.exe /usr/bin/lesskey. cygcheck is similar in many ways. If you list one or more programs on the command line. -s. To search all official Cygwin packages use -p instead. not from a pty/rxvt/xterm) -f. descriptions. --version print the version of cygcheck and exit Note: -c.exe /usr/bin/lessecho. use the -v option. Requires the right to change the registry. see Section 2. If you specify one or more package names.1 .exe handles installing and uninstalling packages. don't change it. --enable-unique-object-names Cygwin-DLL --disable-unique-object-names Cygwin-DLL --show-unique-object-names Cygwin-DLL Enable. cygcheck will limit its output to those packages.3 Example cygcheck usage $ cygcheck -f /usr/bin/less less-381-1 $ cygcheck -l less /usr/bin/less. --list-package list contents of PACKAGE (or all packages if none given) -p. or show the setting of the \"unique object names\" setting in the Cygwin DLL given as argument to this option. If you list one or more programs on the command line and specify -s. to find out about /usr/bin/less and its package: Example 3. disable. -v. The best thing to do in that situation is reinstall the package with setup. providing the names of DLL files on which the program depends. The -f option helps you to track down which package a file came from. --package-query search for REGEXP in the entire cygwin.1 for more information. --find-package find the package to which FILE belongs -l. cygcheck will diagnose the runtime environment of that program or programs. If you don't know what this means. (The major difference is that setup. -r. If you are familiar with dpkg or rpm. --help annotate output with explanatory comments when given with another command.exe /usr/man/man1/less. --dump-only --sysinfo --registry --keycheck The cygcheck program is a diagnostic utility for dealing with Cygwin programs. To see which files are missing. If you specify the -s option.com package repository (requires internet connectivity) --delete-orphaned-installation-keys Delete installation keys of old. and names of files/paths within all packages. See the users guide for more information. now unused installations from the registry.
at the beginning of each section. just leave this out.*\. you should include the / path seperator. since the . In the given example this ensures that filenames that happen to end in ls. The cygcheck program should be used to send information about your system for troubleshooting when requested.* if you want something similar to the wildcard * commonly used in filename globbing. The -r option causes cygcheck to search your registry for information that is relevent to Cygwin programs. Also be aware that the characters such as \ and * are shell metacharacters. expat-1.8-1 XML parser library written in C XML parser library written in C $ cygcheck -p '/ls\. not a glob or wildcard." since the / can match anywhere in the path.exe are not shown. These registry entries are the ones that have "Cygwin" in the name. and path/filenames of the contents of packages. In fact. so they must be either escaped or quoted. The third example above illustrates that if you want to match a whole filename.7-1 expat-1.a' Found 2 matches for 'libexpat. such as the internal version numbers of DLLs. This feature requires an active internet connection. as in the example above. If you are paranoid about privacy. perhaps you are getting an error because you are missing a certain DLL and you want to know which package includes that file: Example 3. the -p option can be used to search the entire official Cygwin package repository. sh-utils and textutils) Note that this option takes a regular expression.2. Similarly. since it must query the cygwin. additional information about recursive DLL usage. However. for example: $ cygcheck -s -v -r -h > cygcheck_output. read the perlre manpage.com that document the Perl language. This allows troubleshooting of problems which could be a result of having multiple concurrent Cygwin installations. you may remove information from this report. to match the period character you should use \. While this is useful information. it also adds some to the size of the report.1-5 coreutils-5. coreutils-5.*\. For example. but please keep in mind that doing so makes it harder to diagnose your problems. This means that you need to use . The -v option causes the output to be more verbose. character in a regexp is a metacharacter that will match any character.Cygwin User's Guide 52 / 82 The -h option prints additional helpful messages in the report. and if a file in one directory in the PATH also occurs in other directories on the PATH. To get a case insensitive match.com web site.0-6 GNU core utilities (includes fileutils. if you're experimenting a lot with different Cygwin . so if you want a compact report or if you know what everything is already.3. or one of many websites such as perldoc.exe' Found 2 matches for '/ls\. It's just there to anchor the match so that it matches a full filename. package descriptions.95.4 Searching all packages for a file $ cygcheck -p 'cygintl-2\.1-3 GNU Internationalization runtime library $ cygcheck -p 'libexpat.exe'.txt Each Cygwin DLL stores its path and installation key in the registry. For complete documentation on Perl-compatible regular expression syntax and options. By default the matching is case-sensitive. begin your regexp with (?i) which is a PCRE-specific feature. Note that this use does not mean "look for packages with ls in the root directory.dll'. When asked to run this command save the output so that you can email it. What this means is that additional information will be reported which is usually not interesting. In contrast to the other options that search the packages that are installed on your local system.a'. It takes as argument a Perl-compatible regular expression which is used to match package names.12. It also adds table column headings.exe such as ncftpls.95. sh-utils and textutils) GNU core utilities (includes fileutils.dll' Found 1 matches for 'cygintl-2\. it is equalivant to the search that is available on the Cygwin package listing page. libintl2-0.
. In contrast to the --disable-. --type TYPE print TYPE form: 'dos'. --long-name print Windows long form of NAMEs (with -w. or output system path information Output type options: -d. For instance.Cygwin User's Guide 53 / 82 installation paths.. --windows print Windows form of NAMEs (C:\WINNT) -t. you can use cygcheck --show-unique-object-names Cygwin-DLL to find out if the given Cygwin DLL use unique object names or not. This problem is probably due to using incompatible versions of the cygwin DLL. before you're allowed to change this setting. trying to run processes under these DLLs concurrently will result in error messages like this one: *** shared version mismatch detected . the --show-unique-object-names option also works for Cygwin DLLs which are currently in use. --dos print DOS (short) form of NAMEs (C:\PROGRA~1\) -m. --unix (default) print Unix form of NAMEs (/cygdrive/c/winnt) -w.. To re-enable the usage of a unique key. Each Cygwin DLL generates a key value from its installation path. 3.e. use the cygcheck --delete-orphaned-installation-keys command. your registry could accumulate a lot of old Cygwin installation entries for which the installation doesn't exist anymore. use the cygcheck --enable-unique-object-names Cygwin-DLL command. --allusers use 'All Users' instead of current user for -D. To disable the usage of a unique key value of a certain Cygwin DLL. The most recent version *should* reside in x:\\cygwin\\bin. Windows. options. Rebooting is also suggested if you are unable to find another cygwin DLL. independently from their installation paths. '/bin:/usr/bin') -s. --short-name print DOS (short) form of NAMEs (with -w. or UTF8. This value is not only stored in the registry. This option has the same characteristics as the --disable-unique-object-names option Finally... This allows running multiple versions of Cygwin DLLs without these versions to interfere with each other. but with regular slashes (C:/WINNT) -M. NAME. To get rid of these orphaned registry entries..2 cygpath Usage: cygpath (-d|-m|-u|-w|-t TYPE) [-f FILE] [OPTION]. or mixed pathname in Windows codepage CP. where 'x' is the drive on which you have installed the cygwin distribution. --desktop output 'Desktop' directory and exit . cygpath [-c HANDLE] cygpath [-ADHOPSW] cygpath [-F ID] Convert Unix and Windows format paths... and --enable-.7. Cygwin-DLL is the Windows path (*not* a Cygwin POSIX path) to the DLL for which you want to disable this feature.. --mixed like --windows. Processes running under a Cygwin DLL installed in C:\cygwin don't see processes running under a Cygwin DLL installed in C:\Program Files\cygwin. or to run small third-party installations for a specific purpose independently from a Cygwin net distribution. or one of the reserved words ANSI. For debugging purposes it could be desired that the various Cygwin DLLs use the same key. --mode report on mode of file (currently binmode or textmode) -u. System information: -A. Search for cygwin1. --codepage CP print DOS. OEM. --path NAME is a PATH list (i. run cygcheck from a DOS command line for this purpose.0x8A88009C/0x75BE0074. cygpath defaults to the character set defined by the current locale. or 'windows' Path conversion options: -a. use the cygcheck --disable-unique-object-names CygwinDLL command. Note that you have to stop all Cygwin processes running under this DLL. If this option is missing. -m only) -p. 'mixed'. it's also used to generate global object names used for interprocess communication. This keeps different Cygwin installations separate. -m only) -C.dll using the Windows Start->Find/Search facility and delete all but the most recent version. 'unix'. -P -D. If the DLLs have different versions. CP can be a numeric codepage identifier. --absolute output absolute path -l.
you can use the -l and -s options to use normal (long) or DOS-style (short) form. --homeroot --mydocs --smprograms --sysdir --windir --folder ID options: --file FILE --option --close HANDLE --ignore --help --version output output output output output output 'Profiles' directory (home root) and exit 'My Documents' directory and exit Start Menu 'Programs' directory and exit system directory and exit 'Windows' directory and exit special folder with numeric ID and exit read FILE for input. decimal codepage number.to read from STDIN read options from FILE as well (for use with --file) close HANDLE (for use in captured process) ignore missing argument output usage information and exit output version information and exit The cygpath program is a utility that converts Windows native filenames to Cygwin POSIX-style pathnames and vice versa. A full list of supported codepages is listed on the Microsoft MSDN page Code Page Identifiers. non-ASCII characters in a specific Windows codepage. -o. Other -f. might expect pathnames in the current OEM codepage. -S. -O. The -C option allows to specify a Windows codepage to print DOS and Windows paths created with one of the -d. the PATH environment variable is semicolon-delimited in Windows. The -d option is identical to -w and -s together. -m. • A numerical. or expects to get a file name from a native Windows program. -c. -h. The -p option means that you want to convert a path-style string rather than a single filename. 28593 for ISO-8859-3. -P. etc. for instance. For example. see Section 2. -v.3) file and path names.4. It can be used in make file rules converting variables that may be omitted to a proper format. The -m option will output Windows-style format but with forward slashes instead of backslashes. to specify the current OEM (console) codepage • UTF8. while graphical tools like Windows Explorer might expect pathnames in the current ANSI codepage. to specify UTF-8. to specify the current ANSI codepage • OEM. which might expect native. Alternatively. which use backslashes as an escape character. The -u and -w options indicate whether you want a conversion to UNIX (POSIX) format (-u) or to Windows format (-w). Console tools. cygpath can output information about the location of important system directories in either format. . Use the -d to get DOS-style (8.Cygwin User's Guide 54 / 82 -H. for instance 936 for GBK. but colon-delimited in UNIX. It can be used when a Cygwin program needs to pass a file name to a native Windows program. or LANG. or -w options. In combination with the -w option. The -C option takes a single parameter: • ANSI. LC_CTYPE. A codepage of 0 is the same as if the -C hasn't been specified at all. -i. use . The default is to use the character set of the current locale defined by one of the internationalization environment variables LC_ALL. This is sometimes not sufficent for interaction with native Windows tools. This option is especially useful in shell scripts. -W. Note that cygpath output may contain spaces (C:\Program Files) so should be enclosed in quotes. The -i option supresses the print out of the usage message if no filename argument was given. By giving -p you are instructing cygpath to convert between these formats. -F.
and -W output directories used by Windows that are not the same on all systems.h from package w32api. for example -S might output C:\WINNT\system32 or C:\Windows\System32. and the default ACL of the directory. The -F outputs other special folders specified by their internal numeric code (decimal or 0xhex). dumper can be also be started from the command line to create a core dump of any running process. When a core dump is loaded into gdb. the owner. you'll need to place identical copies of the executable and dlls in the same directories as on the machine where the core dump was created.. This core dump can be later loaded to gdb and analyzed. the group. 3. If error_start is set this way. --verbose --help --quiet --version be verbose while dumping output help information and exit be quiet while dumping (default) output version information and exit The dumper utility can be used to create a core dump of running Windows process.".5 Example cygpath usage #!/bin/sh if [ "${1}" = "" ]. and the ACL of the file display the filename. 3. -h. -P. --dir display the filename. the target process is terminated too.exe is Windows-style and not cygwin path. -O and -P options. dumper doesn't write those portions of target process' memory space that are loaded from executable and dll files and are unchangeable. The -H shows the Windows profiles directory that can be used as root of home.core -d. -H. it uses these paths to load appropriate files. Instead. By default the output is in UNIX (POSIX) format. -S.7. when a core dump is created and dumper exits.7.Cygwin User's Guide 55 / 82 Example 3.. To save space in the core dump. One common way to use dumper is to plug it into cygwin's Just-In-Time debugging facility by adding error_start=x:\path\to\dumper. -q.4 getfacl Usage: getfacl [-adn] FILE [FILE2. then dumper will be started whenever some program encounters a fatal error.3 dumper Usage: dumper [OPTION] FILENAME WIN32PID Dump core from WIN32PID to FILENAME. -v. For valid codes and symbolic names. use the -w or -d options to get other formats. --all -d. else XPATH="$(cygpath -C ANSI -w "${1}")". the group. The -A option forces use of the "All Users" directories instead of the current user for the -D.exe to the CYGWIN environment variable. The current valid range of codes for folders is 0 (Desktop) to 59 (CDBurn area). Unfortunately. -a. then XPATH=". if it exists . fi explorer $XPATH & The capital options -D. the owner. such as program code and debug info. see the CSIDL_* definitions in the include file /usr/include/w32api/shlobj. dumper saves paths to files which contain that data. because of a Windows API limitation. That means that if you create a core dump on one machine and try to debug it on another.] Display file and directory access control lists (ACLs). Please note that x:\path\to\dumper.
5 kill Usage: kill [-f] [-signal] [-s signal] pid1 [pid2 . if it exists. To make sure you are using the Cygwin version. With no options specified. --version output usage information and exit display user and group IDs instead of names output version information and exit When multiple files are specified on the command line. the owner. Each program defines the signals they understand.. try $ /bin/kill --version which should give the Cygwin kill version number and copyright information. see Section 2. but you can also send program-specified signals such as SIGUSR1 to trigger actions within the program.Cygwin User's Guide 56 / 82 -h. ps -W will display all windows pids. You may need to specify the full path to use kill from within some shells.7. -l. or a list of all signal names if no signal is given.5 in the Cygwin User's Guide. getfacl displays the filename. using win32 interface if necessary print a list of signal names send signal (use kill --list for a list) output usage information and exit output version information and exit The kill program allows you to send arbitrary signals to other Cygwin programs. special file or directory. For each argument that is a regular file. -s. the default Cygwin shell. not the Windows pids.] kill -l [signal] Send signals to processes -f. a blank line separates the ACLs for each file. This is because bash defines a kill builtin function. --noname -v. the group. For more information on Cygwin and Windows ACLs. The usual purpose is to end a running program from some other window when ˆC won't work. The kill -l option prints the name of the given signal. --force --list --signal --help --version force. For directories getfacl displays additionally the default ACL.. including bash. use the -signN option. --help -n. To send a specific signal. the group. The format for ACL output is as follows: # file: filename # owner: name or uid # group: name or uid user::perm user:name or uid:perm group::perm group:name or gid:perm mask:perm other:perm default:user::perm default:user:name or uid:perm default:group::perm default:group:name or gid:perm default:mask:perm default:other:perm 3. and the ACL. Unless you specific the -f option. the "pid" values used by kill are the Cygwin pids. either with a signal number or a signal name (minus the "SIG" part). like enabling debugging or re-opening log files. see the bash man page under BUILTIN COMMANDS for more information. and both the ACL and the default ACL. -h. getfacl displays the owner. use the Cygwin ps program. as shown in these examples: . To get a list of running programs and their Cygwin pids. -v.
-s.7. -u. -m. which should be considered the official source of this information. their numbers. -c.6 locale Usage: locale [-amsuUvh] or: locale [-ck] NAME Get locale-specific information. and some commentary on them. record-lock lost) power failure user defined signal 1 user defined signal 2 3. from the file <sys/signal. -k. --all-locales --category-name --keyword-name --charmaps --system --user List all available supported locales List information about given category NAME Print information about given keyword NAME List all available character maps Print system default locale Print user's default locale . Options: -a.Cygwin User's Guide 57 / 82 Example 3.h>.6 Using the kill command $ $ $ $ kill kill kill kill 123 -1 123 -HUP 123 -f 123 Here is a list of available signals. SIGHUP SIGINT SIGQUIT SIGILL SIGTRAP SIGABRT SIGEMT SIGFPE SIGKILL SIGBUS SIGSEGV SIGSYS SIGPIPE SIGALRM SIGTERM SIGURG SIGSTOP SIGTSTP SIGCONT SIGCHLD SIGCLD SIGTTIN SIGTTOU SIGIO SIGPOLL SIGXCPU SIGXFSZ SIGVTALRM SIGPROF SIGWINCH SIGLOST SIGPWR SIGUSR1 SIGUSR2 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 20 21 22 23 23 24 25 26 27 28 29 29 30 31 hangup interrupt quit illegal instruction (not reset when caught) trace trap (not reset when caught) used by abort EMT instruction floating point exception kill (cannot be caught or ignored) bus error segmentation violation bad argument to system call write on a pipe with no one to read it alarm clock software termination signal from kill urgent condition on IO channel sendable stop signal not from tty stop signal from tty continue a stopped process to parent on child stop or exit System V name for SIGCHLD to readers pgrp upon background tty read like TTIN for output if (tp->t_local<OSTOP) input/output possible System V name for SIGIO exceeded CPU time limit exceeded file size limit virtual time alarm profiling time alarm window changed resource lost (eg.
utf8 be_BY@latin . --utf -v. locale: ca_ES@euro archive: /cygdrive/c/Windows/system32/kernel32. be_BY be_BY.utf8 POSIX af_ZA af_ZA. The -s option prints the systems default locale instead. ca_ES ca_ES..utf8 am_ET am_ET..alias ------------------------------------------------------------------------------language | Catalan ..utf8 ca_ES@euro catalan . With the -U option locale appends a "..dll ------------------------------------------------------------------------------language | Afrikaans territory | South Africa codeset | ISO-8859-1 locale: af_ZA. It prints all available locales and the allowed modifiers.utf8 .UTF-8" to the result More verbose output This text locale without parameters prints information about the current locale environment settings.. --help Attach ".. This can be used in scripts to set the Cygwin locale to the Windows user or system default. The -v option prints more detailed information about each available locale. --verbose -h.dll ------------------------------------------------------------------------------language | Afrikaans territory | South Africa codeset | UTF-8 . Example: bash$ locale -a C C..utf8 archive: /cygdrive/c/Windows/system32/kernel32.UTF-8 The -a option is helpful to learn which locales are supported by your Windows machine.UTF-8". Example: bash$ locale -av locale: af_ZA archive: /cygdrive/c/Windows/system32/kernel32. for instance: bash$ export LANG=$(locale -uU) bash$ echo $LANG en_US..Cygwin User's Guide 58 / 82 -U.dll ------------------------------------------------------------------------------language | Catalan territory | Spain codeset | ISO-8859-15 locale: catalan archive: /usr/share/locale/locale. The -u option prints the current user's Windows default locale to stdout.
Otherwise.--Local [machine[. LC_MONETARY). plus domain groups on domain controllers and domain member machines. -C use character char as domain\group separator in groupname instead of the default '\' -o..--unix grouplist additionally print UNIX groups when using -l or -L on a UNIX Samba server grouplist is a comma-separated list of groupnames or gid ranges (root.offset]] print local groups with gid offset offset (from local machine if no machine specified) -L.offset]] ditto. locale prints the values assigned to these arguments. Arguments can be names of locale categories (for instance: LC_CTYPE.--separator char for -L.--users (ignored) -h.50-100).offset]] ditto. Print /etc/group file to stdout Options: -l.--help print this message -v.--current print current group -C.. -L.--id-offset offset change the default offset (10000) added to gids in domain or foreign server accounts. -g. if arguments are given.--group groupname only return information for the specified group one of -l. but generate groupname with machine prefix -c. The -k option prints additionally the name of the keyword.--version print version information and exit Default is to print local groups on stand-alone machines. (enumerating large ranges can take a long time!) -s. charmap).--no-sids (ignored) -u. Example: bash$ locale -ck LC_MESSAGES LC_MESSAGES yesexpr="^[yY]" noexpr="^[nN]" yesstr="yes" nostr="no" messages-codeset="UTF-8" bash$ locale noexpr ^[nN] 3.--Current ditto.--Domain [domain[. or names of keywords supported in the locale categories (for instance: thousands_sep.--domain [domain[.--local [machine[. -D must be specified. too -b. -d. The -c option prints additionally the name of the category. -D.-25.Cygwin User's Guide 59 / 82 territory | Spain codeset | ISO-8859-1 . but generate groupname with machine or domain prefix -S.. .offset]] print domain groups with gid offset offset (from current domain if no domain specified) -D. but generate groupname with machine prefix -d.7.7 mkgroup Usage: mkgroup [OPTION]. The -m option prints the names of the available charmaps supported by Cygwin to stdout..--no-builtin don't print BUILTIN groups -U.
Print /etc/passwd file to stdout Options: -l. for instance: Example 3. It's used together with -l samba-server or -L samba-server.--current print current user -C. -D must be specified. especially when working in a multi-domain environment. -u.--domain [domain[. The command is initially called by setup. If you want to use one of the -D.8 mkpasswd Usage: mkpasswd [OPTIONS]. -L.--id-offset offset change the default offset (10000) added to uids in domain or foreign server accounts. but generate username with machine or domain prefix -S.Cygwin User's Guide 60 / 82 The mkgroup program can be used to help configure Cygwin by creating a /etc/group file.7. The -d/-D and -l/-L options allow you to specify where the information comes from. or both. you can use mkgroup manually to create a more complete /etc/group file for all domains. but they can show up as a group in ls -l output.offset]] ditto. However.--username username only return information for the specified user one of -l.--path-to-home path use specified path instead of user account home dir or /home prefix -m.--unix userlist additionally print UNIX users when using -l or -L\ . This allows you to create the same gids every time you re-run mkgroup. 3. The normal UNIX groups are usually not enumerated. the local SAM of a machine or from the domain. If you change the group information in your system. Especially when you have the same group name used on multiple machines or in multiple domains. Comma-separated from the machine or domain. -C use character char as domain\user separator in username instead of the default '\' -o. For very simple needs. Its use is essential to include Windows security information. you can specify an offset which is used as base added to the group's RID to compute the gid (offset + RID = gid). but generate username with domain prefix -c..offset]] print domain accounts with uid offset offset (from current domain if no domain specified) -D. you can use the -D. but generate username with machine prefix -d. This should be sufficient in most circumstances.--Current ditto. but you don't like the backslash as domain/group separator.--Domain [domain[. you'll need to regenerate the group file for it to have the new information. The -g option only prints the information for one group. Note that this information is static. you can specify another separator using the -S option. -D.--no-mount don't use mount points for home dir -U. -L and -C options to create unique domain\group style groupnames. -L or -C options.--Local [machine[. too -p.offset]] print local user accounts with uid offset offset (from local machine if no machine specified) -L. an entry for the current user's group can be created by using the option -c or -C.--local [machine[. which my be unreachable or have restricted access. With the -d/-D options the program contacts a Domain Controller. The -U option allows you to enumerate the standard UNIX groups on a Samba machine. -d.7 Setting up group entry for current user with different domain/group separator $ mkgroup -C -S+ > /etc/group $ cat /etc/group DOMAIN+my_group:S-1-5-21-2913048732-1697188782-3448811101-1144:11144: The -o option allows for special cases (such as multiple domains) where the GIDs might match otherwise.exe to create a default /etc/group.--separator char for -L.offset]] ditto..
Comma-separated from the machine or domain. However. don't warn about missing mount point directories output usage information and exit write fstab entries to replicate mount points and cygdrive prefixes . However. An entry for the current user can be created by using the option -c or -C. -L and -C options to create unique domain\user style usernames. see Section 2. you'll need to regenerate the passwd file for it to have the new information. -L or -C options. you can use the -D. The -m option bypasses the current mount table so that. Note that this information is static. especially when working in a multi-domain environment. which may be unreachable or have restricted access.--version on a UNIX Samba server userlist is a comma-separated list of usernames or uid ranges (root. The command is initially called by setup. you can use mkpasswd manually to create a more complete /etc/passwd file for all domains. similar to the mkgroup. The -p option causes mkpasswd to use the specified prefix instead of the account home dir or /home/ .exe to create a default /etc/passwd. you can specify an offset which is used as base added to the user's RID to compute the uid (offset + RID = uid). For more information on SIDs. The mkpasswd program can be used to help configure Cygwin by creating a /etc/passwd from your system information. for example. The -o option allows for special cases (such as multiple domains) where the UIDs might match otherwise. Its use is essential to include Windows security information. With the -d/-D options the program contacts the Domain Controller.9 mount Usage: mount [OPTION] [<win32path> <posixpath>] mount -a mount <posixpath> Display information about mounted filesystems.--no-sids -g. Especially when you have the same user name used on multiple machines or in multiple domains. The normal UNIX users are usually not enumerated. The -d/-D and -l/-L options allow you to specify where the information comes from. but they can show up as file owners in ls -l output. If you want to use one of the -D. If you change the user information in your system. --force -h.8 Using an alternate home root $ mkpasswd -l -p "$(cygpath -H)" > /etc/passwd would put local users' home directories in the Windows 'Profiles' directory. --mount-entries mount all filesystems mentioned in fstab change the cygdrive path prefix to <posixpath> force mount.50-100).-25. this command: Example 3. This allows to create the same uids every time you re-run mkpasswd. It's used together with -l samba-server or -L samba-server.5 in the Cygwin User's Guide.--local-groups -h.--help -v. the actual passwords are determined by Windows. (enumerating large ranges can take a long time!) (ignored) (ignored) displays this message version information and exit Default is to print local accounts on stand-alone machines. or both. 3. The -U option allows you to enumerate the standard UNIX users on a Samba machine. The -u option creates just an entry for the specified user. domain accounts on domain controllers and domain member machines. --change-cygdrive-prefix -f. not by the content of /etc/passwd. This should be sufficient in most circumstances. you can specify another separator using the -S option. but you don't like the backslash as domain/group separator. For example. or mount a filesystem -a.Cygwin User's Guide 61 / 82 -s. --all -c. two users who have a Windows home directory of H: could mount them differently. the local machine or the domain (default or given). --help -m.7.
much like as is done by mount commands on typical UNIX systems.2 for more information on the concepts behind the Cygwin POSIX file system and strategies for using mounts.10 Adding mount points $ ls /data ls: /data: No such file or directory $ mount //pollux/home/joe/data /data mount: warning . in contrast to mount points given in /etc/fstab.9 Displaying the current set of mount points $ mount C:/cygwin/bin on /usr/bin type ntfs (binary) C:/cygwin/lib on /usr/lib type ntfs (binary) C:/cygwin on / type ntfs (binary) C: on /mnt/c type ntfs (binary. Additionally. Please see Section 3. It's not valid to replace system-wide mount points. The -o option is the method via which various options about the mount point may be recorded.7. the root mount is a system-wide mount point that is visible to all users running Cygwin programs. mount points created or changed with mount are not persistent. Example 3. The mount utility is also the mechanism for adding new mounts to the mount table in memory. --options X[.noumount) In this example. provided the old mount point was a user mount point. c:/cygwin is the POSIX root and the D drive is mapped to /mnt/d.1 Using mount If you just type mount with no parameters. the first argument .9.user. .Files default to binary mode (default). Note that in this case. it will display the current mount table for you. However. Different from other mount calls. --show-cygdrive-prefix -v.Allows to remount part of the file hierarchy somewhere else.user.noumount) A given POSIX path may only exist once in the mount table..] -p.Cygwin User's Guide 62 / 82 -o. whereas the /mnt/d mount is only visible to the current user. --version specify mount options show user and/or system cygdrive path prefix output version information and exit The mount program is used to map your drives and shares onto Cygwin's simulated POSIX directory tree. The following options are available (note that most of the options are duplicates of other mount flags): acl binary bind .. The -f (force) option causes the old mount to be silently replaced with the new one. the -f option will silence warnings about the non-existence of directories at the Win32 path location. Attempts to replace the mount will fail with a busy error./data does not exist! $ mount //pollux/home/joe/data on /data type smbfs (binary) C:/cygwin/bin on /usr/bin type ntfs (binary) C:/cygwin/lib on /usr/lib type ntfs (binary) C:/cygwin on / type ntfs (binary) C: on /c type ntfs (binary. To remove mounts temporarily.noumount) D: on /mnt/d type fat (binary. The following example demonstrates how to mount the directory //pollux/home/joe/data to /data for the duration of the current session.user.X. Example 3. .noumount) D: on /d type fat (binary.user.Use the filesystem's access control lists (ACLs) to implement real POSIX permissions (default). They disappear immediately after the last process of the current user exited.1. use umount 3.
You can save this output as a backup when experimenting with the mount table.9.d/<username> file.Always fake inode numbers rather than using the ones returned by the filesystem. rather than a Win32 path. nosuid .Override immutable mount points. or by specifing the posix path alone on the command line. before you can add it again.7. This allows to use broken filesystems which don't return unambiguous inode numbers.2. 3. you have to umount the mount point first. the mount -a adds all new mount points to your user session.Always convert leading spaces and trailing dots and spaces to characters in the UNICODE private use area. posix=1 . posix=0 . you can add these mount points to your current user session using the -a/--all option.1. For example. cygexec .Files default to CRLF text mode line endings.Cygwin User's Guide 63 / 82 specifies an absolute POSIX path. Copy the output to /etc/fstab to restore the old state. instead. we will set the automount prefix to /mnt: . noacl . use the bind mount flag. override . $ mount /my/mount $ mount -a The first command just adds the /my/mount mount point to your current session. If you change a mount point to point to another native path.Treat all files below mount point as cygwin executables. even if they are not recognized as such by Cygwin. and that the rule that system mount points can't be removed or replaced in a running session still applies. Note that symlinks are ignored while performing this path conversion.2 Cygdrive mount points Whenever Cygwin cannot use any of the existing mounts to convert from a particular Win32 path to a POSIX one. if Cygwin accesses z:\foo and the z drive is not currently in the mount table. Cygwin will. The mount utility can be used to change this default automount prefix through the use of the "--change-cygdrive-prefix" option. $ mount -o bind /var /usr/var This command makes the file hirarchy under /var additionally available under /usr/var. exec . This allows to use broken filesystems which only allow DOS filenames. If you added mount points to /etc/fstab or your /etc/fstab. The -m option causes the mount utility to output the current mount table in a series of fstab entries.Ignore ACLs and fake POSIX permissions. convert to a POSIX path using a default mount point: /cygdrive. To bind a POSIX path to another POSIX path.No suid files are allowed (currently unimplemented) notexec . then z:\ will be accessible as /cygdrive/z.Switch off case sensitivity for paths under this mount point.Treat all files below mount point as not executable. consider you added a mount point with the POSIX path /my/mount.Treat all files below mount point as executable. text .Switch on case sensitivity for paths under this mount point (default). This POSIX path is remounted to the POSIX path specified as the second parameter. You can add this mount point with either one of the following two commands to your current user session. It also makes moving your settings to a different machine much easier. Note that all mount points added with mount are user mount points. even if they are not recognized as such by Cygwin. ihash . or if you changed the flags of a mount point. As an example. Please note that all such added mount points are added as user mount points. dos . see Section 3. For a more complete description of the mount options and the /etc/fstab file. The conversion to a Win32 path is done within Cygwin immediately at the time of the call. In the following example. System mount points can only be specified in the /etc/ fstab file.
most everything will work properly when you refer to the mount point explicitly. set system minimum password age to DAYS days. It is sometimes desirable to mount to a non-existent directory. USER can't change password. --minage DAYS -x. set system maximum password age to DAYS days. System operations: -i. c pointing to disks. no password required for USER.7. password is required for USER. --pwd-required -R. The mount utility creates system-wide mounts by default if you do not specify a type. For example if your current working directory is /dir. --expires -p. or if there is a place-holder for the mount point (such as a file. and that as with all mounts. Normally the POSIX mount point in Cygwin is an existing empty directory. as in standard UNIX.10 passwd Usage: passwd [OPTION] [USER] Change USER's password or password attributes. Some strange effects can occur however.3 Limitations Limitations: there is a hard-coded limit of 30 mount points. a user-specific mount takes precedence over the system-wide setting. --lock -u.12 Changing the default prefix with specific mount options $ mount -c /mnt -o binary. unless . and /dir/mtpt is a mount point. --reg-store-pwd lock USER's account. although you can mount to pathnames that do not start with "/". Using the --options flag with --change-cygdrive-prefix makes all new automounted filesystems default to this set of options. Files present in a mount point directory before the mount become invisible to Cygwin programs. enter password to store it in the registry for later usage by services to be able to switch to this user context with network credentials. set system minimum password length to LEN.7. Although mount will give you a warning. --pwd-not-required -P. Also. then mtpt will not show up in an ls or echo * command and find .g. --logonserver SERVER connect to SERVER (e. --can-change -e. --unlock -c. Default server is the local system. USER's password expires according to system's password aging rule.11 Changing the default prefix $ mount --change-cygdrive-prefix /mnt Note that the cygdrive prefix can be set both per-user and system-wide. there is no way to make use of such mount points. domain controller). for example to avoid cluttering the root directory with names such as a.Cygwin User's Guide 64 / 82 Example 3. For instance (using the short form of the command line flags) Example 3. --cannot-change -C. You can always see the user and system cygdrive prefixes with the -p option. a symbolic link pointing anywhere. Other options: -d. will not find mtpt.noacl 3.9. --maxage DAYS -L. --inactive NUM -n. --length LEN set NUM of days before inactive accounts are disabled (inactive accounts are those with expired passwords). USER can change password. 3. User operations: -l. USER's password never expires. unlock USER's account. If this is the case. or a non-empty directory). say. b. you will get the expected behavior. --never-expires -E.
or -P to require a password. Similarly. The -n option is used to set the minimum number of days before a password may be changed. Non-Admin users can only store their password if cygserver is running. -x. password aging information is checked to see if the user is permitted to change their password at this time. display password status for USER (locked. passwd also changes account information. output version information and exit. operate on current user. Please note that storing passwords in that registry area is a privileged operation which only administrative accounts are allowed to do. Don't specify a user or any other option together with the -R option. in which case the default is the content of $LOGONSERVER. -n. The user has only one chance to enter the correct password. This allows you to logon through. If no option is given. Allowed values for the above options are 0 to 999. When a privileged Cygwin application calls the set{e}uid(user_id) system call. System operations must not be mixed with user operations. Note that the current user must be a valid member of the administrators group on the remote machine to perform such actions. Administrators can also use passwd to change system-wide password expiry and length requirements with the -i. Cygwin checks if a password for that user has been stored in this registry area. Note that storing even obfuscated passwords in the registry is not overly secure. non-admin users should be allowed to enter their passwords using passwd -R. After the password has been entered. After MAXDAYS days. for instance. When password or account information of other users should be changed. and -C allows a user to change passwords. a value of 0 means 'no restrictions'. If normal. Users can use the passwd -R to enter a password which then gets stored in a special area of the registry on the local system. but administrators may change passwords on any account. it's required to run cygserver as . Both entries are required to match in order for the password to be changed. To change a user account on a remote machine. ssh with public key authentication and get a full qualified user token with all credentials for network access. --status -h. This password is then encrypted and compared against the stored password. To get current password status information. if one is present. Don't use this feature if you don't need network access within a remote session. the method has some drawbacks security-wise. while the -E option causes the password to expire according to the system's normal aging rules. it uses this password to switch to this user account using that password. the -e option disables expiration. A normal user may only change the password for their own account. For password changes.5. This is explained in more detail in Section 2. The -i option is used to disable an account after the password has been expired for a number of days. passwd refuses to change the password and exits. The user will not be permitted to change the password until MINDAYS days have elapsed. passwd changes passwords for user accounts. the user may no longer sign on to the account. expired. The -L option sets the minimum length of allowed passwords for users who don't belong to the administrators group to LEN characters. All operations affecting the current user are by default run against the logon server of the current user (taken from the environment variable LOGONSERVER. For password expiry.Cygwin User's Guide 65 / 82 -S.) plus global system password settings. Use this feature only if the machine is adequately locked down. However. such as password expiry dates and intervals. Allowed values for the minimum password length are 0 to 14. the default server is the local system. The user is then prompted for a replacement password. passwd will prompt twice for this replacement and compare the second entry against the first. the password is required to be changed. Don't specify a USER when triggering a system operation. The -x option is used to set the maximum number of days a password remains valid. After a user account has had an expired password for NUM days. -c disables a user's ability to change passwords. etc. use the -d option to specify the machine to run the command against. If no user name is given. use the -S option. change USER's password. the user is first prompted for their old password. You can delete your stored password by using 'passwd -R' and specifying an empty password. Administrators can use passwd to perform several account maintenance functions (users may perform some of these functions on their own accounts). and -L options. Accounts may be locked with the -l flag and unlocked with the -u flag. which is also used by Windows to store passwords of accounts running Windows services. The administrators are permitted to bypass this step so that forgotten passwords may be changed. If not. In any of the above cases. If so. output usage information and exit. --version changing the current user. Use -p to disable the password requirement for a user. --help -v.
which outputs a shorter listing of just PID. -u.. S means stopped or suspended (in other words. There are historical UNIX reasons for the synonomous options. The -W option causes ps show non-Cygwin Windows processes as well as Cygwin processes. -W. The other display option is -s. With either the -a or -e option. I means waiting for input or interactive (foreground). all user's processes (and system processes) are listed. TTY. The PID column is the process ID you need to give to the kill command. By default. -l.7.] unset KEY\VALUE load KEY\SUBKEY PATH unload KEY\SUBKEY save KEY\SUBKEY PATH add new SUBKEY exit 0 if KEY exists. pgids. The TTY column gives which pseudo-terminal a process is running on. and COMMAND gives the name of the program running. showing a "long" listing with all the above columns. or a '?' for services. -p. -e. --keys print only KEYs . STIME. and they can be killed with the Cygwin kill command's -f option. and PGID is the process group ID. ppids. in the background). This only affects storing passwords. -h. there is little information to give. ps will only show processes owned by the current user. and O means waiting to output.12 regtool Usage: regtool [OPTION] (add|check|get|list|remove|unset|load|unload|save) KEY View or edit the Win32 registry Actions: add KEY\SUBKEY check KEY get KEY\VALUE list KEY remove KEY set KEY\VALUE [data . The -l option is the default display mode. 3. Listings may also have a status flag in column zero.Cygwin User's Guide 66 / 82 a service under the LocalSystem account before running passwd -R. The PPID is the parent process ID. ppids output usage information and exit show process uids. STIME is the time the process was started. The -u option allows you to show only processes owned by a specific user. Using passwords in privileged processes does not require cygserver to run.. winpids show information for specified PID show process summary list processes owned by UID output version information and exit show windows as well as cygwin processes ps outputs the long format by default The ps program gives the status of all the Cygwin processes running on the system (ps = "process status"). The WINPID column is the process ID displayed by NT's Task Manager program. The -f option outputs a "full" listing with usernames for UIDs. With --all --everyone --full --help --long --process --summary --user --version --windows no options. -f. Limitations: Users may not be able to change their password on some systems.11 ps Usage: ps [-aefls] [-u UID] Report process status -a. The WINPID is also the PID. show processes of all users show processes of all users show process uids. -v. The UID column shows which user owns each process. Due to the limitations of simulating a POSIX environment under Windows. and COMMAND. The -p option allows you to show information for only the process with the specified PID. which are functionally identical. -s. 3. 1 if not prints VALUE to stdout list SUBKEYs and VALUEs remove KEY set VALUE removes VALUE from KEY load hive from PATH into new SUBKEY unload hive and remove SUBKEY save SUBKEY into new hive PATH Options for 'list' Action: -k.7.
it doesn't print the message but does return the non-zero exit code. --dword-be set -e. --binary set -D. The -v option means "verbose". When using the -w switch. the -q option supresses error messages. The get action gets the value of a key. an error message is printed and the program returns a non-zero exit code. this causes additional or lengthier messages to be printed. Conversely. The -w option allows you to access the 64 bit view of the registry. and carelessness here can result in an unusable system. --multi-string set -n. --expand-string set -i. the action must be add. The purpose of this option is mainly for symmetry. --list -p. The add action adds a new key. Note that modifying the Windows registry is dangerous. Several subkeys exist in a 32 bit and a 64 bit version when running on Windows 64.exe get '\user\software\Microsoft\Clock\iFormat' The regtool program allows shell scripts to access and modify the Windows registry. including VALUE contents when applicable access 64 bit registry view (ignored on 32 bit Windows) access 32 bit registry view (ignored on 32 bit Windows) output version information and exit KEY is in the format [host]\prefix\KEY\KEY\VALUE. Since Cygwin is running in 32 bit mode. . It permits creation of OS agnostic scripts which would also work in a hypothetical 64 bit version of Cygwin. nonzero if it does not). set. list. For most commands. The check action checks to see if a key exists (the exit code of the program is zero if it does. Be careful. appends '\' postfix to KEY names Options for 'get' Action: -b. --quiet -v. so you can use the exit status of the program to detect if a key exists or not (for example). or unset. and prints it (and nothing else) to stdout. the 64 bit view is used and regtool can access the entire registry. --version output usage information and exit no error output. You must provide regtool with an action following options (if any). set. The -W option allows you to access the 32 bit view on the registry. --qword set -s. --wow32 -V. --integer set -m. it only has access to the 32 bit view of these registry keys. --verbose -w. Note: if the value doesn't exist. check. --none print data as stream of bytes as stored in registry -x. --key-separator[=]<c> set key separator to <c> instead of '\' Other Options: -h. --string set type type type type type type type type to to to to to to to to REG_BINARY (hex args or '-') REG_DWORD_BIG_ENDIAN REG_EXPAND_SZ REG_DWORD REG_MULTI_SZ REG_NONE REG_QWORD REG_SZ Options for 'set' and 'unset' Actions: -K<c>. just nonzero return if KEY/VALUE missing verbose output. in that case backslash is treated as escape character Example: regtool. --none set -Q. This option is simply ignored when running on 32 bit Windows versions.Cygwin User's Guide 67 / 82 -l. --postfix print only VALUEs like ls -p. --binary print REG_BINARY data as hex bytes -n. --wow64 -W. --help -q. remove. Currently. get. where host is optional remote host in either \\hostname or hostname: format and prefix is any of: root HKCR HKEY_CLASSES_ROOT (local only) config HKCC HKEY_CURRENT_CONFIG (local only) user HKCU HKEY_CURRENT_USER (local only) machine HKLM HKEY_LOCAL_MACHINE users HKU HKEY_USERS You can use forward slash ('/') as a separator instead of backslash. --hex print numerical data as hex numbers Options for 'set' Action: -b. If you give -q.
unless it's value doesn't fit into 32 bit. If it looks like a number. The unload action unloads the file and removes the subkey. the -k option instructs regtool to print only KEYs. setfacl [-r] ([-d acl_entries] [-m acl_entries]) FILE. it's a DWORD. data is printed as hex bytes. it's an expanding string. The get action prints a value within a key. or delete ACL entries. The load action adds a new subkey and loads the contents of a registry hive into it. --delete -f. The remove action removes a key. Note that you may need to remove everything in the key before you may remove it. If it starts with a percent. The save action saves a subkey into a registry hive. the last "\" or "/" is assumed to be the separator between the key and the value.. -Q means the value is a 64 bit integer value (REG_QWORD). -s) must be specified For each file given as parameter. --version output version information and exit At least one of (-d. -n allows to print the data as a typeless stream of bytes. or it will add. but don't rely on this stopping you from accidentally removing too much. For more information on Cygwin and Windows ACLs. it's a regular string. -e means it's an expanding string (REG_EXPAND_SZ) that contains embedded environment variables. binary data is read from stdin instead. modify. The set action sets a value within a key. If you give multiple values.. By default.5 in the Cygwin User's Guide. -f).. see see Section 2. The binary values are specified as hex bytes in the argument list. -f. The unset action removes a value from a key. it's a multi-string. --modify modify one or more specified ACL entries -r.Cygwin User's Guide 68 / 82 The list action lists the subkeys and values belonging to the given key. REG_QWORD) are usually printed as decimal values. The parent key must be HKEY_LOCAL_MACHINE or HKEY_USERS. If the argument is '-'. If you don't specify one of these.13 setfacl Usage: setfacl [-r] (-f ACL_FILE | -s acl_entries) FILE. For example: d[efault]:u[ser]:uid:perm . -m means it's a multi-string (REG_MULTI_SZ). With list. --file delete one or more specified ACL entries set ACL entries for FILE to ACL entries read from a ACL_FILE -m. 3. -b means it's binary data (REG_BINARY). -D means the value is a 32 bit integer value in Big Endian representation (REG_DWORD_BIG_ENDIAN). in which case it's a QWORD. You can use the -K option to provide an alternate key/value separator character. -s means the value is a string (REG_SZ).7. --substitute substitute specified ACL entries for the ACL of FILE -h. and the -l option to print only VALUEs. Acl_entries are one or more comma-separated ACL entries from the following list: u[ser]::perm u[ser]:uid:perm g[roup]::perm g[roup]:gid:perm m[ask]::perm o[ther]::perm Default entries are like the above with the additional default identifier. -d or -i means the value is a 32 bit integer value (REG_DWORD). --help output usage information and exit -v. Else. Integer values (REG_DWORD. but leave VALUEs with no postfix. -m.. setfacl will either replace its complete ACL (-s. The -x option allows to print the numbers as hexadecimal values. With the -b option. The -p option postfixes a '/' to each KEY. Modify file and directory access control lists (ACLs) -d. regtool tries to guess the type based on the value you give. --replace replace mask entry with maximum permissions needed for the file group class -s.
Dangerous if you have race conditions.target_file Required entries are: one user entry for the owner of the file. Directories may contain default ACL entries. trace sub-threads too. use OutputDebugString ("ssp on") to enable stepping enable single-stepping by default. This gets big *fast*. but substitute the file's ACL with Acl_entries specified in a comma-separated list on the command line. use OutputDebugString ("ssp off") to disable stepping output usage information and exit enable dll profiling. A chart of relative DLL usage is produced after the run. Whitespace characters are ignored. Note that you can use this with getfacl and setfacl to copy ACLs from one file to another: $ getfacl source_file | setfacl -f . --version trace every EIP value to the console. While the -d and -m options may be used in the same command. trace every EIP value to a file TRACE. the -f and -s options may be used only exclusively. and the character "#" may be used to start a comment. --dll -s.. one default group entry for the group of the file. Acl_entries to be deleted should be specified without permissions. a value from 0 (equivalent to "---") to 7 ("rwx"). -r Causes the permissions specified in the mask entry to be ignored and replaced by the maximum permissions needed for the file group class. --console-trace -d. -m Add or modify one or more specified ACL entries. and one default other entry. -s Like -f. the default ACL entries are not taken into account currently.7. The special filename "-" indicates reading from stdin. Files created in a directory that contains default ACL entries will have permissions according to the combination of the current umask. --verbose -V. output version information and exit . gid is a group name or a numerical gid. and one other entry. If it is a directory: one default user entry for the owner of the file.14 ssp Usage: ssp [options] low_pc high_pc command. one default mask entry for the file group class. output verbose messages about debug events. 3. --help -l. The following options are supported: -d Delete one or more specified entries from the file's ACL. as in the following list: u[ser]:uid g[roup]:gid d[efault]:u[ser]:uid d[efault]:g[roup]:gid d[efault]:m[ask]: d[efault]:o[ther]: -f Take the Acl_entries from ACL_FILE one per line. group and others entries must not be deleted. one group entry for the group of the file. and no duplicate user or group entries with the same uid/gid. disable single-stepping by default. Acl_entries is a comma-separated list of entries from the same list as above. --sub-threads -t. *Lots* slower. uid is a user name or a numerical uid. --enable -h. --disable -e. Single-step profile COMMAND -c.Cygwin User's Guide 69 / 82 perm is either a 3-char permissions string in the form "rwx" with the character '-' for no permission or it is the octal representation of the permissions. the explicit permissions requested and the default ACL entries Limitations: Under Cygwin.. The owner.SSP. If additional user and group entries are given: a mask entry for the file group class of the file. --trace-eip -v.
457 opcodes per call.57 7. When it's done. For example. The gprof documentation explains a lot about this report. You can turn this data file into a readable report with gprof: $ gprof -b cygwin1.Cygwin User's Guide 70 / 82 Example: ssp 0x401000 0x403000 hello.22 72. Here's a simple example.dll: Sections: Idx Name 0 .text 1 . It records the location of each instruction used. although gprof will claim the values are seconds. By default. they really are instruction counts.15 total ms/call 1574. We can use SSP to selectively profile this function by using OutputDebugString() to control SSP from within the program. so now we've got a huge report that took a long time to generate. Here's a sample program: .15 name strcspn strncasematch The "seconds" columns are really CPU opcodes.122 opcodes.dll The "-b" means 'skip the help pages'.text section and the VMA of the section after it (sections are usually contiguous. it will step the whole program. More on that later. LOAD.exe This will step the whole program. It will take at least 8 minutes on a PII/300 (yes. Let's say we're profiling cygwin1. 1574.text" section.out". file format pei-i386 Size 0007ea00 CONTENTS. just run ssp without options. the first part of the report reports the amount of time spent in each function.dll It will print a report like this: cygwin1. You can omit this until you're familiar with the report layout. .exe SSP . The ms/call values are 10x too big. The results are saved in a format that is usable by the profiling program gprof. You must specify the range of memory addresses to keep track of manually.48 130 442. but ssp changes a few things. So.57 means 157. Use the "objdump" program to determine the bounds of the target's ". In this case. really). DATA The only information we're concerned with are the VMA of the . like this: Each sample counts as 0. Similar adjustments need to be made for the "self" and "children" columns in the second part of the report. OK.02 231. "231. DATA 61080000 61080000 0007ee00 2**2 ALLOC.22" above means 23.95 288. and we've identified a spot we want to work on optimizing. Make sure you've built it with debug symbols (else gprof won't run) and run objdump like this: $ objdump -h cygwin1.70 57. 1/100 second per opcode.43 46 1574. LOAD. . There are two basic ways to use SSP . you can also add the Size to the VMA to get the end address).dll. VMA LMA File off Algn 61001000 61001000 00000400 2**2 ALLOC. Let's say it's the time() function. % cumulative self self time seconds seconds calls ms/call 10. 00008000 CONTENTS.data method) or 0x0x6107fa00 (VMA+Size method).The Single Step Profiler Original Author: DJ Delorie The SSP is a program that uses the Win32 debug API to run a program one ASM instruction at a time. CODE. or selectively profiling parts of the program. the VMA is 0x61001000 and the ending address is either 0x61080000 (start of . it will create a file called "gmon.either profiling a whole program. but it's not hard to figure out what to specify. and all function calls. it does not automatically select a block of code to report statistics on.57 442. how many times that instruction is used. Because the SSP was originally designed to profile the cygwin DLL.data .01 seconds. To profile a whole program. using the numbers above: $ ssp 0x61001000 0x61080000 hello. READONLY.
since it can trace multiple threads. I usually use the -v. Use addr2line -C -f -s -e foo. off otherwise. --usecs -v. -f. No sense optimizing a function in your program if most of the time is spent in the DLL. It's also needed when you want to profile a function that only a subthread calls. However. Clever use of scripts can match addresses with disassembled opcodes if needed. -l . --timestamp -T.subthreads. Generates a pretty table of how much time was spent in each dll the program used. --flush-period=PERIOD -t. add the -d option to ssp to default to *disabling* profiling.exe 3. useful for debugging key chunks of assembler. --new-window MASK can be any combination of the following mnemonics and/or hex values . but sometimes you need to trace all threads. --quiet -S. DLLs loading. -m. OutputDebugString("ssp on").15 strace Usage: strace. Defaults to on if "-p". so this enables that.exe [OPTIONS] <command-line> Usage: strace. Implies -d toggle tracing in a process already being toggle printing of microseconds timestamp traced. OutputDebugString calls. Warning: creates *huge* files.dll profiling.ssp". Since step-profiling makes your program run about 1. This prints messages about threads starting and stopping.verbose.7. You can then use gprof (as usual) to see the performance profile for just that portion of the program's execution. With -t. --version -w. time(&t). This can be used to help debug functions. --pid=n -q. then step until the second. *every* step's address is written to the file "trace. --output=FILENAME -p. Requires -p <pid> output version information and exit spawn program under test in a new window -o. using OutputDebugString automatically enables profiling on the thread that called it. } Then.default true) output usage information and exit set message filter mask output descriptive text instead of error numbers for Windows errors set output file to FILENAME attach to executing program with cygwin pid n toggle "quiet" flag. -s . -c prints each address to the console. OutputDebugString("ssp off").000 times slower than normal.ssp and then perl cvttrace to convert to symbolic traces. -t and -c . Usually. -v . -d. --toggle -u.exe [OPTIONS] -p <pid> Trace system calls and signals -b. flush buffered strace output every PERIOD secs use an absolute hh:mm:ss timestamp insted of the default microsecond timestamp. you only need to trace the main thread.ssp > lines. --buffer-size=SIZE --no-delta --trace-children --help --mask=MASK --crack-error-numbers set size of output file buffer don't display the delta-t microsecond timestamp trace child processes (toggle . -h. very quickly. -n. etc. it's best to understand all the options so that you can narrow down the parts of your program you need to single-step. -s. not the main thread.Cygwin User's Guide 71 / 82 #include <windows. The program will run at full speed until the first OutputDebugString.tracing.exe < trace. and -l options: $ ssp -v -s -l -d 0x61001000 0x61080000 hello.h> main() { time_t t. There are many options to ssp.
For example. 3. --remove-user-mounts -v. As a result it does not understand symlinks. select 0x000200 (_STRACE_SELECT) Info on ugly select internals.".exe [OPTION] [<posixpath>] Unmount filesystems -h. system 0x008000 (_STRACE_SYSTEM) Serious error. or to a file with the -o option. This program is mainly useful for debugging the Cygwin DLL itself.8 Using Cygwin effectively with Windows Cygwin is not a full operating system. See Section 3. done' & This is particularly useful for strace sessions that take a long time to complete. nomutex 0x010000 (_STRACE_NOMUTEX) Don't use mutex for synchronization. flush 0x000002 (_STRACE_FLUSH) Flush output buffer after each message. Note that strace is a standalone Windows program and so does not rely on the Cygwin DLL itself (you can verify this with cygcheck).' like so: --mask=wm+system. special 0x100000 (_STRACE_SPECIAL) Special debugging printfs for non-checked-in code The strace program executes a program. wm 0x000400 (_STRACE_WM) Trace Windows msgs (enable _strace_wm).1. and so must rely on Windows for accomplishing some tasks. debug 0x000040 (_STRACE_DEBUG) Info to help debugging. Combine masks with '+' or '. syscall 0x000010 (_STRACE_SYSCALL) System calls. reporting any Cygwin DLL output from the program(s) to stdout. thread 0x040000 (_STRACE_THREAD) Thread-locking calls. do echo "tracing. inherit 0x000004 (_STRACE_INHERIT) Children inherit mask from parent. you can start an strace session in a new window.malloc+0x00800 Mnemonic Hex Corresponding Def Description ========================================================================= all 0x000001 (_STRACE_ALL) All strace messages. paranoid 0x000080 (_STRACE_PARANOID) Paranoid info. but does not provide filesystem drivers of its own.7.2 for more information on the mount table. startup 0x000020 (_STRACE_STARTUP) argc/envp printout at startup. Note that you can only remove user mount points. Therefore part of using . exitdump 0x004000 (_STRACE_EXITDUMP) Dump strace cache on exit. If you specify a POSIX path that corresponds to a current mount point. for example: $ strace -o tracing_output -w sh -c 'while true. uhoh 0x000008 (_STRACE_UHOH) Unusual or weird phenomenon. --version output usage information and exit remove all user mounts output version information and exit The umount program removes mounts from the mount table in the current session. pthread 0x002000 (_STRACE_PTHREAD) Pthread calls. minimal 0x001000 (_STRACE_MINIMAL) Very minimal strace output. umount will remove it from the current mount table. 3. and optionally the children of the program.. termios 0x000100 (_STRACE_TERMIOS) Info for debugging termios stuff. malloc 0x020000 (_STRACE_MALLOC) Trace malloc calls. sigp 0x000800 (_STRACE_SIGP) Trace signal and process handling. With the -w option.16 umount Usage: umount. --help -U.Cygwin User's Guide 72 / 82 (0x is optional).. The -U flag may be used to specify removing all user mount points from the current user session. goes to console and log. Cygwin provides a POSIX view of the Windows filesystem.
8.exe provides the most Unix-like environment. Another traditional Unix input/output method.exe provides information about network configuration.Cygwin User's Guide 73 / 82 Cygwin effectively is learning to use Windows effectively. and some do not deal gracefully with other situations.exe. require a network connection. Using mintty. Windows NT 4. the younger the Windows version. and XP (the Windows Support Tools). If you chose to install the inetutils package. Unfortunately. The same format works for most Windows programs. The basic problem is that a Cygwin pty is a pipe and some Windows applications do not like having their input or output redirected to pipes. and net. interacting with Windows console applications is not a simple matter of using a translation utility. Windows console applications are designed to run under cmd. which cygpath can translate from a POSIX path with the -p option. 3.2 Console Programs Another issue is receiving output from or giving input to console-based Windows programs. such as find. for example notepad.1 Pathnames Windows programs do not understand POSIX pathnames. Windows 2000 (the Resource Kit Tools). Cygwin provides the cygpath utility for converting between Windows and POSIX paths.com. Generally. semicolon-delimited path list. Microsoft also provides free downloads for Windows NT 4. Many Windows utilities provide a good way to interact with Cygwin's predominately command-line environment. A complete description of its options and examples of its usage are in Section 3. To be most compatible with Windows programs. Cygwin can receive console input only if it is also running in a console window since Windows does not provide any way to attach to the backend of the console device. so any arguments that reference the filesystem must be in Windows (or DOS) format or translated. 3. ipconfig.0 (the Resource Kit Support Tools). use a DOS prompt. Additionally. it is often preferable to use cygpath in shell scripts. Since Cygwin relies on Windows for connectivity. such as ncftp.2. as far as they are not already provided by Cygwin. and wget. If you are having problems using one of these programs.8. Unfortunately. A few Windows tools. To make Cygwin more Unix compatible in this case. For example.java Since using quoting and subshells is somewhat awkward.exe.exe views and configures network file and printer resources. but expect some compatibility problems with Windows programs. Next would be to run bash within a default DOS box. which later versions of Windows expanded. set CYGWIN=tty (see Section 3.0 has only a basic set of tools.exe. including a shell script for starting Windows Explorer in any directory. if one of these tools is not working as expected you may need to troubleshoot using Windows tools.8.exe "$(cygpath -aw "Desktop/Phone Numbers. a Java compilation from bash might look like this: javac -cp "$(cygpath -pw "$CLASSPATH")" hello. simtel. may conflict with the Cygwin versions make sure that you use the full path (/usr/bin/find) or that your Cygwin bin directory comes first in your PATH. 3. ptys (pseudo-terminals). the optional mintty package provides a terminal emulator similar to such X11 programs as xterm (it is not necessary to set CYGWIN=tty with mintty nor is it necessary to be running /Cygwin/X).5). Alternatively. running only the occasional Cygwin command or script.exe. The first test is to see if you can reach the URL's host with ping. To help deal with these issues.3 Cygwin and Windows Networking Many popular Cygwin packages. If you are unfamiliar with the tools available on your system. the more complete are the onboard tools. one of the few utilities included with every Windows version since Windows 95. see if the alternate one works as expected. Most of these tools support the /? switch to display usage information. you may have both Windows and Cygwin versions of utilities such as ftp and telnet. is supported by Cygwin but not entirely by Windows.7. no standard set of tools included with all versions of Windows exists.exe and sort. here is a general guide.net. link.txt")" A few programs require a Windows-style. Cygwin supports customizable levels of Windows versus Unix compatibility behavior. and Microsoft's own Sysinternals provide quite useful command-line utilities. many independent sites such as download. . lynx. For example.
exe). But here's the problem. but not all. dos2unix. or a local port name that is mapped to a printer share. You may also specify a device on the command line with the -d or -P options. Unfortunately.lnk files into tar archives and keep all the information in them. is available from the Ghostscript website.5. Cygwin does not create symlinks as . Use the --help switch for usage information.lnk files.lnk files. which will override the environment variable setting. Unix tools such as tr can convert between CRLF and LF endings. Several of the cygutils tools are useful for interacting with Windows. you may be interested in rasdial. One of the hassles of Unix-Windows interoperability is the different line endings on text files. and unix2dos. which is helpful when using lpr from a shell that uses the backslash as an escape character. 3. If Cygwin handled these native shortcuts like any other symlink. a native Windows application for printing PostScript. and Microsoft . Note that forward slashes may be used in a UNC path (//server_name/printer_name).exe. d2u.8. this means that the usual Unix way of creating and using symlinks does not work with native Windows shortcuts. u2d. select it from the Utils category in setup. It is not included in a default Cygwin install.lnk files are compatible with Windowscreated . They do not include much of the information that is available in a standard Microsoft shortcut. these shortcuts would have lost all the extra information and would be no different than standard Cygwin symlinks.5 Creating shortcuts with cygutils Another problem area is between Unix-style links. which provide a shortcut to a file. The ghostscript package also provides some translation from PostScript to various native printer languages. 3. The cygutils package includes a mkshortcut utility for creating standard native Microsoft . By default. As mentioned in Section 3. but they are still different.exe (Windows 2000 and later). lpt1).lnk files.6 Printing with cygutils There are several options for printing from Cygwin. These symlink . which link one file to another. Users who frequently change their network configuration can script these changes with netsh. are fairly different. lpr sends raw data to the printer. packages such as a2ps and enscript can prepare text files for printing. gsprint. in reality. etc.4 The cygutils package The optional cygutils package contains miscellaneous tools that are small enough to not require their own package.exe for automating dialup connections. Many. . no formatting is done. printers accept plain text as input. the open source NTLM Authorization Proxy Server or the no-charge Hummingbird SOCKS Proxy may allow you to use Cygwin network programs in your environment. After unpacking.2. including the lpr found in cygutils (not to be confused with the native Windows lpr.Cygwin User's Guide 74 / 82 There are a variety of other programs available for specific situations. such as the working directory. an icon.lnk files. For proxy users. you could not archive Microsoft . a reserved DOS device name (prn. 3.8. but cygutils provides several dedicated programs: conv.8. A device name may be a UNC path (\\server_name\printer_name). If your printer supports PostScript. They seem similar at first glance but. Additionally. Therefore these two types of links are treated differently. The easiest way to use cygutils' lpr is to specify a default device name in the PRINTER environment variable. see Section 3. but there's an option to do that. If your system does not have an always-on network connection.
and like any other Cygwin makefile.1 Building Hello World with GCC bash$ gcc hello.Cygwin User's Guide 75 / 82 Chapter 4 Programming with Cygwin 4.c -o hello. you should remove all __export attributes from functions and replace them like this: int foo (int) __attribute__ ((__dllexport__)). including the GUI functions as defined in any Microsoft or off-the-shelf publication. just like under UNIX. int foo (int i) The Makefile is similar to any other UNIX-like Makefile. Refer to the GCC User's Guide for information on standard usage and options.rc resource.exe bash$ hello. However.res : myapp. as you'll be using the GNU tools instead of the Microsoft tools. The only difference is that you use gcc -mwindows to link your program into a GUI application instead of a command-line application.o myapp. For the most part.1 Using GCC with Cygwin Console Mode Applications Use gcc to compile.1. your sources won't need to change at all. Here's a simple example: Example 4. However.exe : myapp.res -o $@ myapp.o myapp. World bash$ 4.exe Hello.h windres $< -O coff -o $@ .2 GUI Mode Applications Cygwin allows you to build programs with full access to the standard Windows 32-bit API. the process of building those applications is slightly different.res gcc -mwindows myapp.1. Here's an example: myapp.1 4.
if (!hWnd) return FALSE. For more information on windres. 0. and other resources you need. UpdateWindow(hWnd). IDI_APPLICATION). LPSTR lpCmdLine. So.lpszMenuName = NULL. GetCommandLine() ). wcex. nCmdShow). HINSTANCE hPrevInstance. CW_USEDEFAULT. wcex.hbrBackground = (HBRUSH)(COLOR_WINDOW+1). wcex. CW_USEDEFAULT.lpszClassName = "HELLO". into one handy object file.hIconSm = NULL.c -o hellogui.h> char glpszText[1024].res format file. The following is a simple GUI-mode "Hello. wcex. hInstance. while (GetMessage(&msg.res naming convention. Normally.lpfnWndProc = WndProc. CW_USEDEFAULT.cbClsExtra = 0.exe */ /*-------------------------------------------------*/ #include <windows. "Hello World\nGetCommandLine(): [%s]\n" "WinMain lpCmdLine: [%s]\n". NULL.hInstance = hInstance.cbWndExtra = 0. LPARAM). int nCmdShow) { sprintf(glpszText. wcex.Cygwin User's Guide 76 / 82 Note the use of windres to compile the Windows resources into a COFF-format . WS_OVERLAPPEDWINDOW. we maintain the . consult the Binutils manual. That will include all the bitmaps. if (!RegisterClassEx(&wcex)) return FALSE. HWND hWnd. wcex. wcex. NULL. IDC_ARROW). wcex. ShowWindow(hWnd.c . int APIENTRY WinMain(HINSTANCE hInstance. "Hello". lpCmdLine. WPARAM. hWnd = CreateWindow("HELLO".gui hello world */ /* build: gcc -mwindows hellogui.cbSize = sizeof(wcex). NULL.hCursor = LoadCursor(NULL.hIcon = LoadIcon(NULL. MSG msg. wcex. World!" program to help get you started: /*-------------------------------------------------*/ /* hellogui. CW_USEDEFAULT.res file. LRESULT CALLBACK WndProc(HWND. WNDCLASSEX wcex. NULL ← ). UINT. but for compatibility with the many examples that assume your linker can handle Windows resource files directly. DispatchMessage(&msg). . icons. wcex. but we can only link COFF objects.style = CS_HREDRAW | CS_VREDRAW. 0)) { TranslateMessage(&msg). if you omitted the "-O coff" it would create a Windows . wcex. wcex. we tell windres to produce a COFF object.
} 4. Diagnosing these bugs and fixing them is made easy by special tools called debuggers. you can type where to find out where it crashed. WPARAM wParam. or info locals to see the values of all the local variables. To invoke GDB. EndPaint(hWnd. &rt.2 Debugging Cygwin Programs When your program doesn't work right. GetClientRect(hWnd. DT_TOP | DT_LEFT). These extra symbols and debugging information give your program enough information about the original sources so that the debugger can make debugging much easier for you. It will display some text telling you about itself. variable names. wParam. UINT message. After it crashes. &ps).c -o myapp What this does is add extra information to the objects (they get much bigger too) that tell the debugger about line numbers. message. meaning there's something wrong with the program itself that is causing unexpected results or crashes. Whenever you see this prompt.wParam. strlen(glpszText). &ps). LPARAM lParam) { PAINTSTRUCT ps. HDC hdc. Crashing programs sometimes create "core" files. case WM_DESTROY: PostQuitMessage(0). break. Example 4. DrawText(hdc. lParam). and other useful things. } LRESULT CALLBACK WndProc(HWND hWnd. Oh :-) type help to get help on the commands you can type in. which stands for "GNU DeBugger". Before you can debug your program. switch (message) { case WM_PAINT: hdc = BeginPaint(hWnd. it means that gdb is waiting for you to type in a command. glpszText.c bash$ gcc -g myapp. In Cygwin these are regular text files that cannot be used directly by GDB. If your program crashes and you're trying to figure out why it crashed. This tool lets you run your program in a controlled environment where you can investigate the state of your program while it is running or after it crashes. like run or help. then (gdb) will appear to prompt you to enter commands. the best thing to do is type run and let your program run.exe at the command prompt. break. RECT rt. } return 0. you need to prepare your program for debugging. &rt). There's also a print that lets you look at individual variables or what pointers point to. What you need to do is add -g to all the other flags you use when compiling your sources to objects. default: return DefWindowProc(hWnd. simply type gdb myapp. the debugger is GDB.Cygwin User's Guide 77 / 82 } return msg. it usually has a "bug" in it. In the case of Cygwin.2 Compiling with -g bash$ gcc -g -O2 -c myapp. or read the [?] for a complete description of GDB and how to use it. .
org/ Let's go through a simple example of how to build a dll.exe at all. we'll use a single file myprog. modify variables. The dlltool program creates the exports section of the dll from your text file of exported symbols.functions. you can use the break command to tell gdb to stop your program when it gets to a specific function or line number: Example 4. but it's possible to do it automatically from the list of functions in your code. There are three parts to a DLL: • the exports • the code and data • the import library The code and data are the parts you write .exe) and a single file mydll. Note that you may specify additional arguments to the run command to provide command-line arguments to your program. The exports contains a list of functions and variables that the dll makes available to other programs.c for the contents of the dll (mydll.3 "break" in gdb (gdb) break my_function (gdb) break 47 Now.3. Think of this as the list of "global" symbols. you'd create this list by hand with a text editor.c for the program (myprog. the rest being hidden. and put into the dll. 4.exe. when you type run 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. see the gcc documentation and website. This information is linked into your . Say you want to build this minimal function in mydll.h> int .dll). To begin an exploration of the many additional options.c: #include <stdio. These two cases are the same as far as your program is concerned: Example 4. They are not put into your . like if you were building one big object files.gnu. with the latest gcc and binutils the process for building a dll is now pretty simple.Cygwin User's Guide 78 / 82 If your program is doing something unexpected.a library. currently at http://gcc.1 Building DLLs This page gives only a few simple examples of gcc's DLL-building capabilities. For this example. which means that they're linked into your program at run time instead of build time. All these are merged together. and step through your program's statements one at a time. The import library is a regular UNIX-like .3 Building and Using DLLs DLLs are Dynamic Link Libraries. variables. Fortunately.4 Debugging with command line arguments bash$ myprog -t foo --queue 47 bash$ gdb myprog (gdb) run -t foo --queue 47 4. Normally. This is also generated by dlltool. etc. but it only contains the tiny bit of information needed to tell the OS how your program interacts with ("imports") the dll.
} Then link to your dll with a command like: gcc -o myprog myprog.dll | grep ' T _' | sed 's/.def --dllname foo.o That's it! To finish up the example.c Then. you will probably want to use the complete syntax: gcc -shared -o cyg${module}.--out-implib=lib${module}.--whole-archive ${old_libs} \ -Wl.a \ -Wl.def nm foo. If you do not have the source or a supplied working import library. tell gcc that it is building a shared library: gcc -shared -o mydll.g '-lpng -lz -L/usr/local/special -lmyspeciallib'.* T _//' >> foo.dll".dll \ -Wl. you need to build a Cygwin-compatible import library.Cygwin User's Guide 79 / 82 hello() { printf ("Hello World!\n").a . if you are building a dll as an export library. bundled together in static libs or single object files and the ${dependency_libs} are import libs you need to link against. Once you have the . you can create an import library from it like this: dlltool --def foo.3. 4.def file with these commands (you might need to do this in bash for the quoting to work correctly): echo EXPORTS > foo.def file. e.1 for details on having gcc build one for you.dll.3.dll mydll.--enable-auto-import \ -Wl./ -lmydll However. Cygwin DLLs use the cyg prefix to differentiate them from native-Windows MinGW DLLs. } First compile mydll.--export-all-symbols \ -Wl. you can get most of the way by creating a . prefixed with cyg for the DLL and lib for the import library. see Section 4.2 Linking Against DLLs If you have an existing DLL already. see the MinGW website for more details. Otherwise you will get an error message: "No symbols in foo.dll --output-lib foo.c -L.def Note that this will only work if the DLL is not stripped. ${old_libs} are all your object files.--no-whole-archive ${dependency_libs} The name of your library is ${module}.c to object code: gcc -c mydll. you can now link to the dll with a simple program: int main () { hello (). If you have the source to compile the DLL.
"name" FONT number.o myapp.width.res -o $@ myapp.DISCARDABLE id DIALOG memflags exstyle x.number VERSIONK number controls: AUTO3STATE params AUTOCHECKBOX params AUTORADIOBUTTON params BEDIT params CHECKBOX params COMBOBOX params .italic MENU id CHARACTERISTICS number LANGUAGE number. VIRTKEY ASCII NOINVERT SHIFT CONTROL ALT 65 12 . "name".width.rc resource.height styles BEG controls END id DIALOGEX memflags exstyle x. id ACCELERATORS suboptions BEG "^C" 12 "Q" 12 65 12 65 12 .h windres $< -O coff -o $@ What follows is a quick-reference to the syntax windres supports. CONTROL.exe : myapp. ALT require VIRTKEY id BITMAP memflags "filename" memflags defaults to MOVEABLE id CURSOR memflags "filename" memflags defaults to MOVEABLE.rc) and converts it to a res or coff file. so please refer to any publication describing the Windows resource format for details.height. ASCII.4 Defining Windows Resources windres reads a Windows resource file (*.Cygwin User's Guide 80 / 82 4.y.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.y.width. The syntax and semantics of the input file are the same as for any other resource compiler.height styles BEG controls END id DIALOGEX memflags exstyle x. ALT (12 is an acc_id) END SHIFT. Also. Here's an example of using it in a project: myapp. SHIFT. VIRTKEY. the windres program itself is fully documented in the Binutils manual. CONTROL.res : myapp.weight.y.o myapp.res gcc -mwindows myapp. NOINVERT.
style. exstyle [data] ICON ["name".w.exstyle] [data] ["name". style.w. x. id.helpid] BEG items END id MESSAGETABLE memflags "filename" memflags defaults to MOVEABLE .h. h. x. helpid [data] IEDIT params LISTBOX params LTEXT params PUSHBOX params PUSHBUTTON params RADIOBUTTON params RTEXT params SCROLLBAR params STATE3 params USERBUTTON "string".] id. type BEG items END POPUP "string". [data] ["name".y [data] ICON ["name". id MENUITEM "string". helpid [data] [data] is optional BEG (string|number) [. x. y.(string|number)] (etc) END id FONT memflags "filename" memflags defaults to MOVEABLE|DISCARDABLE id ICON memflags "filename" memflags defaults to MOVEABLE|DISCARDABLE LANGUAGE num.] id.] id.w.w. type.w. exstyle params: ["name". id BEG items END POPUP "string".y. class. x.y. x.y. class. helpid [data] CTEXT params DEFPUSHBUTTON params EDITTEXT params GROUPBOX params HEDIT params ICON ["name". x. id. w. y.] id.state] POPUP "string" BEG items END POPUP "string". y. style.Cygwin User's Guide 81 / 82 CONTROL ["name".h. state [. type [. id.exstyle] [data] CONTROL ["name". x.] id. w.h. exstyle.y.y.h. id. id. style [.num id MENU options BEG items END items: "string". h. style. style.] id.] 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". h. exstyle.h [. exstyle. style. w. x.] id. x.
(string|number)] (etc) END id VERSIONINFO stuffs BEG verblocks END stuffs: FILEVERSION num.num PRODUCTVERSION num.num VERSIONK num memflags are MOVEABLE/FIXED PURE/IMPURE PRELOAD/LOADONCALL DISCARDABLE .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".(string|number)] (etc) END STRINGTABLE suboptions BEG strings END strings: id "string" id.num.Cygwin User's Guide 82 / 82 id RCDATA suboptions BEG (string|number) [.num. "string" (User data) id id suboptions BEG (string|number) [."bar" vertrans: VALUE num.num.num suboptions: memflags CHARACTERISTICS num LANGUAGE num.