path: root/winsup/doc/pathnames.sgml

<sect1 id="using-pathnames"><title>Mapping path names</title>

<sect2 id="pathnames-intro"><title>Introduction</title>

<para>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.</para>

<para>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 <filename>/disk2</filename> directory).</para>

<para>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.</para>

</sect2>

<sect2 id="mount-table"><title>The Cygwin Mount Table</title>

<para>The <filename>/etc/fstab</filename> 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 <filename>/etc/fstab</filename> 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 <filename>/etc/fstab.d</filename>
and the name of the file is the Cygwin username of the user, as it's
stored in the <filename>/etc/passwd</filename> file.  The content of the
user specifc file is identical to the system-wide
<filename>fstab</filename> file.</para>

<para>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.</para>

<para>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 <literal>'\040'</literal>.</para>

<para>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'.</para>

<para>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.</para>

<para>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.</para>

<screen>
  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).
</screen>

<para>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 <literal>exec</literal> option is used to instruct Cygwin that the
mounted file is "executable".  If the <literal>exec</literal> 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
<literal>cygexec</literal> option is very similar to <literal>exec</literal>,
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 <literal>notexec</literal> option, which
means that no files should be marked as executable under that mount point.
</para>

<para>Note that nouser mount points are not overridable by a later call
to <command>mount</command>.  This is only possible for user mount points. 
Mount points given in <filename>/etc/fstab</filename> 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.</para>

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

<para>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).</para>

<para>Example entries:</para>

<itemizedlist spacing="compact">
<listitem>
  <para>Just a normal mount point:</para>
  <screen>c:/foo /bar fat32 binary 0 0</screen>
</listitem>
<listitem>
  <para>A mount point for a managed, textmode mount:</para>
  <screen>C:/foo /bar/baz ntfs text,managed 0 0</screen>
</listitem>
<listitem>
  <para>A mount point for a Windows directory with spaces in it:</para>
  <screen>C:/Documents\040and\040Settings /docs ext3 binary 0 0</screen>
</listitem>
<listitem>
  <para>A mount point for a remote directory:</para>
  <screen>//server/share/subdir /srv/subdir smbfs binary 0 0</screen>
</listitem>
<listitem>
  <para>This is just a comment:</para>
  <screen># This is just a comment</screen>
</listitem>
<listitem>
  <para>Set the cygdrive prefix to /mnt:</para>
  <screen>none /mnt cygdrive binary 0 0</screen>
</listitem>
</itemizedlist>

<para>Whenever Cygwin generates a Win32 path from a POSIX one, it uses
the longest matching prefix in the mount table.  Thus, if
<filename>C:</filename> is mounted as <filename>/c</filename> and also
as <filename>/</filename>, then Cygwin would translate
<filename>C:/foo/bar</filename> to <filename>/c/foo/bar</filename>.
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.
</para>

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

<example id="pathnames-mount-ex">
<title>Displaying the current set of mount points</title>
<screen>
<prompt>bash$</prompt> <userinput>mount</userinput>
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)
</screen>
</example>

<para>You can also use the <command>mount</command> command to add
new mount points, and the <command>umount</command> 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 <xref linkend="mount"></xref> and <xref linkend="umount"></xref> for more
information.</para>

<para>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 <filename>/cygdrive</filename>.  For example, if Cygwin accesses
<filename>Z:/foo</filename> and the Z drive is not currently in the
mount table, then <filename>Z:/</filename> would be automatically
converted to <filename>/cygdrive/Z</filename>.  The default
prefix of <filename>/cygdrive</filename> may be changed in the fstab file
as outlined above.</para>

</sect2>

<sect2 id="pathnames-additional"><title>Additional Path-related Information</title>

<para>The <command>cygpath</command> program provides the ability to
translate between Win32 and POSIX pathnames in shell scripts. See
<xref linkend="cygpath"></xref> for the details.</para>

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

<para>Symbolic links can also be used to map Win32 pathnames to POSIX.
For example, the command
<command>ln -s //pollux/home/joe/data /data</command> would have about
the same effect as creating a mount point from
<filename>//pollux/home/joe/data</filename> to <filename>/data</filename>
using <command>mount</command>, 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).</para>

</sect2>

</sect1>

