# 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 between Win32 and POSIX paths as necessary.

## The Cygwin Mount Table

The `mount` utility program is used to to map Win32 drives and network shares into Cygwin's internal POSIX directory tree. This is a similar concept to the typical UNIX mount program. For those people coming from a Windows background, the `mount` utility is very similar to the old DOS `join`, in that it makes your drive letters appear as subdirectories somewhere else.

The mapping is stored in the current user's Cygwin mount table in the Windows registry so that the information will be retrieved next time the user logs in. Because it is sometimes desirable to have system-wide as well as user-specific mounts, there is also a system-wide mount table that all Cygwin users inherit. The system-wide table may only be modified by a user with the appropriate priviledges (Administrator priviledges in Windows NT).

The current user's table is located under "HKEY_CURRENT_USER/Software/Cygnus Solutions/Cygwin/mounts v<version>" where <version> is the latest registry version associated with the Cygwin library (this version is not the same as the release number). The system-wide table is located under the same subkeys under HKEY_LOCAL_SYSTEM.

By default, the POSIX root `/` points to the system partition but it can be relocated to any directory in the Windows file system using the `mount` command. Whenever Cygwin generates a POSIX path from a Win32 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`.

Invoking `mount` without any arguments displays Cygwin's current set of mount points. In the following example, the C drive is the POSIX root and D drive is mapped to `/d`. Note that in this case, the root mount is a system-wide mount point that is visible to all users running Cygwin programs, whereas the `/d` mount is only visible to the current user.

### Displaying the current set of mount points

    c:\cygnus\> mount
    Device           Directory           Type        Flags
    D:               /d                  user        textmode
    C:               /                   system      textmode

You can also use the `mount` command to add new mount points, and the `umount` to delete them. See mount and umount for more information on how to use these utilities to set up your Cygwin POSIX file system.

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 (see the mount for more information).

It is possible to assign some special attributes to each mount point. Automatically mounted partitions are displayed as "auto" mounts. Mounts can also be marked as either "textmode" or "binmode" -- whether text files are read in the same manner as binary files by default or not (see using-textbinary for more information on text and binary modes.

## Cygwin Mount Table Strategies

Which set of mounts is right for a given Cygwin user depends largely on how closely you want to simulate a POSIX environment, whether you mix Windows and Cygwin programs, and how many drive letters you are using. If you want to be very POSIX-like (assuming "CygwinRoot" is the top directory of your Cygwin distribution), you may want to do something like this:

### POSIX-like mount setup

    C:\> mount c:\Cygnus\CygwinRoot /
    C:\> mount c:\ /c
    C:\> mount d:\ /d
    C:\> mount e:\ /cdrom

However, if you mix Windows and Cygwin programs a lot, you might want to create an "identity" mapping, so that conversions between the two (see cygpath) can be eliminated:

### Identity mount setup

    C:\> mount c:\ /
    C:\> mount d:\foo /foo
    C:\> mount d:\bar /bar
    C:\> mount e:\grill /grill

You'd have to repeat this for all top-level subdirectories on all drives, but then you'd always have the top-level directories available as the same names in both systems.

## Additional Path-related Information

The `cygpath` program provides the ability to translate between Win32 and POSIX pathnames in shell scripts. See 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:\cygnus\cygwin-b20\H-i586-cygwin32\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).

## Special filenames

## DOS devices

Windows filenames invalid under Windows are also invalid under Cygwin. This means that base filenames such as `AUX`, `COM1`, `LPT1` or `PRN` (to name a few) cannot be used in a regular Cygwin Windows or POSIX path, even with an extension (`prn.txt`). However the special names can be used as filename extensions (`file.aux`). You can use the special names as you would under DOS, for example you can print on your default printer with the command `cat filename > PRN` (make sure to end with a Form Feed).

## POSIX devices

There is no need to create a POSIX `/dev` directory as it is simulated within Cygwin automatically. It supports the following devices: `/dev/null`, `/dev/zero`, `/dev/tty`, `/dev/ttyX`, `/dev/ptmx`, `/dev/comX` (the serial ports), `/dev/windows` (the windows message queue), `/dev/random` and `/dev/urandom`. These devices cannot be seen with the command `ls /dev` although commands such as `ls /dev/tty` work fine.

However, on Windows NT/W2K there are different devices which are supported but have to be created as mount points. These are the raw block special devices and tape devices. These devices need a special handling which is enabled through the mount points. The usage of the native Windows device names is not sufficent.

NT/W2K supports raw block special device support for partitions and drives. The device names for partitions is the drive letter with leading `\\.\`, so the floppy would be `\\.\A:`, the first partition typically `\\.\C:`. Complete drives (except floppies which are supported as partitions only) are named `\\.\PHYSICALDRIVEx`. The `x` is the drive number which you can check in the disk manager. Each drive line has prepended the text "Disk x".

To access tape drives, NT/W2K uses the file name `\\.\TAPEx`. For example the first installed tape device is named `\\.\tape0`.

To access those devices you have to mount them and you have to use the posix name of the device to be recognized by Cygwin. The naming convention is simple: The name has to begin with `/dev/` and the rest is as you like. The only exception are tape devices. To identify if the tape device is used as a rewind or a no-rewind device the name must not begin with `n` (rewind) or has to begin with `n` (no-rewind).

Some examples:

    mount -b //./A: /dev/fd0              # mount floppy as raw block special
    mount -b //./physicaldrive1 /dev/hdb  # mount "Disk 1"
    mount -b //./tape0 /dev/st0           # mount first tape as the rewind device...
    mount -b //./tape0 /dev/nst0          # ...and as the no-rewind device

Note the usage of the `-b` option. It is best to include the -b option when mounting these devices to ensure that all file I/O is in "binary mode".

## The .exe extension

Executable program filenames end with .exe but the .exe need not be included in the command, so that traditional UNIX names can be used. However, for programs that end in ".bat" and ".com", you cannot omit the extension.

As a side effect, the `ls filename` gives information about `filename.exe` if `filename.exe` exists and `filename` does not. In the same situation the function call `stat("filename",..)` gives information about `filename.exe`. The two files can be distinguished by examining their inodes, as demonstrated below.

    C:\Cygnus\> ls *
    a      a.exe     b.exe
    C:\Cygnus\> ls -i a a.exe
    445885548 a       435996602 a.exe
    C:\Cygnus\> ls -i b b.exe
    432961010 b       432961010 b.exe

If a shell script `myprog` and a program `myprog.exe` coexist in a directory, the program has precedence and is selected for execution of `myprog`.

The `gcc` compiler produces an executable named `filename.exe` when asked to produce `filename`. This allows many makefiles written for UNIX systems to work well under Cygwin.

Unfortunately, the `install` and `strip` commands do distinguish between `filename` and `filename.exe`. They fail when working on a non-existing `filename` even if `filename.exe` exists, thus breaking some makefiles. This problem can be solved by writing `install` and `strip` shell scripts to provide the extension ".exe" when needed.

## The @pathnames

To circumvent the limitations on shell line length in the native Windows command shells, Cygwin programs expand their arguments starting with "@" in a special way. If a file `pathname` exists, the argument `@pathname` expands recursively to the content of `pathname`. Double quotes can be used inside the file to delimit strings containing blank space. Embedded double quotes must be repeated. In the following example compare the behaviors of the bash built-in `echo` and of the program `/bin/echo`.

### Using @pathname

    /Cygnus$ echo  'This   is   "a     long"  line' > mylist
    /Cygnus$ echo @mylist
    @mylist
    /Cygnus$ /bin/echo @mylist
    This is a     long line
    /Cygnus$ rm mylist
    /Cygnus$ /bin/echo @mylist
    @mylist