diff options
Diffstat (limited to 'winsup/doc/pathnames.sgml')
| -rw-r--r-- | winsup/doc/pathnames.sgml | 272 |
1 files changed, 272 insertions, 0 deletions
diff --git a/winsup/doc/pathnames.sgml b/winsup/doc/pathnames.sgml new file mode 100644 index 000000000..2338b18ff --- /dev/null +++ b/winsup/doc/pathnames.sgml @@ -0,0 +1,272 @@ +<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> |