Mapping path names Introduction 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. Note that the usage of Win32 paths, though possible, is deprecated, since it circumvents important internal path handling mechanisms. 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 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). cygexec - Treat all files below mount point as cygwin executables. exec - Treat all files below mount point as executable. 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. posix=1 - Switch on case sensitivity for paths under this mount point (default). 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 entry for the root directory is not necessary. If it's wrong, nothing will work as expected. Therefore, the root directory evaluated by Cygwin itself is treated as an immutable mount point and can't be overridden in /etc/fstab... unless you think you really know what you're doing. In this case, use the override flag in the options field in the /etc/fstab file. Since this is a dangerous thing to do, do so at your own risk. /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. /usr/bin points to the directory the Cygwin DLL is installed in, /usr/lib is supposed to point to the /lib directory. This choice is safe and usually shouldn't be changed. An fstab entry for them is not required. nouser mount points are not overridable by a later call to mount. Mount points given in /etc/fstab are by default nouser mount points, unless you specify the option user. This allows the administrator to set certain paths so that they are not overridable by users. 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 textmode mount with case sensitivity switched off: C:/foo /bar/baz ntfs text,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,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 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: Displaying the current set of mount points bash$ mount f:/cygwin/bin on /usr/bin type system (binary,auto) f:/cygwin/lib on /usr/lib type system (binary,auto) f:/cygwin on / type system (binary,auto) e:/src on /usr/src type system (binary) c: on /cygdrive/c type user (binary,posix=0,user,noumount,auto) e: on /cygdrive/e type user (binary,posix=0,user,noumount,auto) 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 and for more information. When you upgrade an existing older Cygwin installation to Cygwin 1.7, 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. Note that entries for /, /usr/bin, and /usr/lib are never generated. The old user mount points in your HKEY_CURRENT_USER branch of the registry are not used to generate /etc/fstab. If you want to create a user specific /etc/fstab.d/${USER} file from your old entries, there's a script available which does exactly that for you, bin/copy-user-registry-fstab. Just start the script and it will create your user specific fstab file. Stop all your Cygwin processes and restart them, and you can simply use your old user mount points as before. The cygdrive path prefix As already outlined in , you can access arbitary drives on your system by using the cygdrive path prefix. The default value for this prefix is /cygdrive, and a path to any drive can be constructed by using the cygdrive prefix and appending the drive letter as subdirectory, like this: bash$ ls -l /cygdrive/f/somedir This lists the content of the directory F:\somedir. The cygdrive prefix is a virtual directory under which all drives on a system are subsumed. The mount options of the cygdrive prefix is used for all file access through the cygdrive prefixed drives. For instance, assuming the cygdrive mount options are binary,posix=0, then any file /cygdrive/x/file will be opened in binary mode by default (mount option binary, 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. Please note that you must not use the cygdrive prefix for any other mount point. For instance this: 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. If you want to mount any drive explicitly in another mode than the cygdrive prefix, use a distinct path prefix: none /cygdrive cygdrive binary 0 0 D: /mnt/d somefs text 0 0 Additional Path-related Information The cygpath program provides the ability to translate between Win32 and POSIX pathnames in shell scripts. See 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). Special filenames Special files in /etc Certain files in Cygwin's /etc directory are read by Cygwin before the mount table has been established. The list of files is /etc/fstab /etc/fstab.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. For that reason there are a few requirements as far as /etc is concerned. To access these files, the Cygwin DLL evaluates it's own full Windows path, strips off the innermost directory component and adds "\etc". Let's assume the Cygwin DLL is installed as C:\cygwin\bin\cygwin1.dll. First the DLL name as well as the innermost directory (bin) is stripped off: C:\cygwin\. Then "etc" and the filename to look for is attached: C:\cygwin\etc\fstab. So the /etc directory must be parallel to the directory in which the cygwin1.dll exists and /etc must not be a Cygwin symlink pointing to another directory. Consequentially none of the files from the above list, including the directory /etc/fstab.d is allowed to be a Cygwin symlink either. However, 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. Last but not least, make sure that these files are world-readable. Every process of any user account has to read these files potentially, so world-readability is essential. The only exception are the user specific files /etc/fstab.d/$USER, which only have to be readable by the $USER user account itself. Invalid filenames Filenames invalid under Win32 are not necessarily invalid under Cygwin since release 1.7.0. There are a few rules which apply to Windows filenames. Most notably, DOS device names like AUX, COM1, LPT1 or PRN (to name a few) cannot be used as filename or extension in a native Win32 application. So filenames like prn.txt or foo.aux are invalid filenames for native Win32 applications. This restriction doesn't apply to Cygwin applications. Cygwin can create and access files with such names just fine. Just don't try to use these files with native Win32 applications. Forbidden characters in filenames Win32 filenames can't contain trailing dots and spaces for backward compatibility. When trying to create files with trailing dots or spaces, all of them are removed before the file is created. This restriction only affects native Win32 applications. Cygwin applications can create and access files with trailing dots and spaces without problems. Some characters are disallowed in filenames on Windows filesystems: " * : < > ? | \ Cygwin can't fix this, but it has a method to workaround this restriction. All of the above characters, except for the backslash, are converted to special UNICODE characters in the range 0xf000 to 0xf0ff (the "Private use area") when creating or accessing files. Filenames with unusual (foreign) characters Windows filesystems use the Unicode character set in the UTF-16 encoding to store filename information. If you don't use the UTF-8 character set (see ) 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. For instance, there are no Chinese characters in the ISO-8859-1 character set. So, converting a filename containing a Chinese character to ISO-8859-1 leaves you with a wrongly converted filename, for instance, containing a question mark '?' as replacement for the unconvertable character. When trying to access the file, Cygwin has to convert the filename back to UTF-16. However, this doesn't result in the original filename because the question mark will not translate back to the original Chinese character, but to a simple question mark instead. This in turn results in strange "File not found" messages. In the default "C" locale, Cygwin creates filenames using the UTF-8 charset. This will always result in some valid filename by default, but again might impose problems when switching to a non-"C" or non-"UTF-8" charset. To avoid this scenario altogether, always use UTF-8 as the character set. If you don't want or can't use UTF-8 as character set for whatever reason, you will nevertheless be able to access the file. How does that work? When Cygwin converts the filename from UTF-16 to your character set, it recognizes characters which can't be converted. If that occurs, Cygwin replaces the non-convertible character with a special character sequence. The sequence starts with an ASCII CAN character (hex code 0x18, equivalent Control-X), followed by the UTF-8 representation of the character. The result is a filename containing some ugly looking characters. While it doesn't look nice, it is nice, because Cygwin knows how to convert this filename back to UTF-16. The filename will be converted using your usual character set. However, when Cygwin recognizes an ASCII CAN character, it skips over the ASCII CAN and handles the following bytes as a UTF-8 character. Thus, the filename is symmetrically converted back to UTF-16 and you can access the file. Please be aware that this method is not entirely foolproof. In some character set combinations it might not work for certain native characters. Only by using the UTF-8 charset you can avoid this problem safely. Case sensitive filenames In the Win32 subsystem filenames are only case-preserved, but not case-sensitive. You can't access two files in the same directory which only differ by case, like Abc and aBc. While NTFS (and some remote filesystems) support case-sensitivity, the NT kernel starting with Windows XP does not support it by default. Rather, you have to tweak a registry setting and reboot. For that reason, case-sensitivity can not be supported by Cygwin, unless you change that registry value. If you really want case-sensitivity in Cygwin, you can switch it on by setting the registry value HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\kernel\obcaseinsensitive to 0 and reboot the machine. For least surprise, Cygwin expects this registry value also on Windows NT4 and Windows 2000, which usually both don't know this registry key. If you want case-sensitivity on these systems, 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, rather stopping all Cygwin processes and then restarting them is sufficient. When installing Microsoft's Services For Unix (SFU), you're asked if you want to use case-sensitive filenames. If you answer "yes" at this point, the installer will change the aforementioned registry value to 0, too. So, if you have SFU installed, there's some chance that the registry value is already set to case sensitivity. After you set this registry value to 0, Cygwin will be case-sensitive by default on NTFS and NFS filesystems. Be aware that using two filenames which only differ by case might result in some weird interoperability issues with native Win32 applications. You're using case-sensitivity at your own risk. You have been warned! Even if you use case-sensitivity, 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). You can do this on a per-mount point base, by using the "posix=0" mount option in /etc/fstab, or your /etc/fstab.d/$USER file. /cygdrive paths are case-insensitive by default. The reason is that the native Windows %PATH% environment variable is not always using the correct case for all paths in it. As a result, if you use case-sensitivity on the /cygdrive prefix, your shell might claim that it can't find Windows commands like attrib or net. To ease the pain, 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 to switch it to case-sensitivity, or you have to make sure that the native Win32 %PATH% environment variable is using the correct case for all paths throughout. 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, /proc/registry32 and /proc/registry64. Registry access is always case-insensitive. Read on for more information. POSIX devices There is no need to create a POSIX /dev directory as Cygwin automatically simulates it internally. These devices cannot be seen with the command ls /dev/ although commands such as ls /dev/tty work fine. If you want to be able to see all well-known devices in /dev/, you can use Igor Pechtchanski's create_devices.sh script. This script does not add the raw disk devices, though. Again, it's not necessary to see an existing device in /dev to access it. The script is just for the fun of it. Cygwin supports the following character devices commonly found on POSIX systems: /dev/null /dev/zero /dev/full /dev/console Pseudo device name for the standard console window created by Windows. Same as the one used for cmd.exe. Every one of them has this name. It's not quite comparable with the console device on UNIX machines. /dev/tty The current tty of a session running in a pseudo tty. /dev/ptmx Pseudo tty master device. /dev/ttym /dev/tty0 Pseudo ttys are numbered from /dev/tty0 upwards as they are /dev/tty1 requested. ... /dev/ttyS0 Serial communication devices. ttyS0 == Win32 COM1, /dev/ttyS1 ttyS1 == COM2, etc. ... /dev/pipe /dev/fifo /dev/mem The physical memory of the machine. Note that access to the /dev/port physical memory has been restricted with Windows Server 2003. /dev/kmem Since this OS, you can't access physical memory from user space. /dev/kmsg Kernel message pipe, for usage with sys logger services. /dev/random Random number generator. /dev/urandom /dev/dsp Default sound device of the system. Cygwin also has several Windows-specific devices: /dev/com1 The serial ports, starting with COM1 which is the same as ttyS0. /dev/com2 Please use /dev/ttySx instead. ... /dev/conin Same as Windows CONIN$. /dev/conout Same as Windows CONOUT$. /dev/clipboard The Windows clipboard, text only /dev/windows The Windows message queue. Block devices are accessible by Cygwin processes using fixed POSIX device names. These POSIX device names are generated using a direct conversion from the POSIX namespace to the internal NT namespace. E.g. the first harddisk is the NT internal device \device\harddisk0\partition0 or the first partition on the third harddisk is \device\harddisk2\partition1. The first floppy in the system is \device\floppy0, the first CD-ROM is \device\cdrom0 and the first tape drive is \device\tape0. The mapping from physical device to the name of the device in the internal NT namespace can be found in various places. For hard disks and CD/DVD drives, the Windows "Disk Management" utility (part of the "Computer Management" console) shows that the mapping of "Disk 0" is \device\harddisk0. "CD-ROM 2" is \device\cdrom2. Another place to find this mapping is the "Device Management" console. Disks have a "Location" number, tapes have a "Tape Symbolic Name", etc. Unfortunately, the places where this information is found is not very well-defined. For external disks (USB-drives, CF-cards in a cardreader, etc) you can use Cygwin to show the mapping. /proc/partitions contains a list of raw drives known to Cygwin. The df command shows a list of drives and their respective sizes. If you match the information between /proc/partitions and the df output, you should be able to figure out which external drive corresponds to which raw disk device name. Apart from tape devices which are not block devices and are by default accessed directly, 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. 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, for the device, and for you. So, please, handle this ability with care. You have been warned. Last but not least, the mapping from POSIX /dev namespace to internal NT namespace is as follows: POSIX device name Internal NT device name /dev/st0 \device\tape0, rewind /dev/nst0 \device\tape0, no-rewind /dev/st1 \device\tape1 /dev/nst1 \device\tape1 ... /dev/st15 /dev/nst15 /dev/fd0 \device\floppy0 /dev/fd1 \device\floppy1 ... /dev/fd15 /dev/sr0 \device\cdrom0 /dev/sr1 \device\cdrom1 ... /dev/sr15 /dev/scd0 \device\cdrom0 /dev/scd1 \device\cdrom1 ... /dev/scd15 /dev/sda \device\harddisk0\partition0 (whole disk) /dev/sda1 \device\harddisk0\partition1 (first partition) ... /dev/sda15 \device\harddisk0\partition15 (fifteenth partition) /dev/sdb \device\harddisk1\partition0 /dev/sdb1 \device\harddisk1\partition1 [up to] /dev/sddx \device\harddisk127\partition0 /dev/sddx1 \device\harddisk127\partition1 ... /dev/sddx15 \device\harddisk127\partition15 if you don't like these device names, 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 ... The .exe extension Win32 executable 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. bash$ ls * a a.exe b.exe bash$ ls -i a a.exe 445885548 a 435996602 a.exe bash$ 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 shell script has precedence and is selected for execution of myprog. Note that this was quite the reverse up to Cygwin 1.5.19. It has been changed for consistency with the rest of Cygwin. 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. The /proc filesystem Cygwin, like Linux and other similar operating systems, supports the /proc virtual filesystem. The files in this directory are representations of various aspects of your system, for example the command cat /proc/cpuinfo displays information such as what model and speed processor you have. One unique aspect of the Cygwin /proc filesystem is /proc/registry, see next section. The Cygwin /proc is not as complete as the one in Linux, but it provides significant capabilities. The procps package contains several utilities that use it. The /proc/registry filesystem The /proc/registry filesystem provides read-only access to the Windows registry. It displays each KEY as a directory and each VALUE as a file. As anytime you deal with the Windows registry, use caution since changes may result in an unstable or broken system. There are additionally subdirectories called /proc/registry32 and /proc/registry64. They are identical to /proc/registry on 32 bit host OSes. On 64 bit host OSes, /proc/registry32 opens the 32 bit processes view on the registry, while /proc/registry64 opens the 64 bit processes view. Reserved characters ('/', '\', ':', and '%') or reserved names (. and ..) are converted by percent-encoding: bash$ regtool list -v '\HKEY_LOCAL_MACHINE\SYSTEM\MountedDevices' ... \DosDevices\C: (REG_BINARY) = cf a8 97 e8 00 08 fe f7 ... bash$ cd /proc/registry/HKEY_LOCAL_MACHINE/SYSTEM bash$ ls -l MountedDevices ... -r--r----- 1 Admin SYSTEM 12 Dec 10 11:20 %5CDosDevices%5CC%3A ... 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 @. If a registry key contains a subkey and a value with the same name foo, Cygwin displays the subkey as foo and the value as foo%val. 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 bash$ echo 'This is "a long" line' > mylist bash$ echo @mylist @mylist bash$ cmd c:\> c:\cygwin\bin\echo @mylist This is a long line