Table of Contents
This chapter explains some key differences between the Cygwin environment and traditional UNIX systems. It assumes a working knowledge of standard UNIX commands.
Cygwin supports both POSIX- and Win32-style paths. Directory delimiters may be either forward slashes or backslashes. Paths using backslashes or starting with a drive letter 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.
The usage of Win32 paths, though possible, is deprecated, since it circumvents important internal path handling mechanisms. See the section called “Using native Win32 paths” and the section called “Using the Win32 file API in Cygwin applications” 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
Because many programs written to run on UNIX systems assume the existence 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.
/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
and the name of the file is the Cygwin username of the user, as it's
created from the Windows account database or stored in the
/etc/passwd file (see
the section called “Mapping Windows accounts to POSIX accounts”). The structure of the
user specific file is identical to the system-wide
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
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. So it
doesn't matter if you write
FAT into this field even if
the filesystem is NTFS. Cygwin figures out the filesystem type and its
capabilities by itself.
The only exception is the file system type cygdrive. This type is used to set the cygdrive prefix. For a description of the cygdrive prefix see the section called “The cygdrive path 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. The list of the options, including their meaning, 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, for instance) 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). sparse - Switch on support for sparse files. This option only makes sense on NTFS and then only if you really need sparse files. Cygwin does not try to create sparse files by default for performance reasons. 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, .lnk) are
assumed to be executable. Files whose first two characters are "#!", "MZ",
or ":\n" are also considered to be executable.
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 "magic" bytes. The
cygexec option is very similar to
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.
by default also automatic mount points generated by the Cygwin DLL similar
to the way the root directory is evaluated.
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
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).
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, don't store POSIX permissions in ACLs:
//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
Remount /var to /usr/var:
/var /usr/var none bind
/var points to
also points to
C:/cygwin/var. This is equivalent
to the Linux
bind option available since
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
/, then Cygwin would translate
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 invoke the Cygwin tool mount without arguments:
Example 3.1. Displaying the current set of mount points
mountf:/cygwin/bin on /usr/bin type ntfs (binary,auto) f:/cygwin/lib on /usr/lib type ntfs (binary,auto) f:/cygwin on / type ntfs (binary,auto) e:/src on /usr/src type vfat (binary) c: on /cygdrive/c type ntfs (binary,posix=0,user,noumount,auto) e: on /cygdrive/e type vfat (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 stored in memory, these mount points will disappear as soon as your last Cygwin process ends. See mount(1) and umount(1) for more information.
Apart from the unified POSIX tree starting at the
directory, UNC pathnames starting with two slashes and a server name
//machine/share/...) are supported as well.
They are handled as POSIX paths if only containing forward slashes. There's
also a virtual directory
// which allows to enumerate
the fileservers known to the local machine with ls.
Same goes for the UNC paths of the type
which allow to enumerate the shares provided by the server
machine. For often used UNC paths it makes sense to
add them to the mount table (see the section called “The Cygwin Mount Table” so
they are included in the unified POSIX path tree.
As already outlined in the section called “File Access”, you can
access arbitary drives on your system by using the cygdrive path prefix.
The default value for this prefix is
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
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
The cygdrive prefix flags are also used for all UNC paths starting with
two slashes, unless they are accessed through a mount point. For instance,
//server/share /mysrv ntfs posix=1,acl 0 0 none /cygdrive cygdrive posix=0,noacl 0 0
Assume there's a file
\\server\share\foo on the
share. When accessing it as
/mysrv/foo, then the flags
posix=1,acl of the /mysrv mount point are used. When
accessing it as
//server/share/foo, then the flags
for the cygdrive prefix,
posix=0,noacl are used.
This only applies to UNC paths using forward slashes. When using backslashes the flags for native paths are used. See the section called “Using native Win32 paths”.
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
To simplify scripting, Cygwin also provides a
/proc/cygdrive symlink, which allows to use a fixed path
in scripts, even if the actual cygdrive prefix has been changed, or is different
between different users. So, in scripts, conveniently use the
/proc/cygdrive symlink to successfully access files
independently from the current cygdrive prefix:
$ mount -p Prefix Type Flags /mnt user binmode $ cat > x.sh <<EOF cd /proc/cygdrive/c/Windows/System32/Drivers/etc ls -l hosts EOF $ sh -c ./x.sh -rwxrwx---+ 1 SYSTEM SYSTEM 826 Sep 4 22:43 hosts
Symbolic links are not present and supported on Windows until Windows
Vista/Server 2008, and then only on some filesystems. Since POSIX applications
are rightfully expecting to use symlinks and the
symlink(2) system call, Cygwin had to find a
workaround for this Windows flaw.
Cygwin creates symbolic links potentially in multiple different ways:
The default symlinks are plain files containing a magic cookie followed by the path to which the link points. They are marked with the DOS SYSTEM attribute so that only files with that attribute have to be read to determine whether or not the file is a symbolic link.
Starting with Cygwin 1.7, symbolic links are using UTF-16 to encode the filename of the target file, to better support internationalization. Symlinks created by older Cygwin releases can be read just fine. However, 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 the section called “Potential Problems when using Locales”). Please note that this new UTF-16 style of symlinks is not compatible with older Cygwin release, which can't read the target filename correctly.
The shortcut style symlinks are Windows
shortcut files with a special header and the DOS READONLY attribute set.
This symlink type is created if the environment variable
CYGWIN (see the section called “The
is set to contain the string
winsymlinks:lnk. On the MVFS filesystem, which does
not support the DOS SYSTEM attribute, this is the one and only supported
symlink type, independently from the
Native Windows symlinks are only created on Windows Vista/2008 and later,
and only on filesystems supporting reparse points. Due to to their weird
restrictions and behaviour, they are only created if the user
explicitely requests creating them. This is done by setting the
CYGWIN to contain the string
winsymlinks:nativestrict. For the difference between
these two settings, see the section called “The
On AFS, native symlinks are the only supported type of symlink due to
AFS lacking support for DOS attributes. This is independent from the
On the NFS filesystem, Cygwin always creates real NFS symlinks.
All of the above four symlink types are recognized and used as symlinks under all circumstances. However, if the default plain file symlink type is lacking its DOS SYSTEM bit, or if the shortcut file is lacking the DOS READONLY attribute, they are not recognized as symlink.
Apart from these four types, there's also a fifth type, which is recognized as symlink but never generated by Cygwin, directory junctions. This is an older reparse point type, supported by Windows since Windows 2000. Filesystem junctions on the other hand are not handled as symlinks, since otherwise they would not be recognized as filesystem borders by commands like find -xdev.
Using native Win32 paths in Cygwin, while possible, is generally inadvisable. Those paths circumvent all internal integrity checking and bypass the information given in the Cygwin mount table.
The following paths are treated as native Win32 paths in Cygwin:
All paths starting with a drive specifier
All paths containing at least one backslash as path component
UNC paths using backslashes
When accessing files using native Win32 paths as above, Cygwin uses a default setting for the mount flags. All paths using DOS notation will be treated as case insensitive, and permissions are just faked as if the underlying drive is a FAT drive. This also applies to NTFS and other filesystems which usually are capable of case sensitivity and storing permissions.
Special care must be taken if your application uses Win32 file API
CreateFile to access files using
relative pathnames, or if your application uses functions like
to start other applications.
When a Cygwin application is started, the Windows idea of the current working directory (CWD) is not necessarily the same as the Cygwin CWD. There are a couple of restrictions in the Win32 API, which disallow certain directories as Win32 CWD:
The Windows subsystem only supports CWD paths of up to 258 chars. This restriction doesn't apply for Cygwin processes, at least not as long as they use the POSIX API (chdir, getcwd). This means, if a Cygwin process has a CWD using an absolute path longer than 258 characters, the Cygwin CWD and the Windows CWD differ.
The Win32 API call to set the current directory,
SetCurrentDirectory, fails for directories for which
the user has no permissions, even if the user is an administrator. This
restriction doesn't apply for Cygwin processes, if they are running under
an administrator account.
SetCurrentDirectory does not support
Last, but not least,
work on virtual Cygwin paths like /proc or /cygdrive. These paths only
exists in the Cygwin realm so they have no meaning to a native Win32
As long as the Cygwin CWD is usable as Windows CWD, the Cygwin and Windows CWDs are in sync within a process. However, if the Cygwin process changes its working directory into one of the directories which are unusable as Windows CWD, we're in trouble. If the process uses the Win32 API to access a file using a relative pathname, the resulting absolute path would not match the expectations of the process. In the worst case, the wrong files are deleted.
To workaround this problem, Cygwin sets the Windows CWD to a special
directory in this case. This special directory points to a virtual
filesystem within the native NT namespace (
Since it's not a real filesystem, the deliberate effect is that a call to,
CreateFile ("foo", ...); will fail,
as long as the processes CWD doesn't work as Windows CWD.
So, in general, don't use the Win32 file API in Cygwin applications.
If you really need to access files using
the Win32 API, or if you really have to use
CreateProcess to start applications, rather than
exec(3) family of functions, you have to
make sure that the Cygwin CWD is set to some directory which is valid as
The cygpath program provides the ability to translate between Win32 and POSIX pathnames in shell scripts. See cygpath(1) for the details.
LD_LIBRARY_PATH environment variables are automatically
converted from Win32 format to POSIX format (e.g. from
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
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).