libs/newlib-cygwin
libs
/
newlib-cygwin
mirror of git://sourceware.org/git/newlib-cygwin.git
4
0
Fork 0
Code Issues Projects Releases Wiki Activity

* Revamp documentation for Cygwin 1.7, part 1.

This commit is contained in:
Corinna Vinschen 2008-07-17 11:49:45 +00:00
parent b2dab9e8bc
commit 85f1119b7b
16 changed files with 908 additions and 746 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
winsup/doc/ChangeLog
View File

@ -1,3 +1,7 @@
2008-07-17 Corinna Vinschen <corinna@vinschen.de>
* Revamp documentation for Cygwin 1.7, part 1.
2008-07-01 Christopher Faylor <me+cygwin@cgf.cx> 2008-07-01 Christopher Faylor <me+cygwin@cgf.cx>
* Makefile.in: Temporarily add ability to generate pdfs. * Makefile.in: Temporarily add ability to generate pdfs.

31
winsup/doc/cygserver.sgml
View File

@ -41,6 +41,7 @@
</para> </para>
<itemizedlist spacing="compact"> <itemizedlist spacing="compact">
<listitem>
<screen>-f, --config-file &lt;file&gt;</screen> <screen>-f, --config-file &lt;file&gt;</screen>
<para> <para>
Use &lt;file&gt; as configuration file instead of the default configuration Use &lt;file&gt; as configuration file instead of the default configuration
@ -52,6 +53,7 @@
This option has no counterpart in the configuration file, for obvious This option has no counterpart in the configuration file, for obvious
reasons. reasons.
</para> </para>
</listitem>
<listitem> <listitem>
<screen>-c, --cleanup-threads &lt;num&gt;</screen> <screen>-c, --cleanup-threads &lt;num&gt;</screen>
<para> <para>
@ -96,8 +98,7 @@
<screen>-y, --syslog</screen> <screen>-y, --syslog</screen>
<para> <para>
Force logging to the system log. This is the default, if stderr is not Force logging to the system log. This is the default, if stderr is not
connected to a tty, e. g. redirected to a file. Note, that on 9x/Me connected to a tty, e. g. redirected to a file.
systems the syslog is faked by a file C:\CYGWIN_SYSLOG.TXT.
Configuration file option: kern.log.syslog Configuration file option: kern.log.syslog
</para> </para>
</listitem> </listitem>
@ -143,8 +144,8 @@
<screen>-S, --shutdown</screen> <screen>-S, --shutdown</screen>
<para> <para>
Shutdown a running daemon and exit. Other methods are sending a SIGHUP Shutdown a running daemon and exit. Other methods are sending a SIGHUP
to the Cygserver PID or, if running as service under NT, calling to the Cygserver PID or, if running as service, calling `net stop
`net stop cygserver' or `cygrunsrv -E cygserver'. cygserver' or `cygrunsrv -E cygserver'.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
@ -168,22 +169,16 @@
<para> <para>
Before you run Cygserver for the first time, you should run the Before you run Cygserver for the first time, you should run the
/usr/bin/cygserver-config script once. It creates the default /usr/bin/cygserver-config script once. It creates the default
configuration file and, upon request, installs Cygserver as service configuration file and, upon request, installs Cygserver as service.
when running under NT. The script only performs a default install, The script only performs a default install, with no further options
with no further options given to Cygserver when running as service. given to Cygserver when running as service. Due to the wide
Due to the wide configurability by changing the configuration file, configurability by changing the configuration file, that's typically
that's typically not necessary. not necessary.
</para> </para>
<para> <para>
On Windows 9x/Me, just start Cygserver in any console window. It's You should always run Cygserver as a service under LocalSystem account.
advisable to redirect stderr to a file of choice (e. g. This is the way it is installed for you by the /usr/bin/cygserver-config
/var/log/cygserver.log) and to use the -e and -Y options or the script.
set the appropriate settings in the configuration file (see below).
</para>
<para>
On Windows NT/2000/XP or 2003, you should always run Cygserver as a
service under LocalSystem account. This is the way it is installed
for you by the /usr/bin/cygserver-config script.
</para> </para>
</sect2> </sect2>

6
winsup/doc/cygwin-ug.in.sgml
View File

