newlib/winsup/doc/pathnames.sgml

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

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

</sect2>

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

<para>The <command>mount</command> 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
<command>mount</command> utility is very similar to the old DOS
<command>join</command>, in that it makes your drive letters appear as
subdirectories somewhere else.</para>

<para>The mapping is stored in the current user's Cygwin
<FirstTerm>mount table</FirstTerm> 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).</para>

<para>The current user's table is located under
"HKEY_CURRENT_USER/Software/Cygnus Solutions/Cygwin/mounts
v&lt;version&gt;"
where &lt;version&gt; 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.</para>

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

<para>Invoking <command>mount</command> 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
<filename>/d</filename>.  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 <filename>/d</filename> mount is only visible
to the current user.</para>

<example>
<title>Displaying the current set of mount points</title>
<screen>
<prompt>c:\cygnus\&gt;</prompt> <userinput>mount</userinput>
Device           Directory           Type        Flags
D:               /d                  user        textmode
C:               /                   system      textmode
</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.  See <Xref Linkend="mount"> and <Xref Linkend="umount"> for more
information on how to use these utilities to set up your Cygwin POSIX
file system.</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 (see the
<Xref Linkend="mount"> for more information).</para>

<para>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 <Xref Linkend="using-textbinary"> for more
information on text and binary modes.</para>

</sect2>

<sect2><title>Cygwin Mount Table Strategies</title>

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

<example><title>POSIX-like mount setup</title>
<screen>
<prompt>C:\&gt;</prompt> <userinput>mount c:\Cygnus\CygwinRoot /</userinput>
<prompt>C:\&gt;</prompt> <userinput>mount c:\ /c</userinput>
<prompt>C:\&gt;</prompt> <userinput>mount d:\ /d</userinput>
<prompt>C:\&gt;</prompt> <userinput>mount e:\ /cdrom</userinput>
</screen>
</example>

<para>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 <Xref Linkend="cygpath">) can be eliminated:</para>

<example><title>Identity mount setup</title>
<screen>
<prompt>C:\&gt;</prompt> <userinput>mount c:\ /</userinput>
<prompt>C:\&gt;</prompt> <userinput>mount d:\foo /foo</userinput>
<prompt>C:\&gt;</prompt> <userinput>mount d:\bar /bar</userinput>
<prompt>C:\&gt;</prompt> <userinput>mount e:\grill /grill</userinput>
</screen>
</example>

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

</sect2>

<sect2><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"> 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:\cygnus\cygwin-b20\H-i586-cygwin32\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> <title>DOS devices</title>

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

</sect2>

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

<para>Windows NT/W2K/XP additionally support raw devices like floppies,
disks, partitions and tapes.  These are accessed from Cygwin applications
using POSIX device names which are supported in two different ways.
Up to 1.3.3, Cygwin only uses Win32 device names, since 1.3.4
it additionally uses NT internal device names.
</para>

<para>Up to Cygwin 1.3.3 the only way to access those devices is
to mount the Win32 device names to a POSIX device name.
</para>

<para>
The Win32 device name for a partition is the drive letter
with leading <filename>\\.\</filename>, so the floppy would be
<filename>\\.\A:</filename>, the first partition typically
<filename>\\.\C:</filename>. Complete drives (except floppies and CD-ROMS
which are supported as partitions only) are named
<filename>\\.\PHYSICALDRIVEx</filename>. The <literal>x</literal>
is the drive number which you can check in the disk manager.
Each drive line has prepended the text "Disk x".
</para>

<para>To access tape drives the Win32 file name <filename>\\.\TAPEx</filename>
is used. For example the first installed tape device is named
<filename>\\.\tape0</filename>.
</para>

<para>
The naming convention is simple: The name of the POSIX device has to begin with
<filename>/dev/</filename> 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
<literal>n</literal> (rewind) or has to begin with <literal>n</literal>
(no-rewind).
</para>

<para>Some examples:</para>

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

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

<para>
Since Cygwin 1.3.4 raw devices are accessible from inside of Cygwin processes
using fixed POSIX device names.  That means, you don't have to mount the devices
anymore which results in a more cleaner mount table.
</para>

<para>
These new fixed 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.
</para>

<para>The new fixed POSIX names are mapped to NT internal devices as
follows:</para>

<screen>
/dev/st0	\device\tape0, rewind
/dev/nst0	\device\tape0, no-rewind
/dev/st1	\device\tape1
...

/dev/fd0	\device\floppy0
/dev/fd1	\device\floppy1
...

/dev/scd0	\device\cdrom0
/dev/scd1	\device\cdrom1
...

/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/sdl	\device\harddisk11\partition0
/dev/sdl1	\device\harddisk11\partition1
...
/dev/sdl15	\device\harddisk11\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/scd0 /dev/cdrom
ln -s /dev/st0  /dev/tape
...
</screen>

<para>
Note that you can't use the mount table to map from fixed device name
to your own device name or to map from internal NT device name to
your own device name.  The following two examples will not work:
</para>

<screen>
mount -s -f -b /dev/st0 /dev/tape
mount -s -f -b /device/tape0 /dev/tape
</screen>

</sect2>

<sect2><title>The .exe extension</title>

<para> 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.
</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>C:\Cygnus\&gt;</prompt> <userinput>ls * </userinput>
a      a.exe     b.exe
<prompt>C:\Cygnus\&gt;</prompt> <userinput>ls -i a a.exe</userinput>
445885548 a       435996602 a.exe
<prompt>C:\Cygnus\&gt;</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 program
has precedence and is selected for execution of
<command>myprog</command>.</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>

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

<sect2><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><title> Using @pathname</title>
<screen>
<prompt>/Cygnus$</prompt> <userinput>echo  'This   is   "a     long"  line' > mylist</userinput>
<prompt>/Cygnus$</prompt> <userinput>echo @mylist</userinput>
@mylist
<prompt>/Cygnus$</prompt> <userinput>/bin/echo @mylist</userinput>
This is a     long line
<prompt>/Cygnus$</prompt> <userinput>rm mylist</userinput>
<prompt>/Cygnus$</prompt> <userinput>/bin/echo @mylist</userinput>
@mylist
</screen>
</example>
</sect2> 
</sect1>