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>
* Makefile.in: Temporarily add ability to generate pdfs.

31
winsup/doc/cygserver.sgml
View File

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

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

@ -1,10 +1,12 @@
<?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"[
<!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>">
<!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
be reproduced, modified, or distributed

172
winsup/doc/cygwinenv.sgml
View File

@ -1,6 +1,9 @@
<sect1 id="using-cygwinenv"><title>The <envar>CYGWIN</envar> environment
variable</title>
<sect2 id="cygwinenv-implemented-options">
<title>Implemented options</title>
<para>The <envar>CYGWIN</envar> environment variable is used to configure
many global settings for the Cygwin runtime system. It contains the options
listed below, separated by blank characters. Many options can be turned off
@ -12,7 +15,8 @@ by prefixing with <literal>no </literal>.</para>
(e.g. pipe and COM ports) file opens default to binary mode
(no CRLF translation) instead of text mode. Defaults to set (binary
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
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.
</para>
</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>
<para><envar>codepage:[ansi|oem]</envar> - Windows console
applications can use different character sets (codepages) for drawing
characters. The first setting, called "ansi", is the default.
This character set contains various forms of latin characters used
in European languages. The name originates from the ANSI Latin1
(ISO 8859-1) standard, used in Windows 1.0, though the character
sets have since diverged from any standard. The second setting
selects an older, DOS-based character set, containing various line
drawing and special characters. It is called "oem" since it was
originally encoded in the firmware of IBM PCs by original
equipment manufacturers (OEMs). 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.
</para>
<para><envar>codepage:[ansi|oem|utf8]</envar> - This option controls
which single- or multibyte character set is used for file and console
operations. Windows is using UTF-16 characters internally and this
option specifies how 8-byte character sets are converted to UTF-16 and
vice versa. The default setting is <envar>ansi</envar> which means,
conversion is based on the current ANSI codepage, typically 1252 in
many Western language versions of Windows. The name originates from the
ANSI Latin1 (ISO 8859-1) standard, used in Windows 1.0, though the
character sets have since diverged from any standard. The second
setting selects an older, DOS-based character set, containing various
line drawing and special characters. It is called <envar>oem</envar>
since it was originally encoded in the firmware of IBM PCs by original
equipment manufacturers (OEMs).</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>
@ -77,16 +57,18 @@ path name. Defaults to set.</para>
<listitem>
<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
and may contain values that depend on the previous mount table
contents. Defaults to set.</para>
</listitem>
<listitem>
<para><envar>(no)export</envar> - If set, the final values of these
settings are re-exported to the environment as <envar>CYGWIN</envar> again.
Defaults to off.</para>
</listitem>
<listitem>
<para>
<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.
</para>
</listitem>
<listitem>
<para><envar>forkchunk:32768</envar> - causes the <function>fork()</function>
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.
</para>
</listitem>
<listitem>
<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
occur when processes are being started while a user is logging off.
</para>
</listitem>
<listitem>
<para><envar>(no)glob[:ignorecase]</envar> - if set, command line arguments
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.
If supplied, wildcard matching is case insensitive. The default is <literal>noignorecase</literal></para>
</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>
<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
time and when handles are inherited. Defaults to set.</para>
</listitem>
<listitem>
<para><envar>(no)server</envar> - if set, allows client applications
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".
</para>
</listitem>
<listitem>
<para><envar>(no)strip_title</envar> - if set, strips the directory
part off the window title, if any. Default is not set.</para>
</listitem>
<listitem>
<para><envar>(no)title</envar> - if set, the title bar
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
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>
set.</para>
</listitem>
<listitem>
<para><envar>(no)tty</envar> - if set, Cygwin enables extra support
(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).
</para>
</listitem>
<listitem>
<para><envar>(no)winsymlinks</envar> - if set, Cygwin creates
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,
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>
</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>

64
winsup/doc/effectively.sgml
View File

@ -18,23 +18,27 @@ support the <literal>/?</literal> switch to display usage information.
<para>
Unfortunately, no standard set of tools included with all versions of
Windows exists. If you are unfamiliar with the tools available
on your system, here is a general guide. Windows 95, 98, and ME have
very limited command-line configuration tools. Windows NT 4.0 has much
better coverage, which Windows 2000 and XP expanded.
on your system, here is a general guide. Windows NT 4.0 has only a basic
set of tools, which later versions of Windows expanded.
Microsoft also provides free downloads for Windows NT 4.0 (the Resource Kit
Support Tools), Windows 2000 (the Resource Kit Tools), and XP (the
Windows Support Tools). Additionally, many independent sites such as
<ulink url="http://download.com.com">download.com</ulink>,
Windows Support Tools). Generally, the younger the Windows version, the
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>,
and <ulink url="http://sysinternals.com">sysinternals.com</ulink>
provide command-line utilities. A few Windows tools, such as
<command>find.exe</command> and <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>.
and Microsoft's own
<ulink url="http://technet.microsoft.com/en-us/sysinternals/default.aspx">Sysinternals</ulink>
provide quite useful command-line utilities, as far as they are not
already provided by Cygwin. A few Windows tools, such as
<command>find.exe</command>, <command>link.exe</command> and
<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>
<sect2> <title>Pathnames</title>
<sect2 id="using-pathnames-effectively"> <title>Pathnames</title>
<para>
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> <title>Console Programs</title>
<sect2 id="using-console"> <title>Console Programs</title>
<para>
Another issue is receiving output from or giving input to console-based
Windows programs. Unfortunately, interacting with Windows console
applications is not a simple matter of using a translation utility. Windows
console applications are designed to run under <command>command.com</command>
or <command>cmd.exe</command>, and some do not deal gracefully with other
console applications are designed to run under
<command>cmd.exe</command>, and some do not deal gracefully with other
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
traditional Unix input/output method, ptys (pseudo-terminals), 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>
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
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,
@ -92,7 +96,7 @@ but expect some compatibility problems with Windows programs.
</sect2>
<sect2> <title>Cygwin and Windows Networking</title>
<sect2 id="using-net"> <title>Cygwin and Windows Networking</title>
<para>
Many popular Cygwin packages, such as <systemitem>ncftp</systemitem>,
<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>
There are a variety of other programs available for specific situations.
If your system does not have an always-on network connection, you
may be interested in <command>rasdial.exe</command> (or alternatives for
Windows 95, 98, and ME) for automating dialup connections.
may be interested in <command>rasdial.exe</command> for automating dialup
connections.
Users who frequently change their network
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">
NTLM Authorization Proxy Server</ulink> or the no-charge
<ulink url="http://www.hummingbird.com/products/nc/socks/index.html">
@ -125,15 +129,15 @@ programs in your environment.
</sect2>
<sect2><title>The cygutils package</title>
<sect2 id="using-cygutils"><title>The cygutils package</title>
<para>
The optional <systemitem>cygutils</systemitem> package contains miscellaneous tools that are
small enough to not require their own package. It is not included in a
default Cygwin install; select it from the Utils category in
<command>setup.exe</command>. Several of the <systemitem>cygutils</systemitem> tools are useful
for interacting with Windows.
</para>
The optional <systemitem>cygutils</systemitem> package contains
miscellaneous tools that are small enough to not require their own package.
It is not included in a default Cygwin install; select it from the Utils
category in <command>setup.exe</command>. Several of the
<systemitem>cygutils</systemitem> tools are useful for interacting with
Windows.</para>
<para>
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>
</sect2>
<sect2><title>Creating shortcuts with cygutils</title>
<sect2 id="using-shortcuts"><title>Creating shortcuts with cygutils</title>
<para>
Another problem area is between Unix-style links, which link one file
to another, and Microsoft .lnk files, which provide a shortcut to a
@ -172,7 +176,7 @@ Windows shortcuts.
</para>
</sect2>
<sect2><title>Printing with cygutils</title>
<sect2 id="using-printing"><title>Printing with cygutils</title>
<para>
There are several options for printing from Cygwin, including 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>
<para>On Windows 9x systems, files are always readable, and Cygwin uses the
native read-only mode to determine if they are writable. Files are
<para>On FAT or FAT32 filesystems, files are always readable, and Cygwin
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
if its content starts with #!. Consequently <command>chmod</command> can
only affect the "w" mode, it silently ignores actions involving the other
modes. This means that <command>ls -l</command>
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
9x but there is optional functionality in Cygwin that can make file
systems behave more like on UNIX systems. This is turned on by adding
the "ntea" option to the <envar>CYGWIN</envar> environment variable.</para>
<para>On NTFS, file permissions are evaluated using the Access Control
Lists (ACLs) attached to a file. This can be switched off by using the
"noacl" option to the respective mount point in the
<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
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>
<!-- TODO: Put the file permission stuff from ntsec here??? -->
<para>Under NT, the test "[ -w filename]" is only true if filename is
writable across the board, e.g. <command>chmod +w filename</command>. </para>
<xref linkend="ntsec"></xref>.
</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>