<sect1 id="using-specialnames"><title>Special filenames</title>

<sect2 id="pathnames-dosdevices">
<title>DOS devices</title>

<para>Filenames invalid under Win32 are not necessarily invalid
under Cygwin since release 1.7.0.  There are a couple of rules which
apply to Windows filenames.  First of all, DOS device names like
<filename>AUX</filename>, <filename>COM1</filename>,
<filename>LPT1</filename> or <filename>PRN</filename> (to name a few)
cannot be used in a native Win32 application, even with an
extension (<filename>prn.txt</filename>).  Cygwin can handle files with
these names just fine.</para>

</sect2>

<sect2 id="pathnames-specialchars">
<title>Special characters in filenames</title>

<para>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 does
only affect native Win32 applications.  Cygwin applications can create and
access files with trailing dots and spaces without problems.</para>

<para>Some characters are disallowed in filenames on Windows filesystems:</para>

<screen>
  "   *   :   &lt;   &gt;   ?   |   \
</screen>

<para>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.</para>

</sect2>

<sect2 id="pathnames-casesensitive">
<title>Case sensitive filenames</title>

<para>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 <filename>Abc</filename> and
<filename>aBc</filename>.  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 is not supported by Cygwin,
unless you change that registry value.</para>

<para>If you really want case-sensitivity in Cygwin, you can switch it
on by setting the registry value</para>

<screen>
HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\kernel\obcaseinsensitive
</screen>

<para>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.</para>

<note>
<para>
Note that 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.
</para>
</note>

<para>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!</para>

<para>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.</para>

<para>For a start, it might be best to switch the cygdrive path to
case-insensitivity, because the default Windows $PATH variable is not
always using the correct case by default.  As a result, your shell will
claim that it can't find Windows commands like <command>attrib</command>
or <command>net</command>.  Here's an example how you can switch the
cygdrive prefix to case-insensitivity:</para>

<example id="mount-caseinsensitive">
<title>Example mount point to enforce case-insensitivity on cygdrive paths</title>
<screen>
none /cygdrive cygdrive binary,posix=0 0 0
</screen>
</example>

<para>Note that mount points as well as device names and virtual
paths like /proc are always case-sensitive!  The only exception are
the subdirs and filenames under /proc/registry, /proc/registry32
and /proc/registry64.  Registry access is always case-insensitive.
Read on for more information.</para>

</sect2>

<sect2 id="pathnames-posixdevices"> <title>POSIX devices</title>
<para>There is no need to create a POSIX <filename>/dev</filename> 
directory as Cygwin automatically simulates it internally. 
These devices cannot be seen with the command <command>ls /dev/</command>
although commands such as <command>ls /dev/tty</command> work fine.
If you want to be able to see all devices in
<filename>/dev/</filename>, you can use Igor Pechtchanski's
<ulink
url="http://cygwin.com/ml/cygwin/2004-03/txt00028.txt">create_devices.sh</ulink>
script.
</para>

<para>
Cygwin supports the following character devices commonly found on POSIX systems:
</para>

<screen>
/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.
</screen>

<para>
Cygwin also has several Windows-specific devices:
</para>

<screen>
/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.
</screen>

<para>
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
to the POSIX /dev namespace is as follows:
</para>

<screen>
/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
</screen>

<para>
if you don't like these device names, feel free to create symbolic
links as they are created on Linux systems for convenience:
</para>

<screen>
ln -s /dev/sr0 /dev/cdrom
ln -s /dev/nst0 /dev/tape
...
</screen>

</sect2>

<sect2 id="pathnames-exe"><title>The .exe extension</title>

<para>Win32 executable filenames end with <filename>.exe</filename>
but the <filename>.exe</filename> need not be included in the command,
so that traditional UNIX names can be used.  However, for programs that
end in <filename>.bat</filename> and <filename>.com</filename>, you
cannot omit the extension.  </para>

