1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
|
<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/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\></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>
|