diff options
Diffstat (limited to 'winsup/doc/pathnames.sgml')
-rw-r--r-- | winsup/doc/pathnames.sgml | 379 |
1 files changed, 0 insertions, 379 deletions
diff --git a/winsup/doc/pathnames.sgml b/winsup/doc/pathnames.sgml deleted file mode 100644 index 5ab09e472..000000000 --- a/winsup/doc/pathnames.sgml +++ /dev/null @@ -1,379 +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 from POSIX to Win32 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 privileges (Administrator privileges 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. The user mount table takes precedence over -the system-wide table if a path is mounted in both. This includes the -setting of the cygdrive prefix.</para> - -<para>The <command>mount</command> command can set the POSIX root -<filename>/</filename> to any directory in the Windows file system. -In absence of such a mount, Cygwin maps <filename>/</filename> to the -root of the current Windows working directory (for example, -<filename>H:\</filename> or <filename>\\computer\share</filename>). -Normally Cygwin's <command>setup.exe</command> creates the initial -mount point for the POSIX root. -</para> - -<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>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:\></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. See <xref linkend="mount"></xref> and <xref linkend="umount"></xref> 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"></xref> 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"></xref> for more -information on text and binary modes.</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"></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> <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 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 devices commonly found on POSIX systems: -<filename>/dev/dsp</filename>, <filename>/dev/null</filename>, -<filename>/dev/zero</filename>, <filename>/dev/console</filename>, -<filename>/dev/tty</filename>, <filename>/dev/ttym</filename>, -<filename>/dev/ttyX</filename>, <filename>/dev/ttySX</filename>, -<filename>/dev/pipe</filename>, <filename>/dev/port</filename>, -<filename>/dev/ptmx</filename>, <filename>/dev/mem</filename>, -<filename>/dev/random</filename>, and <filename>/dev/urandom</filename>. -Some other POSIX devices, such as -<filename>/dev/kmem</filename>, are planned for development. -Cygwin also has several Windows-specific devices: -<filename>/dev/comX</filename> (the serial ports, starting with -<filename>COM1</filename> which is the same as <filename>ttyS0</filename>), -<filename>/dev/conin</filename> (Windows <filename>CONIN$</filename>), -<filename>/dev/conout</filename> (Windows <filename>CONOUT$</filename>), -<filename>/dev/clipboard</filename> (the Windows clipboard, currently -text only), and <filename>/dev/windows</filename> (the Windows message -queue). -</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. -</para> - -<para>Up to Cygwin 1.3.3 the only way to access those devices was -to mount the Win32 device names to a POSIX device name but this usage -is discouraged since Cygwin 1.3.4 and only kept for backward compatibility. -</para> - -<para> -Beginning with Cygwin 1.3.4, raw devices are accessible by Cygwin processes -using fixed POSIX device names. These 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/sr0 \device\cdrom0 -/dev/sr1 \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/nst0 /dev/tape -... -</screen> - -<warning> -<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. Also using symbolic links to map from the internal -NT device name to your own device name will not do what you want. -The following three examples will not work as expected: -</para> - -<screen> -mount -f -b /dev/nst0 /dev/tape # DOES NOT WORK -mount -f -b /device/tape0 /dev/tape # DOES NOT WORK -ln -s /device/tape0 /dev/tape # DOES NOT WORK -</screen> -</warning> - -</sect2> - -<sect2><title>The .exe extension</title> - -<para> Executable program 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>C:\></prompt> <userinput>ls * </userinput> -a a.exe b.exe -<prompt>C:\></prompt> <userinput>ls -i a a.exe</userinput> -445885548 a 435996602 a.exe -<prompt>C:\></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> - -<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 /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>, which displays the Windows -registry with 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. -</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><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>bash$</prompt> <userinput>echo 'This is "a long" line' > mylist</userinput> -<prompt>bash$</prompt> <userinput>echo @mylist</userinput> -@mylist -<prompt>c:\></prompt> <userinput>c:\cygwin\bin\echo @mylist</userinput> -This is a long line -</screen> -</example> -</sect2> -</sect1> |