<para>As a side effect, the <command> ls filename</command> gives
information about <filename>filename.exe</filename> if
<filename>filename.exe</filename> exists and <filename>filename</filename>
does not.  In the same situation the function call
<function>stat("filename",..)</function> gives information about
<filename>filename.exe</filename>.  The two files can be distinguished
by examining their inodes, as demonstrated below.
<screen>
<prompt>bash$</prompt> <userinput>ls * </userinput>
a      a.exe     b.exe
<prompt>bash$</prompt> <userinput>ls -i a a.exe</userinput>
445885548 a       435996602 a.exe
<prompt>bash$</prompt> <userinput>ls -i b b.exe</userinput>
432961010 b       432961010 b.exe
</screen>
If a shell script <filename>myprog</filename> and a program
<filename>myprog.exe</filename> coexist in a directory, the shell
script has precedence and is selected for execution of
<command>myprog</command>.  Note that this was quite the reverse up to
Cygwin 1.5.19.  It has been changed for consistency with the rest of Cygwin.
</para>

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

</sect2>

<sect2 id="pathnames-proc"><title>The /proc filesystem</title> 
<para>
Cygwin, like Linux and other similar operating systems, supports the
<filename>/proc</filename> virtual filesystem. The files in this
directory are representations of various aspects of your system,
for example the command <userinput>cat /proc/cpuinfo</userinput> 
displays information such as what model and speed processor you have.
</para>
<para>
One unique aspect of the Cygwin <filename>/proc</filename> filesystem
is <filename>/proc/registry</filename>, see next section.
</para>
<para>
The Cygwin <filename>/proc</filename> is not as complete as the
one in Linux, but it provides significant capabilities. The
<systemitem>procps</systemitem> package contains several utilities
that use it.
</para>
</sect2>

<sect2 id="pathnames-proc-registry"><title>The /proc/registry filesystem</title>
<para>
The <filename>/proc/registry</filename> filesystem provides read-only
access to the Windows registry.  It displays each <literal>KEY</literal>
as a directory and each <literal>VALUE</literal> 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
<filename>/proc/registry32</filename> and <filename>/proc/registry64</filename>.
They are identical to <filename>/proc/registry</filename> on 32 bit
host OSes.  On 64 bit host OSes, <filename>/proc/registry32</filename>
opens the 32 bit processes view on the registry, while
<filename>/proc/registry64</filename> opens the 64 bit processes view.
</para>
<para>
Reserved characters ('/', '\', ':', and '%') or reserved names
(<filename>.</filename> and <filename>..</filename>) are converted by
percent-encoding:
<screen>
<prompt>bash$</prompt> <userinput>regtool list -v '\HKEY_LOCAL_MACHINE\SYSTEM\MountedDevices'</userinput>
...
\DosDevices\C: (REG_BINARY) = cf a8 97 e8 00 08 fe f7
...
<prompt>bash$</prompt> <userinput>cd /proc/registry/HKEY_LOCAL_MACHINE/SYSTEM</userinput>
<prompt>bash$</prompt> <userinput>ls -l MountedDevices</userinput>
...
-r--r----- 1 Admin SYSTEM  12 Dec 10 11:20 %5CDosDevices%5CC%3A
...
<prompt>bash$</prompt> <userinput>od -t x1 MountedDevices/%5CDosDevices%5CC%3A</userinput>
0000000 cf a8 97 e8 00 08 fe f7 01 00 00 00
</screen>
The unnamed (default) value of a key can be accessed using the filename
<filename>@</filename>.
</para>
<para>
If a registry key contains a subkey and a value with the same name
<filename>foo</filename>, Cygwin displays the subkey as
<filename>foo</filename> and the value as <filename>foo%val</filename>.
</para>
</sect2>

<sect2 id="pathnames-at"><title>The @pathnames</title> 
<para>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
<filename>pathname</filename> exists, the argument
<filename>@pathname</filename> expands recursively to the content of
<filename>pathname</filename>. 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
<command>echo</command> and of the program <command>/bin/echo</command>.</para>

<example id="pathnames-at-ex"><title> Using @pathname</title>
<screen>
<prompt>bash$</prompt> <userinput>echo  'This   is   "a     long"  line' > mylist</userinput>
<prompt>bash$</prompt> <userinput>echo @mylist</userinput>
@mylist
<prompt>bash$</prompt> <userinput>cmd</userinput>
<prompt>c:\&gt;</prompt> <userinput>c:\cygwin\bin\echo @mylist</userinput>
This is a     long line
</screen>
</example>
</sect2> 
</sect1>