Chapter 3. Using Cygwin

Table of Contents

Mapping path names
Introduction
The Cygwin Mount Table
Additional Path-related Information
Text and Binary modes
The Issue
The default Cygwin behavior
Example
Binary or text?
Programming
File permissions
Special filenames
DOS devices
Special characters in filenames
Case sensitive filenames
POSIX devices
The .exe extension
The /proc filesystem
The /proc/registry filesystem
The @pathnames
The CYGWIN environment variable
Implemented options
Removed options
Cygserver
What is Cygserver?
Cygserver command line options
How to start Cygserver
How to use the Cygserver services
The Cygserver configuration file
Cygwin Utilities
cygcheck
cygpath
dumper
getfacl
kill
mkgroup
mkpasswd
mount
passwd
ps
regtool
setfacl
ssp
strace
umount
Using Cygwin effectively with Windows
Pathnames
Console Programs
Cygwin and Windows Networking
The cygutils package
Creating shortcuts with cygutils
Printing with cygutils

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

Introduction

Cygwin supports both Win32- and POSIX-style paths, where directory delimiters may be either forward or back slashes. UNC pathnames (starting with two slashes and a network name) are also supported.

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 content of the user specifc 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'.

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 noticable 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.
  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.
  binary   - Files default to binary mode (default).
  text     - Files default to CRLF text mode line endings.
  nouser   - Mount is a system-wide mount.
  user     - Mount is a user mount.
  exec     - Treat all files below mount point as executable.
  notexec  - Treat all files below mount point as not executable.
  cygexec  - Treat all files below mount point as cygwin executables.
  nosuid   - No suid files are allowed (currently unimplemented).
  posix=0  - Switch off case sensitivity for paths under this mount point.
  posix=1  - Switch on case sensitivity for paths under this mount point
	     (default).

Normally, 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.

Note that nouser mount points are not overridable by a later call to mount. This is only possible for user mount points. Mount points given in /etc/fstab are by default nouser mount points, unless you specify the option user. In contrast, all mount points in the user specific fstab file are user mount points.

The fifth and sixth field are ignored. They are so far only specified to keep a Linux-like fstab file layout.

Note that you don't have to specify an fstab entry for the root dir, unless you want to have the root dir pointing to somewhere entirely different (hopefully you know what you're doing), or if you want to mount the root dir with special options (for instance, as text mount).

Example entries:

  • Just a normal mount point:

    c:/foo /bar fat32 binary 0 0
  • A mount point for a managed, textmode mount:

    C:/foo /bar/baz ntfs text,managed 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:

    //server/share/subdir /srv/subdir smbfs binary 0 0
  • This is just a comment:

    # This is just a comment
  • Set the cygdrive prefix to /mnt:

    none /mnt cygdrive binary 0 0

Whenever Cygwin generates a Win32 path from a POSIX one, it uses the longest matching prefix in the mount table. Thus, if C: is mounted as /c and also as /, then Cygwin would translate C:/foo/bar to /c/foo/bar. This translation is normally only used when trying to derive the POSIX equivalent current directory. Otherwise, the handling of MS-DOS filenames bypasses the mount table.

If you want to see the current set of mount points valid in your session, you can invoking the Cygwin tool mount without arguments:

Example 3.1. Displaying the current set of mount points

bash-3.2$ mount
f:/cygwin/bin on /usr/bin type system (binmode)
f:/cygwin/lib on /usr/lib type system (binmode)
f:/cygwin on / type system (binmode)
e:/src on /usr/src type system (binmode)
c: on /cygdrive/c type user (binmode,noumount)
e: on /cygdrive/e type user (binmode,noumount)

You can also use the mount command to add new mount points, and the umount to delete them. However, since they are only noted in memory, these mount points will disappear as soon as your last Cygwin process ends. See the section called “mount” and the section called “umount” for more information.

Whenever Cygwin cannot use any of the existing mounts to convert from a particular Win32 path to a POSIX one, Cygwin will automatically default to an imaginary mount point under the default POSIX path /cygdrive. For example, if Cygwin accesses Z:/foo and the Z drive is not currently in the mount table, then Z:/ would be automatically converted to /cygdrive/Z. The default prefix of /cygdrive may be changed in the fstab file as outlined above.

Additional Path-related Information

The cygpath program provides the ability to translate between Win32 and POSIX pathnames in shell scripts. See the section called “cygpath” for the details.

The HOME, PATH, and LD_LIBRARY_PATH environment variables are automatically converted from Win32 format to POSIX format (e.g. from c:/cygwin\bin to /bin, if there was a mount from that Win32 path to that POSIX path) when a Cygwin process first starts.

Symbolic links can also be used to map Win32 pathnames to POSIX. For example, 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, except that symbolic links cannot set the default file access mode. 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. Note that symbolic links will only work on network drives that are properly configured to support the "system" file attribute. Many do not do so by default (the Unix Samba server does not by default, for example).