273 lines
12 KiB
Plaintext
273 lines
12 KiB
Plaintext
<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<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.</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\></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:
|
|
|
|
<example><title>POSIX-like mount setup</title>
|
|
<screen>
|
|
<prompt>C:\></prompt> <userinput>mount c:\Cygnus\CygwinRoot /</userinput>
|
|
<prompt>C:\></prompt> <userinput>mount c:\ /c</userinput>
|
|
<prompt>C:\></prompt> <userinput>mount d:\ /d</userinput>
|
|
<prompt>C:\></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:\></prompt> <userinput>mount c:\ \</userinput>
|
|
<prompt>C:\></prompt> <userinput>mount d:\foo /foo</userinput>
|
|
<prompt>C:\></prompt> <userinput>mount d:\bar /bar</userinput>
|
|
<prompt>C:\></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> <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/tty</filename> and
|
|
<filename>/dev/comX</filename> (the serial ports).
|
|
These devices cannot be seen with the command <command>ls /dev</command>
|
|
although commands such as <command>ls /dev/tty</command> work fine.
|
|
<comment>
|
|
FIXME: Are there other devices under /dev. What about the funny ones
|
|
mounted by default, such as /dev/fd1. What do they really do?
|
|
</comment>
|
|
</para>
|
|
|
|
<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\></prompt> <userinput>ls * </userinput>
|
|
a a.exe b.exe
|
|
<prompt>C:\Cygnus\></prompt> <userinput>ls -i a a.exe</userinput>
|
|
445885548 a 435996602 a.exe
|
|
<prompt>C:\Cygnus\></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>.
|
|
|
|
<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>
|