2
winsup/doc/gcc.sgml
View File

@ -6,7 +6,7 @@
Refer to the GCC User's Guide for information on standard usage and
options. Here's a simple example:</para>
<example>
<example id="gcc-hello-world">
<title>Building Hello World with GCC</title>
<screen>
<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
your sources to objects.</para>
<example><title>Compiling with -g</title>
<example id="gdb-g"><title>Compiling with -g</title>
<screen>
<prompt>$</prompt> gcc -g -O2 -c myapp.c
<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
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>
<prompt>(gdb)</prompt> break my_function
<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
concerned:</para>
<example><title>Debugging with command line arguments</title>
<example id="gdb-cliargs"><title>Debugging with command line arguments</title>
<screen>
<prompt>$</prompt> myprog -t foo --queue 47

2
winsup/doc/legal.sgml
View File

@ -1,6 +1,6 @@
<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
<link linkend="using-cygwinenv"><envar>CYGWIN</envar> environment
variable</link> setting <literal>(no)ntsec</literal> which is set to
<literal>ntsec</literal> by default.</para>
<para>The setting of POSIX like object permissions is controlled by the
<link linkend="mount-table">mount option</link> <literal>(no)acl</literal>
which is set to <literal>acl</literal> by default. The design goal
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
permission structure based upon the security features of Windows NT.
To describe the changes, I will first give a short overview in
<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>
<para>We start with a short overview. Note that this overview must
be necessarily short. If you want to learn more about the Windows security
model, see the <ulink url="http://msdn.microsoft.com/en-us/library/aa374860(VS.85).aspx">Access Control</ulink> article in MSDN documentation.</para>
<sect2 id="ntsec-common"><title>NT security</title>
<para>The NT security allows a process to allow or deny access of
different kind to `objects'. `Objects' are files, processes,
threads, semaphores, etc.</para>
<para>In the NT security model, almost any "object" is securable.
"Objects" are files, processes, threads, semaphores, etc.</para>
<para>The main data structure of NT security is the `security descriptor'
(SD) structure. It explains the permissions, that are granted (or denied)
to an object and contains information, that is related to so called
`security identifiers' (SID).</para>
<para>Every object has a data structure called "security descriptor" (SD)
attached. The SD contains all information necessary to control who can
how access an object. The SD of an object consists of five parts:</para>
<para>A SID is a unique identifier for users, groups and domains.
SIDs are comparable to UNIX UIDs and GIDs, but are more complicated
because they are unique across networks. Example:</para>
<itemizedlist spacing="compact">
<listitem><para>Flags which control several aspects of this SD. This is
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>
S-1-5-21-165875785-1005667432-441284377
</screen>
<para>SID of a user `johndoe' of the system `foo':</para>
<para>SID of a user "johndoe" of the system "foo":</para>
<screen>
S-1-5-21-165875785-1005667432-441284377-1023
</screen>
<para>The above example shows the convention for printing SIDs. The leading
`S' should show that it is a SID. The next number is a version number which
is always 1. The next number is the so called `top-level authority' that
identifies the source that issued the SID.</para>
<para>The leading "S" has no further meaning except to show that this is
a SID. The next number is a version number which is always 1 so far.
The next two numbers are the authority which shows the initiated what
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
is modified in NT domains: The SID of the domain controller is the
base SID for each domain user. If an NT user has one account as domain
user and another account on his local machine, these accounts are under
any circumstances DIFFERENT, regardless of the usage of the same user
name and password!</para>
<para>As you can see in the above example, SIDs of users (and groups)
are identical to the computer SID, except for an additional part, the
so-called "relative identifier" (RID). So the SID of a user is always
uniquely attached to the system on which the account has been generated.</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>
S-1-5-21-186985262-1144665072-740312968
</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>
S-1-5-21-186985262-1144665072-740312968-1207
</screen>
<para>The last part of the SID, the so called `relative identifier' (RID),
is by default used as UID and/or GID under Cygwin. As the name and the
above example implies, this id is unique only relative to one system or
domain.</para>
<para>Ok, so you now have two accounts called johndoe, one account
created on the machine "foo", one created in the domain "bar.local".
Both have different SIDs and not even the RID is the same. How do
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
different systems. The resulting SIDs are nevertheless different, so
the SIDs are representing different users in an NT network.</para>
<para>The last part of the SID, the so called "Relative IDentifier" (RID),
is by default used as UID and/or GID under Cygwin when you create the
<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
the so called `well known groups'. For example UNIX has no GID for the
group of `all users'. NT has an SID for them, called `Everyone' in the
English versions. The SIDs of well-known groups are not unique across
an NT network but their meanings are unmistakable.
Examples of well-known groups:</para>
<para>Do you still remember the SIDs with special meaning? In offical
notation they are called "well-known SIDs". For example, POSIX has no GID
for the group of "all users" or "world" or "others". The last three rwx
bits in a permission value just represent the permissions for "everyone
who is not the owner or is member of the owning group". Windows has a
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>
everyone S-1-1-0
creator/owner S-1-3-0
batch process (via `at') S-1-5-3
authenticated users S-1-5-11
system S-1-5-18
Everyone S-1-1-0 Simply everyone...
Batch S-1-5-3 Processes started via the task
scheduler are member of this group.
Interactive S-1-5-4 Only processes of users which are
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>
<para>The last important group of SIDs are the `predefined groups'. This
groups are used mainly on systems outside of domains to simplify the
administration of user permissions. The corresponding SIDs are not unique
across the network so they are interpreted only locally:</para>
<para>For a full list please refer to
<ulink url="http://msdn.microsoft.com/en-us/library/aa379649.aspx">Well-known SIDs</ulink>.
Naturally well-known SIDs are the same on each machine, so they are
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>
administrators S-1-5-32-544
@ -126,187 +149,143 @@ guests S-1-5-32-546
...
</screen>
<para>Now, how are permissions given to objects? A process may assign an SD
to the object. The SD of an object consists of three parts:</para>
<para>For instance, every account is usually member in the "Users"
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">
<listitem><para>the SID of the owner </para></listitem>
<listitem><para>the SID of the group </para></listitem>
<listitem><para>a list of SIDs with their permissions, called
`access control list' (ACL) </para></listitem>
<listitem><para>The type of the ACE (allow ACE or deny ACE).</para></listitem>
<listitem><para>Permission bits, 32 of them.</para></listitem>
<listitem><para>The SID for which the permissions are allowed or denied.</para></listitem>
</itemizedlist>
<para>UNIX is able to create three different permissions, the permissions
for the owner, for the group and for the world. In contrast the ACL
has a potentially infinite number of members. Every member is a so called
`access control element' (ACE). An ACE contains three parts:</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 two (for us) important types of ACEs are the "access allowed
ACE" and the "access denied ACE". As the names imply, the allow ACE
tells the system to allow the given permissions to the SID, the deny ACE
results in denying the specific permission bits.</para>
<para>The possible permissions on objects are more detailed than in
UNIX. For example, the permission to delete an object is different
from the write permission.</para>
<para>With the aforementioned method NT is able to grant or revoke permissions
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>
POSIX. For example, the permission to delete an object is different
from the permission to change object data, and even changing object data
can be separated into different permission bits for different kind of
data.</para>
</sect2>
<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
assigned to the file containing the owner and group and ACEs for the
owner, the group and `Everyone'.</para>
<para>On NTFS and if the <literal>noacl</literal> mount option is not
specified for a mount point, Cygwin sets file permissions as in POSIX.
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
`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
<para>To use NT security correctly, Cygwin depends on the files
<filename>/etc/passwd</filename> and <filename>/etc/group</filename>.
In Cygwin release 1.0 the names and the IDs must correspond to the
appropriate NT IDs! The IDs used in Cygwin are the RID of the NT SID, as
mentioned earlier.
A SID of e.g. the user `corinna' on my NT workstation:</para>
These files define the traslation between the Cygwin uid/gid and the
Windows SID. The SID is stored in the pw_gecos field in
<filename>/etc/passwd</filename>, and in the gr_passwd field in
<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>
S-1-5-21-165875785-1005667432-441284377-1000
</screen>
<para>Note the last number: It's the RID 1000, Cygwin's UID.</para>
<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
SYSTEM:*:18:544:,S-1-5-18::
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
corinna:unused:11001:11125:U-BAR\corinna,S-1-5-21-2913048732-1697188782-3448811101-1001:/home/corinna:/bin/tcsh
</screen>
</example>
<example>
<title>/etc/group</title>
<para>The SYSTEM entry is usually needed by services. The Administrators
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>
everyone::0:
system::18:
none::513:
administrators::544:
users::545:
guests::546:
powerusers::547:
root:unused:0:513:U-FOO\Administrator,S-1-5-21-790525478-115176313-839522115-500:/home/Administrator:/bin/bash
thursday_next:unused:11001:11125:U-BAR\corinna,S-1-5-21-2913048732-1697188782-3448811101-1001:/home/corinna:/bin/tcsh
</screen>
</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)
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>
@ -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>
<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>
<itemizedlist spacing="compact">
<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
don't influence each other. So it's possible to have same Id's for a
user and a group:</para>
<example>
<example id="ntsec-passwd-root">
<title>/etc/passwd:</title>
<screen>
root::0:0:S-1-5-21-54355234-56236534-345635656-500:/home/root:/bin/sh
</screen>
</example>
<example>
<example id="ntsec-group-root">
<title>/etc/group:</title>
<screen>
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>
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>
the_king::1:1:Elvis Presley,U-STILLHERE\elvis,S-1-5-21-1234-5678-9012-1000:/bin/sh
</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...
for fun.</para>
<example>
<example id="ntsec-passwd-ex-2">
<title>/etc/passwd</title>
<screen>
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>
</example>
<example>
<example id="ntsec-group-ex-2">
<title>/etc/group</title>
<screen>
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>
<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
are not part of the Windows API.
Nevertheless these calls are supported under Windows NT/W2K since Cygwin

36
winsup/doc/overview.sgml
View File

@ -5,17 +5,15 @@
<para>
Cygwin is a Linux-like environment for Windows. It consists of a DLL
(<filename>cygwin1.dll</filename>), which acts as an emulation layer
providing substantial <ulink
url="http://www.pasc.org/#POSIX">POSIX</ulink> (Portable Operating
System Interface) system call functionality, and a collection of tools,
which provide a Linux look and feel. The Cygwin DLL works with all x86
versions of Windows since Windows 95. The API follows the <ulink
url="http://www.opengroup.org/onlinepubs/009695399/nfindex.html">Single
providing substantial <ulink url="http://www.pasc.org/#POSIX">POSIX</ulink>
(Portable Operating System Interface) system call functionality, and a
collection of tools, which provide a Linux look and feel. The Cygwin DLL
works with all x86 and AMD64 versions of Windows NT since Windows NT 4.
The API follows the
<ulink url="http://www.opengroup.org/onlinepubs/009695399/nfindex.html">Single
Unix Specification</ulink> as much as possible, and then Linux practice.
Two other major differences between Cygwin and Linux are the C library
(<literal>newlib</literal> instead of <literal>glibc</literal>) and
default <command>/bin/sh</command>, which is <command>ash</command> on
Cygwin but <command>bash</command> on most Linux distributions.
The major differences between Cygwin and Linux is the C library
(<literal>newlib</literal> instead of <literal>glibc</literal>).
</para>
<para>
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
library, you may want the Cygwin proprietary-use license.
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>. Customers of the native Win32 GNUPro should feel free to submit bug
<ulink url="http://www.redhat.com/software/tools/cygwin/">http://www.redhat.com/software/tools/cygwin/</ulink>.
Customers of the native Win32 GNUPro should feel free to submit bug
reports and ask questions through the normal channels. All other
questions should be sent to the project mailing list
<email>cygwin@cygwin.com</email>.</para>
@ -60,9 +58,9 @@ questions should be sent to the project mailing list
<note>
<para>
A more complete historical look Cygwin is Geoffrey J. Noer's 1998 paper,
"Cygwin32: A Free Win32 Porting Layer for UNIX&reg; Applications" which can be
found at the <ulink
A historical look into the first years of Cygwin development is
Geoffrey J. Noer's 1998 paper, "Cygwin32: A Free Win32 Porting Layer for
UNIX&reg; Applications" which can be found at the <ulink
url="http://www.usenix.org/publications/library/proceedings/usenix-nt98/technical.html">
2nd USENIX Windows NT Symposium Online Proceedings</ulink>.
</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>
have seen continuous development.
</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>
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.
</para>
<para>
Developers coming from a Windows background will find a set of tools capable of
writing console or GUI executables that rely on the Microsoft Win32 API. The
<command>dlltool</command> utility may be used to write Windows Dynamically
Linked Libraries (DLLs). The resource compiler <command>windres</command> is
also provided.
Developers coming from a Windows background will be able to write
console or GUI executables that rely on the Microsoft Win32 API instead
of Cygwin using the -mno-cygwin option to GCC. The <command>-shared</command>
option allows to write Windows Dynamically Linked Libraries (DLLs). The
resource compiler <command>windres</command> is also provided.
</para>
</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
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
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
changes.
</para>
@ -88,138 +88,148 @@ changes.
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
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
of the DLL can access. This is used to keep track of open file descriptors and
assist fork and exec, among other purposes. In addition to the shared memory
regions, every process also has a per_process structure that contains
run creates shared memory areas and global synchronization objects that other
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
purposes. Every process also has a per_process structure that contains
information such as process id, user id, signal masks, and other similar
process-specific information.</para>
<para>The DLL is implemented using the Win32 API, which allows it to run on all
Win32 hosts. Because processes run under the standard Win32 subsystem, they
<para>The DLL is implemented as a standard DLL in the Win32 subsystem. Under
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
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
example, they could write a Win32-specific GUI using Win32 API calls on top of
a UNIX back-end that uses Cygwin.</para>
<para>Early on in the development process, we made the important design
decision that it would not be necessary to strictly adhere to existing UNIX
standards like POSIX.1 if it was not possible or if it would significantly
diminish the usability of the tools on the Win32 platform. In many cases, an
environment variable can be set to override the default behavior and force
standards compliance.</para>
</sect2>
<para>The native NT API is used mainly for speed, as well as to access
NT capabilities which are useful to implement certain POSIX features, but
are hidden to the Win32 API.
</para>
<sect2 id="ov-hi-win9xnt"><title>Supporting both Windows NT and 9x</title>
<para>While Windows 95 and Windows 98 are similar enough to each other that we
can safely ignore the distinction when implementing Cygwin, Windows NT is an
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>
<para>Due to some restrictions in Windows, it's not always possible
to strictly adhere to existing UNIX standards like POSIX.1. Fortunately
these are mostely border cases.</para>
</sect2>
<sect2 id="ov-hi-perm"><title>Permissions and Security</title>
<para>Windows NT includes a sophisticated security model based on Access
Control Lists (ACLs). Cygwin maps Win32 file ownership and permissions to the
more standard, older UNIX model by default. Cygwin version 1.1 introduces
support for ACLs according to the system calls used on newer versions of
Solaris. This ability is used when the `ntsec' feature is switched on which
is described in <xref linkend="ntsec"></xref>.
The chmod call maps UNIX-style permissions
back to the Win32 equivalents. Because many programs expect to be able to find
the /etc/passwd and /etc/group files, we provide <ulink
url="http://cygwin.com/cygwin-ug-net/using-utils.html#mount">utilities</ulink>
Control Lists (ACLs). Cygwin maps Win32 file ownership and permissions to
ACLs by default, on file systems supporting them (usually NTFS). Solaris
style ACLs and accompanying function calls are also supported.
The chmod call maps UNIX-style permissions back to the Win32 equivalents.
Because many programs expect to be able to find the
<filename>/etc/passwd</filename> and
<filename>/etc/group</filename> files, we provide <ulink
url="http://cygwin.com/cygwin-ug-net/using-utils.html">utilities</ulink>
that can be used to construct them from the user and group information
provided by the operating system.</para>
<para>Under Windows NT, users with Administrator rights are permitted to
chown files. With version 1.1.3 Cygwin introduced a mechanism for setting real
and effective UIDs under Windows NT/W2K. This is described in
<xref linkend="ntsec"></xref>. As of version 1.5.13, the Cygwin developers
are not aware of any feature in the Cygwin DLL that would allow users to gain
privileges or to access objects to which they have no rights under Windows.
However there is no guarantee that Cygwin is as secure as the Windows it runs
on. Cygwin processes share some variables and are thus easier targets of
denial of service type of attacks.
<para>Users with Administrator rights are permitted to chown files.
With version 1.1.3 Cygwin introduced a mechanism for setting real and
effective UIDs. This is described in <xref linkend="ntsec"></xref>. As
of version 1.5.13, the Cygwin developers are not aware of any feature in
the Cygwin DLL that would allow users to gain privileges or to access
objects to which they have no rights under Windows. However there is no
guarantee that Cygwin is as secure as the Windows it runs on. Cygwin
processes share some variables and are thus easier targets of denial of
service type of attacks.
</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 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
directory delimiter. Paths coming into the DLL are translated from Win32 to
POSIX as needed. As a result, the library believes that the file system is a
POSIX-compliant one, translating paths back to Win32 paths whenever it calls a
Win32 API function. UNC pathnames (starting with two slashes) are
supported.</para>
both POSIX- and Win32-style paths, using either forward or back slashes as the
directory delimiter. Paths coming into the DLL are translated from POSIX to
native NT as needed. From the application perspective, the file system is
a POSIX-compliant one. The implementation details are safely hidden in the
Cygwin DLL. UNC pathnames (starting with two slashes) are supported for
network paths.</para>
<para>The layout of this POSIX view of the Windows file system space is stored
in the Windows registry. While the slash ('/') directory points to the system
partition by default, this is easy to change with the Cygwin mount utility.
In addition to selecting the slash partition, it allows mounting arbitrary
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,
etc...).</para>
<para>Since version 1.7.0, the layout of this POSIX view of the Windows file
system space is stored in the <filename>/etc/fstab</filename> file. Actually,
there is a system-wide <filename>/etc/fstab</filename> file as well as a
user-specific fstab file <filename>/etc/fstab.d/${USER}</filename>.</para>
<para>At startup the DLL has to find out where it can find the
<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
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.
Instead, they can do the same path translations by executing the cygpath
utility program that we provide with Cygwin.</para>
Instead, they can do the same path translations by executing the
<command>cygpath</command> utility program that we provide with Cygwin.</para>
<para>Win32 file systems are case preserving but case insensitive. Cygwin
does not currently support case distinction because, in practice, few UNIX
programs actually rely on it. While we could mangle file names to support case
distinction, this would add unnecessary overhead to the library and make it
more difficult for non-Cygwin applications to access those files.</para>
<para>Win32 applications handle filenames case preserving but case
insensitive. Cygwin supports case sensitivity on file systems supporting
that. Since Windows XP, the OS only supports case sensitivity when a
specific registry value is changed. Therefore case sensitivity is not
the default usually.</para>
<para>Symbolic links are emulated by files containing a magic cookie followed
by the path to which the link points. They are marked with the System
attribute so that only files with that attribute have to be read to determine
whether or not the file is a symbolic link. Hard links are fully supported
under Windows NT on NTFS file systems. On a FAT file system, the call falls
back to simply copying the file, a strategy that works in many cases.</para>
<para>Symbolic links are not present and supported on Windows up to and
including Windows Server 2003 R2. Only starting with Windows Vista,
native symlinks are available. Unfortunately they are strangly implemented
and so not very useful for a POSIX emulation layer. Consequentially
Cygwin recognizes them as symlinks but does not create them.</para>
<para>The inode number for a file is calculated by hashing its full Win32 path.
The inode number generated by the stat call always matches the one returned in
d_ino of the dirent structure. It is worth noting that the number produced by
this method is not guaranteed to be unique. However, we have not found this to
be a significant problem because of the low probability of generating a
duplicate inode number.</para>
<para>Symbolic links are potentially created in two different ways.
The file style symlinks are files containing a magic cookie followed by
the path to which the link points. They are marked with the System DOS
attribute so that only files with that attribute have to be read to
determine whether or not the file is a symbolic link. The shortcut style
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
supported native by Windows. This implies some restrictions. First of all,
the chroot 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 that 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) and CIFS paths (//server/share or \\server\share) as well.</para>
<para>Hard links are fully supported on NTFS and NFS file systems. On FAT
and some other file systems, the call falls back to simply copying the file,
a strategy that works in many cases.</para>
<para>On file systems which don't support unique persistent file IDs (FAT,
older Samba shares) the inode number for a file is calculated by hashing its
full Win32 path. The inode number generated by the stat call always matches
the one returned in <literal>d_ino</literal> of the <literal>dirent</literal>
structure. It is worth noting that the number produced by this method is not
guaranteed to be unique. However, we have not found this to be a significant
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 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
and math calls from scratch. Newlib is a BSD-derived ANSI C library,
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
as the glob, regexp, and getopt libraries saved us considerable
@ -258,8 +270,8 @@ malloc if it so desires.</para>
</sect2>
<sect2 id="ov-hi-process"><title>Process Creation</title>
<para>The fork call in Cygwin is particularly interesting because it
does not map well on top of the Win32 API. This makes it very
<para>The <function>fork</function> call in Cygwin is particularly interesting
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
non-copy-on-write implementation similar to what was present in early
flavors of UNIX.</para>
@ -335,26 +347,43 @@ it.</para>
</sect2>
<sect2 id="ov-hi-sockets"><title>Sockets</title>
<para>Socket-related calls in Cygwin simply
call the functions by the same name in Winsock, Microsoft's
implementation of Berkeley sockets. Only a few changes were needed to
match the expected UNIX semantics - one of the most troublesome
differences was that Winsock must be initialized before the first
socket function is called. As a result, Cygwin has to perform this
initialization when appropriate. In order to support sockets across
fork calls, child processes initialize Winsock if any inherited file
descriptor is a socket.</para>
<para>Socket-related calls in Cygwin basically call the functions by the
same name in Winsock, Microsoft's implementation of Berkeley sockets, but
with lots of tweaks. All sockets are non-blocking under the hood to allow
to interrupt blocking calls by POSIX signals. Additional bookkeeping is
necessary to implement correct socket sharing POSIX semantics and especially
for the select call. Some socket-related functions are not implemented at
all in Winsock, as, for example, socketpair. Starting with Windows Vista,
Microsoft removed the legacy calls <function>rcmd(3)</function>,
<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 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
dismay, we discovered that the Win32 select in Winsock only worked on
socket handles. Our implementation allows select to function normally

