libs/newlib-cygwin
libs/newlib-cygwin
4
0
Fork 0
mirror of git://sourceware.org/git/newlib-cygwin.git synced 2025-02-20 07:51:35 +08:00
Code Issues Projects Releases Wiki Activity

* Various syntactical and semantical fixes throughout.

Browse Source
This commit is contained in:
Corinna Vinschen 2009-04-03 11:51:31 +00:00
parent d10a1e5154
commit f5e097fa4b
10 changed files with 190 additions and 176 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 @@
2009-04-03 Kevin Buettner <kevinb@redhat.com>
* Various syntactical and semantical fixes throughout.
2009-04-01 Corinna Vinschen <corinna@vinschen.de>
* faq-using.xml (faq.using.symlinkstoppedworking): Rename.

8
winsup/doc/cygserver.sgml
View File

@ -53,7 +53,7 @@
<screen>-f, --config-file &lt;file&gt;</screen>
<para>
Use &lt;file&gt; as configuration file instead of the default configuration
line. The default configuration file is /etc/cygserver.conf, typically.
line. The default configuration file is /etc/cygserver.conf.
The --help and --version options will print the default configuration
pathname.
</para>
@ -194,10 +194,10 @@
<sect2 id="cygserver-config"><title>The Cygserver configuration file</title>
<para>
Cygserver has many options, which allow to customize the server
Cygserver has many options, which allow you to customize the server
to your needs. Customization is accomplished by editing the configuration
file, which is by default /etc/cygserver.conf. This file is read only
once on startup of Cygserver. There's no option to re-read the file on
file, which is by default /etc/cygserver.conf. This file is only read
once, at startup of Cygserver. There's no option to re-read the file at
runtime by, say, sending a signal to Cygserver.
</para>
<para>

31
winsup/doc/cygwinenv.sgml
View File

@ -44,7 +44,7 @@ There is no default set.
</listitem>
<listitem>
<para><envar>forkchunk:32768</envar> - causes the <function>fork()</function>
<para><envar>forkchunk:32768</envar> - causes <function>fork()</function>
to copy memory some number of bytes at a time, in the above example
32768 bytes (32Kb) at a time. The default is to copy as many bytes as
possible, which is preferable in most cases but may slow some older systems
@ -53,9 +53,10 @@ down.
</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><envar>proc_retry:n</envar> - causes <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>
@ -103,11 +104,11 @@ other terminals (i.e., rxvt or xterm).
<listitem>
<para><envar>(no)upcaseenv</envar> - if set, Cygwin converts all
environment variables to all-uppercase, when a Cygwin process is started
from a non-Cygwin native Windows process. This is how it has been done
until Cygwin 1.5. If not set, Cygwin does not change the case of environment
variables, except for a restricted set to maintain minimal backward
compatibility and for correct handling of certain essential variables.
The current list of always uppercased variables is:</para>
from a non-Cygwin native Windows process. This was the default behavior in
releases prior to Cygwin 1.7. If not set, Cygwin does not change the case
of environment variables, except for a restricted set to maintain minimal
backward compatibility and for correct handling of certain essential
variables. The current list of always uppercased variables is:</para>
<screen>
ALLUSERSPROFILE
COMMONPROGRAMFILES
@ -152,11 +153,12 @@ old symlinks used the current ANSI or OEM charset.</para>
</sect2>
<sect2 id="cygwinenv-removed-options">
<title>Removed options</title>
<title>Obsolete 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>
Certain CYGWIN options available in past releases have been removed in
Cygwin 1.7 for one reason or another. These obsolete options are listed
below.</para>
<itemizedlist mark="bullet">
@ -181,7 +183,7 @@ is now doing all character conversion by itself, depending on the
application call to the <function>setlocale()</function> function, and in
turn by the setting of the environment variables <envar>$LANG</envar>,
<envar>$LC_ALL</envar>, or <envar>$LC_CTYPE</envar>, this setting
got useless.</para>
became superfluous.</para>
</listitem>
<listitem>
@ -221,7 +223,8 @@ Cygwin.</para>
<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>
it's behaviour has been getting worse with each new OS version. This
complicates its usage so the option has been removed for now.</para>
</listitem>
</itemizedlist>