@ -1,10 +1,12 @@
<?xml version="1.0"?> <?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"[ <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"[
<!ENTITY cygnus-copyright "<year>1999,2000,2001</year> <!ENTITY cygnus-copyright "<year>1999,2000,2001,2002,2003,2004,2005,2006,2007,2008</year>
<holder>Red Hat, Inc.</holder>"> <holder>Red Hat, Inc.</holder>">
<!ENTITY cygnus-code-copyright " <!ENTITY cygnus-code-copyright "
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Copyright (C) 1998, 1999, 2000, 2001 Red Hat, Inc. Copyright (C) 1998, 1999, 2000, 2001, 2002,
2003, 2004, 2005, 2006, 2007,
2008 Red Hat, Inc.
This is copyrighted software that may only This is copyrighted software that may only
be reproduced, modified, or distributed be reproduced, modified, or distributed

174
winsup/doc/cygwinenv.sgml
View File

@ -1,10 +1,13 @@
<sect1 id="using-cygwinenv"><title>The <envar>CYGWIN</envar> environment <sect1 id="using-cygwinenv"><title>The <envar>CYGWIN</envar> environment
variable</title> variable</title>
<sect2 id="cygwinenv-implemented-options">
<title>Implemented options</title>
<para>The <envar>CYGWIN</envar> environment variable is used to configure <para>The <envar>CYGWIN</envar> environment variable is used to configure
many global settings for the Cygwin runtime system. It contains the options many global settings for the Cygwin runtime system. It contains the options
listed below, separated by blank characters. Many options can be turned off listed below, separated by blank characters. Many options can be turned off
by prefixing with <literal>no </literal>.</para> by prefixing with <literal>no</literal>.</para>
<itemizedlist mark="bullet"> <itemizedlist mark="bullet">
<listitem> <listitem>
@ -12,7 +15,8 @@ by prefixing with <literal>no </literal>.</para>
(e.g. pipe and COM ports) file opens default to binary mode (e.g. pipe and COM ports) file opens default to binary mode
(no CRLF translation) instead of text mode. Defaults to set (binary (no CRLF translation) instead of text mode. Defaults to set (binary
mode). By default, devices are opened in binary mode, so this option mode). By default, devices are opened in binary mode, so this option
has little effect on normal cygwin operations. has little effect on normal cygwin operations. Sockets are always
in binary mode.
It does affect two things, however. For non-NTFS filesystems, this It does affect two things, however. For non-NTFS filesystems, this
option will control the line endings for standard output/input/error option will control the line endings for standard output/input/error
@ -21,52 +25,28 @@ the default translation mode of a pipe, although most shells set the
pipe to binary by default. pipe to binary by default.
</para> </para>
</listitem> </listitem>
<listitem>
<para><envar>check_case:level</envar> - THIS OPTION IS DEPRECATED.
Don't use it unless you know what you're doing and don't see any way
around it. And even then, this option is error prone, slows down Cygwin
and not well maintained. This option controls the behavior of
Cygwin when a user tries to open or create a file using a case different from
the case of the path as saved on the disk.
<literal>level</literal> is one of <literal>relaxed</literal>,
<literal>adjust</literal> and <literal>strict</literal>.</para>
<itemizedlist mark="bullet">
<listitem>
<para><envar>relaxed</envar> which is the default behaviour simply
ignores case. That's the default for native Windows applications as well.</para>
</listitem>
<listitem>
<para><envar>adjust</envar> behaves mostly invisible. The POSIX input
path is internally adjusted in case, so that the resulting DOS path uses the
correct case throughout. You can see the result when changing the directory
using a wrong case and calling <command>/bin/pwd</command> afterwards.</para>
</listitem>
<listitem>
<para><envar>strict</envar> results in a error message if the case
isn't correct. Trying to open a file <filename>Foo</filename> while a file
<filename>fOo</filename> exists results in a "no such file or directory"
error. Trying to create a file <filename>BAR</filename> while a file
<filename>Bar</filename> exists results in a "Filename exists with different
case" error.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem> <listitem>
<para><envar>codepage:[ansi|oem]</envar> - Windows console <para><envar>codepage:[ansi|oem|utf8]</envar> - This option controls
applications can use different character sets (codepages) for drawing which single- or multibyte character set is used for file and console
characters. The first setting, called "ansi", is the default. operations. Windows is using UTF-16 characters internally and this
This character set contains various forms of latin characters used option specifies how 8-byte character sets are converted to UTF-16 and
in European languages. The name originates from the ANSI Latin1 vice versa. The default setting is <envar>ansi</envar> which means,
(ISO 8859-1) standard, used in Windows 1.0, though the character conversion is based on the current ANSI codepage, typically 1252 in
sets have since diverged from any standard. The second setting many Western language versions of Windows. The name originates from the
selects an older, DOS-based character set, containing various line ANSI Latin1 (ISO 8859-1) standard, used in Windows 1.0, though the
drawing and special characters. It is called "oem" since it was character sets have since diverged from any standard. The second
originally encoded in the firmware of IBM PCs by original setting selects an older, DOS-based character set, containing various
equipment manufacturers (OEMs). If you find that some characters line drawing and special characters. It is called <envar>oem</envar>
(especially non-US or 'graphical' ones) do not display correctly in since it was originally encoded in the firmware of IBM PCs by original
Cygwin, you can use this option to select an appropriate codepage. equipment manufacturers (OEMs).</para>
</para> <para>If you find that some characters (especially non-US or 'graphical' ones)
do not display correctly in Cygwin, you can use this option to select an
appropriate codepage. Finally, <envar>utf8</envar> treats all file names
and console characters as UTF-8 chars. Please note that, for correct
operation, you have to set the environment variable LC_CTYPE to "C-UTF-8"
for the time being. The reason is that newlib's multibyte conversion
functions require this setting.</para>
</listitem> </listitem>
<listitem> <listitem>
@ -77,16 +57,18 @@ path name. Defaults to set.</para>
<listitem> <listitem>
<para><envar>(no)envcache</envar> - If set, environment variable <para><envar>(no)envcache</envar> - If set, environment variable
conversions (between Win32 and POSIX) are cached. Note that this is may conversions (between Win32 and POSIX) are cached. Note that this may
cause problems if the mount table changes, as the cache is not invalidated cause problems if the mount table changes, as the cache is not invalidated
and may contain values that depend on the previous mount table and may contain values that depend on the previous mount table
contents. Defaults to set.</para> contents. Defaults to set.</para>
</listitem> </listitem>
<listitem> <listitem>
<para><envar>(no)export</envar> - If set, the final values of these <para><envar>(no)export</envar> - If set, the final values of these
settings are re-exported to the environment as <envar>CYGWIN</envar> again. settings are re-exported to the environment as <envar>CYGWIN</envar> again.
Defaults to off.</para> Defaults to off.</para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
<envar>error_start:Win32filepath</envar> - if set, runs <envar>error_start:Win32filepath</envar> - if set, runs
@ -98,6 +80,7 @@ usually set to the path to <command>gdb</command> or
There is no default set. There is no default set.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para><envar>forkchunk:32768</envar> - causes the <function>fork()</function> <para><envar>forkchunk:32768</envar> - causes the <function>fork()</function>
to copy memory some number of bytes at a time, in the above example to copy memory some number of bytes at a time, in the above example
@ -106,12 +89,14 @@ possible, which is preferable in most cases but may slow some older systems
down. down.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para><envar>proc_retry:n</envar> - causes the <function>fork()</function> and <function>exec*()</function> <para><envar>proc_retry:n</envar> - causes the <function>fork()</function> and <function>exec*()</function>
to retry n times when a child process fails due to certain windows-specific errors. These errors usually to retry n times when a child process fails due to certain windows-specific errors. These errors usually
occur when processes are being started while a user is logging off. occur when processes are being started while a user is logging off.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para><envar>(no)glob[:ignorecase]</envar> - if set, command line arguments <para><envar>(no)glob[:ignorecase]</envar> - if set, command line arguments
containing UNIX-style file wildcard characters (brackets, question mark, containing UNIX-style file wildcard characters (brackets, question mark,
@ -122,40 +107,13 @@ Default is set.</para>
<para>This option also accepts an optional <literal>[no]ignorecase</literal> modifer. <para>This option also accepts an optional <literal>[no]ignorecase</literal> modifer.
If supplied, wildcard matching is case insensitive. The default is <literal>noignorecase</literal></para> If supplied, wildcard matching is case insensitive. The default is <literal>noignorecase</literal></para>
</listitem> </listitem>
<listitem>
<para><envar>(no)ntea</envar> - if set, use NT Extended Attributes to
store UNIX-like inode information.
This option only operates under Windows NT. Defaults to not set.
Only FAT and NTFS support Extended Attributes, not FAT32, so it's
of no use there. Furthermore, on NTFS partitions ntsec, which provides
real permissions, overrides ntea, which only provides faked permissions.
So setting ntea only makes sense if you either have FAT partitions,
or if you switch off ntsec explicitely. </para>
<warning><title>Warning!</title> <para>This may create additional
<emphasis>large</emphasis> files on FAT partitions.</para></warning>
</listitem>
<listitem>
<para><envar>(no)ntsec</envar> - if set, use the NT security
model to set UNIX-like permissions on files and processes. The
file permissions can only be set on NTFS partitions. FAT/FAT32 don't
support the NT file security. Defaults to set. For more information, read
the documentation in <xref linkend="ntsec"></xref>.</para>
</listitem>
<listitem>
<para><envar>(no)smbntsec</envar> - if set, use <envar>ntsec</envar> on remote
drives as well (default is "nosmbntesc"). When setting "smbntsec" there's
a chance that you get problems with Samba shares so you should use this
option with care. One reason for a non working <envar>ntsec</envar> on
remote drives could be insufficient permissions of the users. The requires
user rights are somewhat dangerous (SeRestorePrivilege), so it's not always
an option to grant that rights to users. However, this shouldn't be a
problem in NT domain environments.</para>
</listitem>
<listitem> <listitem>
<para><envar>(no)reset_com</envar> - if set, serial ports are reset <para><envar>(no)reset_com</envar> - if set, serial ports are reset
to 9600-8-N-1 with no flow control when used. This is done at open to 9600-8-N-1 with no flow control when used. This is done at open
time and when handles are inherited. Defaults to set.</para> time and when handles are inherited. Defaults to set.</para>
</listitem> </listitem>
<listitem> <listitem>
<para><envar>(no)server</envar> - if set, allows client applications <para><envar>(no)server</envar> - if set, allows client applications
to use the Cygserver facilities. This option must be enabled explicitely to use the Cygserver facilities. This option must be enabled explicitely
@ -166,18 +124,18 @@ successfully. These function calls will return with
<literal>ENOSYS</literal>, "Bad system call". <literal>ENOSYS</literal>, "Bad system call".
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para><envar>(no)strip_title</envar> - if set, strips the directory <para><envar>(no)strip_title</envar> - if set, strips the directory
part off the window title, if any. Default is not set.</para> part off the window title, if any. Default is not set.</para>
</listitem> </listitem>
<listitem> <listitem>
<para><envar>(no)title</envar> - if set, the title bar <para><envar>(no)title</envar> - if set, the title bar
reflects the name of the program currently running. Default is not reflects the name of the program currently running. Default is not
set. Note that under Win9x the title bar is always enabled and it is set.</para>
stripped by default, but this is because of the way Win9x works. In
order not to strip, specify <literal>title</literal> or <literal>title
nostrip_title</literal>.</para>
</listitem> </listitem>
<listitem> <listitem>
<para><envar>(no)tty</envar> - if set, Cygwin enables extra support <para><envar>(no)tty</envar> - if set, Cygwin enables extra support
(i.e., termios) for UNIX-like ttys in the Windows console. (i.e., termios) for UNIX-like ttys in the Windows console.
@ -190,11 +148,65 @@ and it cannot be changed in the shell. It should not be set when using
other terminals (i.e., rxvt or xterm). other terminals (i.e., rxvt or xterm).
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para><envar>(no)winsymlinks</envar> - if set, Cygwin creates <para><envar>(no)winsymlinks</envar> - if set, Cygwin creates
symlinks as Windows shortcuts with a special header and the R/O attribute symlinks as Windows shortcuts with a special header and the R/O attribute
set. If not set, Cygwin creates symlinks as plain files with a magic number, set. If not set, Cygwin creates symlinks as plain files with a magic number,
a path and the system attribute set. Defaults to set.</para> a path and the system attribute set. Defaults to not set since plain
file symlinks are faster to write and faster to read.</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</sect2>
<sect2 id="cygwinenv-removed-options">
<title>Removed options</title>
<para>
Some CYGWIN options have been removed in Cygwin 1.7 for one reason or another.
These removed options are listed below.</para>
<itemizedlist mark="bullet">
<listitem>
<para><envar>check_case</envar> - This option has been removed in favor of
real case sensitivity and the per-mount option "posix=[0|1]". For more
information, read the documentation in <xref linkend="mount-table"></xref> and
<xref linkend="pathnames-casesensitive"></xref>.</para>
</listitem>
<listitem>
<para><envar>(no)ntea</envar> - This option has been removed since it
only fakes security which is considered dangerous and useless. It also
created an uncontrollably large file on FAT and was entirely useless
on FAT32.</para>
</listitem>
<listitem>
<para><envar>(no)ntsec</envar> - This option has been removed in favor of
the per-mount option "acl"/"noacl". For more information, read the
documentation in <xref linkend="mount-table"></xref>.</para>
</listitem>
<listitem>
<para><envar>(no)smbntsec</envar> - This option has been removed in favor of
the per-mount option "acl"/"noacl". For more information, read the
documentation in <xref linkend="mount-table"></xref>.</para>
</listitem>
<listitem>
<para><envar>(no)transparent_exe</envar> - This option has been removed
because the behaviour it switched on is now the standard behaviour in
Cygwin.</para>
</listitem>
<listitem>
<para><envar>(no)traverse</envar> - This option has been removed because
traverse checking is not quite correctly implemented by Microsoft and
it's behaviour is getting worse with each new OS version.</para>
</listitem>
</itemizedlist>
</sect2>
</sect1> </sect1>

64
winsup/doc/effectively.sgml
View File

@ -18,23 +18,27 @@ support the <literal>/?</literal> switch to display usage information.
<para> <para>
Unfortunately, no standard set of tools included with all versions of Unfortunately, no standard set of tools included with all versions of
Windows exists. If you are unfamiliar with the tools available Windows exists. If you are unfamiliar with the tools available
on your system, here is a general guide. Windows 95, 98, and ME have on your system, here is a general guide. Windows NT 4.0 has only a basic
very limited command-line configuration tools. Windows NT 4.0 has much set of tools, which later versions of Windows expanded.
better coverage, which Windows 2000 and XP expanded.
Microsoft also provides free downloads for Windows NT 4.0 (the Resource Kit Microsoft also provides free downloads for Windows NT 4.0 (the Resource Kit
Support Tools), Windows 2000 (the Resource Kit Tools), and XP (the Support Tools), Windows 2000 (the Resource Kit Tools), and XP (the
Windows Support Tools). Additionally, many independent sites such as Windows Support Tools). Generally, the younger the Windows version, the
<ulink url="http://download.com.com">download.com</ulink>, more complete are the on-board tools. Additionally, many independent sites
such as
<ulink url="http://download.com">download.com</ulink>,
<ulink url="http://simtel.net">simtel.net</ulink>, <ulink url="http://simtel.net">simtel.net</ulink>,
and <ulink url="http://sysinternals.com">sysinternals.com</ulink> and Microsoft's own
provide command-line utilities. A few Windows tools, such as <ulink url="http://technet.microsoft.com/en-us/sysinternals/default.aspx">Sysinternals</ulink>
<command>find.exe</command> and <command>sort.exe</command>, provide quite useful command-line utilities, as far as they are not
may conflict with the Cygwin versions; make sure that you use the full already provided by Cygwin. A few Windows tools, such as
path (<command>/usr/bin/find</command>) or that your Cygwin <command>find.exe</command>, <command>link.exe</command> and
<literal>bin</literal> directory comes first in your <envar>PATH</envar>. <command>sort.exe</command>, may conflict with the Cygwin versions
make sure that you use the full path (<command>/usr/bin/find</command>)
or that your Cygwin <literal>bin</literal> directory comes first in your
<envar>PATH</envar>.
</para> </para>
<sect2> <title>Pathnames</title> <sect2 id="using-pathnames-effectively"> <title>Pathnames</title>
<para> <para>
Windows programs do not understand POSIX pathnames, so any arguments Windows programs do not understand POSIX pathnames, so any arguments
@ -60,15 +64,15 @@ preferable to use <command>cygpath</command> in shell scripts.
</sect2> </sect2>
<sect2> <title>Console Programs</title> <sect2 id="using-console"> <title>Console Programs</title>
<para> <para>
Another issue is receiving output from or giving input to console-based Another issue is receiving output from or giving input to console-based
Windows programs. Unfortunately, interacting with Windows console Windows programs. Unfortunately, interacting with Windows console
applications is not a simple matter of using a translation utility. Windows applications is not a simple matter of using a translation utility. Windows
console applications are designed to run under <command>command.com</command> console applications are designed to run under
or <command>cmd.exe</command>, and some do not deal gracefully with other <command>cmd.exe</command>, and some do not deal gracefully with other
situations. Cygwin can receive console input only if it situations. Cygwin can receive console input only if it
is also running in a console (DOS box) since Windows does not provide is also running in a console window since Windows does not provide
any way to attach to the backend of the console device. Another any way to attach to the backend of the console device. Another
traditional Unix input/output method, ptys (pseudo-terminals), is traditional Unix input/output method, ptys (pseudo-terminals), is
supported by Cygwin but not entirely by Windows. The basic problem is supported by Cygwin but not entirely by Windows. The basic problem is
@ -78,7 +82,7 @@ having their input or output redirected to pipes.
<para> <para>
To help deal with these issues, Cygwin supports customizable levels of To help deal with these issues, Cygwin supports customizable levels of
Windows verses Unix compatibility behavior. To be most compatible with Windows versus Unix compatibility behavior. To be most compatible with
Windows programs, use a DOS prompt, running only the occasional Cygwin Windows programs, use a DOS prompt, running only the occasional Cygwin
command or script. Next would be to run <command>bash</command> within command or script. Next would be to run <command>bash</command> within
a default DOS box. To make Cygwin more Unix compatible in this case, a default DOS box. To make Cygwin more Unix compatible in this case,
@ -92,7 +96,7 @@ but expect some compatibility problems with Windows programs.
</sect2> </sect2>
<sect2> <title>Cygwin and Windows Networking</title> <sect2 id="using-net"> <title>Cygwin and Windows Networking</title>
<para> <para>
Many popular Cygwin packages, such as <systemitem>ncftp</systemitem>, Many popular Cygwin packages, such as <systemitem>ncftp</systemitem>,
<systemitem>lynx</systemitem>, and <systemitem>wget</systemitem>, require a <systemitem>lynx</systemitem>, and <systemitem>wget</systemitem>, require a
@ -111,11 +115,11 @@ of these programs, see if the alternate one works as expected.
<para> <para>
There are a variety of other programs available for specific situations. There are a variety of other programs available for specific situations.
If your system does not have an always-on network connection, you If your system does not have an always-on network connection, you
may be interested in <command>rasdial.exe</command> (or alternatives for may be interested in <command>rasdial.exe</command> for automating dialup
Windows 95, 98, and ME) for automating dialup connections. connections.
Users who frequently change their network Users who frequently change their network
configuration can script these changes with <command>netsh.exe</command> configuration can script these changes with <command>netsh.exe</command>
(Windows 2000 and XP). For proxy users, the open source (Windows 2000 and later). For proxy users, the open source
<ulink url="http://apserver.sourceforge.net"> <ulink url="http://apserver.sourceforge.net">
NTLM Authorization Proxy Server</ulink> or the no-charge NTLM Authorization Proxy Server</ulink> or the no-charge
<ulink url="http://www.hummingbird.com/products/nc/socks/index.html"> <ulink url="http://www.hummingbird.com/products/nc/socks/index.html">
@ -125,15 +129,15 @@ programs in your environment.
</sect2> </sect2>
<sect2><title>The cygutils package</title> <sect2 id="using-cygutils"><title>The cygutils package</title>
<para> <para>
The optional <systemitem>cygutils</systemitem> package contains miscellaneous tools that are The optional <systemitem>cygutils</systemitem> package contains
small enough to not require their own package. It is not included in a miscellaneous tools that are small enough to not require their own package.
default Cygwin install; select it from the Utils category in It is not included in a default Cygwin install; select it from the Utils
<command>setup.exe</command>. Several of the <systemitem>cygutils</systemitem> tools are useful category in <command>setup.exe</command>. Several of the
for interacting with Windows. <systemitem>cygutils</systemitem> tools are useful for interacting with
</para> Windows.</para>
<para> <para>
One of the hassles of Unix-Windows interoperability is the different line One of the hassles of Unix-Windows interoperability is the different line
@ -146,7 +150,7 @@ endings, but <systemitem>cygutils</systemitem> provides several dedicated progra
</para> </para>
</sect2> </sect2>
<sect2><title>Creating shortcuts with cygutils</title> <sect2 id="using-shortcuts"><title>Creating shortcuts with cygutils</title>
<para> <para>
Another problem area is between Unix-style links, which link one file Another problem area is between Unix-style links, which link one file
to another, and Microsoft .lnk files, which provide a shortcut to a to another, and Microsoft .lnk files, which provide a shortcut to a
@ -172,7 +176,7 @@ Windows shortcuts.
</para> </para>
</sect2> </sect2>
<sect2><title>Printing with cygutils</title> <sect2 id="using-printing"><title>Printing with cygutils</title>
<para> <para>
There are several options for printing from Cygwin, including the There are several options for printing from Cygwin, including the
<command>lpr</command> found in <systemitem>cygutils</systemitem> (not to be confused with the <command>lpr</command> found in <systemitem>cygutils</systemitem> (not to be confused with the

41
winsup/doc/filemodes.sgml
View File

@ -1,34 +1,33 @@
<sect1 id="using-filemodes"><title>File permissions</title> <sect1 id="using-filemodes"><title>File permissions</title>
<para>On Windows 9x systems, files are always readable, and Cygwin uses the <para>On FAT or FAT32 filesystems, files are always readable, and Cygwin
native read-only mode to determine if they are writable. Files are uses the DOS read-only attribute to determine if they are writable. Files are
considered to be executable if the filename ends with .bat, .com or .exe, or considered to be executable if the filename ends with .bat, .com or .exe, or
if its content starts with #!. Consequently <command>chmod</command> can if its content starts with #!. Consequently <command>chmod</command> can
only affect the "w" mode, it silently ignores actions involving the other only affect the "w" mode, it silently ignores actions involving the other
modes. This means that <command>ls -l</command> modes. This means that <command>ls -l</command>
needs to open and read files. It can thus be relatively slow.</para> needs to open and read files. It can thus be relatively slow.</para>
<para>Under NT, file permissions default to the same behavior as Windows <para>On NTFS, file permissions are evaluated using the Access Control
9x but there is optional functionality in Cygwin that can make file Lists (ACLs) attached to a file. This can be switched off by using the
systems behave more like on UNIX systems. This is turned on by adding "noacl" option to the respective mount point in the
the "ntea" option to the <envar>CYGWIN</envar> environment variable.</para> <filename>/etc/fstab</filename> or <filename>/etc/fstab.d/$USER</filename>
file. For more information on file permissions, see
<para>When the "ntea" feature is activated, Cygwin will start with basic <!-- TODO: Put the file permission stuff from ntsec here??? -->
permissions as determined above, but can store POSIX file permissions in NT
Extended Attributes. This feature works quite well on NTFS partitions
because the attributes can be stored sensibly inside the normal NTFS
filesystem structure. However, on a FAT partition, NT stores extended
attributes in a flat file at the root of the partition called <filename>EA
DATA. SF</filename>. This file can grow to extremely large sizes if you
have a large number of files on the partition in question, slowing the
system to a crawl. In addition, the <filename>EA DATA. SF</filename> file
can only be deleted outside of Windows because of its "in use" status. For
these reasons, the use of NT Extended Attributes is off by default in
Cygwin. Finally, note that specifying "ntea" in <envar>CYGWIN</envar> has no
effect under Windows 9x. </para>
<para>Under NT, the test "[ -w filename]" is only true if filename is <xref linkend="ntsec"></xref>.
writable across the board, e.g. <command>chmod +w filename</command>. </para> </para>
<!-- TODO -->
<para>On NFS shares, file permissions are exactly the POSIX permissions
transmitted from the server using the NFSv3 protocol, if the NFS client
is the one from Microsoft's "Services For Unix", or the one built into
Windows Vista or later.
</para>
<para>Only the user and group ownership is not necessarily correct.</para>
</sect1> </sect1>

2
winsup/doc/gcc.sgml
View File

@ -6,7 +6,7 @@
Refer to the GCC User's Guide for information on standard usage and Refer to the GCC User's Guide for information on standard usage and
options. Here's a simple example:</para> options. Here's a simple example:</para>
<example> <example id="gcc-hello-world">
<title>Building Hello World with GCC</title> <title>Building Hello World with GCC</title>
<screen> <screen>
<prompt>C:\&gt;</prompt> <userinput>gcc hello.c -o hello.exe</userinput> <prompt>C:\&gt;</prompt> <userinput>gcc hello.c -o hello.exe</userinput>

6
winsup/doc/gdb.sgml
View File

@ -18,7 +18,7 @@ program for debugging. What you need to do is add
<literal>-g</literal> to all the other flags you use when compiling <literal>-g</literal> to all the other flags you use when compiling
your sources to objects.</para> your sources to objects.</para>
<example><title>Compiling with -g</title> <example id="gdb-g"><title>Compiling with -g</title>
<screen> <screen>
<prompt>$</prompt> gcc -g -O2 -c myapp.c <prompt>$</prompt> gcc -g -O2 -c myapp.c
<prompt>$</prompt> gcc -g myapp.c -o myapp <prompt>$</prompt> gcc -g myapp.c -o myapp
@ -57,7 +57,7 @@ at individual variables or what pointers point to.</para>
<command>break</command> command to tell gdb to stop your program when it <command>break</command> command to tell gdb to stop your program when it
gets to a specific function or line number:</para> gets to a specific function or line number:</para>
<example><title>"break" in gdb</title> <example id="gdb-break"><title>"break" in gdb</title>
<screen> <screen>
<prompt>(gdb)</prompt> break my_function <prompt>(gdb)</prompt> break my_function
<prompt>(gdb)</prompt> break 47 <prompt>(gdb)</prompt> break 47
@ -75,7 +75,7 @@ time.</para>
your program. These two cases are the same as far as your program is your program. These two cases are the same as far as your program is
concerned:</para> concerned:</para>
<example><title>Debugging with command line arguments</title> <example id="gdb-cliargs"><title>Debugging with command line arguments</title>
<screen> <screen>
<prompt>$</prompt> myprog -t foo --queue 47 <prompt>$</prompt> myprog -t foo --queue 47

2
winsup/doc/legal.sgml
View File

@ -1,6 +1,6 @@
<legalnotice id="legal"> <legalnotice id="legal">
<para>Copyright &copy; 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 Red Hat, Inc.</para> <para>Copyright &copy; 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Red Hat, Inc.</para>
<!-- <!--

491
winsup/doc/ntsec.sgml
View File

@ -1,123 +1,146 @@
<sect1 id="ntsec"><title>NT security and usage of <literal>ntsec</literal></title> <sect1 id="ntsec"><title>NT security</title>
<para>The setting of UNIX like object permissions is controlled by the <para>The setting of POSIX like object permissions is controlled by the
<link linkend="using-cygwinenv"><envar>CYGWIN</envar> environment <link linkend="mount-table">mount option</link> <literal>(no)acl</literal>
variable</link> setting <literal>(no)ntsec</literal> which is set to which is set to <literal>acl</literal> by default. The design goal
<literal>ntsec</literal> by default.</para> is to utilize the Windows access control API to implement real POSIX
permissions.</para>
<para>The design goal of <literal>ntsec</literal> is to get a more UNIX-like <para>We start with a short overview. Note that this overview must
permission structure based upon the security features of Windows NT. be necessarily short. If you want to learn more about the Windows security
To describe the changes, I will first give a short overview in model, see the <ulink url="http://msdn.microsoft.com/en-us/library/aa374860(VS.85).aspx">Access Control</ulink> article in MSDN documentation.</para>
<xref linkend="ntsec-common"></xref>.
</para>
<para><link linkend="ntsec-processes" endterm="ntsec-processes.title"></link>
discusses the changes in ntsec related to privileges on processes.</para>
<para><link linkend="ntsec-files" endterm="ntsec-files.title"></link> shows
the basics of UNIX-like setting of file permissions.</para>
<para><link linkend="ntsec-sids" endterm="ntsec-sids.title"></link>
talks about using SIDs in <filename>/etc/passwd</filename> and
<filename>/etc/group</filename>.</para>
<para><link linkend="ntsec-mapping" endterm="ntsec-mapping.title"></link>
illustrates the permission mapping leak of Windows NT.</para>
<para><link linkend="ntsec-aclfuncs" endterm="ntsec-aclfuncs.title"></link>
describes in short the ACL API since release 1.1.</para>
<para><link linkend="ntsec-setuid" endterm="ntsec-setuid.title"></link>
describes the new support of a setuid concept introduced with release
1.1.3.</para>
<para><link linkend="ntsec-switch" endterm="ntsec-switch.title"></link>
gives the basics of using the SYSTEM user to switch user context.
</para>
<para><link linkend="ntsec-ids" endterm="ntsec-ids.title"></link>
explains the way Cygwin shows users and groups that are not in
<filename>/etc/passwd</filename> or <filename>/etc/group</filename>.
</para>
<sect2 id="ntsec-common"><title>NT security</title> <sect2 id="ntsec-common"><title>NT security</title>
<para>The NT security allows a process to allow or deny access of <para>In the NT security model, almost any "object" is securable.
different kind to `objects'. `Objects' are files, processes, "Objects" are files, processes, threads, semaphores, etc.</para>
threads, semaphores, etc.</para>
<para>The main data structure of NT security is the `security descriptor' <para>Every object has a data structure called "security descriptor" (SD)
(SD) structure. It explains the permissions, that are granted (or denied) attached. The SD contains all information necessary to control who can
to an object and contains information, that is related to so called how access an object. The SD of an object consists of five parts:</para>
`security identifiers' (SID).</para>
<para>A SID is a unique identifier for users, groups and domains. <itemizedlist spacing="compact">
SIDs are comparable to UNIX UIDs and GIDs, but are more complicated <listitem><para>Flags which control several aspects of this SD. This is
because they are unique across networks. Example:</para> not discussed here.</para></listitem>
<listitem><para>The SID of the object owner.</para></listitem>
<listitem><para>The SID of the object owner group.</para></listitem>
<listitem><para>A list of "Access Control Entries" (ACE), called the
"Discretionary Access Control List" (DACL).</para></listitem>
<listitem><para>Another list of ACEs, called the
"Security Access Control List" (SACL), which doesn't matter for our
purpose.</para></listitem>
</itemizedlist>
<para>SID of a system `foo':</para> <para>Every ACE contains a so-called "Security IDentifier" (SID) and
other stuff which is explained a bit later. Let's talk about the SID first.
</para>
<para>A SID is a unique identifier for users, groups, computers and AD
domains. SIDs are basically comparable to POSIX UIDs and GIDs, but are
more complicated because they are unique across multiple machines or
domains. A SID is a structure of multiple numerical values. There's
a convenient convention to type SIDs. Here's an example:</para>
<para>SID of a machine "foo":</para>
<screen> <screen>
S-1-5-21-165875785-1005667432-441284377 S-1-5-21-165875785-1005667432-441284377
</screen> </screen>
<para>SID of a user `johndoe' of the system `foo':</para> <para>SID of a user "johndoe" of the system "foo":</para>
<screen> <screen>
S-1-5-21-165875785-1005667432-441284377-1023 S-1-5-21-165875785-1005667432-441284377-1023
</screen> </screen>
<para>The above example shows the convention for printing SIDs. The leading <para>The leading "S" has no further meaning except to show that this is
`S' should show that it is a SID. The next number is a version number which a SID. The next number is a version number which is always 1 so far.
is always 1. The next number is the so called `top-level authority' that The next two numbers are the authority which shows the initiated what
identifies the source that issued the SID.</para> kind of SID this is. There are a couple of builtin accounts and
accounts with very special meaning. However, computer and domain SIDs
always start with "S-1-5-21". The next three numbers, all 32 bit values,
are the unique 96 bit identifier of the comupter system. This is
hopefully unique all over the world, but in practice it's sufficient if
the comuter SIDs are unique within a single Windows network.</para>
<para>While each system in a NT network has it's own SID, the situation <para>As you can see in the above example, SIDs of users (and groups)
is modified in NT domains: The SID of the domain controller is the are identical to the computer SID, except for an additional part, the
base SID for each domain user. If an NT user has one account as domain so-called "relative identifier" (RID). So the SID of a user is always
user and another account on his local machine, these accounts are under uniquely attached to the system on which the account has been generated.</para>
any circumstances DIFFERENT, regardless of the usage of the same user
name and password!</para>
<para>SID of a domain `bar':</para> <para>It's a bit different in domains. The domain has its own SID, and
that SID is identical to the SID of the first domain controller, on
which the domain is created. Domain user SIDs look exactly like the
computer user SIDs, the leading part is just the domain SID and the RID
is created when the user is created.</para>
<para>Ok, consider you created a new domain "bar" on some new domain
controller and you would like to create a domain account "johndoe":</para>
<para>SID of a domain "bar.local":</para>
<screen> <screen>
S-1-5-21-186985262-1144665072-740312968 S-1-5-21-186985262-1144665072-740312968
</screen> </screen>
<para>SID of a user `johndoe' in the domain `bar':</para> <para>SID of a user "johndoe" in the domain "bar.local":</para>
<screen> <screen>
S-1-5-21-186985262-1144665072-740312968-1207 S-1-5-21-186985262-1144665072-740312968-1207
</screen> </screen>
<para>The last part of the SID, the so called `relative identifier' (RID), <para>Ok, so you now have two accounts called johndoe, one account
is by default used as UID and/or GID under Cygwin. As the name and the created on the machine "foo", one created in the domain "bar.local".
above example implies, this id is unique only relative to one system or Both have different SIDs and not even the RID is the same. How do
domain.</para> the systems know it's the same account? After all, the name is
the same, right? The answer is, these accounts are NOT identical.
For all the machines know there are two different accounts, one is
"FOO\johndoe", the other one is "BAR\johndoe" or "johndoe@bar.local".
Different SID, different account. Full stop.
</para>
<para>Note, that it's possible that a user has the same RID on two <para>The last part of the SID, the so called "Relative IDentifier" (RID),
different systems. The resulting SIDs are nevertheless different, so is by default used as UID and/or GID under Cygwin when you create the
the SIDs are representing different users in an NT network.</para> <filename>/etc/passwd</filename> and <filename>/etc/group</filename>
files using the <command>mkpasswd</command> and <command>mkgroup</command>
tools. Domain account UIDs and GIDs are offset by 10000 by default
which might be a bit low for very big organizations. Fortunately there's
an option in both tools to change the offset...</para>
<para>There is a big difference between UNIX IDs and NT SIDs: the existence of <para>Do you still remember the SIDs with special meaning? In offical
the so called `well known groups'. For example UNIX has no GID for the notation they are called "well-known SIDs". For example, POSIX has no GID
group of `all users'. NT has an SID for them, called `Everyone' in the for the group of "all users" or "world" or "others". The last three rwx
English versions. The SIDs of well-known groups are not unique across bits in a permission value just represent the permissions for "everyone
an NT network but their meanings are unmistakable. who is not the owner or is member of the owning group". Windows has a
Examples of well-known groups:</para> SID for these poor souls, the "Everyone" SID. Other well-known SIDs
represent more circumstances instead of actual users or groups. Here
are a few examples for well-known SIDs:</para>
<screen> <screen>
everyone S-1-1-0 Everyone S-1-1-0 Simply everyone...
creator/owner S-1-3-0 Batch S-1-5-3 Processes started via the task
batch process (via `at') S-1-5-3 scheduler are member of this group.
authenticated users S-1-5-11 Interactive S-1-5-4 Only processes of users which are
system S-1-5-18 logged in via an interactive
session are members here.
Authenticated Users S-1-5-11 Users which have gone through
the authentication process and
survived. Anonymously accessing
users are not incuded here.
SYSTEM S-1-5-18 A special account which has all
kinds of dangerous rights, sort of
an uber-root account.
</screen> </screen>
<para>The last important group of SIDs are the `predefined groups'. This <para>For a full list please refer to
groups are used mainly on systems outside of domains to simplify the <ulink url="http://msdn.microsoft.com/en-us/library/aa379649.aspx">Well-known SIDs</ulink>.
administration of user permissions. The corresponding SIDs are not unique Naturally well-known SIDs are the same on each machine, so they are
across the network so they are interpreted only locally:</para> not unique to a machine or domain. They have the same meaning across
the Windows network.</para>
<para>Additionally there are a couple of well-known builtin groups,
which have the same SID on every machine and which have certain user
rights by default:</para>
<screen> <screen>
administrators S-1-5-32-544 administrators S-1-5-32-544
@ -126,187 +149,143 @@ guests S-1-5-32-546
... ...
</screen> </screen>
<para>Now, how are permissions given to objects? A process may assign an SD <para>For instance, every account is usually member in the "Users"
to the object. The SD of an object consists of three parts:</para> group. All administrator accounts are member of the "Administrators"
group. That's all about it as far as single machines are involved. In
a domain environment it's a bit more tricky. Since these SIDs are not
unique to a machine, every domain user and every domain group can be a
member of these well known groups. Consider the domain group "Domain
Admins". This group is by default in the "Administrators" group. Let's
assume the above computer called "foo" is a member machine of the domain
"bar.local". If you stick the user "BAR\johndoe" into the group "Domain
Admins", this guy will automatically be a mamber of the administrators
group on "foo", when logging in on "foo". Neat, isn't it?</para>
<para>Back to ACE and ACL. POSIX is able to create three different
permissions, the permissions for the owner, for the group and for the
world. In contrast the Windows ACL has a potentially infinite number of
members... as long as they fit into 64K. Every member is an ACE.
ACE consist of three parts:</para>
<itemizedlist spacing="compact"> <itemizedlist spacing="compact">
<listitem><para>the SID of the owner </para></listitem> <listitem><para>The type of the ACE (allow ACE or deny ACE).</para></listitem>
<listitem><para>the SID of the group </para></listitem> <listitem><para>Permission bits, 32 of them.</para></listitem>
<listitem><para>a list of SIDs with their permissions, called <listitem><para>The SID for which the permissions are allowed or denied.</para></listitem>
`access control list' (ACL) </para></listitem>
</itemizedlist> </itemizedlist>
<para>UNIX is able to create three different permissions, the permissions <para>The two (for us) important types of ACEs are the "access allowed
for the owner, for the group and for the world. In contrast the ACL ACE" and the "access denied ACE". As the names imply, the allow ACE
has a potentially infinite number of members. Every member is a so called tells the system to allow the given permissions to the SID, the deny ACE
`access control element' (ACE). An ACE contains three parts:</para> results in denying the specific permission bits.</para>
<itemizedlist spacing="compact">
<listitem><para>the type of the ACE </para></listitem>
<listitem><para>permissions, described with a DWORD </para></listitem>
<listitem><para>the SID, for which the above mentioned permissions are
set </para></listitem>
</itemizedlist>
<!-- Is the historical note really important here? we're at version 1.5.9, after all.. -->
<para>The two important types of ACEs are the `access allowed ACE' and the
`access denied ACE'. The ntsec functionality only used `access allowed ACEs' up
to Cygwin version 1.1.0. Later versions also use `access denied ACEs'
to reflect the UNIX permissions as well as possible.</para>
<para>The possible permissions on objects are more detailed than in <para>The possible permissions on objects are more detailed than in
UNIX. For example, the permission to delete an object is different POSIX. For example, the permission to delete an object is different
from the write permission.</para> from the permission to change object data, and even changing object data
can be separated into different permission bits for different kind of
<para>With the aforementioned method NT is able to grant or revoke permissions data.</para>
to objects in a far more specific way. But what about cygwin? In a POSIX
environment it would be fine to have the security behavior of a POSIX
system. The NT security model is MOSTLY able to reproduce the POSIX model.
The ntsec method tries to do this in cygwin.</para>
<para>You ask "Mostly? Why mostly???" Because there's a leak in the NT model.
I will describe that in detail in chapter 5.</para>
<para>Creating explicit object security is not that easy so you will often
see only two simple variations in use:</para>
<itemizedlist spacing="compact">
<listitem><para>default permissions, computed by the operating system </para></listitem>
<listitem><para>each permission to everyone </para></listitem>
</itemizedlist>
<para>For parameters to functions that create or open securable objects another
data structure is used, the `security attributes' (SA). This structure
contains an SD and a flag that specifies whether the returned handle
to the object is inherited to child processes or not.
This property is not important for ntsec so in
this document the difference between SDs and SAs is ignored.</para>
</sect2>
<sect2 id="ntsec-processes"><title id="ntsec-processes.title">Process privileges</title>
<para>Any process started under control of Cygwin has a semaphore attached
to it, that is used for signaling purposes. The creation of this semaphore
can be found in sigproc.cc, function `getsem'. The first parameter to the
function call `CreateSemaphore' is an SA. Without ntsec this SA
assigns default security to the semaphore. There is a simple disadvantage:
Only the owner of the process may send signals to it. Or, in other words,
if the owner of the process is not a member of the administrators' group,
no administrator may kill the process! This is especially annoying, if
processes are started via service manager.</para>
<para>Ntsec now assigns an SA to the process control semaphore, that
has each permission set for the user of the process, for the
administrators' group and for `system', which is a synonym for the
operating system itself. The creation of this SA is done by the function
`sec_user', that can be found in `shared.cc'. Each member of the
administrators' group is now allowed to send signals to any process
created in Cygwin, regardless of the process owner.</para>
<para>Moreover, each process now has the appropriate security settings, when
it is started via `CreateProcess'. You will find this in function
`spawn_guts' in module `spawn.cc'. The security settings for starting a
process in another user context have to add the SID of the new user, too.
In the case of the `CreateProcessAsUser' call, sec_user creates an SA with
an additional entry for the sid of the new user.</para>
</sect2> </sect2>
<sect2 id="ntsec-files"><title id="ntsec-files.title">File permissions</title> <sect2 id="ntsec-files"><title id="ntsec-files.title">File permissions</title>
<para>If ntsec is turned on, file permissions are set as in UNIX. An SD is <para>On NTFS and if the <literal>noacl</literal> mount option is not
assigned to the file containing the owner and group and ACEs for the specified for a mount point, Cygwin sets file permissions as in POSIX.
owner, the group and `Everyone'.</para> Basically this is done by defining a SD with the matching owner and group
SIDs, and a DACL which contains ACEs for the owner, the group and for
"Everyone", which represents what POSIX calls "others".</para>
<para>The complete settings of UNIX like permissions can be found in the file <para>To use NT security correctly, Cygwin depends on the files
`security.cc'. The two functions `get_nt_attribute' and `set_nt_attribute'
are the main code. The reading and writing of the SDs is done by the
functions `read_sd' and `write_sd'. `write_sd' uses the function `BackupRead'
instead of the simpler function `SetFileSecurity' because the latter is
unable to set owners different from the caller.</para>
<para>If you are creating a file `foo' outside of Cygwin, you will see something
like the following on <command>ls -ln</command>:</para>
<para>If your login is member of the administrators' group:</para>
<screen>
rwxrwxrwx 1 544 513 ... foo
</screen>
<para>if not:</para>
<screen>
rwxrwxrwx 1 1000 513 ... foo
</screen>
<para>Note the user and group IDs. 544 is the UID of the administrators' group.
This is a `feature' <literal>:-P</literal> of WinNT. If you are a member of
the administrators' group, every file that you create is owned by the
administrators' group, instead of by you.</para>
<para>The second example shows the UID of the first user, that has been
created with NT's the user administration tool. The users and groups are
sequentially numbered, starting with 1000. Users and groups are using the
same numbering scheme, so a user and a group don't share the same ID.</para>
<para>In both examples the GID 513 is of special interest. This GID is a
well known group with different naming in local systems and domains.
Outside of domains the group is named 'None' (`Kein' in German, `Aucun'
in French, etc.), in domains it is named 'Domain Users'. Unfortunately,
the group `None' is never shown in the user admin tool outside of domains!
This is very confusing but this seems to have no negative consequences.</para>
<para>To work correctly, ntsec depends on the files
<filename>/etc/passwd</filename> and <filename>/etc/group</filename>. <filename>/etc/passwd</filename> and <filename>/etc/group</filename>.
In Cygwin release 1.0 the names and the IDs must correspond to the These files define the traslation between the Cygwin uid/gid and the
appropriate NT IDs! The IDs used in Cygwin are the RID of the NT SID, as Windows SID. The SID is stored in the pw_gecos field in
mentioned earlier. <filename>/etc/passwd</filename>, and in the gr_passwd field in
A SID of e.g. the user `corinna' on my NT workstation:</para> <filename>/etc/group</filename>. Since the pw_gecos field can contain
more information than just a SID, there are some rules for the layout.
It's required that the SID is the last entry of the pw_gecos field,
assuming that the entries in pw_gecos are comma-separated. The
commands <command>mkpasswd</command> and <command>mkgroup</command>
usually do this for you.</para>
<para>Another interesting entry in the pw_gecos field (which is also
usually created by running <command>mkpasswd</command>) is the Windows user
name entry. It takes the form "U-domain\username" and is typically used
by services to authenticate a user. Logging in through <command>ssh</command>
or <command>telnet</command> are two typical scenarios.
</para>
<para>A typical snippet from <filename>/etc/passwd</filename>:</para>
<example id="ntsec-passwd">
<title>/etc/passwd:</title>
<screen> <screen>
S-1-5-21-165875785-1005667432-441284377-1000 SYSTEM:*:18:544:,S-1-5-18::
</screen> Administrators:*:544:544:,S-1-5-32-544::
Administrator:unused:500:513:U-FOO\Administrator,S-1-5-21-790525478-115176313-839522115-500:/home/Administrator:/bin/bash
<para>Note the last number: It's the RID 1000, Cygwin's UID.</para> corinna:unused:11001:11125:U-BAR\corinna,S-1-5-21-2913048732-1697188782-3448811101-1001:/home/corinna:/bin/tcsh
<para>Unfortunately, workstations and servers outside of domains are not
able to set primary groups! In these cases, where there is no correlation
of users to primary groups, NT returns 513 (None) as primary group,
regardless of the membership to existing local groups.</para>
<para>When using <command>mkpasswd -l -g</command> on such systems, you
have to change the primary group by hand if `None' as primary group is
not what you want (and I'm sure, it's not what you want!)</para>
<para>Look at the following examples, which were parts of my files before
storing SIDs in /etc/passwd and /etc/group had been introduced (See next
chapter for details). With the exception of my personal user entry, all
entries are well known entries.</para>
<example>
<title>/etc/passwd</title>
<screen>
everyone:*:0:0:::
system:*:18:18:::
administrator::500:544::/home/root:/bin/bash
guest:*:501:546:::
administrators:*:544:544::/home/root:
corinna::1000:547:Corinna Vinschen:/home/corinna:/bin/tcsh
</screen> </screen>
</example> </example>
<example> <para>The SYSTEM entry is usually needed by services. The Administrators
<title>/etc/group</title> entry (Huh? A group in /etc/passwd?) is only here to allow
<command>ls</command> to print some file ownerships correctly. Windows
doesn't care if the owner of a file is a user or a group. In older
versions of Windows NT the default ownership for files created by an
administrator account was set to the group Administrators instead of to
the creating user account. This has changed, but for those older
systems it's convenient to have the Administrators group in
<filename>/etc/passwd</filename>.</para>
<para>The really interesting entries are the next two. The Administrator
entry is for the local administrator, the corinna entry matches the corinna
account in the domain BAR. The information given in the pw_gecos field
are all we need to exactly identify an account, and to have a two way
translation, from Windows account name/SID to Cygwin account name uid and
vice versa. Having this complete information allows us to choose a Cygwin
name and uid which doesn't have to match the Windows account at all. As
long as the pw_gecos information is available, we're on the safe side:</para>
<example id="ntsec-passwd-tweaked">
<title>/etc/passwd, tweaked:</title>
<screen> <screen>
everyone::0: root:unused:0:513:U-FOO\Administrator,S-1-5-21-790525478-115176313-839522115-500:/home/Administrator:/bin/bash
system::18: thursday_next:unused:11001:11125:U-BAR\corinna,S-1-5-21-2913048732-1697188782-3448811101-1001:/home/corinna:/bin/tcsh
none::513:
administrators::544:
users::545:
guests::546:
powerusers::547:
</screen> </screen>
</example> </example>
<para> The above <filename>/etc/passwd</filename> will still work fine.
You can now login via <command>ssh</command> as the user "root", and
Cygwin dutyfully translates "root" into the Windows user
"FOO\Administrators" and files owned by FOO\Administrators are shown to
have the uid 0 when calling <command>ls -ln</command>. All you do you're
actually doing as Administrator. Files created as root will be owned by
FOO\Administrator. And the domain user BAR\corinna can now happily
pretend to be Thursday Next, but will wake up sooner or later finding
out she's still actually the domain user BAR\corinna...</para>
<para>Do I have to mention that you can also rename groups in
<filename>/etc/group</filename>? As long as the SID is present and correct,
all is well. This allows for instance to rename the "Administrators" group
to "root" as well:</para>
<example id="ntsec-group-tweaked">
<title>/etc/group, tweaked:</title>
<screen>
root:S-1-5-32-544:544:
</screen>
</example>
<para>Last but not least you can also change the primary group of a user
in <filename>/etc/passwd</filename>. The only requirement is that the user
is actually a member of the new primary group in Windows. For instance,
normal users in a domain environment are members in the group "Domain Users",
which in turn is member of the well-known group "Users". Additionally let's
assume the user is also a member of the newly created group . The default
primary group for users is
<!-- TODO: The rest of the file... -->
</para>
<para>As you can see, I changed my primary group membership from 513 (None) <para>As you can see, I changed my primary group membership from 513 (None)
to 547 (powerusers). So all files I created inside of Cygwin were now owned to 547 (powerusers). So all files I created inside of Cygwin were now owned
by the powerusers group instead of None. This is the way I liked it.</para> by the powerusers group instead of None. This is the way I liked it.</para>
@ -330,14 +309,6 @@ processes, which are started through service manager.</para>
<sect2 id="ntsec-sids"><title id="ntsec-sids.title">NT SIDs in Cygwin</title> <sect2 id="ntsec-sids"><title id="ntsec-sids.title">NT SIDs in Cygwin</title>
<para>In Cygwin release 1.1 a new technique of using the
<filename>/etc/passwd</filename> and <filename>/etc/group</filename>
was introduced.</para>
<para>Both files may now contain SIDs of users and groups. They
are saved in the last field of pw_gecos in <filename>/etc/passwd</filename>
and in the gr_passwd field in <filename>/etc/group</filename>.</para>
<para>This has the following advantages:</para> <para>This has the following advantages:</para>
<itemizedlist spacing="compact"> <itemizedlist spacing="compact">
<listitem><para>ntsec works better in domain environments.</para></listitem> <listitem><para>ntsec works better in domain environments.</para></listitem>
@ -378,14 +349,14 @@ root::500:513::/home/root:/bin/sh
<listitem><para>As in U*X systems UIDs and GIDs numbering scheme now <listitem><para>As in U*X systems UIDs and GIDs numbering scheme now
don't influence each other. So it's possible to have same Id's for a don't influence each other. So it's possible to have same Id's for a
user and a group:</para> user and a group:</para>
<example> <example id="ntsec-passwd-root">
<title>/etc/passwd:</title> <title>/etc/passwd:</title>
<screen> <screen>
root::0:0:S-1-5-21-54355234-56236534-345635656-500:/home/root:/bin/sh root::0:0:S-1-5-21-54355234-56236534-345635656-500:/home/root:/bin/sh
</screen> </screen>
</example> </example>
<example> <example id="ntsec-group-root">
<title>/etc/group:</title> <title>/etc/group:</title>
<screen> <screen>
root:S-1-5-32-544:0: root:S-1-5-32-544:0:
@ -402,14 +373,6 @@ not to do this since ntsec works better when having the SIDs available.</para>
<para>Please note that the pw_gecos field in <filename>/etc/passwd</filename> <para>Please note that the pw_gecos field in <filename>/etc/passwd</filename>
is defined as a comma separated list. The SID has to be the last field!</para> is defined as a comma separated list. The SID has to be the last field!</para>
<para>As aforementioned you are able to use Cygwin account names different
from the NT account names. If you want to login through `telnet' or something
else you have to use the special <command>login</command>. You may then
add another field to pw_gecos which contains the NT user name including
it's domain. So you are able to login as each domain user. The syntax
is easy: Just add an entry of the form U-ntdomain\ntusername to the pw_gecos
field. Note that the SID must still remain the last field in pw_gecos!</para>
<screen> <screen>
the_king::1:1:Elvis Presley,U-STILLHERE\elvis,S-1-5-21-1234-5678-9012-1000:/bin/sh the_king::1:1:Elvis Presley,U-STILLHERE\elvis,S-1-5-21-1234-5678-9012-1000:/bin/sh
</screen> </screen>
@ -429,7 +392,7 @@ examples. Please note that I've changed these files heavily! There's no
need to change them that way, it's just for testing purposes and... need to change them that way, it's just for testing purposes and...
for fun.</para> for fun.</para>
<example> <example id="ntsec-passwd-ex-2">
<title>/etc/passwd</title> <title>/etc/passwd</title>
<screen> <screen>
root:*:0:0:Administrators group,S-1-5-32-544:: root:*:0:0:Administrators group,S-1-5-32-544::
@ -440,7 +403,7 @@ Guest:*:501:546:,S-1-5-21-1844237615-436374069-1060284298-501:/home/Guest:/bin/b
</screen> </screen>
</example> </example>
<example> <example id="ntsec-group-ex-2">
<title>/etc/group</title> <title>/etc/group</title>
<screen> <screen>
root:S-1-5-32-544:0: root:S-1-5-32-544:0:
@ -593,7 +556,7 @@ found on <ulink url="http://docs.sun.com">http://docs.sun.com</ulink> </para>
<sect2 id="ntsec-setuid"><title id="ntsec-setuid.title">New setuid concept</title> <sect2 id="ntsec-setuid"><title id="ntsec-setuid.title">New setuid concept</title>
<para>UNIX applications which have to switch the user context are using <para>POSIX applications which have to switch the user context are using
the <command>setuid</command> and <command>seteuid</command> calls which the <command>setuid</command> and <command>seteuid</command> calls which
are not part of the Windows API. are not part of the Windows API.
Nevertheless these calls are supported under Windows NT/W2K since Cygwin Nevertheless these calls are supported under Windows NT/W2K since Cygwin

36
winsup/doc/overview.sgml
View File

@ -5,17 +5,15 @@
<para> <para>
Cygwin is a Linux-like environment for Windows. It consists of a DLL Cygwin is a Linux-like environment for Windows. It consists of a DLL
(<filename>cygwin1.dll</filename>), which acts as an emulation layer (<filename>cygwin1.dll</filename>), which acts as an emulation layer
providing substantial <ulink providing substantial <ulink url="http://www.pasc.org/#POSIX">POSIX</ulink>
url="http://www.pasc.org/#POSIX">POSIX</ulink> (Portable Operating (Portable Operating System Interface) system call functionality, and a
System Interface) system call functionality, and a collection of tools, collection of tools, which provide a Linux look and feel. The Cygwin DLL
which provide a Linux look and feel. The Cygwin DLL works with all x86 works with all x86 and AMD64 versions of Windows NT since Windows NT 4.
versions of Windows since Windows 95. The API follows the <ulink The API follows the
url="http://www.opengroup.org/onlinepubs/009695399/nfindex.html">Single <ulink url="http://www.opengroup.org/onlinepubs/009695399/nfindex.html">Single
Unix Specification</ulink> as much as possible, and then Linux practice. Unix Specification</ulink> as much as possible, and then Linux practice.
Two other major differences between Cygwin and Linux are the C library The major differences between Cygwin and Linux is the C library
(<literal>newlib</literal> instead of <literal>glibc</literal>) and (<literal>newlib</literal> instead of <literal>glibc</literal>).
default <command>/bin/sh</command>, which is <command>ash</command> on
Cygwin but <command>bash</command> on most Linux distributions.
</para> </para>
<para> <para>
With Cygwin installed, users have access to many standard UNIX With Cygwin installed, users have access to many standard UNIX
@ -48,8 +46,8 @@ information on how the GNU GPL may affect your use of these
tools. If you intend to port a proprietary application using the Cygwin tools. If you intend to port a proprietary application using the Cygwin
library, you may want the Cygwin proprietary-use license. library, you may want the Cygwin proprietary-use license.
For more information about the proprietary-use license, please go to For more information about the proprietary-use license, please go to
<ulink url="http://www.redhat.com/software/tools/cygwin/">http://www.redhat.com/software/tools/cygwin/ <ulink url="http://www.redhat.com/software/tools/cygwin/">http://www.redhat.com/software/tools/cygwin/</ulink>.
</ulink>. Customers of the native Win32 GNUPro should feel free to submit bug Customers of the native Win32 GNUPro should feel free to submit bug
reports and ask questions through the normal channels. All other reports and ask questions through the normal channels. All other
questions should be sent to the project mailing list questions should be sent to the project mailing list
<email>cygwin@cygwin.com</email>.</para> <email>cygwin@cygwin.com</email>.</para>
@ -60,9 +58,9 @@ questions should be sent to the project mailing list
<note> <note>
<para> <para>
A more complete historical look Cygwin is Geoffrey J. Noer's 1998 paper, A historical look into the first years of Cygwin development is
"Cygwin32: A Free Win32 Porting Layer for UNIX&reg; Applications" which can be Geoffrey J. Noer's 1998 paper, "Cygwin32: A Free Win32 Porting Layer for
found at the <ulink UNIX&reg; Applications" which can be found at the <ulink
url="http://www.usenix.org/publications/library/proceedings/usenix-nt98/technical.html"> url="http://www.usenix.org/publications/library/proceedings/usenix-nt98/technical.html">
2nd USENIX Windows NT Symposium Online Proceedings</ulink>. 2nd USENIX Windows NT Symposium Online Proceedings</ulink>.
</para> </para>
@ -108,6 +106,14 @@ New Cygwin Net Release</ulink> which provided the native Win32 program
separately. Since then, the Cygwin DLL and <command>setup.exe</command> separately. Since then, the Cygwin DLL and <command>setup.exe</command>
have seen continuous development. have seen continuous development.
</para> </para>
<para>
The latest major improvement in this development is the 1.7 release in
2008, which dropped Windows 95/98/Me support in favor of using Windows
NT features more extensively. It adds a lot of new features like
case-sensitive filenames, NFS interoperability, IPv6 support and much
more.</para>
</sect1> </sect1>
DOCTOOL-INSERT-highlights DOCTOOL-INSERT-highlights

281
winsup/doc/overview2.sgml
View File

@ -33,11 +33,11 @@ After installation, you can find Cygwin-specific documentation in
the <literal>/usr/share/doc/Cygwin/</literal> directory. the <literal>/usr/share/doc/Cygwin/</literal> directory.
</para> </para>
<para> <para>
Developers coming from a Windows background will find a set of tools capable of Developers coming from a Windows background will be able to write
writing console or GUI executables that rely on the Microsoft Win32 API. The console or GUI executables that rely on the Microsoft Win32 API instead
<command>dlltool</command> utility may be used to write Windows Dynamically of Cygwin using the -mno-cygwin option to GCC. The <command>-shared</command>
Linked Libraries (DLLs). The resource compiler <command>windres</command> is option allows to write Windows Dynamically Linked Libraries (DLLs). The
also provided. resource compiler <command>windres</command> is also provided.
</para> </para>
</sect1> </sect1>
@ -75,7 +75,7 @@ Developers coming from a UNIX background will find a set of utilities
they are already comfortable using, including a working UNIX shell. The they are already comfortable using, including a working UNIX shell. The
compiler tools are the standard GNU compilers most people will have previously compiler tools are the standard GNU compilers most people will have previously
used under UNIX, only ported to the Windows host. Programmers wishing to port used under UNIX, only ported to the Windows host. Programmers wishing to port
UNIX software to Windows NT or 9x will find that the Cygwin library provides UNIX software to Windows NT will find that the Cygwin library provides
an easy way to port many UNIX packages, with only minimal source code an easy way to port many UNIX packages, with only minimal source code
changes. changes.
</para> </para>
@ -88,138 +88,148 @@ changes.
against the library is executed, the Cygwin DLL is loaded into the against the library is executed, the Cygwin DLL is loaded into the
application's text segment. Because we are trying to emulate a UNIX kernel application's text segment. Because we are trying to emulate a UNIX kernel
which needs access to all processes running under it, the first Cygwin DLL to which needs access to all processes running under it, the first Cygwin DLL to
run creates shared memory areas that other processes using separate instances run creates shared memory areas and global synchronization objects that other
of the DLL can access. This is used to keep track of open file descriptors and processes using separate instances of the DLL can access. This is used to keep track of open file descriptors and to assist fork and exec, among other
assist fork and exec, among other purposes. In addition to the shared memory purposes. Every process also has a per_process structure that contains
regions, every process also has a per_process structure that contains
information such as process id, user id, signal masks, and other similar information such as process id, user id, signal masks, and other similar
process-specific information.</para> process-specific information.</para>
<para>The DLL is implemented using the Win32 API, which allows it to run on all <para>The DLL is implemented as a standard DLL in the Win32 subsystem. Under
Win32 hosts. Because processes run under the standard Win32 subsystem, they the hood it's using the Win32 API, as well as the native NT API, where
appropriate.</para>
<para>Because processes run under the standard Win32 subsystem, they
can access both the UNIX compatibility calls provided by Cygwin as well as can access both the UNIX compatibility calls provided by Cygwin as well as
any of the Win32 API calls. This gives the programmer complete flexibility in any of the Win32 API calls. This gives the programmer complete flexibility in
designing the structure of their program in terms of the APIs used. For designing the structure of their program in terms of the APIs used. For
example, they could write a Win32-specific GUI using Win32 API calls on top of example, they could write a Win32-specific GUI using Win32 API calls on top of
a UNIX back-end that uses Cygwin.</para> a UNIX back-end that uses Cygwin.</para>
<para>Early on in the development process, we made the important design <para>The native NT API is used mainly for speed, as well as to access
decision that it would not be necessary to strictly adhere to existing UNIX NT capabilities which are useful to implement certain POSIX features, but
standards like POSIX.1 if it was not possible or if it would significantly are hidden to the Win32 API.
diminish the usability of the tools on the Win32 platform. In many cases, an </para>
environment variable can be set to override the default behavior and force
standards compliance.</para>
</sect2>
<sect2 id="ov-hi-win9xnt"><title>Supporting both Windows NT and 9x</title> <para>Due to some restrictions in Windows, it's not always possible
<para>While Windows 95 and Windows 98 are similar enough to each other that we to strictly adhere to existing UNIX standards like POSIX.1. Fortunately
can safely ignore the distinction when implementing Cygwin, Windows NT is an these are mostely border cases.</para>
extremely different operating system. For this reason, whenever the DLL is
loaded, the library checks which operating system is active so that it can act
accordingly.</para>
<para>In some cases, the Win32 API is only different for
historical reasons. In this situation, the same basic functionality is
available under Windows 9x and NT but the method used to gain this
functionality differs. A trivial example: in our implementation of
uname, the library examines the sysinfo.dwProcessorType structure
member to figure out the processor type under Windows 9x. This field
is not supported in NT, which has its own operating system-specific
structure member called sysinfo.wProcessorLevel.</para>
<para>Other differences between NT and 9x are much more fundamental in
nature. The best example is that only NT provides a security model.</para>
</sect2> </sect2>
<sect2 id="ov-hi-perm"><title>Permissions and Security</title> <sect2 id="ov-hi-perm"><title>Permissions and Security</title>
<para>Windows NT includes a sophisticated security model based on Access <para>Windows NT includes a sophisticated security model based on Access
Control Lists (ACLs). Cygwin maps Win32 file ownership and permissions to the Control Lists (ACLs). Cygwin maps Win32 file ownership and permissions to
more standard, older UNIX model by default. Cygwin version 1.1 introduces ACLs by default, on file systems supporting them (usually NTFS). Solaris
support for ACLs according to the system calls used on newer versions of style ACLs and accompanying function calls are also supported.
Solaris. This ability is used when the `ntsec' feature is switched on which The chmod call maps UNIX-style permissions back to the Win32 equivalents.
is described in <xref linkend="ntsec"></xref>. Because many programs expect to be able to find the
The chmod call maps UNIX-style permissions <filename>/etc/passwd</filename> and
back to the Win32 equivalents. Because many programs expect to be able to find <filename>/etc/group</filename> files, we provide <ulink
the /etc/passwd and /etc/group files, we provide <ulink url="http://cygwin.com/cygwin-ug-net/using-utils.html">utilities</ulink>
url="http://cygwin.com/cygwin-ug-net/using-utils.html#mount">utilities</ulink>
that can be used to construct them from the user and group information that can be used to construct them from the user and group information
provided by the operating system.</para> provided by the operating system.</para>
<para>Under Windows NT, users with Administrator rights are permitted to <para>Users with Administrator rights are permitted to chown files.
chown files. With version 1.1.3 Cygwin introduced a mechanism for setting real With version 1.1.3 Cygwin introduced a mechanism for setting real and
and effective UIDs under Windows NT/W2K. This is described in effective UIDs. This is described in <xref linkend="ntsec"></xref>. As
<xref linkend="ntsec"></xref>. As of version 1.5.13, the Cygwin developers of version 1.5.13, the Cygwin developers are not aware of any feature in
are not aware of any feature in the Cygwin DLL that would allow users to gain the Cygwin DLL that would allow users to gain privileges or to access
privileges or to access objects to which they have no rights under Windows. objects to which they have no rights under Windows. However there is no
However there is no guarantee that Cygwin is as secure as the Windows it runs guarantee that Cygwin is as secure as the Windows it runs on. Cygwin
on. Cygwin processes share some variables and are thus easier targets of processes share some variables and are thus easier targets of denial of
denial of service type of attacks. service type of attacks.
</para> </para>
<para>Under Windows 9x, the situation is considerably different. Since a
security model is not provided, Cygwin fakes file ownership by making all
files look like they are owned by a default user and group id. As under NT,
file permissions can still be determined by examining their read/write/execute
status. Rather than return an unimplemented error, under Windows 9x, the
chown call succeeds immediately without actually performing any action
whatsoever. This is appropriate since essentially all users jointly own the
files when no concept of file ownership exists.</para>
</sect2> </sect2>
<sect2 id="ov-hi-files"><title>File Access</title> <para>Cygwin supports <sect2 id="ov-hi-files"><title>File Access</title> <para>Cygwin supports
both Win32- and POSIX-style paths, using either forward or back slashes as the both POSIX- and Win32-style paths, using either forward or back slashes as the
directory delimiter. Paths coming into the DLL are translated from Win32 to directory delimiter. Paths coming into the DLL are translated from POSIX to
POSIX as needed. As a result, the library believes that the file system is a native NT as needed. From the application perspective, the file system is
POSIX-compliant one, translating paths back to Win32 paths whenever it calls a a POSIX-compliant one. The implementation details are safely hidden in the
Win32 API function. UNC pathnames (starting with two slashes) are Cygwin DLL. UNC pathnames (starting with two slashes) are supported for
supported.</para> network paths.</para>
<para>The layout of this POSIX view of the Windows file system space is stored <para>Since version 1.7.0, the layout of this POSIX view of the Windows file
in the Windows registry. While the slash ('/') directory points to the system system space is stored in the <filename>/etc/fstab</filename> file. Actually,
partition by default, this is easy to change with the Cygwin mount utility. there is a system-wide <filename>/etc/fstab</filename> file as well as a
In addition to selecting the slash partition, it allows mounting arbitrary user-specific fstab file <filename>/etc/fstab.d/${USER}</filename>.</para>
Win32 paths into the POSIX file system space. Many people use the utility to
mount each drive letter under the slash partition (e.g. C:\ to /c, D:\ to /d, <para>At startup the DLL has to find out where it can find the
etc...).</para> <filename>/etc/fstab</filename> file. The mechanism used for this is simple.
First it retrieves it's own path, for instance
<filename>C:\Cygwin\bin\cygwin1.dll</filename>. From there it deduces
that the root path is <filename>C:\Cygwin</filename>. So it looks for the
<filename>fstab</filename> file in <filename>C:\Cygwin\etc\fstab</filename>.
The layout of this file is very similar to the layout of the
<filename>fstab</filename> file on Linux. Just instead of block devices,
the mount points point to Win32 paths. An installation with
<command>setup.exe</command> installs a <filename>fstab</filename> file by
default, which can easily be changed using the editor of your choice.</para>
<para>In addition to selecting the root partition, the
<filename>fstab</filename> file allows mounting arbitrary Win32 paths into
the POSIX file system space. A special case is the so-called cygdrive prefix.
It's the path under which every available drive in the system is mounted
under its drive letter. The default value is <filename>/cygdrive</filename>,
so you can access the drives as <filename>/cygdrive/c</filename>,
<filename>/cygdrive/d</filename>, etc... The cygdrive prefix can be set to
some other value (<filename>/mnt</filename> for instance) in the
<filename>fstab</filename> file(s).</para>
<para>The library exports several Cygwin-specific functions that can be used <para>The library exports several Cygwin-specific functions that can be used
by external programs to convert a path or path list from Win32 to POSIX or vice by external programs to convert a path or path list from Win32 to POSIX or vice
versa. Shell scripts and Makefiles cannot call these functions directly. versa. Shell scripts and Makefiles cannot call these functions directly.
Instead, they can do the same path translations by executing the cygpath Instead, they can do the same path translations by executing the
utility program that we provide with Cygwin.</para> <command>cygpath</command> utility program that we provide with Cygwin.</para>
<para>Win32 file systems are case preserving but case insensitive. Cygwin <para>Win32 applications handle filenames case preserving but case
does not currently support case distinction because, in practice, few UNIX insensitive. Cygwin supports case sensitivity on file systems supporting
programs actually rely on it. While we could mangle file names to support case that. Since Windows XP, the OS only supports case sensitivity when a
distinction, this would add unnecessary overhead to the library and make it specific registry value is changed. Therefore case sensitivity is not
more difficult for non-Cygwin applications to access those files.</para> the default usually.</para>
<para>Symbolic links are emulated by files containing a magic cookie followed <para>Symbolic links are not present and supported on Windows up to and
by the path to which the link points. They are marked with the System including Windows Server 2003 R2. Only starting with Windows Vista,
attribute so that only files with that attribute have to be read to determine native symlinks are available. Unfortunately they are strangly implemented
whether or not the file is a symbolic link. Hard links are fully supported and so not very useful for a POSIX emulation layer. Consequentially
under Windows NT on NTFS file systems. On a FAT file system, the call falls Cygwin recognizes them as symlinks but does not create them.</para>
back to simply copying the file, a strategy that works in many cases.</para>
<para>The inode number for a file is calculated by hashing its full Win32 path. <para>Symbolic links are potentially created in two different ways.
The inode number generated by the stat call always matches the one returned in The file style symlinks are files containing a magic cookie followed by
d_ino of the dirent structure. It is worth noting that the number produced by the path to which the link points. They are marked with the System DOS
this method is not guaranteed to be unique. However, we have not found this to attribute so that only files with that attribute have to be read to
be a significant problem because of the low probability of generating a determine whether or not the file is a symbolic link. The shortcut style
duplicate inode number.</para> symlinks are Windows shortcut files with a special header and the
Readonly DOS attribute set. The advantage of file symlinks is speed,
the advantage of shortcut symlinks is the fact that they can be utilized
by non-Cygwin Win32 tools as well.</para>
<para>Chroot is supported since release 1.1.3. Note that chroot isn't <para>Hard links are fully supported on NTFS and NFS file systems. On FAT
supported native by Windows. This implies some restrictions. First of all, and some other file systems, the call falls back to simply copying the file,
the chroot call isn't a privileged call. Each user may call it. Second, the a strategy that works in many cases.</para>
chroot environment isn't safe against native windows processes. If you
want to support a chroot environment as, for example, by allowing an <para>On file systems which don't support unique persistent file IDs (FAT,
anonymous ftp with restricted access, you'll have to care that only older Samba shares) the inode number for a file is calculated by hashing its
native Cygwin applications are accessible inside of the chroot environment. full Win32 path. The inode number generated by the stat call always matches
Since that applications are only using the Cygwin POSIX API to access the the one returned in <literal>d_ino</literal> of the <literal>dirent</literal>
file system their access can be restricted as it is intended. This includes structure. It is worth noting that the number produced by this method is not
not only POSIX paths but Win32 paths (containing drive letter and/or guaranteed to be unique. However, we have not found this to be a significant
backslashes) and CIFS paths (//server/share or \\server\share) as well.</para> problem because of the low probability of generating a duplicate inode number.
</para>
<para><function>chroot(2)</function> is supported since Cygwin 1.1.3.
However, chroot is not a concept known by Windows. This implies some
restrictions. First of all, the <function>chroot</function> call isn't a
privileged call. Each user may call it. Second, the chroot environment
isn't safe against native windows processes. If you want to support a
chroot environment as, for example, by allowing an anonymous ftp with
restricted access, you'll have to care that only native Cygwin applications
are accessible inside of the chroot environment. Since those applications
are only using the Cygwin POSIX API to access the file system their access
can be restricted as it is intended. This includes not only POSIX paths but
Win32 paths containing drive letter and/or backslashes as well as UNC paths
(<filename>//server/share</filename> or <filename>\\server\share</filename>).
</para>
</sect2> </sect2>
<sect2 id="ov-hi-textvsbinary"><title>Text Mode vs. Binary Mode</title> <sect2 id="ov-hi-textvsbinary"><title>Text Mode vs. Binary Mode</title>
@ -246,7 +256,9 @@ set to override this behavior.</para>
"newlib" as part of the library, rather than write all of the lib C "newlib" as part of the library, rather than write all of the lib C
and math calls from scratch. Newlib is a BSD-derived ANSI C library, and math calls from scratch. Newlib is a BSD-derived ANSI C library,
previously only used by cross-compilers for embedded systems previously only used by cross-compilers for embedded systems
development.</para> development. Other functions, which are not supported by newlib have
been added to the Cygwin sources using BSD implementations as much as
possible.</para>
<para>The reuse of existing free implementations of such things <para>The reuse of existing free implementations of such things
as the glob, regexp, and getopt libraries saved us considerable as the glob, regexp, and getopt libraries saved us considerable
@ -258,8 +270,8 @@ malloc if it so desires.</para>
</sect2> </sect2>
<sect2 id="ov-hi-process"><title>Process Creation</title> <sect2 id="ov-hi-process"><title>Process Creation</title>
<para>The fork call in Cygwin is particularly interesting because it <para>The <function>fork</function> call in Cygwin is particularly interesting
does not map well on top of the Win32 API. This makes it very because it does not map well on top of the Win32 API. This makes it very
difficult to implement correctly. Currently, the Cygwin fork is a difficult to implement correctly. Currently, the Cygwin fork is a
non-copy-on-write implementation similar to what was present in early non-copy-on-write implementation similar to what was present in early
flavors of UNIX.</para> flavors of UNIX.</para>
@ -335,26 +347,43 @@ it.</para>
</sect2> </sect2>
<sect2 id="ov-hi-sockets"><title>Sockets</title> <sect2 id="ov-hi-sockets"><title>Sockets</title>
<para>Socket-related calls in Cygwin simply <para>Socket-related calls in Cygwin basically call the functions by the
call the functions by the same name in Winsock, Microsoft's same name in Winsock, Microsoft's implementation of Berkeley sockets, but
implementation of Berkeley sockets. Only a few changes were needed to with lots of tweaks. All sockets are non-blocking under the hood to allow
match the expected UNIX semantics - one of the most troublesome to interrupt blocking calls by POSIX signals. Additional bookkeeping is
differences was that Winsock must be initialized before the first necessary to implement correct socket sharing POSIX semantics and especially
socket function is called. As a result, Cygwin has to perform this for the select call. Some socket-related functions are not implemented at
initialization when appropriate. In order to support sockets across all in Winsock, as, for example, socketpair. Starting with Windows Vista,
fork calls, child processes initialize Winsock if any inherited file Microsoft removed the legacy calls <function>rcmd(3)</function>,
descriptor is a socket.</para> <function>rexec(3)</function> and <function>rresvport(3)</function>.
Recent versions of Cygwin now implement all these calls internally.</para>
<para>An especially troublesome feature of Winsock is that it must be
initialized before the first socket function is called. As a result, Cygwin
has to perform this initialization on the fly, as soon as the first
socket-related function is called by the application. In order to support
sockets across fork calls, child processes initialize Winsock if any
inherited file descriptor is a socket.</para>
<para>AF_UNIX (AF_LOCAL) sockets are not available in Winsock. They are
implemented in Cygwin by using local AF_INET sockets instead. This is
completely transparent to the application. Cygwin's implementation also
supports the getpeereid BSD extension. A yet missing feature is
descriptor passing, though.</para>
<para>Starting with release 1.7.0, Cygwin gets IPv6 support. However, this
depends on the availability of the Windows IPv6 stack. Up to Windows 2003,
the IPv6 stack is treated as "experimental" and it's not feature complete.
Full support is only available starting with Windows Vista and Windows Server
2008. The newly implemented <function>getaddrinfo</function> and
<function>getnameinfo</function> functions are not dependent on the OS,
though. Cygwin 1.7.0 adds replacement functions which implement the full
functionality for IPv4.</para>
<para>Unfortunately, implicitly loading DLLs
at process startup is usually a slow affair. Because many processes
do not use sockets, Cygwin explicitly loads the Winsock DLL the
first time it calls the Winsock initialization routine. This single
change sped up GNU configure times by thirty
percent.</para>
</sect2> </sect2>
<sect2 id="ov-hi-select"><title>Select</title> <sect2 id="ov-hi-select"><title>Select</title>
<para>The UNIX select function is another <para>The UNIX <function>select</function> function is another
call that does not map cleanly on top of the Win32 API. Much to our call that does not map cleanly on top of the Win32 API. Much to our
dismay, we discovered that the Win32 select in Winsock only worked on dismay, we discovered that the Win32 select in Winsock only worked on
socket handles. Our implementation allows select to function normally socket handles. Our implementation allows select to function normally

438
winsup/doc/pathnames.sgml
View File

@ -1,6 +1,6 @@
<sect1 id="using-pathnames"><title>Mapping path names</title> <sect1 id="using-pathnames"><title>Mapping path names</title>
<sect2><title>Introduction</title> <sect2 id="pathnames-intro"><title>Introduction</title>
<para>Cygwin supports both Win32- and POSIX-style paths, where <para>Cygwin supports both Win32- and POSIX-style paths, where
directory delimiters may be either forward or back slashes. UNC directory delimiters may be either forward or back slashes. UNC
@ -24,41 +24,112 @@ necessary.</para>
<sect2 id="mount-table"><title>The Cygwin Mount Table</title> <sect2 id="mount-table"><title>The Cygwin Mount Table</title>
<para>The <command>mount</command> utility program is used to <para>The <filename>/etc/fstab</filename> file is used to map Win32
to map Win32 drives and network shares into Cygwin's internal POSIX drives and network shares into Cygwin's internal POSIX directory tree.
directory tree. This is a similar concept to the typical UNIX mount This is a similar concept to the typical UNIX fstab file. The mount
program. For those people coming from a Windows background, the points stored in <filename>/etc/fstab</filename> are globally set for
<command>mount</command> utility is very similar to the old DOS all users. Sometimes there's a requirement to have user specific
<command>join</command>, in that it makes your drive letters appear as mount points. The Cygwin DLL supports user specific fstab files.
subdirectories somewhere else.</para> These are stored in the directory <filename>/etc/fstab.d</filename>
and the name of the file is the Cygwin username of the user, as it's
stored in the <filename>/etc/passwd</filename> file. The content of the
user specifc file is identical to the system-wide
<filename>fstab</filename> file.</para>
<para>The mapping is stored in the current user's Cygwin <para>The file fstab contains descriptive information about the various file
<firstterm>mount table</firstterm> in the Windows registry so that the systems. fstab is only read by programs, and not written; it is the
information will be retrieved next time the user logs in. Because it duty of the system administrator to properly create and maintain this
is sometimes desirable to have system-wide as well as user-specific file. Each filesystem is described on a separate line; fields on each
mounts, there is also a system-wide mount table that all Cygwin users line are separated by tabs or spaces. Lines starting with '#' are
inherit. The system-wide table may only be modified by a user with comments.</para>
the appropriate privileges (Administrator privileges in Windows
NT).</para>
<para>The current user's table is located under <para>The first field describes the block special device or
"HKEY_CURRENT_USER/Software/Cygnus Solutions/Cygwin/mounts remote filesystem to be mounted. On Cygwin, this is the native Windows
v&lt;version&gt;" path which the mount point links in. As path separator you MUST use a
where &lt;version&gt; is the latest registry version associated with slash. Usage of a backslash might lead to unexpected results. UNC
the Cygwin library (this version is not the same as the release paths (using slashes, not backslashes) are allowed. If the path
number). The system-wide table is located under the same subkeys contains spaces these can be escaped as <literal>'\040'</literal>.</para>
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 <para>The second field describes the mount point for the filesystem.
<filename>/</filename> to any directory in the Windows file system. If the name of the mount point contains spaces these can be
In absence of such a mount, Cygwin maps <filename>/</filename> to the escaped as '\040'.</para>
root of the current Windows working directory (for example,
<filename>H:\</filename> or <filename>\\computer\share</filename>). <para>The third field describes the type of the filesystem.
Normally Cygwin's <command>setup.exe</command> creates the initial Cygwin supports any string here, since the file system type is usually
mount point for the POSIX root. not evaluated. The noticable exception is the file system type
</para> cygdrive. This type is used to set the cygdrive prefix.</para>
<para>The fourth field describes the mount options associated
with the filesystem. It is formatted as a comma separated list of
options. It contains at least the type of mount (binary or text) plus
any additional options appropriate to the filesystem type. Recognized
options are binary, text, nouser, user, exec, notexec, cygexec, nosuid,
posix=[0|1]. The meaning of the options is as follows.</para>
<screen>
acl - Cygwin uses the filesystem's access control lists (ACLs) to
implement real POSIX permissions (default). This flag only
affects filesystems supporting ACLs (NTFS) and is ignored
otherwise.
noacl - Cygwin ignores filesystem ACLs and only fakes a subset of
permission bits based on the DOS readonly attribute. This
behaviour is the default on FAT and FAT32. The flag is
ignored on NFS filesystems.
binary - Files default to binary mode (default).
text - Files default to CRLF text mode line endings.
nouser - Mount is a system-wide mount.
user - Mount is a user mount.
exec - Treat all files below mount point as executable.
notexec - Treat all files below mount point as not executable.
cygexec - Treat all files below mount point as cygwin executables.
nosuid - No suid files are allowed (currently unimplemented).
posix=0 - Switch off case sensitivity for paths under this mount point.
posix=1 - Switch on case sensitivity for paths under this mount point
(default).
</screen>
<para>Note that nouser mount points are not overridable by a later call
to mount(2). This is only possible for user mount points. Mount points
are by default nouser mount points, unless you specify the option user.
In contrast, all mount points in the user specific fstab file are user
mount points.</para>
<para>The fifth and sixth field are ignored. They are
so far only specified to keep a Linux-like fstab file layout.</para>
<para>Note that you don't have to specify an fstab entry for the root dir,
unless you want to have the root dir pointing to somewhere entirely
different (hopefully you know what you're doing), or if you want to
mount the root dir with special options (for instance, as text mount).</para>
<para>Example entries:</para>
<itemizedlist spacing="compact">
<listitem>
<para>Just a normal mount point:</para>
<screen>c:/foo /bar fat32 binary 0 0</screen>
</listitem>
<listitem>
<para>A mount point for a managed, textmode mount:</para>
<screen>C:/foo /bar/baz ntfs text,managed 0 0</screen>
</listitem>
<listitem>
<para>A mount point for a Windows directory with spaces in it:</para>
<screen>C:/Documents\040and\040Settings /docs ext3 binary 0 0</screen>
</listitem>
<listitem>
<para>A mount point for a remote directory:</para>
<screen>//server/share/subdir /srv/subdir smbfs binary 0 0</screen>
</listitem>
<listitem>
<para>This is just a comment:</para>
<screen># This is just a comment</screen>
</listitem>
<listitem>
<para>Set the cygdrive prefix to /mnt:</para>
<screen>none /mnt cygdrive binary 0 0</screen>
</listitem>
</itemizedlist>
<para>Whenever Cygwin generates a Win32 path from a POSIX one, it uses <para>Whenever Cygwin generates a Win32 path from a POSIX one, it uses
the longest matching prefix in the mount table. Thus, if the longest matching prefix in the mount table. Thus, if
@ -70,19 +141,14 @@ POSIX equivalent current directory. Otherwise, the handling of MS-DOS
filenames bypasses the mount table. filenames bypasses the mount table.
</para> </para>
<para>Invoking <command>mount</command> without any arguments displays <para>If you want to see the current set of mount points valid in your
Cygwin's current set of mount points. session, you can invoking the Cygwin tool <command>mount</command> without
In the following example, the C arguments:</para>
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> <example id="pathnames-mount-ex">
<title>Displaying the current set of mount points</title> <title>Displaying the current set of mount points</title>
<screen> <screen>
<prompt>c:\&gt;</prompt> <userinput>mount</userinput> <prompt>bash-3.2$</prompt> <userinput>mount</userinput>
f:\cygwin\bin on /usr/bin type system (binmode) f:\cygwin\bin on /usr/bin type system (binmode)
f:\cygwin\lib on /usr/lib type system (binmode) f:\cygwin\lib on /usr/lib type system (binmode)
f:\cygwin on / type system (binmode) f:\cygwin on / type system (binmode)
@ -94,9 +160,10 @@ e: on /cygdrive/e type user (binmode,noumount)
<para>You can also use the <command>mount</command> command to add <para>You can also use the <command>mount</command> command to add
new mount points, and the <command>umount</command> to delete new mount points, and the <command>umount</command> to delete
them. See <xref linkend="mount"></xref> and <xref linkend="umount"></xref> for more them. However, since they are only noted in memory, these mount
information on how to use these utilities to set up your Cygwin POSIX points will disappear as soon as your last Cygwin process ends.
file system.</para> See <xref linkend="mount"></xref> and <xref linkend="umount"></xref> for more
information.</para>
<para>Whenever Cygwin cannot use any of the existing mounts to convert <para>Whenever Cygwin cannot use any of the existing mounts to convert
from a particular Win32 path to a POSIX one, Cygwin will from a particular Win32 path to a POSIX one, Cygwin will
@ -105,19 +172,12 @@ path <filename>/cygdrive</filename>. For example, if Cygwin accesses
<filename>Z:\foo</filename> and the Z drive is not currently in the <filename>Z:\foo</filename> and the Z drive is not currently in the
mount table, then <filename>Z:\</filename> would be automatically mount table, then <filename>Z:\</filename> would be automatically
converted to <filename>/cygdrive/Z</filename>. The default converted to <filename>/cygdrive/Z</filename>. The default
prefix of <filename>/cygdrive</filename> may be changed (see the prefix of <filename>/cygdrive</filename> may be changed in the fstab file
<xref linkend="mount"></xref> for more information).</para> as outlined above.</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>
<sect2><title>Additional Path-related Information</title> <sect2 id="pathnames-additional"><title>Additional Path-related Information</title>
<para>The <command>cygpath</command> program provides the ability to <para>The <command>cygpath</command> program provides the ability to
translate between Win32 and POSIX pathnames in shell scripts. See translate between Win32 and POSIX pathnames in shell scripts. See
@ -150,23 +210,113 @@ not by default, for example).</para>
<sect1 id="using-specialnames"><title>Special filenames</title> <sect1 id="using-specialnames"><title>Special filenames</title>
<sect2> <title>DOS devices</title> <sect2 id="pathnames-dosdevices">
<title>DOS devices</title>
<para>Windows filenames invalid under Windows are also invalid under <para>Filenames invalid under Win32 are not necessarily invalid
Cygwin. This means that base filenames such as under Cygwin since release 1.7.0. There are a couple of rules which
apply to Windows filenames. First of all, DOS device names like
<filename>AUX</filename>, <filename>COM1</filename>, <filename>AUX</filename>, <filename>COM1</filename>,
<filename>LPT1</filename> or <filename>PRN</filename> (to name a few) <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 cannot be used in a native Win32 application, even with an
extension (<filename>prn.txt</filename>). However the special names can be extension (<filename>prn.txt</filename>). Cygwin can handle files with
used as filename extensions (<filename>file.aux</filename>). You can use these names just fine.</para>
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>
<sect2> <title>POSIX devices</title> <sect2 id="pathnames-specialchars">
<title>Special characters in filenames</title>
<para>Win32 filenames can't contain trailing dots and spaces for backward
compatibility. When trying to create files with trailing dots or spaces,
all of them are removed before the file is created. This restriction does
only affect native Win32 applications. Cygwin applications can create and
access files with trailing dots and spaces without problems.</para>
<para>Some characters are disallowed in filenames on Windows filesystems:</para>
<screen>
" * : &lt; &gt; ? | \
</screen>
<para>Cygwin can't fix this, but it has a method to workaround this
restriction. All of the above characters, except for the backslash,
are converted to special UNICODE characters in the range 0xf000 to 0xf0ff
(the "Private use area") when creating or accessing files.</para>
</sect2>
<sect2 id="pathnames-casesensitive">
<title>Case sensitive filenames</title>
<para>In the Win32 subsystem filenames are only case-preserved, but not
case-sensitive. You can't access two files in the same directory which
only differ by case, like <filename>Abc</filename> and
<filename>aBc</filename>. While NTFS (and some remote filesystems)
support case-sensitivity, the NT kernel starting with Windows XP does
not support it by default. Rather, you have to tweak a registry setting
and reboot. For that reason, case-sensitivity is not supported by Cygwin,
unless you change that registry value.</para>
<para>If you really want case-sensitivity in Cygwin, you can switch it
on by setting the registry value</para>
<screen>
HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\kernel\obcaseinsensitive
</screen>
<para>to 0 and reboot the machine. For least surprise, Cygwin expects
this registry value also on Windows NT4 and Windows 2000, which usually
both don't know this registry key. If you want case-sensitivity on these
systems, create that registry value and set it to 0. On these systems
(and *only* on these systems) you don't have to reboot to bring it
into effect.</para>
<note>
<para>
Note that when installing Microsoft's Services For Unix (SFU), you're asked if
you want to use case-sensitive filenames. If you answer "yes" at this point,
the installer will change the aforementioned registry value to 0, too. So, if
you have SFU installed, there's some chance that the registry value is already
set to case sensitivity.
</para>
</note>
<para>After you set this registry value to 0, Cygwin will be case-sensitive
by default on NTFS and NFS filesystems. Be aware that using two filenames
which only differ by case might result in some weird interoperability
issues with native Win32 applications. You're using case-sensitivity
at your own risk. You have been warned!</para>
<para>Even if you use case-sensitivity, it might be feasible to switch to
case-insensitivity for certain paths for better interoperability with
native Win32 applications (even if it's just Windows Explorer). You can do
this on a per-mount point base, by using the "posix=0" mount option in
/etc/fstab, or your /etc/fstab.d/$USER file.</para>
<para>For a start, it might be best to switch the cygdrive path to
case-insensitivity, because the default Windows $PATH variable is not
always using the correct case by default. As a result, your shell will
claim that it can't find Windows commands like <command>attrib</command>
or <command>net</command>. Here's an example how you can switch the
cygdrive prefix to case-insensitivity:</para>
<example id="mount-caseinsensitive">
<title>Example mount point to enforce case-insensitivity on cygdrive paths</title>
<screen>
none /cygdrive cygdrive binary,posix=0 0 0
</screen>
</example>
<para>Note that mount points as well as device names and virtual
paths like /proc are always case-sensitive! The only exception are
the subdirs and filenames under /proc/registry, /proc/registry32
and /proc/registry64. Registry access is always case-insensitive.
Read on for more information.</para>
</sect2>
<sect2 id="pathnames-posixdevices"> <title>POSIX devices</title>
<para>There is no need to create a POSIX <filename>/dev</filename> <para>There is no need to create a POSIX <filename>/dev</filename>
directory as Cygwin automatically simulates it internally. directory as Cygwin automatically simulates it internally.
These devices cannot be seen with the command <command>ls /dev/</command> These devices cannot be seen with the command <command>ls /dev/</command>
@ -177,67 +327,97 @@ If you want to be able to see all devices in
url="http://cygwin.com/ml/cygwin/2004-03/txt00028.txt">create_devices.sh</ulink> url="http://cygwin.com/ml/cygwin/2004-03/txt00028.txt">create_devices.sh</ulink>
script. script.
</para> </para>
<para>
Cygwin supports the following character devices commonly found on POSIX systems:
</para>
<screen>
/dev/null
/dev/zero
/dev/full
/dev/console Pseudo device name for the standard console window created
by Windows. Same as the one used for cmd.exe. Every one
of them has this name. It's not quite comparable with the
console device on UNIX machines.
/dev/tty The current tty of a session running in a pseudo tty.
/dev/ptmx Pseudo tty master device.
/dev/ttym
/dev/tty0 Pseudo ttys are numbered from /dev/tty0 upwards as they are
/dev/tty1 requested.
...
/dev/ttyS0 Serial communication devices. ttyS0 == Win32 COM1,
/dev/ttyS1 ttyS1 == COM2, etc.
...
/dev/pipe
/dev/fifo
/dev/mem The physical memory of the machine. Note that access to the
/dev/port physical memory has been restricted with Windows Server 2003.
/dev/kmem Since this OS, you can't access physical memory from user space.
/dev/kmsg Kernel message pipe, for usage with sys logger services.
/dev/random Random number generator.
/dev/urandom
/dev/dsp Default sound device of the system.
</screen>
<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: 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>
<para>Windows NT/W2K/XP additionally support raw devices like floppies, <screen>
disks, partitions and tapes. These are accessed from Cygwin applications /dev/com1 The serial ports, starting with COM1 which is the same as ttyS0.
using POSIX device names which are supported in two different ways. /dev/com2 Please use /dev/ttySx instead.
</para> ...
<para>Up to Cygwin 1.3.3 the only way to access those devices was /dev/conin Same as Windows CONIN$.
to mount the Win32 device names to a POSIX device name but this usage /dev/conout Same as Windows CONOUT$.
is discouraged since Cygwin 1.3.4 and only kept for backward compatibility. /dev/clipboard The Windows clipboard, text only
</para> /dev/windows The Windows message queue.
</screen>
<para> <para>
Beginning with Cygwin 1.3.4, raw devices are accessible by Cygwin processes Block devices are accessible by Cygwin processes using fixed POSIX device
using fixed POSIX device names. These fixed POSIX device names are generated names. These POSIX device names are generated using a direct conversion
using a direct conversion from the POSIX namespace to the internal NT namespace. from the POSIX namespace to the internal NT namespace.
E.g. the first harddisk is the NT internal device \device\harddisk0\partition0 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. 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 The first floppy in the system is \device\floppy0, the first CD-ROM is
\device\cdrom0 and the first tape drive is \device\tape0. \device\cdrom0 and the first tape drive is \device\tape0. The mapping
to the POSIX /dev namespace is as follows:
</para> </para>
<para>The new fixed POSIX names are mapped to NT internal devices as
follows:</para>
<screen> <screen>
/dev/st0 \device\tape0, rewind /dev/st0 \device\tape0, rewind
/dev/nst0 \device\tape0, no-rewind /dev/nst0 \device\tape0, no-rewind
/dev/st1 \device\tape1 /dev/st1 \device\tape1
/dev/nst1 \device\tape1
... ...
/dev/st15
/dev/nst15
/dev/fd0 \device\floppy0 /dev/fd0 \device\floppy0
/dev/fd1 \device\floppy1 /dev/fd1 \device\floppy1
... ...
/dev/fd15
/dev/scd0 \device\cdrom0
/dev/scd1 \device\cdrom1
...
/dev/sr0 \device\cdrom0 /dev/sr0 \device\cdrom0
/dev/sr1 \device\cdrom1 /dev/sr1 \device\cdrom1
... ...
/dev/sr15
/dev/scd0 \device\cdrom0
/dev/scd1 \device\cdrom1
...
/dev/scd15
/dev/sda \device\harddisk0\partition0 (whole disk) /dev/sda \device\harddisk0\partition0 (whole disk)
/dev/sda1 \device\harddisk0\partition1 (first partition) /dev/sda1 \device\harddisk0\partition1 (first partition)
@ -249,10 +429,10 @@ follows:</para>
[up to] [up to]
/dev/sdl \device\harddisk11\partition0 /dev/sddx \device\harddisk127\partition0
/dev/sdl1 \device\harddisk11\partition1 /dev/sddx1 \device\harddisk127\partition1
... ...
/dev/sdl15 \device\harddisk11\partition15 /dev/sddx15 \device\harddisk127\partition15
</screen> </screen>
<para> <para>
@ -261,32 +441,16 @@ links as they are created on Linux systems for convenience:
</para> </para>
<screen> <screen>
ln -s /dev/scd0 /dev/cdrom ln -s /dev/sr0 /dev/cdrom
ln -s /dev/nst0 /dev/tape ln -s /dev/nst0 /dev/tape
... ...
</screen> </screen>
<warning>
<para>
Note that you can't use the mount table to map from a 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>
<sect2><title>The .exe extension</title> <sect2 id="pathnames-exe"><title>The .exe extension</title>
<para> Executable program filenames end with <filename>.exe</filename> <para>Win32 executable filenames end with <filename>.exe</filename>
but the <filename>.exe</filename> need not be included in the command, but the <filename>.exe</filename> need not be included in the command,
so that traditional UNIX names can be used. However, for programs that so that traditional UNIX names can be used. However, for programs that
end in <filename>.bat</filename> and <filename>.com</filename>, you end in <filename>.bat</filename> and <filename>.com</filename>, you
@ -319,18 +483,9 @@ Cygwin 1.5.19. It has been changed for consistency with the rest of Cygwin.
<filename>filename</filename>. This allows many makefiles written <filename>filename</filename>. This allows many makefiles written
for UNIX systems to work well under Cygwin.</para> 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>
<sect2><title>The /proc filesystem</title> <sect2 id="pathnames-proc"><title>The /proc filesystem</title>
<para> <para>
Cygwin, like Linux and other similar operating systems, supports the Cygwin, like Linux and other similar operating systems, supports the
<filename>/proc</filename> virtual filesystem. The files in this <filename>/proc</filename> virtual filesystem. The files in this
@ -344,7 +499,12 @@ is <filename>/proc/registry</filename>, which displays the Windows
registry with each <literal>KEY</literal> as a directory and each registry with each <literal>KEY</literal> as a directory and each
<literal>VALUE</literal> as a file. As anytime you deal with the <literal>VALUE</literal> as a file. As anytime you deal with the
Windows registry, use caution since changes may result in an unstable Windows registry, use caution since changes may result in an unstable
or broken system. or broken system. There are additionally subdirectories called
<filename>/proc/registry32</filename> and <filename>/proc/registry64</filename>.
They are identical to <filename>/proc/registry</filename> on 32 bit
host OSes. On 64 bit host OSes, <filename>/proc/registry32</filename>
opens the 32 bit processes view on the registry, while
<filename>/proc/registry64</filename> opens the 64 bit processes view.
</para> </para>
<para> <para>
The Cygwin <filename>/proc</filename> is not as complete as the The Cygwin <filename>/proc</filename> is not as complete as the
@ -354,7 +514,7 @@ that use it.
</para> </para>
</sect2> </sect2>
<sect2><title>The @pathnames</title> <sect2 id="pathnames-at"><title>The @pathnames</title>
<para>To circumvent the limitations on shell line length in the native <para>To circumvent the limitations on shell line length in the native
Windows command shells, Cygwin programs expand their arguments Windows command shells, Cygwin programs expand their arguments
starting with "@" in a special way. If a file starting with "@" in a special way. If a file
@ -366,7 +526,7 @@ Embedded double quotes must be repeated.
In the following example compare the behaviors of the bash built-in In the following example compare the behaviors of the bash built-in
<command>echo</command> and of the program <command>/bin/echo</command>.</para> <command>echo</command> and of the program <command>/bin/echo</command>.</para>
<example><title> Using @pathname</title> <example id="pathnames-at-ex"><title> Using @pathname</title>
<screen> <screen>
<prompt>bash$</prompt> <userinput>echo 'This is "a long" line' > mylist</userinput> <prompt>bash$</prompt> <userinput>echo 'This is "a long" line' > mylist</userinput>
<prompt>bash$</prompt> <userinput>echo @mylist</userinput> <prompt>bash$</prompt> <userinput>echo @mylist</userinput>

20
winsup/doc/setup-net.sgml
View File

@ -35,7 +35,7 @@ to make use of <ulink url="http://www.google.com/search?q=new+to+unix">
other resources</ulink>. other resources</ulink>.
</para> </para>
<sect2><title>Download Source</title> <sect2 id="setup-download"><title>Download Source</title>
<para> <para>
Cygwin uses packages to manage installing various software. When Cygwin uses packages to manage installing various software. When
the default <literal>Install from Internet</literal> option is chosen, the default <literal>Install from Internet</literal> option is chosen,
@ -69,7 +69,7 @@ this; search the list for <command>mkcygwget</command> for ideas.
</para> </para>
</sect2> </sect2>
<sect2><title>Selecting an Install Directory</title> <sect2 id="setup-dir"><title>Selecting an Install Directory</title>
<para> <para>
The <literal>Root Directory</literal> for Cygwin (default The <literal>Root Directory</literal> for Cygwin (default
<literal>C:\cygwin</literal>) will become <literal>/</literal> <literal>C:\cygwin</literal>) will become <literal>/</literal>
@ -97,7 +97,7 @@ have a very good reason to switch it to
</para> </para>
</sect2> </sect2>
<sect2><title>Local Package Directory</title> <sect2 id="setup-localdir"><title>Local Package Directory</title>
<para> <para>
The <literal>Local Package Directory</literal> is the cache where The <literal>Local Package Directory</literal> is the cache where
<command>setup.exe</command> stores the packages before they are <command>setup.exe</command> stores the packages before they are
@ -111,7 +111,7 @@ or in case you need to reinstall a package.
</para> </para>
</sect2> </sect2>
<sect2><title>Connection Method</title> <sect2 id="setup-connection"><title>Connection Method</title>
<para> <para>
The <literal>Direct Connection</literal> method of downloading will The <literal>Direct Connection</literal> method of downloading will
directly download the packages, while the IE5 method will leverage your directly download the packages, while the IE5 method will leverage your
@ -124,7 +124,7 @@ authorization for proxy servers.
</para> </para>
</sect2> </sect2>
<sect2><title>Choosing Mirrors</title> <sect2 id="setup-mirror"><title>Choosing Mirrors</title>
<para> <para>
Since there is no way of knowing from where you will be downloading Since there is no way of knowing from where you will be downloading
Cygwin, you need to choose at least one mirror site. Cygwin mirrors Cygwin, you need to choose at least one mirror site. Cygwin mirrors
@ -137,7 +137,7 @@ mirror) you can add it.
</para> </para>
</sect2> </sect2>
<sect2><title>Choosing Packages</title> <sect2 id="setup-packages"><title>Choosing Packages</title>
<para> <para>
For each selected mirror site, <command>setup.exe</command> downloads a For each selected mirror site, <command>setup.exe</command> downloads a
small text file called <literal>setup.bz2</literal> that contains a list small text file called <literal>setup.bz2</literal> that contains a list
@ -201,7 +201,7 @@ stable version.
</para> </para>
</sect2> </sect2>
<sect2><title>Download and Installation Progress</title> <sect2 id="setup-progress"><title>Download and Installation Progress</title>
<para> <para>
First, <command>setup.exe</command> will download all selected packages First, <command>setup.exe</command> will download all selected packages
to the local directory chosen earlier. Before installing, to the local directory chosen earlier. Before installing,
@ -212,7 +212,7 @@ show progress bars for the current task and total remaining disk space.
</para> </para>
</sect2> </sect2>
<sect2><title>Icons</title> <sect2 id="setup-icons"><title>Icons</title>
<para> <para>
You may choose to install shortcuts on the Desktop and/or Start Menu You may choose to install shortcuts on the Desktop and/or Start Menu
to start a <literal>bash</literal> shell. If you prefer to use a different to start a <literal>bash</literal> shell. If you prefer to use a different
@ -221,7 +221,7 @@ use these shortcuts as a guide to creating your own.
</para> </para>
</sect2> </sect2>
<sect2><title>Post-Install Scripts</title> <sect2 id="setup-postinstall"><title>Post-Install Scripts</title>
<para> <para>
Last of all, <command>setup.exe</command> will run any post-install Last of all, <command>setup.exe</command> will run any post-install
scripts to finish correctly setting up installed packages. Since each scripts to finish correctly setting up installed packages. Since each
@ -236,7 +236,7 @@ Relevant documentation can be found in the <literal>/usr/doc/Cygwin/</literal>
or <literal>/usr/share/doc/Cygwin/</literal> directory. or <literal>/usr/share/doc/Cygwin/</literal> directory.
</para> </para>
</sect2> </sect2>
<sect2><title>Troubleshooting</title> <sect2 id="setup-troubleshooting"><title>Troubleshooting</title>
<para> <para>
Unfortunately, the complex setup process means that odd problems can Unfortunately, the complex setup process means that odd problems can
occur. If you're having trouble downloading packages, it may be network occur. If you're having trouble downloading packages, it may be network

30
winsup/doc/setup2.sgml
View File

@ -23,20 +23,21 @@ DOS shell, before launching bash. </para>
The <envar>PATH</envar> environment variable is used by Cygwin The <envar>PATH</envar> environment variable is used by Cygwin
applications as a list of directories to search for executable files applications as a list of directories to search for executable files
to run. This environment variable is converted from Windows format to run. This environment variable is converted from Windows format
(e.g. <filename>C:\WinNT\system32;C:\WinNT</filename>) to UNIX format (e.g. <filename>C:\Windows\system32;C:\Windows</filename>) to UNIX format
(e.g., <filename>/WinNT/system32:/WinNT</filename>) when a Cygwin (e.g., <filename>/cygdrive/c/Windows/system32:/cygdrive/c/Windows</filename>)
process first starts. when a Cygwin process first starts.
Set it so that it contains at least the <filename>x:\cygwin\bin</filename> Set it so that it contains at least the <filename>x:\cygwin\bin</filename>
directory where "<filename>x:\cygwin</filename> is the "root" of your directory where "<filename>x:\cygwin</filename> is the "root" of your
cygwin installation if you wish to use cygwin tools outside of bash. cygwin installation if you wish to use cygwin tools outside of bash.
This is usually done by the batch file you're starting your shell with.
</para> </para>
<para> <para>
The <envar>HOME</envar> environment variable is used by many programs to The <envar>HOME</envar> environment variable is used by many programs to
determine the location of your home directory and we recommend that it be determine the location of your home directory and we recommend that it be
defined. This environment variable is also converted from Windows format defined. This environment variable is also converted from Windows format
when a Cygwin process first starts. Set it to point to your home directory when a Cygwin process first starts. It's usually set in the shell
before launching bash. profile scripts in the /etc directory.
</para> </para>
<para> <para>
@ -79,8 +80,8 @@ when using <command>regtool</command> since damaging your system registry can
result in an unusable system. This example sets memory limit to 1024 MB: result in an unusable system. This example sets memory limit to 1024 MB:
<screen> <screen>
regtool -i set /HKLM/Software/Cygnus\ Solutions/Cygwin/heap_chunk_in_mb 1024 regtool -i set /HKLM/Software/Cygwin/heap_chunk_in_mb 1024
regtool -v list /HKLM/Software/Cygnus\ Solutions/Cygwin regtool -v list /HKLM/Software/Cygwin
</screen> </screen>
</para> </para>
@ -121,6 +122,7 @@ gcc max_memory.c -o max_memory.exe
Run the program and it will output the maximum amount of allocatable memory. Run the program and it will output the maximum amount of allocatable memory.
</para> </para>
</sect1> </sect1>
<sect1 id="setup-files"><title>Customizing bash</title> <sect1 id="setup-files"><title>Customizing bash</title>
@ -128,19 +130,19 @@ Run the program and it will output the maximum amount of allocatable memory.
<para> <para>
To set bash up so that cut and paste work properly, click on the To set bash up so that cut and paste work properly, click on the
"Properties" button of the window, then on the "Misc" tab. Make sure "Properties" button of the window, then on the "Misc" tab. Make sure
that "Quick Edit" is checked and "Fast Pasting" isn't. These settings that "QuickEdit mode" and "Insert mode" are checked. These settings
will be remembered next time you run bash from that will be remembered next time you run bash from that shortcut. Similarly
shortcut. Similarly you can set the working directory inside the you can set the working directory inside the "Program" tab. The entry
"Program" tab. The entry "%HOME%" is valid. "%HOME%" is valid, but requires that you set <envar>HOME</envar> in
the Windows environment.
</para> </para>
<para> <para>
Your home directory should contain three initialization files Your home directory should contain three initialization files
that control the behavior of bash. They are that control the behavior of bash. They are
<filename>.profile</filename>, <filename>.bashrc</filename> and <filename>.profile</filename>, <filename>.bashrc</filename> and
<filename>.inputrc</filename>. These initialization files will only <filename>.inputrc</filename>. The Cygwin base installation creates
be read if <envar>HOME</envar> is defined before starting bash. stub files when you start bash for the first time.</para>
</para>
<para> <para>
<filename>.profile</filename> (other names are also valid, see the bash man <filename>.profile</filename> (other names are also valid, see the bash man

28
winsup/doc/textbinary.sgml
View File

@ -1,6 +1,6 @@
<sect1 id="using-textbinary"><title>Text and Binary modes</title> <sect1 id="using-textbinary"><title>Text and Binary modes</title>
<sect2> <title>The Issue</title> <sect2 id="textbin-issue"> <title>The Issue</title>
<para>On a UNIX system, when an application reads from a file it gets <para>On a UNIX system, when an application reads from a file it gets
exactly what's in the file on disk and the converse is true for writing. exactly what's in the file on disk and the converse is true for writing.
@ -28,7 +28,7 @@ other programs (such as <command>cat</command>, <command>cmp</command>,
</sect2> </sect2>
<sect2><title>The default Cygwin behavior</title> <sect2 id="textbin-default"><title>The default Cygwin behavior</title>
<para>The Cygwin system gives us some flexibility in deciding how files <para>The Cygwin system gives us some flexibility in deciding how files
are to be opened when the mode is not specified explicitly. are to be opened when the mode is not specified explicitly.
@ -49,22 +49,8 @@ backslash or a colon), the default is binary.
<listitem> <listitem>
<para>Pipes and non-file devices are opened in binary mode, <para>Pipes and non-file devices are opened in binary mode,
except if the <envar>CYGWIN</envar> environment variable contains except if the <envar>CYGWIN</envar> environment variable contains
<literal>nobinmode</literal>.</para> <literal>nobinmode</literal>. Sockets are always opened in binary
<warning><title>Warning!</title><para>In b20.1 of 12/98, a file will be opened mode.</para>
in binary mode if any of the following conditions hold:</para>
<orderedlist numeration="arabic" spacing="compact">
<listitem><para>binary mode is specified in the open call</para>
</listitem>
<listitem><para>the filename is a MS-DOS filename</para>
</listitem>
<listitem><para>the file resides on a binary mounted partition</para>
</listitem>
<listitem><para><envar>CYGWIN</envar> contains <literal>binmode</literal></para>
</listitem>
<listitem><para>the file is not a disk file</para>
</listitem>
</orderedlist>
</warning>
</listitem> </listitem>
<listitem> <listitem>
@ -79,7 +65,7 @@ and <command> program &lt; filename </command> are not equivalent when
</orderedlist> </orderedlist>
</sect2> </sect2>
<sect2><title>Example</title> <sect2 id="textbin-example"><title>Example</title>
<para>To illustrate the various rules, we provide scripts to delete CRs <para>To illustrate the various rules, we provide scripts to delete CRs
from files by using the <command>tr</command> program, which can only write from files by using the <command>tr</command> program, which can only write
to standard output. to standard output.
@ -115,7 +101,7 @@ In the second case we rely on the DOS shell to redirect in binary mode.
</para> </para>
</sect2> </sect2>
<sect2><title>Binary or text?</title> <sect2 id="textbin-question"><title>Binary or text?</title>
<para>UNIX programs that have been written for maximum portability <para>UNIX programs that have been written for maximum portability
will know the difference between text and binary files and act will know the difference between text and binary files and act
@ -150,7 +136,7 @@ in binary mode.</para>
</sect2> </sect2>
<sect2><title>Programming</title> <sect2 id="textbin-devel"><title>Programming</title>
<para>In the <function>open()</function> function call, binary mode can be <para>In the <function>open()</function> function call, binary mode can be
specified with the flag <literal>O_BINARY</literal> and text mode with specified with the flag <literal>O_BINARY</literal> and text mode with