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