26
winsup/doc/new-features.sgml
View File

@ -1,9 +1,9 @@
<sect1 id="ov-new1.7"><title>What's new and what changed in Cygwin 1.7</title>
<sect2 id="ov-new1.7-os"><title>OS releated changes</title>
<sect2 id="ov-new1.7-os"><title>OS related changes</title>
<screen>
- Windows 95, 98 and Me are not supported anymore. The new Cywin 1.7 DLL
- Windows 95, 98 and Me are not supported anymore. The new Cygwin 1.7 DLL
will not run on any of these systems.
</screen>
@ -21,7 +21,7 @@
the character will be converted to a sequence Ctrl-N + UTF-8 representation
of the character. This allows to access all files, even those not
having a valid representation of their filename in the current character
set (codepage). To have always a valid string, use the UTF-8 charset
set (codepage). To always have a valid string, use the UTF-8 charset
by setting the environment variable $LANG, $LC_ALL, or $LC_CTYPE to a
valid POSIX value, for instance in Cygwin.bat like this:
@ -48,7 +48,7 @@
- Creating files with special DOS device filename components ("aux",
"nul", "prn") is supported.
- File name are case sensitive if the OS and the underlying file system
- File names are case sensitive if the OS and the underlying file system
supports it. Works on NTFS and NFS. Does not work on FAT and Samba
shares. Requires to change a registry key (see the user's guide).
Can be switched off on a per-mount base.
@ -79,7 +79,7 @@
default again when creating symlinks. Only create Windows shortcut
style symlinks if CYGWIN=winsymlinks is set in the environment.
- Symlinks are now using UTF-16 encoding for the target filename for
- Symlinks now use UTF-16 encoding for the target filename for
better internationalization support. Cygwin 1.7 can read all old style
symlinks, but the new style is not compatible with older Cygwin releases.
@ -241,20 +241,20 @@
script. The advantages and disadvantages are noted in
http://cygwin.com/ml/cygwin-developers/2006-11/msg00000.html
- Cygwin now allows to store and use user passwords in a hidden area of
- Cygwin now allows storage and use of user passwords in a hidden area of
the registry. This is tried first when Cygwin is called by privileged
processes to switch the user context. This allows, for instance,
ssh public key sessions with full network credentials to access shares
on other machines.
- The mkpasswd and mkgroup tools have changed behaviour and a couple of
new options to ease consistent usage in multi-machine or multi-domain
environments.
- New options have been added to the mkpasswd and mkgroup tools to
ease use in multi-machine and multi-domain environments. The existing
options have a slightly changed behaviour.
</screen>
</sect2>
<sect2 id="ov-new1.7-misc"><title>Miscellanous</title>
<sect2 id="ov-new1.7-misc"><title>Miscellaneous</title>
<screen>
- New ldd utility, similar to Linux.
@ -265,8 +265,8 @@
since they don't understand these paths.
- On the first usage of a DOS path (C:\foo, \\foo\bar), the Cygwin DLL
emits a scary warning that DOS paths shouldn't be used. There's also
the new CYGWIN=nodosfilewarning setting to disable that.
emits a scary warning that DOS paths shouldn't be used. This warning
may be disabled via the new CYGWIN=nodosfilewarning setting.
- The CYGWIN environment variable option "server" has been removed.
Cygwin automatically uses cygserver if it's available.
@ -294,7 +294,7 @@
- Optimized strstr and memmem implementation.
- Remove backwards compatibility with old signal masks (some *very* old
- Remove backwards compatibility with old signal masks. (Some *very* old
programs which use signal masks may no longer work correctly).
</screen>

114
winsup/doc/ntsec.sgml
View File

@ -153,11 +153,11 @@ SIDs</ulink>. The Cygwin package called "csih" provides a tool,
/usr/lib/csih/getAccountName.exe, which can be used to print the
(possibly localized) name for the various well-known SIDS.</para>
<para>Naturally well-known SIDs are the same on each machine, so they are
<para>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,
<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>
@ -202,7 +202,7 @@ 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. But there's a problem with the definition of a "correct" ACL
which disallows to map certain POSIX permissions cleanly. See
which disallows mapping of certain POSIX permissions cleanly. See
<xref linkend="ntsec-mapping"></xref>.</para>
<para>POSIX is able to create only three different permissions? Not quite.
@ -295,8 +295,8 @@ 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>
all is well. This allows you to, for instance, rename the "Administrators"
group to "root" as well:</para>
<example id="ntsec-group-tweaked">
<title>/etc/group, tweaked:</title>
@ -305,26 +305,29 @@ root:S-1-5-32-544:544:
</screen>
</example>
<para>Last but not least you can also change the primary group of a user
<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". So, if it's
more feasible in your environment that the user's primary group is
which in turn belongs to the well-known group "Users". So, if it's
more convenient in your environment for the user's primary group to be
"Users", just set the user's primary group in <filename>/etc/passwd</filename>
to the Cygwin uid of "Users" (see in <filename>/etc/group</filename>,
default 545) and let the user create files with a default group ownership
of "Users".</para>
<para>However, here's a WARNING: If you want to do similar changes to
your files, please do that only if you're feeling comfortable with the
concepts. Otherwise don't be surprised if some stuff doesn't work
anymore. If you screwed up things, revert to <filename>/etc/passwd</filename>
and <filename>/etc/group</filename> files created by mkpasswd
and mkgroup. Especially don't change the UID or the name of user
SYSTEM. Even if that works mostly, some Cygwin applications running as
local service under that account could suddenly start behaving
strangely.</para>
<note><para>
If you wish to make these kind of changes to /etc/passwd and /etc/group,
do so only if you feel comfortable with the concepts. Otherwise, do not
be surprised if things break in either subtle or surprising ways! If you
do screw things up, revert to copies of <filename>/etc/passwd</filename>
and <filename>/etc/group</filename> files created by
<command>mkpasswd</command> and <command>mkgroup</command>. (Make
backup copies of these files before modifying them.) Especially, don't
change the UID or the name of the user SYSTEM. It may mostly work, but
some Cygwin applications running as a local service under that account
could suddenly start behaving strangely.
</para></note>
</sect2>
@ -403,7 +406,7 @@ the possible confusion.
<sect2 id="ntsec-mapping"><title id="ntsec-mapping.title">The POSIX permission mapping leak</title>
<para>As promised earlier, here's the problem when trying to map the
POSIX permission model on the Windows permission model.</para>
POSIX permission model onto the Windows permission model.</para>
<para>There's a leak in the definition of a "correct" ACL which
disallows a certain POSIX permission setting. The official
@ -447,7 +450,8 @@ rw-r-xrw-
</screen>
<para>Ok, so here's the first try to create a matching ACL, assuming
the Windows permissions only have three bits, as their POSIX pendants:</para>
the Windows permissions only have three bits, as their POSIX counterpart:
</para>
<screen>
UserAllow: 110
@ -505,7 +509,7 @@ aren't able (or willing) to deal with that order.</para>
"Switch User" feature, which switches the entire desktop to another user
while leaving the original user's desktop "suspended". Another Windows
feature (since Windows 2000) is the "Run as..." context menu entry,
which allows to start an application using another user account when
which allows you to start an application using another user account when
right-clicking on applications and shortcuts.</para>
<para>On POSIX systems, this operation can be performed by processes
@ -531,7 +535,7 @@ with restricted permissions.</para>
<sect2 id="ntsec-logonuser"><title id="ntsec-logonuser.title">Switching the user context with password authentication</title>
<para>To switch the user context the process has to request such an access
<para>To switch the user context, the process has to request such an access
token for the new user. This is typically done by calling the Win32 API
function <command>LogonUser</command> with the user name and the user's
cleartext password as arguments. If the user exists and the password was
@ -549,13 +553,14 @@ these extensions to the original concept are important for this
documentation.</para>
<para>Back to this logon with password, how can this be used to
implement <command>set(e)uid</command>? Well, it requires to patch the
calling application. Two Cygwin functions have been introduced to support
porting <command>setuid</command> applications which only require login
with passwords. You only give Cygwin the right access token and then
you can call <command>seteuid</command> or <command>setuid</command> as
usual in POSIX applications. Porting such a <command>setuid</command>
application is illustrated by a short example:</para>
implement <command>set(e)uid</command>? Well, it requires modification
of the calling application. Two Cygwin functions have been introduced
to support porting <command>setuid</command> applications which only
require login with passwords. You only give Cygwin the right access
token and then you can call <command>seteuid</command> or
<command>setuid</command> as usual in POSIX applications. Porting such
a <command>setuid</command> application is illustrated by a short
example:</para>
<screen>
<![CDATA[
@ -608,26 +613,25 @@ application is illustrated by a short example:</para>
<sect2 id="ntsec-nopasswd1"><title id="ntsec-nopasswd1.title">Switching the user context without password, Method 1: Create a token from scratch</title>
<para>So far unfortunate for the implementation of a
<command>set(e)uid</command> call is the fact that the calling process
needs the password of the user it wants to switch to. Applications like
<para>An unfortunate aspect of the implementation of
<command>set(e)uid</command> is the fact that the calling process
requires the password of the user to which to switch. Applications such as
<command>sshd</command> wishing to switch the user context after a
successful public key authentication, or <command>cron</command> which
has to switch the user without any authentication are stuck here. But
there are other ways to get new user tokens.</para>
successful public key authentication, or the <command>cron</command>
application which, again, wants to switch the user without any authentication
are stuck here. But there are other ways to get new user tokens.</para>
<para>One way is just to create a user token from scratch. This is
accomplished by using an (officially undocumented) function on the NT
function level. The NT function level is closer to the actual kernel
than the Win32 level. Actually the Win32 functions are implemented
using the NT functions. The function we're interested in is
<command>NtCreateToken</command>. This function allows to specify
user, groups, permissions and almost everything you need to create
a user token, without the need to specify the user password. The
function level. The NT function level is used to implement the Win32
level, and, as such is closer to the kernel than the Win32 level. The
function of interest, <command>NtCreateToken</command>, allows you to
specify user, groups, permissions and almost everything you need to
create a user token, without the need to specify the user password. The
only restriction for using this function is that the calling process
needs the "Create a token object" user right, which only the
SYSTEM user account has by default, and which is considered the most
dangerous right a user can have on Windows systems.</para>
needs the "Create a token object" user right, which only the SYSTEM user
account has by default, and which is considered the most dangerous right
a user can have on Windows systems.</para>
<para>That sounds good. We just start the servers which have to switch
the user context (<command>sshd</command>, <command>inetd</command>,
@ -639,23 +643,23 @@ has a few drawbacks.</para>
<para>First of all, beginning with Windows Server 2003,
the permission "Create a token object" gets explicitely removed from
the SYSTEM user's access token, when starting services under that
account. That requires to create a new account with this specific
account. That requires us to create a new account with this specific
permission just to run this kind of services. But that's a minor
problem.</para>
<para>A more important problem is that using <command>NtCreateToken</command>
is not sufficient to create a new logon session for the new user. What
does that mean? Every logon usually creates also a new logon session.
does that mean? Every logon usually creates a new logon session.
A logon session has a couple of attributes which are unique to the
session. One of these attributes is the fact, that Windows functions
identify the user domain and user name not by the SID of the access
token owner, but only by the logon session the process is running under.</para>
<para>What that means is this. Consider a service started under the
SYSTEM account (up to Windows XP) switches the user context to
DOMAIN\my_user using a token created directly by calling the
<command>NtCreateToken</command> function. A process running under this
new access token might want to know under which user account it's
<para>This has the following unfortunate consequence. Consider a
service started under the SYSTEM account (up to Windows XP) switches the
user context to DOMAIN\my_user using a token created directly by calling
the <command>NtCreateToken</command> function. A process running under
this new access token might want to know under which user account it's
running. The corresponding SID is returned correctly, for instance
S-1-5-21-1234-5678-9012-77777. However, if the same process asks the OS
for the user name of this SID something wierd happens. For instance,
@ -703,7 +707,7 @@ bash$ grep foo //server/share/foofile
with Windows 2000. Windows NT4 users have to use one of the other
methods described in this document.</para>
<para>So we're looking for another way to switch the user context without
<para>We're looking for another way to switch the user context without
having to provide the password. Another technique is to create an
LSA authentication package. LSA is an acronym for "Local Security Authority"
which is a protected part of the operating system which only allows changes
@ -748,8 +752,6 @@ using <command>NtCreateToken</command>, isn't it?</para>
</sect2>
<!-- TODO: The rest of the file... -->
<sect2 id="ntsec-nopasswd3"><title id="ntsec-nopasswd3.title">Switching the user context without password, Method 3: With password</title>
<para>Ok, so we have solved almost any problem, except for the network
@ -759,11 +761,11 @@ script is a harsh problem for automated logons for testing purposes
and similar stuff.</para>
<para>Fortunately there is a solution, but it has its own drawbacks.
But first thing first, how does it work? The title of this section
But, first things first, how does it work? The title of this section
says it all. Instead of trying to logon without password, we just logon
with password. The password gets stored two-way encrypted in a hidden,
obfuscated area of the registry, the LSA private registry area. This
part of the registry contains for instance the passwords of the Windows
part of the registry contains, for instance, the passwords of the Windows
services which run under some non-default user account.</para>
<para>So what we do is to utilize this registry area for the purpose of
@ -825,7 +827,7 @@ safely use this method.</para>
</sect2>
<sect2 id="ntsec-setuid-impl"><title id="ntsec-setuid-impl.title">Switching the user context, how does that all fit together?</title>
<sect2 id="ntsec-setuid-impl"><title id="ntsec-setuid-impl.title">Switching the user context, how does it all fit together?</title>
<para>Now we learned about four different ways to switch the user
context using the <command>set(e)uid</command> system call, but

4
winsup/doc/overview.sgml
View File

@ -66,8 +66,8 @@ url="http://www.usenix.org/publications/library/proceedings/usenix-nt98/technica
</para>
</note>
<para>
Cygwin began development in 1995 at Cygnus Solutions (now part of Red Hat
Software). The first thing done was to enhance the development tools
Cygwin began development in 1995 at Cygnus Solutions (now part of Red Hat,
Inc.). The first thing done was to enhance the development tools
(<command>gcc</command>, <command>gdb</command>, <command>gas</command>,
etc.) so that they could generate and interpret Win32 native
object files.

76
winsup/doc/overview2.sgml
View File

@ -193,17 +193,17 @@ versa. Shell scripts and Makefiles cannot call these functions directly.
Instead, they can do the same path translations by executing the
<command>cygpath</command> utility program that we provide with Cygwin.</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>Win32 applications handle filenames in a case preserving, but case
insensitive manner. 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 usually the default.</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>
including Windows Server 2003 R2. Native symlinks are available starting
with Windows Vista. Due to their strange implementation, however,
they are not useful in a POSIX emulation layer. Cygwin recognizes
native symlinks, but does not create them.</para>
<para>Symbolic links are potentially created in two different ways.
The file style symlinks are files containing a magic cookie followed by
@ -240,10 +240,10 @@ problem because of the low probability of generating a duplicate inode number.
<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
privileged call. Any user may call it. Second, the chroot environment
isn't safe against native windows processes. If you want to use a
chroot environment to, for example, allow anonymous ftp with restricted
access, you must make sure 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
@ -253,22 +253,24 @@ Win32 paths containing drive letter and/or backslashes as well as UNC paths
</sect2>
<sect2 id="ov-hi-textvsbinary"><title>Text Mode vs. Binary Mode</title>
<para>Interoperability with other Win32 programs such as text editors was
critical to the success in the early days of Cygwin. Most Red Hat
customers upgrading from the older DOS-hosted toolchains expected the new
Win32-hosted ones to continue to work with their old development
sources.</para>
<para>It is often important that files created by native Windows
applications be interoperable with Cygwin applications. For example, a
file created by a native Windows text editor should be readable by a
Cygwin application, and vice versa.</para>
<para>Unfortunately, UNIX and Win32 use different end-of-line terminators in
text files. Consequently, carriage-return newlines have to be translated on
the fly by Cygwin into a single newline when reading in text mode.</para>
<para>Unfortunately, UNIX and Win32 have different end-of-line
conventions in text files. A UNIX text file will have a single newline
character (LF) whereas a Win32 text file will instead use a two
character sequence (CR+LF). Consequently, the two character sequence
must be translated on the fly by Cygwin into a single character newline
when reading in text mode.</para>
<para>This solution addresses the compatibility requirement at the expense of
violating the POSIX standard that states that text and binary mode will be
identical. Consequently, processes that attempt to lseek through text files can
no longer rely on the number of bytes read as an accurate indicator of position
in the file. For this reason, Cygwin allows to choose the mode in which to
read a file in several ways.</para>
<para>This solution addresses the newline interoperability concern at
the expense of violating the POSIX requirement that text and binary mode
be identical. Consequently, processes that attempt to lseek through
text files can no longer rely on the number of bytes read to be an
accurate indicator of position within the file. For this reason, Cygwin
allows you to choose the mode in which a file is read in several ways.</para>
</sect2>
<sect2 id="ov-hi-ansiclib"><title>ANSI C Library</title>
@ -388,17 +390,17 @@ 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>
supports the getpeereid BSD extension. However, Cygwin does not yet support
descriptor passing.</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>IPv6 is supported beginning with Cygwin release 1.7.0. This
support is dependent, however, on the availability of the Windows IPv6
stack. The IPv6 stack was "experimental", i.e. not feature complete in
Windows 2003 and earlier. Full IPv6 support became available starting
with Windows Vista and Windows Server 2008. Cygwin does not depend on
the underlying OS for the (newly implemented) <function>getaddrinfo</function>
and <function>getnameinfo</function> functions. Cygwin 1.7.0 adds
replacement functions which implement the full functionality for IPv4.</para>
</sect2>

35
winsup/doc/pathnames.sgml
View File

@ -56,7 +56,7 @@ 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
not evaluated. The notable 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
@ -323,7 +323,7 @@ are invalid filenames for native Win32 applications.</para>
<para>This restriction doesn't apply to Cygwin applications. Cygwin
can create and access files with such names just fine. Just don't try
to use these files with native Win32 aqpplications...</para>
to use these files with native Win32 applications.</para>
</sect2>
@ -332,8 +332,8 @@ to use these files with native Win32 aqpplications...</para>
<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
all of them are removed before the file is created. This restriction only
affects 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>
@ -358,17 +358,17 @@ character set (see <xref linkend="setup-locale"></xref>) then there's a
chance that a filename is using one or more characters which have no
representation in the character set you're using.</para>
<para>For instance, there are no chinese characters in the ISO-8859-1
character set. So, converting a filename containing a chinese character
to ISO-8859-1 leaves you with a wrongly converted filename, for instance
<para>For instance, there are no Chinese characters in the ISO-8859-1
character set. So, converting a filename containing a Chinese character
to ISO-8859-1 leaves you with a wrongly converted filename, for instance,
containing a question mark '?' as replacement for the unconvertable
character. When trying to access the file, Cygwin has to convert the
filename back to UTF-16. However, this doesn't result in the original
filename because the question mark will not translate back to the original
chinese character, but to a simple question mark instead. This in turn
Chinese character, but to a simple question mark instead. This in turn
results in strange "File not found" messages.</para>
<note><para>To avoid this scenario altogether, just use always UTF-8 as
<note><para>To avoid this scenario altogether, always use UTF-8 as the
character set.</para></note>
<para>If you don't want or can't use UTF-8 as character set for whatever
@ -451,7 +451,7 @@ The reason is that the native Windows %PATH% environment variable is not
always using the correct case for all paths in it. As a result, if you use
case-sensitivity on the <filename>/cygdrive</filename> prefix, your shell
might claim that it can't find Windows commands like <command>attrib</command>
or <command>net</command>. To ease the pain the <filename>/cygdrive</filename>
or <command>net</command>. To ease the pain, the <filename>/cygdrive</filename>
path is case-insensitive by default and you have to use the "posix=1" setting
explicitely in <filename>/etc/fstab</filename> or
<filename>/etc/fstab.d/$USER</filename> to switch it to case-sensitivity,
@ -460,7 +460,7 @@ is using the correct case for all paths throughout.</para>
<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
the subdirectories and filenames under /proc/registry, /proc/registry32
and /proc/registry64. Registry access is always case-insensitive.
Read on for more information.</para>
@ -547,16 +547,17 @@ The first floppy in the system is \device\floppy0, the first CD-ROM is
<para>The mapping from physical device to the name of the device in the
internal NT namespace can be found in various places. For hard disks and
CD/DVD drives the Windows "Disk management" (part of the "Computer Management"
console) shoes the mapping "Disk 0" is \device\harddisk0, "CD-ROM 2" is
\device\cdrom2. Another place to find this mapping is the "Device Management"
console. Disks have a "Location" number, tapes have a "Tape Symbolic Name",
etc. Unfortunately the places where to find this information is not very
CD/DVD drives, the Windows "Disk Management" utility (part of the
"Computer Management" console) shows that the mapping of "Disk 0" is
\device\harddisk0. "CD-ROM 2" is \device\cdrom2. Another place to find
this mapping is the "Device Management" console. Disks have a
"Location" number, tapes have a "Tape Symbolic Name", etc.
Unfortunately, the places where this information is found is not very
well-defined.</para>
<para>
For external disks (USB-drives, CF-cards in a cardreader, etc) you can use
Cygwin to find out the mapping. <filename>/proc/partitions</filename>
Cygwin to show the mapping. <filename>/proc/partitions</filename>
contains a list of raw drives known to Cygwin. The <command>df</command>
command shows a list of drives and their respective sizes. If you match
the information between <filename>/proc/partitions</filename> and the

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

@ -62,7 +62,7 @@ or <literal>Download from Internet</literal>, then copy the whole
</para>
<para>
Though this provides some basic mirroring functionality, if you
are managing a wide Cygwin installation, to keep up to date we recommend
are managing a large Cygwin installation, to keep up to date we recommend
using a mirroring tool such as <command>wget</command>. A helpful user on
the Cygwin mailing list created a simple demonstration script to accomplish
this; search the list for <command>mkcygwget</command> for ideas.
@ -152,7 +152,7 @@ The chooser is the most complex part of <command>setup.exe</command>.
Packages are grouped into categories, and one package may belong to multiple
categories (assigned by the volunteer package maintainer). Each package
can be found under any of those categories in the heirarchial chooser view.
By default <command>setup.exe</command>
By default, <command>setup.exe</command>
will install only the packages in the <literal>Base</literal> category
and their dependencies, resulting in a minimal Cygwin installation.
However, this will not include many commonly used tools such as
@ -177,8 +177,8 @@ Once you have an existing Cygwin installation, the <command>setup.exe</command>
chooser is also used to manage your Cygwin installation.
Information on installed packages is kept in the
<literal>/etc/setup/</literal> directory of your Cygwin installation; if
<command>setup.exe</command> cannot find this directory it will act just like
you had no Cygwin installation. If <command>setup.exe</command>
<command>setup.exe</command> cannot find this directory it will act as if
you have no Cygwin installation. If <command>setup.exe</command>
finds a newer version of an installed package available, it will automatically
mark it to be upgraded.
To <literal>Uninstall</literal>, <literal>Reinstall</literal>, or get the
@ -208,7 +208,7 @@ to the local directory chosen earlier. Before installing,
<command>setup.exe</command> performs a checksum on each package. If the
local directory is a slow medium (such as a network drive) this can take
a long time. During the download and installation, <command>setup.exe</command>
show progress bars for the current task and total remaining disk space.
shows progress bars for the current task and total remaining disk space.
</para>
</sect2>

58
winsup/doc/setup2.sgml
View File

@ -1,12 +1,15 @@
<sect1 id="setup-env"><title>Environment Variables</title>
<para>
Before starting bash, you may set some environment variables. A .bat
file is provided where the most important ones are set before bash in
launched. This is the safest way to launch bash initially. The .bat
file is installed in the root directory that you specified during setup
and pointed to in the Start Menu under the "Cygwin" option. You can
edit it this file your liking.</para>
You may wish to specify settings of several important environment
variables that affect Cygwin's operation. Some of these settings need
to be in effect prior to launching the initial Cygwin session (before
starting your bash shell, for instance), and are, consequentially, best
placed in a .bat file. An initial file is named Cygwin.bat and is created
in the Cygwin root directory that you specified during setup. Note that
the "Cygwin" option of the Start Menu points to Cygwin.bat. Edit
Cygwin.bat to your liking or create your own .bat files to start
Cygwin processes.</para>
<para>
The <envar>CYGWIN</envar> variable is used to configure many global
@ -82,7 +85,7 @@ and set it to the desired memory limit in decimal MB. It is preferred to do
this in Cygwin using the <command>regtool</command> program included in the
Cygwin package.
(For more information about <command>regtool</command> or the other Cygwin
utilities, see <xref linkend="using-utils"></xref> or use each the
utilities, see <xref linkend="using-utils"></xref> or use the
<literal>--help</literal> option of each util.) You should always be careful
when using <command>regtool</command> since damaging your system registry can
result in an unusable system. This example sets memory limit to 1024 MB:
@ -201,11 +204,11 @@ internationalization environment variables.
</para></listitem>
<listitem><para>
Assuming you set one of the aforementioned environment variables to some
valid POSIX locale value, other than "C" and "POSIX", and assuming you
Assume that you've set one of the aforementioned environment variables to some
valid POSIX locale value, other than "C" and "POSIX", and assume that you
call an application which calls <function>setlocale</function> as above.</para>
<para>Assuming further you're living in Japan. So you might want to use
<para>Assume further that you're living in Japan. You might want to use
the language code "ja" and the territory "JP", thus setting, say,
<envar>LANG</envar> to "ja_JP". You didn't set a character set, so
what will Cygwin use now? Easy! It will use the default Windows ANSI
@ -289,22 +292,21 @@ the UTF-8 charset. This would be especially a problem in variables like
consist of valid ASCII characters, and only of uppercase letters, digits, and
the underscore for maximum portablilty.</para></note>
<para>And here's another problem when switching charsets on the fly.
Symbolic links. A symbolic link contains the filename of the target
file the symlink points to. When a symlink had been created with older
versions of Cygwin, the current ANSI or OEM character set had been used
to store the target filename, dependent on the old <envar>CYGWIN</envar>
environment variable setting <envar>codepage</envar>
(see <xref linkend="cygwinenv-removed-options"></xref>. If the target
filename contains non-ASCII characters and you use another
character set than your default ANSI/OEM charset, the target filename of
the symlink is now potentially an invalid character sequence in the new
character set. This behaviour is not different from the behaviour in other
Operating Systems. So, if you suddenly can't access a symlink anymore
which worked all these years before, maybe it's because you switched to
<para>Symbolic links, too, may pose a problem when switching charsets on
the fly. A symbolic link contains the filename of the target file the
symlink points to. When a symlink had been created with older versions
of Cygwin, the current ANSI or OEM character set had been used to store
the target filename, dependent on the old <envar>CYGWIN</envar>
environment variable setting <envar>codepage</envar> (see <xref
linkend="cygwinenv-removed-options"></xref>. If the target filename
contains non-ASCII characters and you use another character set than
your default ANSI/OEM charset, the target filename of the symlink is now
potentially an invalid character sequence in the new character set.
This behaviour is not different from the behaviour in other Operating
Systems. So, if you suddenly can't access a symlink anymore which
worked all these years before, maybe it's because you switched to
another character set. This doesn't occur with symlinks created with
Cygwin 1.7 or later.
</para>
Cygwin 1.7 or later. </para>
</sect2>
@ -322,8 +324,8 @@ symbols, for a decimalpoint other than '.', no support for native time
formats, and no support for native language sorting orders.
</para>
<para>However, internationalization is work in progress and we would be glad
for coding help in this area.</para>
<para>Cygwin's internationalization support is work in progress and we would
be glad for coding help in this area.</para>
</sect2>
@ -415,7 +417,7 @@ oif the "CPxxx" style charsets, always use them with the trailing "CP".</para>
<sect1 id="setup-files"><title>Customizing bash</title>
<para>
To set bash up so that cut and paste work properly, click on the
To set up bash so that cut and paste work properly, click on the
"Properties" button of the window, then on the "Misc" tab. Make sure
that "QuickEdit mode" and "Insert mode" are checked. These settings
will be remembered next time you run bash from that shortcut. Similarly