436
winsup/doc/pathnames.sgml
View File

@ -1,6 +1,6 @@
<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
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>
<para>The <command>mount</command> utility program is used to
to map Win32 drives and network shares into Cygwin's internal POSIX
directory tree. This is a similar concept to the typical UNIX mount
program. For those people coming from a Windows background, the
<command>mount</command> utility is very similar to the old DOS
<command>join</command>, in that it makes your drive letters appear as
subdirectories somewhere else.</para>
<para>The <filename>/etc/fstab</filename> file is used to map Win32
drives and network shares into Cygwin's internal POSIX directory tree.
This is a similar concept to the typical UNIX fstab file. The mount
points stored in <filename>/etc/fstab</filename> are globally set for
all users. Sometimes there's a requirement to have user specific
mount points. The Cygwin DLL supports user specific fstab files.
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
<firstterm>mount table</firstterm> in the Windows registry so that the
information will be retrieved next time the user logs in. Because it
is sometimes desirable to have system-wide as well as user-specific
mounts, there is also a system-wide mount table that all Cygwin users
inherit. The system-wide table may only be modified by a user with
the appropriate privileges (Administrator privileges in Windows
NT).</para>
<para>The file fstab contains descriptive information about the various file
systems. fstab is only read by programs, and not written; it is the
duty of the system administrator to properly create and maintain this
file. Each filesystem is described on a separate line; fields on each
line are separated by tabs or spaces. Lines starting with '#' are
comments.</para>
<para>The current user's table is located under
"HKEY_CURRENT_USER/Software/Cygnus Solutions/Cygwin/mounts
v&lt;version&gt;"
where &lt;version&gt; is the latest registry version associated with
the Cygwin library (this version is not the same as the release
number). The system-wide table is located under the same subkeys
under HKEY_LOCAL_SYSTEM. The user mount table takes precedence over
the system-wide table if a path is mounted in both. This includes the
setting of the cygdrive prefix.</para>
<para>The first field describes the block special device or
remote filesystem to be mounted. On Cygwin, this is the native Windows
path which the mount point links in. As path separator you MUST use a
slash. Usage of a backslash might lead to unexpected results. UNC
paths (using slashes, not backslashes) are allowed. If the path
contains spaces these can be escaped as <literal>'\040'</literal>.</para>
<para>The <command>mount</command> command can set the POSIX root
<filename>/</filename> to any directory in the Windows file system.
In absence of such a mount, Cygwin maps <filename>/</filename> to the
root of the current Windows working directory (for example,
<filename>H:\</filename> or <filename>\\computer\share</filename>).
Normally Cygwin's <command>setup.exe</command> creates the initial
mount point for the POSIX root.
</para>
<para>The second field describes the mount point for the filesystem.
If the name of the mount point contains spaces these can be
escaped as '\040'.</para>
<para>The third field describes the type of the filesystem.
Cygwin supports any string here, since the file system type is usually
not evaluated. The noticable exception is the file system type
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
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.
</para>
<para>Invoking <command>mount</command> without any arguments displays
Cygwin's current set of mount points.
In the following example, the C
drive is the POSIX root and D drive is mapped to
<filename>/d</filename>. Note that in this case, the root mount is a
system-wide mount point that is visible to all users running Cygwin
programs, whereas the <filename>/d</filename> mount is only visible
to the current user.</para>
<para>If you want to see the current set of mount points valid in your
session, you can invoking the Cygwin tool <command>mount</command> without
arguments:</para>
<example>
<example id="pathnames-mount-ex">
<title>Displaying the current set of mount points</title>
<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\lib on /usr/lib 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
new mount points, and the <command>umount</command> to delete
them. See <xref linkend="mount"></xref> and <xref linkend="umount"></xref> for more
information on how to use these utilities to set up your Cygwin POSIX
file system.</para>
them. However, since they are only noted in memory, these mount
points will disappear as soon as your last Cygwin process ends.
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
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
mount table, then <filename>Z:\</filename> would be automatically
converted to <filename>/cygdrive/Z</filename>. The default
prefix of <filename>/cygdrive</filename> may be changed (see the
<xref linkend="mount"></xref> for more information).</para>
<para>It is possible to assign some special attributes to each mount
point. Automatically mounted partitions are displayed as "auto"
mounts. Mounts can also be marked as either "textmode" or "binmode"
-- whether text files are read in the same manner as binary files by
default or not (see <xref linkend="using-textbinary"></xref> for more
information on text and binary modes.</para>
prefix of <filename>/cygdrive</filename> may be changed in the fstab file
as outlined above.</para>
</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
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>
<sect2> <title>DOS devices</title>
<sect2 id="pathnames-dosdevices">
<title>DOS devices</title>
<para>Windows filenames invalid under Windows are also invalid under
Cygwin. This means that base filenames such as
<para>Filenames invalid under Win32 are not necessarily invalid
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>LPT1</filename> or <filename>PRN</filename> (to name a few)
cannot be used in a regular Cygwin Windows or POSIX path, even with an
extension (<filename>prn.txt</filename>). However the special names can be
used as filename extensions (<filename>file.aux</filename>). You can use
the special names as you would under DOS, for example you can print on your
default printer with the command <command>cat filename > PRN</command>
(make sure to end with a Form Feed).
</para>
cannot be used in a native Win32 application, even with an
extension (<filename>prn.txt</filename>). Cygwin can handle files with
these names just fine.</para>
</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>
directory as Cygwin automatically simulates it internally.
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>
script.
</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>
Cygwin supports the following devices commonly found on POSIX systems:
<filename>/dev/dsp</filename>, <filename>/dev/null</filename>,
<filename>/dev/zero</filename>, <filename>/dev/console</filename>,
<filename>/dev/tty</filename>, <filename>/dev/ttym</filename>,
<filename>/dev/ttyX</filename>, <filename>/dev/ttySX</filename>,
<filename>/dev/pipe</filename>, <filename>/dev/port</filename>,
<filename>/dev/ptmx</filename>, <filename>/dev/mem</filename>,
<filename>/dev/random</filename>, and <filename>/dev/urandom</filename>.
Some other POSIX devices, such as
<filename>/dev/kmem</filename>, are planned for development.
Cygwin also has several Windows-specific devices:
<filename>/dev/comX</filename> (the serial ports, starting with
<filename>COM1</filename> which is the same as <filename>ttyS0</filename>),
<filename>/dev/conin</filename> (Windows <filename>CONIN$</filename>),
<filename>/dev/conout</filename> (Windows <filename>CONOUT$</filename>),
<filename>/dev/clipboard</filename> (the Windows clipboard, currently
text only), and <filename>/dev/windows</filename> (the Windows message
queue).
</para>
<para>Windows NT/W2K/XP additionally support raw devices like floppies,
disks, partitions and tapes. These are accessed from Cygwin applications
using POSIX device names which are supported in two different ways.
</para>
<screen>
/dev/com1 The serial ports, starting with COM1 which is the same as ttyS0.
/dev/com2 Please use /dev/ttySx instead.
...
<para>Up to Cygwin 1.3.3 the only way to access those devices was
to mount the Win32 device names to a POSIX device name but this usage
is discouraged since Cygwin 1.3.4 and only kept for backward compatibility.
</para>
/dev/conin Same as Windows CONIN$.
/dev/conout Same as Windows CONOUT$.
/dev/clipboard The Windows clipboard, text only
/dev/windows The Windows message queue.
</screen>
<para>
Beginning with Cygwin 1.3.4, raw devices are accessible by Cygwin processes
using fixed POSIX device names. These fixed POSIX device names are generated
using a direct conversion from the POSIX namespace to the internal NT namespace.
Block devices are accessible by Cygwin processes using fixed POSIX device
names. These POSIX device names are generated using a direct conversion
from the POSIX namespace to the internal NT namespace.
E.g. the first harddisk is the NT internal device \device\harddisk0\partition0
or the first partition on the third harddisk is \device\harddisk2\partition1.
The first floppy in the system is \device\floppy0, the first CD-ROM is
\device\cdrom0 and the first tape drive is \device\tape0.
\device\cdrom0 and the first tape drive is \device\tape0. The mapping
to the POSIX /dev namespace is as follows:
</para>
<para>The new fixed POSIX names are mapped to NT internal devices as
follows:</para>
<screen>
/dev/st0 \device\tape0, rewind
/dev/nst0 \device\tape0, no-rewind
/dev/st1 \device\tape1
/dev/nst1 \device\tape1
...
/dev/st15
/dev/nst15
/dev/fd0 \device\floppy0
/dev/fd1 \device\floppy1
...
/dev/scd0 \device\cdrom0
/dev/scd1 \device\cdrom1
...
/dev/fd15
/dev/sr0 \device\cdrom0
/dev/sr1 \device\cdrom1
...
/dev/sr15
/dev/scd0 \device\cdrom0
/dev/scd1 \device\cdrom1
...
/dev/scd15
/dev/sda \device\harddisk0\partition0 (whole disk)
/dev/sda1 \device\harddisk0\partition1 (first partition)
@ -249,10 +429,10 @@ follows:</para>
[up to]
/dev/sdl \device\harddisk11\partition0
/dev/sdl1 \device\harddisk11\partition1
/dev/sddx \device\harddisk127\partition0
/dev/sddx1 \device\harddisk127\partition1
...
/dev/sdl15 \device\harddisk11\partition15
/dev/sddx15 \device\harddisk127\partition15
</screen>
<para>
@ -261,32 +441,16 @@ links as they are created on Linux systems for convenience:
</para>
<screen>
ln -s /dev/scd0 /dev/cdrom
ln -s /dev/sr0 /dev/cdrom
ln -s /dev/nst0 /dev/tape
...
</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><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,
so that traditional UNIX names can be used. However, for programs that
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
for UNIX systems to work well under Cygwin.</para>
<para>Unfortunately, the <command>install</command> and
<command>strip</command> commands do distinguish between
<filename>filename</filename> and <filename>filename.exe</filename>. They
fail when working on a non-existing <filename>filename</filename> even if
<filename>filename.exe</filename> exists, thus breaking some makefiles.
This problem can be solved by writing <command>install</command> and
<command>strip</command> shell scripts to provide the extension ".exe"
when needed.
</para>
</sect2>
<sect2><title>The /proc filesystem</title>
<sect2 id="pathnames-proc"><title>The /proc filesystem</title>
<para>
Cygwin, like Linux and other similar operating systems, supports the
<filename>/proc</filename> virtual filesystem. The files in this
@ -344,7 +499,12 @@ is <filename>/proc/registry</filename>, which displays the Windows
registry with each <literal>KEY</literal> as a directory and each
<literal>VALUE</literal> as a file. As anytime you deal with the
Windows registry, use caution since changes may result in an unstable
or broken system.
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>
The Cygwin <filename>/proc</filename> is not as complete as the
@ -354,7 +514,7 @@ that use it.
</para>
</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
Windows command shells, Cygwin programs expand their arguments
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
<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>
<prompt>bash$</prompt> <userinput>echo 'This is "a long" line' > 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>.
</para>
<sect2><title>Download Source</title>
<sect2 id="setup-download"><title>Download Source</title>
<para>
Cygwin uses packages to manage installing various software. When
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>
</sect2>
<sect2><title>Selecting an Install Directory</title>
<sect2 id="setup-dir"><title>Selecting an Install Directory</title>
<para>
The <literal>Root Directory</literal> for Cygwin (default
<literal>C:\cygwin</literal>) will become <literal>/</literal>
@ -97,7 +97,7 @@ have a very good reason to switch it to
</para>
</sect2>
<sect2><title>Local Package Directory</title>
<sect2 id="setup-localdir"><title>Local Package Directory</title>
<para>
The <literal>Local Package Directory</literal> is the cache where
<command>setup.exe</command> stores the packages before they are
@ -111,7 +111,7 @@ or in case you need to reinstall a package.
</para>
</sect2>
<sect2><title>Connection Method</title>
<sect2 id="setup-connection"><title>Connection Method</title>
<para>
The <literal>Direct Connection</literal> method of downloading will
directly download the packages, while the IE5 method will leverage your
@ -124,7 +124,7 @@ authorization for proxy servers.
</para>
</sect2>
<sect2><title>Choosing Mirrors</title>
<sect2 id="setup-mirror"><title>Choosing Mirrors</title>
<para>
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
@ -137,7 +137,7 @@ mirror) you can add it.
</para>
</sect2>
<sect2><title>Choosing Packages</title>
<sect2 id="setup-packages"><title>Choosing Packages</title>
<para>
For each selected mirror site, <command>setup.exe</command> downloads a
small text file called <literal>setup.bz2</literal> that contains a list
@ -201,7 +201,7 @@ stable version.
</para>
</sect2>
<sect2><title>Download and Installation Progress</title>
<sect2 id="setup-progress"><title>Download and Installation Progress</title>
<para>
First, <command>setup.exe</command> will download all selected packages
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>
</sect2>
<sect2><title>Icons</title>
<sect2 id="setup-icons"><title>Icons</title>
<para>
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
@ -221,7 +221,7 @@ use these shortcuts as a guide to creating your own.
</para>
</sect2>
<sect2><title>Post-Install Scripts</title>
<sect2 id="setup-postinstall"><title>Post-Install Scripts</title>
<para>
Last of all, <command>setup.exe</command> will run any post-install
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.
</para>
</sect2>
<sect2><title>Troubleshooting</title>
<sect2 id="setup-troubleshooting"><title>Troubleshooting</title>
<para>
Unfortunately, the complex setup process means that odd problems can
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
applications as a list of directories to search for executable files
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>/WinNT/system32:/WinNT</filename>) when a Cygwin
process first starts.
(e.g. <filename>C:\Windows\system32;C:\Windows</filename>) to UNIX format
(e.g., <filename>/cygdrive/c/Windows/system32:/cygdrive/c/Windows</filename>)
when a Cygwin process first starts.
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
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>
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
defined. This environment variable is also converted from Windows format
when a Cygwin process first starts. Set it to point to your home directory
before launching bash.
when a Cygwin process first starts. It's usually set in the shell
profile scripts in the /etc directory.
</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:
<screen>
regtool -i set /HKLM/Software/Cygnus\ Solutions/Cygwin/heap_chunk_in_mb 1024
regtool -v list /HKLM/Software/Cygnus\ Solutions/Cygwin
regtool -i set /HKLM/Software/Cygwin/heap_chunk_in_mb 1024
regtool -v list /HKLM/Software/Cygwin
</screen>
</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.
</para>
</sect1>
<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>
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
that "Quick Edit" is checked and "Fast Pasting" isn't. These settings
will be remembered next time you run bash from that
shortcut. Similarly you can set the working directory inside the
"Program" tab. The entry "%HOME%" is valid.
that "QuickEdit mode" and "Insert mode" are checked. These settings
will be remembered next time you run bash from that shortcut. Similarly
you can set the working directory inside the "Program" tab. The entry
"%HOME%" is valid, but requires that you set <envar>HOME</envar> in
the Windows environment.
</para>
<para>
Your home directory should contain three initialization files
that control the behavior of bash. They are
<filename>.profile</filename>, <filename>.bashrc</filename> and
<filename>.inputrc</filename>. These initialization files will only
be read if <envar>HOME</envar> is defined before starting bash.
</para>
<filename>.inputrc</filename>. The Cygwin base installation creates
stub files when you start bash for the first time.</para>
<para>
<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>
<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
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><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
are to be opened when the mode is not specified explicitly.
@ -49,22 +49,8 @@ backslash or a colon), the default is binary.
<listitem>
<para>Pipes and non-file devices are opened in binary mode,
except if the <envar>CYGWIN</envar> environment variable contains
<literal>nobinmode</literal>.</para>
<warning><title>Warning!</title><para>In b20.1 of 12/98, a file will be opened
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>
<literal>nobinmode</literal>. Sockets are always opened in binary
mode.</para>
</listitem>
<listitem>
@ -79,7 +65,7 @@ and <command> program &lt; filename </command> are not equivalent when
</orderedlist>
</sect2>
<sect2><title>Example</title>
<sect2 id="textbin-example"><title>Example</title>
<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
to standard output.
@ -115,7 +101,7 @@ In the second case we rely on the DOS shell to redirect in binary mode.
</para>
</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
will know the difference between text and binary files and act
@ -150,7 +136,7 @@ in binary mode.</para>
</sect2>
<sect2><title>Programming</title>
<sect2 id="textbin-devel"><title>Programming</title>
<para>In the <function>open()</function> function call, binary mode can be
specified with the flag <literal>O_BINARY</literal> and text mode with