+2013-05-01 Warren Young <warren@etr-usa.com>
+
+ * cygwin-ug.xml: Renamed from cygwin-ug.in.sgml
+ (bookinfo) Extracted <bookinfo> section into new ug-info.xml file
+ * ug-info.xml: Created
+ * cygwin-ug-net.xml: Renamed from cygwin-ug-net.in.sgml
+ (bookinfo) Replaced content with XInclude referencing ug-info.xml
+ * configure.ac: Replaced a *.sgml file reference with *.xml
+ * cygserver.xml cygwinenv.xml dll.xml effectively.xml filemodes.xml
+ gcc.xml gdb.xml legal.xml new-features.xml ntsec.xml overview.xml
+ pathnames.xml programming.xml setup.xml setup-net.xml textbinary.xml
+ using.xml windres.xml: Renamed from *.sgml.
+ Added <?xml> and <!DOCTYPE> tags to the top.
+ * cygserver.sgml cygwinenv.sgml dll.sgml effectively.sgml filemodes.sgml
+ gcc.sgml gdb.sgml legal.sgml new-features.sgml ntsec.sgml overview.sgml
+ pathnames.sgml programming.sgml setup.sgml setup-net.sgml textbinary.sgml
+ using.sgml windres.sgml: Renamed to *.xml
+ * faq.xml: Renamed from faq-sections.sgml. (Not faq.sgml!)
+ Replaced FAQ section ENTITY declarations with XIncludes.
+ Removed all other ENTITY declarations as they just name entities
+ already defined in the current DocBook stylesheets.
+ * faq.sgml: Removed without translating to DocBook XML. Obsolete.
+ * faq-*.xml: Added <?xml> and <!DOCTYPE> tags to the top.
+ Moved <qandadiv> tags from faq.xml and faq-sections.xml into
+ individual section files so they individually pass XML validation.
+ * pathnames.xml: Contained two top-level <sect1> elements, which is
+ malformed XML. Moved second to new specialnames.xml file.
+ * specialnames.xml: Created; extracted from pathnames.sgml
+ * overview2.xml: Broke it up into following three files, and
+ removed the original.
+ * ov-ex-win.xml (ov-ex-win): Created; contents extracted from
+ overview2.sgml
+ * ov-ex-unix.xml (ov-ex-unix): Ditto
+ * highlights.xml (highlights): Ditto
+ * setup2.xml: Broke it up into setup-*.xml.
+ * setup-env.xml setup-files.xml setup-locale.xml setup-maxmem.xml:
+ Created; contents extracted from setup2.sgml
+
2013-04-24 Corinna Vinschen <corinna@vinschen.de>
* faq-programming.xml (faq.programming.64bitporting): Fix typo.
srcdir = @srcdir@
VPATH = @srcdir@
-SGMLDIRS = -d $(srcdir) -d $(srcdir)/../utils -d $(srcdir)/../cygwin
+DBXDIRS = -d $(srcdir) -d $(srcdir)/../utils -d $(srcdir)/../cygwin
CC:=@CC@
CC_FOR_TARGET:=@CC@
include $(srcdir)/../Makefile.common
-TOCLEAN:=faq.txt ./*.html readme.txt doctool.o doctool.exe *.junk \
- cygwin-ug.sgml cygwin-ug cygwin-ug-net.html.gz \
- cygwin-ug-net.sgml cygwin-ug-net cygwin-ug-net.html \
- cygwin-api.sgml cygwin-api cygwin-api-int.sgml cygwin-api-int \
- faq
-
-FAQ_SOURCES:= faq-api.xml faq-programming.xml faq-resources.xml \
- faq-sections.xml faq-setup.xml faq-using.xml faq-what.xml faq.xml
+FAQ_SOURCES:= faq*.xml
.SUFFIXES:
-all : \
+all: Makefile \
cygwin-ug-net/cygwin-ug-net.html \
cygwin-ug-net/cygwin-ug-net-nochunks.html.gz \
cygwin-api/cygwin-api.html \
- faq/faq.html faq/faq-nochunks.html \
+ faq/faq.html \
cygwin-ug-net/cygwin-ug-net.pdf \
cygwin-api/cygwin-api.pdf
clean:
- rm -Rf $(TOCLEAN)
+ rm -f doctool.exe doctool.o
+ rm -f cygwin-api.xml
+ rm -f *.html *.html.gz
+ rm -Rf cygwin-api cygwin-ug cygwin-ug-net faq
install: all
-cygwin-ug-net/cygwin-ug-net-nochunks.html.gz : cygwin-ug-net.sgml doctool
- -${XMLTO} html-nochunks -m $(srcdir)/cygwin.dsl $<
+cygwin-ug-net/cygwin-ug-net-nochunks.html.gz : cygwin-ug-net.xml
+ -${XMLTO} html-nochunks -m $(srcdir)/cygwin.xsl $<
-cp cygwin-ug-net.html cygwin-ug-net/cygwin-ug-net-nochunks.html
-rm -f cygwin-ug-net/cygwin-ug-net-nochunks.html.gz
-gzip cygwin-ug-net/cygwin-ug-net-nochunks.html
-cygwin-ug-net/cygwin-ug-net.html : cygwin-ug-net.sgml doctool
- -${XMLTO} html -o cygwin-ug-net/ -m $(srcdir)/cygwin.dsl $<
+cygwin-ug-net/cygwin-ug-net.html : cygwin-ug-net.xml
+ -${XMLTO} html -o cygwin-ug-net/ -m $(srcdir)/cygwin.xsl $<
# Some versions of jw hang with the -o option
-cygwin-ug-net/cygwin-ug-net.pdf : cygwin-ug-net.sgml
+cygwin-ug-net/cygwin-ug-net.pdf : cygwin-ug-net.xml
-${XMLTO} pdf -o cygwin-ug-net/ $<
-cygwin-ug-net.sgml : cygwin-ug-net.in.sgml ./doctool Makefile
- -./doctool -m $(SGMLDIRS) -s $(srcdir) -o $@ $<
-
-cygwin-api/cygwin-api.html : cygwin-api.sgml
- -${XMLTO} html -o cygwin-api/ -m $(srcdir)/cygwin.dsl $<
+cygwin-api/cygwin-api.html : cygwin-api.xml
+ -${XMLTO} html -o cygwin-api/ -m $(srcdir)/cygwin.xsl $<
-cygwin-api/cygwin-api.pdf : cygwin-api.sgml
+cygwin-api/cygwin-api.pdf : cygwin-api.xml
-${XMLTO} pdf -o cygwin-api/ $<
-cygwin-api.sgml : cygwin-api.in.sgml ./doctool Makefile
- -./doctool -m $(SGMLDIRS) -s $(srcdir) -o $@ $<
+cygwin-api.xml : cygwin-api.in.xml ./doctool Makefile
+ -./doctool -m $(DBXDIRS) -s $(srcdir) -o $@ $<
faq/faq.html : $(FAQ_SOURCES)
- -${XMLTO} html -o faq -m $(srcdir)/cygwin.dsl $(srcdir)/faq-sections.xml
- -sed -i 's;</a><a name="id[0-9]*"></a>;</a>;g' faq/faq.*.html
-
-faq/faq-nochunks.html : $(FAQ_SOURCES)
- -${XMLTO} html -o faq -m $(srcdir)/cygwin.dsl $(srcdir)/faq.xml
- -sed -i 's;</a><a name="id[0-9]*"></a>;</a>;g' faq/faq-nochunks.html
+ -${XMLTO} html -o faq -m $(srcdir)/cygwin.xsl $(srcdir)/faq.xml
+ -sed -i 's;</a><a name="id[0-9]*"></a>;</a>;g' faq/faq.html
./doctool : doctool.c
gcc -g $< -o $@
TBFILES = cygwin-ug-net.dvi cygwin-ug-net.rtf cygwin-ug-net.ps \
- cygwin-ug-net.pdf cygwin-ug-net.sgml \
+ cygwin-ug-net.pdf cygwin-ug-net.xml \
cygwin-api.dvi cygwin-api.rtf cygwin-api.ps \
- cygwin-api.pdf cygwin-api.sgml
+ cygwin-api.pdf cygwin-api.xml
TBDIRS = cygwin-ug-net cygwin-api
TBDEPS = cygwin-ug-net/cygwin-ug-net.html cygwin-api/cygwin-api.html
#! /bin/sh
# Guess values for system-dependent variables and create Makefiles.
-# Generated by GNU Autoconf 2.68.
+# Generated by GNU Autoconf 2.69.
#
#
-# Copyright (C) 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, 2001,
-# 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Free Software
-# Foundation, Inc.
+# Copyright (C) 1992-1996, 1998-2012 Free Software Foundation, Inc.
#
#
# This configure script is free software; the Free Software Foundation
# CDPATH.
(unset CDPATH) >/dev/null 2>&1 && unset CDPATH
+# Use a proper internal environment variable to ensure we don't fall
+ # into an infinite loop, continuously re-executing ourselves.
+ if test x"${_as_can_reexec}" != xno && test "x$CONFIG_SHELL" != x; then
+ _as_can_reexec=no; export _as_can_reexec;
+ # We cannot yet assume a decent shell, so we have to provide a
+# neutralization value for shells without unset; and this also
+# works around shells that cannot unset nonexistent variables.
+# Preserve -v and -x to the replacement shell.
+BASH_ENV=/dev/null
+ENV=/dev/null
+(unset BASH_ENV) >/dev/null 2>&1 && unset BASH_ENV ENV
+case $- in # ((((
+ *v*x* | *x*v* ) as_opts=-vx ;;
+ *v* ) as_opts=-v ;;
+ *x* ) as_opts=-x ;;
+ * ) as_opts= ;;
+esac
+exec $CONFIG_SHELL $as_opts "$as_myself" ${1+"$@"}
+# Admittedly, this is quite paranoid, since all the known shells bail
+# out after a failed `exec'.
+$as_echo "$0: could not re-execute with $CONFIG_SHELL" >&2
+as_fn_exit 255
+ fi
+ # We don't want this to propagate to other subprocesses.
+ { _as_can_reexec=; unset _as_can_reexec;}
if test "x$CONFIG_SHELL" = x; then
as_bourne_compatible="if test -n \"\${ZSH_VERSION+set}\" && (emulate sh) >/dev/null 2>&1; then :
emulate sh
else
exitcode=1; echo positional parameters were not saved.
fi
-test x\$exitcode = x0 || exit 1"
+test x\$exitcode = x0 || exit 1
+test -x / || exit 1"
as_suggested=" as_lineno_1=";as_suggested=$as_suggested$LINENO;as_suggested=$as_suggested" as_lineno_1a=\$LINENO
as_lineno_2=";as_suggested=$as_suggested$LINENO;as_suggested=$as_suggested" as_lineno_2a=\$LINENO
eval 'test \"x\$as_lineno_1'\$as_run'\" != \"x\$as_lineno_2'\$as_run'\" &&
if test "x$CONFIG_SHELL" != x; then :
- # We cannot yet assume a decent shell, so we have to provide a
- # neutralization value for shells without unset; and this also
- # works around shells that cannot unset nonexistent variables.
- # Preserve -v and -x to the replacement shell.
- BASH_ENV=/dev/null
- ENV=/dev/null
- (unset BASH_ENV) >/dev/null 2>&1 && unset BASH_ENV ENV
- export CONFIG_SHELL
- case $- in # ((((
- *v*x* | *x*v* ) as_opts=-vx ;;
- *v* ) as_opts=-v ;;
- *x* ) as_opts=-x ;;
- * ) as_opts= ;;
- esac
- exec "$CONFIG_SHELL" $as_opts "$as_myself" ${1+"$@"}
+ export CONFIG_SHELL
+ # We cannot yet assume a decent shell, so we have to provide a
+# neutralization value for shells without unset; and this also
+# works around shells that cannot unset nonexistent variables.
+# Preserve -v and -x to the replacement shell.
+BASH_ENV=/dev/null
+ENV=/dev/null
+(unset BASH_ENV) >/dev/null 2>&1 && unset BASH_ENV ENV
+case $- in # ((((
+ *v*x* | *x*v* ) as_opts=-vx ;;
+ *v* ) as_opts=-v ;;
+ *x* ) as_opts=-x ;;
+ * ) as_opts= ;;
+esac
+exec $CONFIG_SHELL $as_opts "$as_myself" ${1+"$@"}
+# Admittedly, this is quite paranoid, since all the known shells bail
+# out after a failed `exec'.
+$as_echo "$0: could not re-execute with $CONFIG_SHELL" >&2
+exit 255
fi
if test x$as_have_required = xno; then :
} # as_fn_mkdir_p
+
+# as_fn_executable_p FILE
+# -----------------------
+# Test if FILE is an executable regular file.
+as_fn_executable_p ()
+{
+ test -f "$1" && test -x "$1"
+} # as_fn_executable_p
# as_fn_append VAR VALUE
# ----------------------
# Append the text in VALUE to the end of the definition contained in VAR. Take
chmod +x "$as_me.lineno" ||
{ $as_echo "$as_me: error: cannot create $as_me.lineno; rerun with a POSIX shell" >&2; as_fn_exit 1; }
+ # If we had to re-execute with $CONFIG_SHELL, we're ensured to have
+ # already done that, so ensure we don't try to do so again and fall
+ # in an infinite loop. This has already happened in practice.
+ _as_can_reexec=no; export _as_can_reexec
# Don't try to exec as it changes $[0], causing all sort of problems
# (the dirname of $[0] is not the place where we might find the
# original and so on. Autoconf is especially sensitive to this).
# ... but there are two gotchas:
# 1) On MSYS, both `ln -s file dir' and `ln file dir' fail.
# 2) DJGPP < 2.04 has no symlinks; `ln -s' creates a wrapper executable.
- # In both cases, we have to default to `cp -p'.
+ # In both cases, we have to default to `cp -pR'.
ln -s conf$$.file conf$$.dir 2>/dev/null && test ! -f conf$$.exe ||
- as_ln_s='cp -p'
+ as_ln_s='cp -pR'
elif ln conf$$.file conf$$ 2>/dev/null; then
as_ln_s=ln
else
- as_ln_s='cp -p'
+ as_ln_s='cp -pR'
fi
else
- as_ln_s='cp -p'
+ as_ln_s='cp -pR'
fi
rm -f conf$$ conf$$.exe conf$$.dir/conf$$.file conf$$.file
rmdir conf$$.dir 2>/dev/null
as_mkdir_p=false
fi
-if test -x / >/dev/null 2>&1; then
- as_test_x='test -x'
-else
- if ls -dL / >/dev/null 2>&1; then
- as_ls_L_option=L
- else
- as_ls_L_option=
- fi
- as_test_x='
- eval sh -c '\''
- if test -d "$1"; then
- test -d "$1/.";
- else
- case $1 in #(
- -*)set "./$1";;
- esac;
- case `ls -ld'$as_ls_L_option' "$1" 2>/dev/null` in #((
- ???[sx]*):;;*)false;;esac;fi
- '\'' sh
- '
-fi
-as_executable_p=$as_test_x
+as_test_x='test -x'
+as_executable_p=as_fn_executable_p
# Sed expression to map a string onto a valid CPP name.
as_tr_cpp="eval sed 'y%*$as_cr_letters%P$as_cr_LETTERS%;s%[^_$as_cr_alnum]%_%g'"
PACKAGE_BUGREPORT=
PACKAGE_URL=
-ac_unique_file="cygwin-api.in.sgml"
+ac_unique_file="cygwin-api.in.xml"
ac_no_link=no
ac_subst_vars='LTLIBOBJS
LIBOBJS
if test "x$host_alias" != x; then
if test "x$build_alias" = x; then
cross_compiling=maybe
- $as_echo "$as_me: WARNING: if you wanted to set the --build type, don't use --host.
- If a cross compiler is detected then cross compile mode will be used" >&2
elif test "x$build_alias" != "x$host_alias"; then
cross_compiling=yes
fi
if $ac_init_version; then
cat <<\_ACEOF
configure
-generated by GNU Autoconf 2.68
+generated by GNU Autoconf 2.69
-Copyright (C) 2010 Free Software Foundation, Inc.
+Copyright (C) 2012 Free Software Foundation, Inc.
This configure script is free software; the Free Software Foundation
gives unlimited permission to copy, distribute and modify it.
_ACEOF
running configure, to aid debugging if configure makes a mistake.
It was created by $as_me, which was
-generated by GNU Autoconf 2.68. Invocation command line was
+generated by GNU Autoconf 2.69. Invocation command line was
$ $0 $@
IFS=$as_save_IFS
test -z "$as_dir" && as_dir=.
for ac_exec_ext in '' $ac_executable_extensions; do
- if { test -f "$as_dir/$ac_word$ac_exec_ext" && $as_test_x "$as_dir/$ac_word$ac_exec_ext"; }; then
+ if as_fn_executable_p "$as_dir/$ac_word$ac_exec_ext"; then
ac_cv_prog_CC="${ac_tool_prefix}gcc"
$as_echo "$as_me:${as_lineno-$LINENO}: found $as_dir/$ac_word$ac_exec_ext" >&5
break 2
IFS=$as_save_IFS
test -z "$as_dir" && as_dir=.
for ac_exec_ext in '' $ac_executable_extensions; do
- if { test -f "$as_dir/$ac_word$ac_exec_ext" && $as_test_x "$as_dir/$ac_word$ac_exec_ext"; }; then
+ if as_fn_executable_p "$as_dir/$ac_word$ac_exec_ext"; then
ac_cv_prog_ac_ct_CC="gcc"
$as_echo "$as_me:${as_lineno-$LINENO}: found $as_dir/$ac_word$ac_exec_ext" >&5
break 2
IFS=$as_save_IFS
test -z "$as_dir" && as_dir=.
for ac_exec_ext in '' $ac_executable_extensions; do
- if { test -f "$as_dir/$ac_word$ac_exec_ext" && $as_test_x "$as_dir/$ac_word$ac_exec_ext"; }; then
+ if as_fn_executable_p "$as_dir/$ac_word$ac_exec_ext"; then
ac_cv_prog_CC="${ac_tool_prefix}gcc"
$as_echo "$as_me:${as_lineno-$LINENO}: found $as_dir/$ac_word$ac_exec_ext" >&5
break 2
IFS=$as_save_IFS
test -z "$as_dir" && as_dir=.
for ac_exec_ext in '' $ac_executable_extensions; do
- if { test -f "$as_dir/$ac_word$ac_exec_ext" && $as_test_x "$as_dir/$ac_word$ac_exec_ext"; }; then
+ if as_fn_executable_p "$as_dir/$ac_word$ac_exec_ext"; then
ac_cv_prog_ac_ct_CC="gcc"
$as_echo "$as_me:${as_lineno-$LINENO}: found $as_dir/$ac_word$ac_exec_ext" >&5
break 2
IFS=$as_save_IFS
test -z "$as_dir" && as_dir=.
for ac_exec_ext in '' $ac_executable_extensions; do
- if { test -f "$as_dir/$ac_word$ac_exec_ext" && $as_test_x "$as_dir/$ac_word$ac_exec_ext"; }; then
+ if as_fn_executable_p "$as_dir/$ac_word$ac_exec_ext"; then
ac_cv_prog_CC="${ac_tool_prefix}cc"
$as_echo "$as_me:${as_lineno-$LINENO}: found $as_dir/$ac_word$ac_exec_ext" >&5
break 2
IFS=$as_save_IFS
test -z "$as_dir" && as_dir=.
for ac_exec_ext in '' $ac_executable_extensions; do
- if { test -f "$as_dir/$ac_word$ac_exec_ext" && $as_test_x "$as_dir/$ac_word$ac_exec_ext"; }; then
+ if as_fn_executable_p "$as_dir/$ac_word$ac_exec_ext"; then
if test "$as_dir/$ac_word$ac_exec_ext" = "/usr/ucb/cc"; then
ac_prog_rejected=yes
continue
IFS=$as_save_IFS
test -z "$as_dir" && as_dir=.
for ac_exec_ext in '' $ac_executable_extensions; do
- if { test -f "$as_dir/$ac_word$ac_exec_ext" && $as_test_x "$as_dir/$ac_word$ac_exec_ext"; }; then
+ if as_fn_executable_p "$as_dir/$ac_word$ac_exec_ext"; then
ac_cv_prog_CC="$ac_tool_prefix$ac_prog"
$as_echo "$as_me:${as_lineno-$LINENO}: found $as_dir/$ac_word$ac_exec_ext" >&5
break 2
IFS=$as_save_IFS
test -z "$as_dir" && as_dir=.
for ac_exec_ext in '' $ac_executable_extensions; do
- if { test -f "$as_dir/$ac_word$ac_exec_ext" && $as_test_x "$as_dir/$ac_word$ac_exec_ext"; }; then
+ if as_fn_executable_p "$as_dir/$ac_word$ac_exec_ext"; then
ac_cv_prog_ac_ct_CC="$ac_prog"
$as_echo "$as_me:${as_lineno-$LINENO}: found $as_dir/$ac_word$ac_exec_ext" >&5
break 2
/* end confdefs.h. */
#include <stdarg.h>
#include <stdio.h>
-#include <sys/types.h>
-#include <sys/stat.h>
+struct stat;
/* Most of the following tests are stolen from RCS 5.7's src/conf.sh. */
struct buf { int x; };
FILE * (*rcsopen) (struct buf *, struct stat *, int);
# ... but there are two gotchas:
# 1) On MSYS, both `ln -s file dir' and `ln file dir' fail.
# 2) DJGPP < 2.04 has no symlinks; `ln -s' creates a wrapper executable.
- # In both cases, we have to default to `cp -p'.
+ # In both cases, we have to default to `cp -pR'.
ln -s conf$$.file conf$$.dir 2>/dev/null && test ! -f conf$$.exe ||
- as_ln_s='cp -p'
+ as_ln_s='cp -pR'
elif ln conf$$.file conf$$ 2>/dev/null; then
as_ln_s=ln
else
- as_ln_s='cp -p'
+ as_ln_s='cp -pR'
fi
else
- as_ln_s='cp -p'
+ as_ln_s='cp -pR'
fi
rm -f conf$$ conf$$.exe conf$$.dir/conf$$.file conf$$.file
rmdir conf$$.dir 2>/dev/null
as_mkdir_p=false
fi
-if test -x / >/dev/null 2>&1; then
- as_test_x='test -x'
-else
- if ls -dL / >/dev/null 2>&1; then
- as_ls_L_option=L
- else
- as_ls_L_option=
- fi
- as_test_x='
- eval sh -c '\''
- if test -d "$1"; then
- test -d "$1/.";
- else
- case $1 in #(
- -*)set "./$1";;
- esac;
- case `ls -ld'$as_ls_L_option' "$1" 2>/dev/null` in #((
- ???[sx]*):;;*)false;;esac;fi
- '\'' sh
- '
-fi
-as_executable_p=$as_test_x
+
+# as_fn_executable_p FILE
+# -----------------------
+# Test if FILE is an executable regular file.
+as_fn_executable_p ()
+{
+ test -f "$1" && test -x "$1"
+} # as_fn_executable_p
+as_test_x='test -x'
+as_executable_p=as_fn_executable_p
# Sed expression to map a string onto a valid CPP name.
as_tr_cpp="eval sed 'y%*$as_cr_letters%P$as_cr_LETTERS%;s%[^_$as_cr_alnum]%_%g'"
# values after options handling.
ac_log="
This file was extended by $as_me, which was
-generated by GNU Autoconf 2.68. Invocation command line was
+generated by GNU Autoconf 2.69. Invocation command line was
CONFIG_FILES = $CONFIG_FILES
CONFIG_HEADERS = $CONFIG_HEADERS
ac_cs_config="`$as_echo "$ac_configure_args" | sed 's/^ //; s/[\\""\`\$]/\\\\&/g'`"
ac_cs_version="\\
config.status
-configured by $0, generated by GNU Autoconf 2.68,
+configured by $0, generated by GNU Autoconf 2.69,
with options \\"\$ac_cs_config\\"
-Copyright (C) 2010 Free Software Foundation, Inc.
+Copyright (C) 2012 Free Software Foundation, Inc.
This config.status script is free software; the Free Software Foundation
gives unlimited permission to copy, distribute and modify it."
_ACEOF
cat >>$CONFIG_STATUS <<_ACEOF || ac_write_fail=1
if \$ac_cs_recheck; then
- set X '$SHELL' '$0' $ac_configure_args \$ac_configure_extra_args --no-create --no-recursion
+ set X $SHELL '$0' $ac_configure_args \$ac_configure_extra_args --no-create --no-recursion
shift
\$as_echo "running CONFIG_SHELL=$SHELL \$*" >&6
CONFIG_SHELL='$SHELL'
dnl Process this file with autoconf to produce a configure script.
AC_PREREQ(2.59)
-AC_INIT(cygwin-api.in.sgml)
+AC_INIT(cygwin-api.in.xml)
AC_CONFIG_AUX_DIR(../..)
AC_NO_EXECUTABLES
+<?xml version="1.0" encoding='UTF-8'?>
+<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+
<sect1 id="using-cygserver"><title>Cygserver</title>
<sect2 id="what-is-cygserver"><title>What is Cygserver?</title>
-<?xml version="1.0"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
-"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" []>
+<?xml version="1.0" encoding='UTF-8'?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<book id="cygwin-api">
+<book id="cygwin-api" xmlns:xi="http://www.w3.org/2001/XInclude">
<bookinfo>
<date>1998-08-31</date>
<title>Cygwin API Reference</title>
-
- DOCTOOL-INSERT-legal
-
+ <xi:include href="legal.xml"/>
</bookinfo>
<toc></toc>
+++ /dev/null
-<?xml version="1.0"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
-"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" []>
-
-<book id="cygwin-ug-net">
-
- <bookinfo>
- <date>2009-03-18</date>
- <title>Cygwin User's Guide</title>
-
-DOCTOOL-INSERT-legal
-
- </bookinfo>
-
- <toc></toc>
-
-DOCTOOL-INSERT-overview
-
-DOCTOOL-INSERT-setup-net
-
-DOCTOOL-INSERT-using
-
-DOCTOOL-INSERT-programming
-
-</book>
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+
+<book id="cygwin-ug-net" xmlns:xi="http://www.w3.org/2001/XInclude">
+ <bookinfo>
+ <date>2009-03-18</date>
+ <title>Cygwin User's Guide</title>
+ <xi:include href="legal.xml"/>
+ </bookinfo>
+
+ <xi:include href="overview.xml"/>
+ <xi:include href="setup-net.xml"/>
+ <xi:include href="using.xml"/>
+ <xi:include href="programming.xml"/>
+</book>
+++ /dev/null
-<?xml version="1.0"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
- <!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, 2002,
- 2003, 2004, 2005, 2006, 2007,
- 2008 Red Hat, Inc.
-
-This is copyrighted software that may only
-be reproduced, modified, or distributed
-under license from Red Hat, Inc.
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-">
- ]>
-
-<book id="cygwin-ug">
-
- <bookinfo>
- <date>2001-22-03</date>
- <title>Cygwin User's Guide</title>
- <authorgroup>
- <author>
- <firstname>Joshua Daniel</firstname>
- <surname>Franklin</surname>
- </author>
- <author>
- <firstname>Corinna</firstname>
- <surname>Vinschen</surname>
- </author>
- <author>
- <firstname>Christopher</firstname>
- <surname>Faylor</surname>
- </author>
- <author>
- <firstname>DJ</firstname>
- <surname>Delorie</surname>
- </author>
- <author>
- <firstname>Pierre</firstname>
- <surname>Humblet</surname>
- </author>
- <author>
- <firstname>Geoffrey</firstname>
- <surname>Noer</surname>
- </author>
- </authorgroup>
-
-DOCTOOL-INSERT-legal
-
- </bookinfo>
-
- <toc></toc>
-
-DOCTOOL-INSERT-overview
-
-DOCTOOL-INSERT-setup
-
-DOCTOOL-INSERT-using
-
-DOCTOOL-INSERT-programming
-
-</book>
--- /dev/null
+<?xml version="1.0" encoding='UTF-8'?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+
+<book id="cygwin-ug" xmlns:xi="http://www.w3.org/2001/XInclude">
+ <xi:include href="ug-info.xml"/>
+ <xi:include href="overview.xml"/>
+ <xi:include href="setup.xml"/>
+ <xi:include href="using.xml"/>
+ <xi:include href="programming.xml"/>
+</book>
+<?xml version="1.0" encoding='UTF-8'?>
+<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+
<sect1 id="using-cygwinenv"><title>The <envar>CYGWIN</envar> environment
variable</title>
+<?xml version="1.0" encoding='UTF-8'?>
+<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+
<sect1 id="dll"><title>Building and Using DLLs</title>
<para>DLLs are Dynamic Link Libraries, which means that they're linked
+<?xml version="1.0" encoding='UTF-8'?>
+<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+
<sect1 id="using-effectively">
<title>Using Cygwin effectively with Windows</title>
+<?xml version="1.0" encoding='UTF-8'?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+
+<qandadiv id="faq.api">
+<title>Cygwin API Questions</title>
+
<!-- faq-api.xml -->
<qandaentry id="faq.api.everything">
<question><para>How does everything work?</para></question>
using the xterm escape sequences for mouse events.
</para>
</answer></qandaentry>
-
+</qandadiv>
--- /dev/null
+<?xml version="1.0" encoding='UTF-8'?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<!-- faq-copyright.xml -->
+
+<qandadiv id="faq.copyright">
+ <title>Copyright</title>
+
+ <qandaentry id="faq.what.copyright">
+ <question><para>What are the copyrights?</para></question>
+
+ <answer>
+ <para>Please see <ulink url="http://cygwin.com/license.html"/>
+ for more information about Cygwin copyright and licensing.</para>
+ </answer>
+ </qandaentry>
+</qandadiv>
+<?xml version="1.0" encoding='UTF-8'?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<!-- faq-programming.xml -->
+<qandadiv id="faq.programming">
+<title>Programming Questions</title>
+
<qandaentry id="faq.programming.packages">
<question><para>How do I contribute a package?</para></question>
<answer>
linker flag.</para></listitem>
</orderedlist></listitem></orderedlist>
</answer></qandaentry>
+
+</qandadiv>
+<?xml version="1.0" encoding='UTF-8'?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+
+<qandadiv id="faq.resources">
+<title>Further Resources</title>
+
<!-- faq-resources.xml -->
<qandaentry id="faq.resources.documentation">
<question><para>Where's the documentation?</para></question>
<para>Comprehensive information about reporting problems with Cygwin can be found at <ulink url="http://cygwin.com/problems.html" />.
</para>
</answer></qandaentry>
-
+</qandadiv>
+++ /dev/null
-<?xml version='1.0'?>
-<!DOCTYPE article PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN'
- "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
- <!-- see http://www.unicode.org/charts/PDF/U0080.pdf -->
- <!ENTITY pound "£">
- <!ENTITY brokenpipe "¦">
-
- <!-- all the files -->
- <!ENTITY FAQ-WHAT SYSTEM "faq-what.xml">
- <!ENTITY FAQ-SETUP SYSTEM "faq-setup.xml">
- <!ENTITY FAQ-RESOURCES SYSTEM "faq-resources.xml">
- <!ENTITY FAQ-USING SYSTEM "faq-using.xml">
- <!ENTITY FAQ-API SYSTEM "faq-api.xml">
- <!ENTITY FAQ-PROGRAMMING SYSTEM "faq-programming.xml">
-]>
-
-<article id="faq" lang="en">
- <articleinfo>
- <title>Cygwin FAQ</title>
- </articleinfo>
-
-<sect1 id="faq.about">
-<title>About Cygwin</title>
-<qandaset><?dbhtml toc="1"?>
-&FAQ-WHAT;
-</qandaset></sect1>
-
-<sect1 id="faq.setup">
-<title>Setting up Cygwin</title>
-<qandaset><?dbhtml toc="1"?>
-&FAQ-SETUP;
-</qandaset></sect1>
-
-<sect1 id="faq.resources">
-<title>Further Resources</title>
-<qandaset><?dbhtml toc="1"?>
-&FAQ-RESOURCES;
-</qandaset></sect1>
-
-<sect1 id="faq.using">
-<title>Using Cygwin</title>
-<qandaset><?dbhtml toc="1"?>
-&FAQ-USING;
-</qandaset></sect1>
-
-<sect1 id="faq.api">
-<title>Cygwin API Questions</title>
-<qandaset><?dbhtml toc="1"?>
-&FAQ-API;
-</qandaset></sect1>
-
-<sect1 id="faq.programming">
-<title>Programming Questions</title>
-<qandaset><?dbhtml toc="1"?>
-&FAQ-PROGRAMMING;
-</qandaset></sect1>
-
-<sect1 id="faq.copyright">
-<title>Copyright</title>
-<qandaset><?dbhtml toc="1"?>
-
-
-<qandaentry id="faq.what.copyright">
-<question><para>What are the copyrights?</para></question>
-<answer>
-
-<para>Please see
-<ulink url="http://cygwin.com/license.html" /> for more information
-about Cygwin copyright and licensing.
-</para>
-
-</answer></qandaentry>
-</qandaset></sect1>
-
-</article>
+<?xml version="1.0" encoding='UTF-8'?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+
+<qandadiv id="faq.setup">
+<title>Setting up Cygwin</title>
+
<!-- faq-setup.xml -->
<qandaentry id="faq.setup.setup">
<question><para>What is the recommended installation procedure?</para></question>
except for the installation directory information stored there for the sake
of setup.exe. There's nothing left to manipulate anymore.
</para></answer></qandaentry>
+</qandadiv>
+<?xml version="1.0" encoding='UTF-8'?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+
+<qandadiv id="faq.using">
+<title>Using Cygwin</title>
+
<!-- faq-problems.xml -->
<qandaentry id="faq.using.missing-dlls">
<question><para>Why can't my application locate cygncurses-8.dll? or cygintl-3.dll? or cygreadline6.dll? or ...?</para></question>
difficult to make <literal>fork()</literal> work reliably.</para>
</answer>
</qandaentry>
+</qandadiv>
+<?xml version="1.0" encoding='UTF-8'?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+
+<qandadiv id="faq.about">
+<title>About Cygwin</title>
+
<!-- faq-what.xml -->
-<qandaentry id="faq.what">
+<qandaentry id="faq.what.what">
<question><para>What is it?</para></question>
<answer>
<para>Many thanks to everyone using the tools for their many contributions in
the form of advice, bug reports, and code fixes. Keep them coming!
</para></answer></qandaentry>
-
+</qandadiv>
-<?xml version='1.0'?>
-<!DOCTYPE article PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN'
- "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
- <!-- see http://www.unicode.org/charts/PDF/U0080.pdf -->
- <!ENTITY pound "£">
- <!ENTITY brokenpipe "¦">
+<?xml version="1.0" encoding='UTF-8'?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
- <!-- all the files -->
- <!ENTITY FAQ-WHAT SYSTEM "faq-what.xml">
- <!ENTITY FAQ-SETUP SYSTEM "faq-setup.xml">
- <!ENTITY FAQ-RESOURCES SYSTEM "faq-resources.xml">
- <!ENTITY FAQ-USING SYSTEM "faq-using.xml">
- <!ENTITY FAQ-API SYSTEM "faq-api.xml">
- <!ENTITY FAQ-PROGRAMMING SYSTEM "faq-programming.xml">
-]>
-
-<article id="faq-nochunks" lang="en">
+<article id="faq" lang="en" xmlns:xi="http://www.w3.org/2001/XInclude">
<articleinfo>
<title>Cygwin FAQ</title>
</articleinfo>
-<qandaset>
-<?dbhtml toc="1"?>
-
-<qandadiv id="faq.about">
-<title>About Cygwin</title>
-&FAQ-WHAT;
-</qandadiv>
-
-<qandadiv id="faq.setup">
-<title>Setting up Cygwin</title>
-&FAQ-SETUP;
-</qandadiv>
-
-<qandadiv id="faq.resources">
-<title>Further Resources</title>
-&FAQ-RESOURCES;
-</qandadiv>
-
-<qandadiv id="faq.using">
-<title>Using Cygwin</title>
-&FAQ-USING;
-</qandadiv>
-
-<qandadiv id="faq.api">
-<title>Cygwin API Questions</title>
-&FAQ-API;
-</qandadiv>
-
-<qandadiv id="faq.programming">
-<title>Programming Questions</title>
-&FAQ-PROGRAMMING;
-</qandadiv>
-
-<qandadiv id="faq.copyright">
-<title>Copyright</title>
-
-<qandaentry id="faq.what.copyright">
-<question><para>What are the copyrights?</para></question>
-<answer>
-
-<para>Please see
-<ulink url="http://cygwin.com/license.html" /> for more information
-about Cygwin copyright and licensing.
-</para>
-
-</answer></qandaentry>
-</qandadiv>
-</qandaset>
-
+ <qandaset>
+ <?dbhtml toc="1"?>
+
+ <xi:include href="faq-what.xml"/>
+ <xi:include href="faq-setup.xml"/>
+ <xi:include href="faq-resources.xml"/>
+ <xi:include href="faq-using.xml"/>
+ <xi:include href="faq-api.xml"/>
+ <xi:include href="faq-programming.xml"/>
+ <xi:include href="faq-copyright.xml"/>
+ </qandaset>
</article>
+<?xml version="1.0" encoding='UTF-8'?>
+<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+
<sect1 id="using-filemodes"><title>File permissions</title>
<para>On FAT or FAT32 filesystems, files are always readable, and Cygwin
+<?xml version="1.0" encoding='UTF-8'?>
+<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+
<sect1 id="gcc"><title>Using GCC with Cygwin</title>
<sect2 id="gcc-cons"><title>Console Mode Applications</title>
+<?xml version="1.0" encoding='UTF-8'?>
+<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<sect1 id="gdb"><title>Debugging Cygwin Programs</title>
-<sect1 id="ov-ex-win">
-<title>Quick Start Guide for those more experienced with Windows</title>
-<para>
-If you are new to the world of UNIX, you may find it difficult to
-understand at first. This guide is not meant to be comprehensive,
-so we recommend that you use the many available Internet resources
-to become acquainted with UNIX basics (search for "UNIX basics" or
-"UNIX tutorial").
-</para>
-<para>
-To install a basic Cygwin environment, run the
-<command>setup.exe</command> program and click <literal>Next</literal>
-at each page. The default settings are correct for most users. If you
-want to know more about what each option means, see
-<xref linkend="internet-setup"></xref>. Use <command>setup.exe</command>
-any time you want to update or install a Cygwin package. If you are
-installing Cygwin for a specific purpose, use it to install the tools
-that you need. For example, if you want to compile C++ programs, you
-need the <systemitem>gcc-g++</systemitem> package and probably a text
-editor like <systemitem>nano</systemitem>. When running
-<command>setup.exe</command>, clicking on categories and packages in the
-package installation screen will provide you with the ability to control
-what is installed or updated.
-</para>
-<para>
-Another option is to install everything by clicking on the
-<literal>Default</literal> field next to the <literal>All</literal>
-category. However, be advised that this will download and install
-several hundreds of megabytes of software to your computer. The best
-plan is probably to click on individual categories and install either
-entire categories or packages from the categories themselves.
-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 be able to write
-console or GUI executables that rely on the Microsoft Win32 API instead
-of Cygwin using the mingw32 or mingw64 cross-compiler toolchains. The
-<command>-shared</command> option to GCC allows to write Windows Dynamically
-Linked Libraries (DLLs). The resource compiler <command>windres</command>
-is also provided.
-</para>
-</sect1>
-
-<sect1 id="ov-ex-unix">
-<title>Quick Start Guide for those more experienced with UNIX</title>
-<para>
-If you are an experienced UNIX user who misses a powerful command-line
-environment, you will enjoy Cygwin.
-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 will find that the Cygwin library provides
-an easy way to port many UNIX packages, with only minimal source code
-changes.
-</para>
-<para>
-Note that there are some workarounds that cause Cygwin to behave differently
-than most UNIX-like operating systems; these are described in more detail in
-<xref linkend="using-effectively"></xref>.
-</para>
-<para>
-Use the graphical command <command>setup.exe</command> any time you want
-to update or install a Cygwin package. This program must be run
-manually every time you want to check for updated packages since Cygwin
-does not currently include a mechanism for automatically detecting
-package updates.
-</para>
-<para>
-By default, <command>setup.exe</command> only installs a minimal subset of
-packages. Add any other packages by clicking on the <literal>+</literal>
-next to the Category name and selecting the package from the displayed
-list. You may search for specfic tools by using the
-<ulink url="http://cygwin.com/packages/">Setup Package Search</ulink>
-at the Cygwin web site.
-</para>
-<para>
-Another option is to install everything by clicking on the
-<literal>Default</literal> field next to the <literal>All</literal>
-category. However, be advised that this will download and install
-several hundreds of megabytes of software to your computer. The best
-plan is probably to click on individual categories and install either
-entire categories or packages from the categories themselves.
-After installation, you can find Cygwin-specific documentation in
-the <literal>/usr/share/doc/Cygwin/</literal> directory.
-</para>
-<para>
-For more information about what each option in
-<command>setup.exe</command> means, see <xref
-linkend="internet-setup"></xref>.
-</para>
-
-</sect1>
+<?xml version="1.0" encoding='UTF-8'?>
+<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<sect1 id="highlights"><title>Highlights of Cygwin Functionality</title>
+<?xml version="1.0" encoding='UTF-8'?>
+<!DOCTYPE legalnotice PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+
<legalnotice id="legal">
<para>Copyright © 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012 Red Hat, Inc.</para>
+<?xml version="1.0" encoding='UTF-8'?>
+<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+
<sect1 id="ov-new1.7"><title>What's new and what changed in Cygwin 1.7</title>
<sect2 id="ov-new1.7.19"><title>What's new and what changed from 1.7.18 to 1.7.19</title>
+<?xml version="1.0" encoding='UTF-8'?>
+<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+
<sect1 id="ntsec"><title>Using Windows security in Cygwin</title>
<para>This section discusses how the Windows security model is
--- /dev/null
+<?xml version="1.0" encoding='UTF-8'?>
+<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+
+<sect1 id="ov-ex-unix">
+<title>Quick Start Guide for those more experienced with UNIX</title>
+<para>
+If you are an experienced UNIX user who misses a powerful command-line
+environment, you will enjoy Cygwin.
+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 will find that the Cygwin library provides
+an easy way to port many UNIX packages, with only minimal source code
+changes.
+</para>
+<para>
+Note that there are some workarounds that cause Cygwin to behave differently
+than most UNIX-like operating systems; these are described in more detail in
+<xref linkend="using-effectively"></xref>.
+</para>
+<para>
+Use the graphical command <command>setup.exe</command> any time you want
+to update or install a Cygwin package. This program must be run
+manually every time you want to check for updated packages since Cygwin
+does not currently include a mechanism for automatically detecting
+package updates.
+</para>
+<para>
+By default, <command>setup.exe</command> only installs a minimal subset of
+packages. Add any other packages by clicking on the <literal>+</literal>
+next to the Category name and selecting the package from the displayed
+list. You may search for specfic tools by using the
+<ulink url="http://cygwin.com/packages/">Setup Package Search</ulink>
+at the Cygwin web site.
+</para>
+<para>
+Another option is to install everything by clicking on the
+<literal>Default</literal> field next to the <literal>All</literal>
+category. However, be advised that this will download and install
+several hundreds of megabytes of software to your computer. The best
+plan is probably to click on individual categories and install either
+entire categories or packages from the categories themselves.
+After installation, you can find Cygwin-specific documentation in
+the <literal>/usr/share/doc/Cygwin/</literal> directory.
+</para>
+<para>
+For more information about what each option in
+<command>setup.exe</command> means, see <xref
+linkend="internet-setup"></xref>.
+</para>
+
+</sect1>
--- /dev/null
+<?xml version="1.0" encoding='UTF-8'?>
+<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+
+<sect1 id="ov-ex-win">
+<title>Quick Start Guide for those more experienced with Windows</title>
+<para>
+If you are new to the world of UNIX, you may find it difficult to
+understand at first. This guide is not meant to be comprehensive,
+so we recommend that you use the many available Internet resources
+to become acquainted with UNIX basics (search for "UNIX basics" or
+"UNIX tutorial").
+</para>
+<para>
+To install a basic Cygwin environment, run the
+<command>setup.exe</command> program and click <literal>Next</literal>
+at each page. The default settings are correct for most users. If you
+want to know more about what each option means, see
+<xref linkend="internet-setup"></xref>. Use <command>setup.exe</command>
+any time you want to update or install a Cygwin package. If you are
+installing Cygwin for a specific purpose, use it to install the tools
+that you need. For example, if you want to compile C++ programs, you
+need the <systemitem>gcc-g++</systemitem> package and probably a text
+editor like <systemitem>nano</systemitem>. When running
+<command>setup.exe</command>, clicking on categories and packages in the
+package installation screen will provide you with the ability to control
+what is installed or updated.
+</para>
+<para>
+Another option is to install everything by clicking on the
+<literal>Default</literal> field next to the <literal>All</literal>
+category. However, be advised that this will download and install
+several hundreds of megabytes of software to your computer. The best
+plan is probably to click on individual categories and install either
+entire categories or packages from the categories themselves.
+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 be able to write
+console or GUI executables that rely on the Microsoft Win32 API instead
+of Cygwin using the mingw32 or mingw64 cross-compiler toolchains. The
+<command>-shared</command> option to GCC allows to write Windows Dynamically
+Linked Libraries (DLLs). The resource compiler <command>windres</command>
+is also provided.
+</para>
+</sect1>
-<chapter id="overview"><title>Cygwin Overview</title>
+<?xml version="1.0" encoding='UTF-8'?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+
+<chapter id="overview" xmlns:xi="http://www.w3.org/2001/XInclude">
+<title>Cygwin Overview</title>
<sect1 id="what-is-it"><title>What is it?</title>
</para>
</sect1>
-DOCTOOL-INSERT-ov-ex-win
-DOCTOOL-INSERT-ov-ex-unix
+<xi:include href="ov-ex-win.xml"/>
+<xi:include href="ov-ex-unix.xml"/>
<sect1 id="are-free"><title>Are the Cygwin tools free software?</title>
</sect1>
-DOCTOOL-INSERT-highlights
-DOCTOOL-INSERT-ov-new1.7
+<xi:include href="highlights.xml"/>
+<xi:include href="new-features.xml"/>
</chapter>
+<?xml version="1.0" encoding='UTF-8'?>
+<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+
<sect1 id="using-pathnames"><title>Mapping path names</title>
<sect2 id="pathnames-intro"><title>Introduction</title>
</sect2>
</sect1>
-
-<sect1 id="using-specialnames"><title>Special filenames</title>
-
-<sect2 id="pathnames-etc"><title>Special files in /etc</title>
-
-<para>Certain files in Cygwin's <filename>/etc</filename> directory are
-read by Cygwin before the mount table has been established. The list
-of files is</para>
-
-<screen>
- /etc/fstab
- /etc/fstab.d/$USER
- /etc/passwd
- /etc/group
-</screen>
-
-<para>These file are read using native Windows NT functions which have
-no notion of Cygwin symlinks or POSIX paths. For that reason
-there are a few requirements as far as <filename>/etc</filename> is
-concerned.</para>
-
-<para>To access these files, the Cygwin DLL evaluates it's own full
-Windows path, strips off the innermost directory component and adds
-"\etc". Let's assume the Cygwin DLL is installed as
-<filename>C:\cygwin\bin\cygwin1.dll</filename>. First the DLL name as
-well as the innermost directory (<filename>bin</filename>) is stripped
-off: <filename>C:\cygwin\</filename>. Then "etc" and the filename to
-look for is attached: <filename>C:\cygwin\etc\fstab</filename>. So the
-/etc directory must be parallel to the directory in which the cygwin1.dll
-exists and <filename>/etc</filename> must not be a Cygwin symlink
-pointing to another directory. Consequentially none of the files from
-the above list, including the directory <filename>/etc/fstab.d</filename>
-is allowed to be a Cygwin symlink either.</para>
-
-<para>However, native NTFS symlinks and reparse points are transparent
-when accessing the above files so all these files as well as
-<filename>/etc</filename> itself may be NTFS symlinks or reparse
-points.</para>
-
-<para>Last but not least, make sure that these files are world-readable.
-Every process of any user account has to read these files potentially,
-so world-readability is essential. The only exception are the user
-specific files <filename>/etc/fstab.d/$USER</filename>, which only have
-to be readable by the $USER user account itself.</para>
-
-</sect2>
-
-<sect2 id="pathnames-dosdevices"><title>Invalid filenames</title>
-
-<para>Filenames invalid under Win32 are not necessarily invalid
-under Cygwin since release 1.7.0. There are a few rules which
-apply to Windows filenames. Most notably, DOS device names like
-<filename>AUX</filename>, <filename>COM1</filename>,
-<filename>LPT1</filename> or <filename>PRN</filename> (to name a few)
-cannot be used as filename or extension in a native Win32 application.
-So filenames like <filename>prn.txt</filename> or <filename>foo.aux</filename>
-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 applications.</para>
-
-</sect2>
-
-<sect2 id="pathnames-specialchars">
-<title>Forbidden characters in filenames</title>
-
-<para>Some characters are disallowed in filenames on Windows filesystems.
-These forbidden characters are the ASCII control characters from ASCII
-value 1 to 31, plus the following characters which have a special meaning
-in the Win32 API:</para>
-
-<screen>
- " * : < > ? | \
-</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>
-
-<para>The backslash has to be exempt from this conversion, because Cygwin
-accepts Win32 filenames including backslashes as path separators on input.
-Converting backslashes using the above method would make this impossible.</para>
-
-<para>Additionally Win32 filenames can't contain trailing dots and spaces
-for DOS backward compatibility. When trying to create files with trailing
-dots or spaces, 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>An exception from this rule are some network filesystems (NetApp,
-NWFS) which choke on these filenames. They return with an error like
-"No such file or directory" when trying to create such files. Starting
-with Cygwin 1.7.6, Cygwin recognizes these filesystems and works around
-this problem by applying the same rule as for the other forbidden characters.
-Leading spaces and trailing dots and spaces will be converted to UNICODE
-characters in the private use area. This behaviour can be switched on
-explicitely for a filesystem or a directory tree by using the mount option
-<literal>dos</literal>.</para>
-
-</sect2>
-
-<sect2 id="pathnames-unusual">
-<title>Filenames with unusual (foreign) characters</title>
-
-<para> Windows filesystems use Unicode encoded as UTF-16
-to store filename information. If you don't use the UTF-8
-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>
-
-<note><para>In the default "C" locale, Cygwin creates filenames using
-the UTF-8 charset. This will always result in some valid filename by
-default, but again might impose problems when switching to a non-"C"
-or non-"UTF-8" charset.</para></note>
-
-<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
-reason, you will nevertheless be able to access the file. How does that
-work? When Cygwin converts the filename from UTF-16 to your character
-set, it recognizes characters which can't be converted. If that occurs,
-Cygwin replaces the non-convertible character with a special character
-sequence. The sequence starts with an ASCII CAN character (hex code
-0x18, equivalent Control-X), followed by the UTF-8 representation of the
-character. The result is a filename containing some ugly looking
-characters. While it doesn't <emphasis role='bold'>look</emphasis> nice, it
-<emphasis role='bold'>is</emphasis> nice, because Cygwin knows how to convert
-this filename back to UTF-16. The filename will be converted using your
-usual character set. However, when Cygwin recognizes an ASCII CAN
-character, it skips over the ASCII CAN and handles the following bytes as
-a UTF-8 character. Thus, the filename is symmetrically converted back to
-UTF-16 and you can access the file.</para>
-
-<note><para>Please be aware that this method is not entirely foolproof.
-In some character set combinations it might not work for certain native
-characters.</para>
-
-<para>Only by using the UTF-8 charset you can avoid this problem safely.
-</para></note>
-
-</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 can not be 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.</para>
-
-<note>
-<para>
-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. However, there are limitations:
-while two <emphasis role='bold'>programs</emphasis> <filename>Abc.exe</filename>
-and <filename>aBc.exe</filename> can be created and accessed like other files,
-starting applications is still case-insensitive due to Windows limitations
-and so the program you try to launch may not be the one actually started. Also,
-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
-<filename>/etc/fstab</filename>, or your <filename>/etc/fstab.d/$USER</filename>
-file.</para>
-
-<para><filename>/cygdrive</filename> paths are case-insensitive by default.
-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>
-path is case-insensitive by default and you have to use the "posix=1" setting
-explicitly in <filename>/etc/fstab</filename> or
-<filename>/etc/fstab.d/$USER</filename> to switch it to case-sensitivity,
-or you have to make sure that the native Win32 %PATH% environment variable
-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 subdirectories 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>While there is no need to create a POSIX <filename>/dev</filename>
-directory, the directory is automatically created as part of a Cygwin
-installation. It's existence is often a prerequisit to run certain
-applications which create symbolic links, fifos, or UNIX sockets in
-<filename>/dev</filename>. Also, the directories <filename>/dev/shm</filename>
-and <filename>/dev/mqueue</filename> are required to exist to use named POSIX
-semaphores, shared memory, and message queues, so a system without a real
-<filename>/dev</filename> directory is functionally crippled.
-</para>
-
-<para>Apart from that, Cygwin automatically simulates POSIX devices
-internally. Up to Cygwin 1.7.11, these devices couldn't be seen with the
-command <command>ls /dev/</command> although commands such as
-<command>ls /dev/tty</command> worked fine. Starting with Cygwin 1.7.12,
-the <filename>/dev</filename> directory is automagically populated with
-existing POSIX devices by Cygwin in a way comparable with a
-<ulink url="http://en.wikipedia.org/wiki/Udev">udev</ulink> based virtual
-<filename>/dev</filename> directory under Linux.</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 current console window of a session.
- Up to Cygwin 1.7.9, this was the only name for a console.
- Different consoles were indistinguishable.
- Cygwin's /dev/console is not quite comparable with the console
- device on UNIX machines.
-
-/dev/cons0 Starting with Cygwin 1.7.10, Console sessions are numbered from
-/dev/cons1 /dev/cons0 upwards. Console device names are pseudo device
-... names, only accessible from processes within this very console
- session. This is due to a restriction in Windows.
-
-/dev/tty The current controlling tty of a session.
-
-/dev/ptmx Pseudo tty master device.
-
-/dev/pty0 Pseudo ttys are numbered from /dev/pty0 upwards as they are
-/dev/pty1 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 also has several Windows-specific devices:
-</para>
-
-<screen>
-/dev/com1 The serial ports, starting with COM1 which is the same as ttyS0.
-/dev/com2 Please use /dev/ttySx instead.
-...
-
-/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>
-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.</para>
-
-<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" 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 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
-<command>df</command> output, you should be able to figure out which
-external drive corresponds to which raw disk device name.</para>
-
-<note><para>Apart from tape devices which are not block devices and are
-by default accessed directly, accessing mass storage devices raw
-is something you should only do if you know what you're doing and know how to
-handle the information. <emphasis role='bold'>Writing</emphasis> to a raw
-mass storage device you should only do if you
-<emphasis role='bold'>really</emphasis> know what you're doing and are aware
-of the fact that any mistake can destroy important information, for the
-device, and for you. So, please, handle this ability with care.
-<emphasis role='bold'>You have been warned.</emphasis></para></note>
-
-<para>
-Last but not least, the mapping from POSIX /dev namespace to internal
-NT namespace is as follows:
-</para>
-
-<screen>
-POSIX device name Internal NT device name
-
-/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/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)
-...
-/dev/sda15 \device\harddisk0\partition15 (fifteenth partition)
-
-/dev/sdb \device\harddisk1\partition0
-/dev/sdb1 \device\harddisk1\partition1
-
-[up to]
-
-/dev/sddx \device\harddisk127\partition0
-/dev/sddx1 \device\harddisk127\partition1
-...
-/dev/sddx15 \device\harddisk127\partition15
-</screen>
-
-<para>
-if you don't like these device names, feel free to create symbolic
-links as they are created on Linux systems for convenience:
-</para>
-
-<screen>
-ln -s /dev/sr0 /dev/cdrom
-ln -s /dev/nst0 /dev/tape
-...
-</screen>
-
-</sect2>
-
-<sect2 id="pathnames-exe"><title>The .exe extension</title>
-
-<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
-cannot omit the extension. </para>
-
-<para>As a side effect, the <command> ls filename</command> gives
-information about <filename>filename.exe</filename> if
-<filename>filename.exe</filename> exists and <filename>filename</filename>
-does not. In the same situation the function call
-<function>stat("filename",..)</function> gives information about
-<filename>filename.exe</filename>. The two files can be distinguished
-by examining their inodes, as demonstrated below.
-<screen>
-<prompt>bash$</prompt> <userinput>ls * </userinput>
-a a.exe b.exe
-<prompt>bash$</prompt> <userinput>ls -i a a.exe</userinput>
-445885548 a 435996602 a.exe
-<prompt>bash$</prompt> <userinput>ls -i b b.exe</userinput>
-432961010 b 432961010 b.exe
-</screen>
-If a shell script <filename>myprog</filename> and a program
-<filename>myprog.exe</filename> coexist in a directory, the shell
-script has precedence and is selected for execution of
-<command>myprog</command>. Note that this was quite the reverse up to
-Cygwin 1.5.19. It has been changed for consistency with the rest of Cygwin.
-</para>
-
-<para>The <command>gcc</command> compiler produces an executable named
-<filename>filename.exe</filename> when asked to produce
-<filename>filename</filename>. This allows many makefiles written
-for UNIX systems to work well under Cygwin.</para>
-
-</sect2>
-
-<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
-directory are representations of various aspects of your system,
-for example the command <userinput>cat /proc/cpuinfo</userinput>
-displays information such as what model and speed processor you have.
-</para>
-<para>
-One unique aspect of the Cygwin <filename>/proc</filename> filesystem
-is <filename>/proc/registry</filename>, see next section.
-</para>
-<para>
-The Cygwin <filename>/proc</filename> is not as complete as the
-one in Linux, but it provides significant capabilities. The
-<systemitem>procps</systemitem> package contains several utilities
-that use it.
-</para>
-</sect2>
-
-<sect2 id="pathnames-proc-registry"><title>The /proc/registry filesystem</title>
-<para>
-The <filename>/proc/registry</filename> filesystem provides read-only
-access to the Windows registry. It displays 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. 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>
-Reserved characters ('/', '\', ':', and '%') or reserved names
-(<filename>.</filename> and <filename>..</filename>) are converted by
-percent-encoding:
-<screen>
-<prompt>bash$</prompt> <userinput>regtool list -v '\HKEY_LOCAL_MACHINE\SYSTEM\MountedDevices'</userinput>
-...
-\DosDevices\C: (REG_BINARY) = cf a8 97 e8 00 08 fe f7
-...
-<prompt>bash$</prompt> <userinput>cd /proc/registry/HKEY_LOCAL_MACHINE/SYSTEM</userinput>
-<prompt>bash$</prompt> <userinput>ls -l MountedDevices</userinput>
-...
--r--r----- 1 Admin SYSTEM 12 Dec 10 11:20 %5CDosDevices%5CC%3A
-...
-<prompt>bash$</prompt> <userinput>od -t x1 MountedDevices/%5CDosDevices%5CC%3A</userinput>
-0000000 cf a8 97 e8 00 08 fe f7 01 00 00 00
-</screen>
-The unnamed (default) value of a key can be accessed using the filename
-<filename>@</filename>.
-</para>
-<para>
-If a registry key contains a subkey and a value with the same name
-<filename>foo</filename>, Cygwin displays the subkey as
-<filename>foo</filename> and the value as <filename>foo%val</filename>.
-</para>
-</sect2>
-
-<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, when invoked by non-Cygwin processes, expand their arguments
-starting with "@" in a special way. If a file
-<filename>pathname</filename> exists, the argument
-<filename>@pathname</filename> expands recursively to the content of
-<filename>pathname</filename>. Double quotes can be used inside the
-file to delimit strings containing blank space.
-In the following example compare the behaviors
-<command>/bin/echo</command> when run from bash and from the Windows command prompt.</para>
-
-<example id="pathnames-at-ex"><title> Using @pathname</title>
-<screen>
-<prompt>bash$</prompt> <userinput>/bin/echo 'This is "a long" line' > mylist</userinput>
-<prompt>bash$</prompt> <userinput>/bin/echo @mylist</userinput>
-@mylist
-<prompt>bash$</prompt> <userinput>cmd</userinput>
-<prompt>c:\></prompt> <userinput>c:\cygwin\bin\echo @mylist</userinput>
-This is a long line
-</screen>
-</example>
-</sect2>
-</sect1>
+++ /dev/null
-<chapter id="programming"><title>Programming with Cygwin</title>
-
-DOCTOOL-INSERT-gcc
-
-DOCTOOL-INSERT-gdb
-
-DOCTOOL-INSERT-dll
-
-DOCTOOL-INSERT-windres
-
-</chapter>
--- /dev/null
+<?xml version="1.0" encoding='UTF-8'?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+
+<chapter id="programming" xmlns:xi="http://www.w3.org/2001/XInclude">
+ <title>Programming with Cygwin</title>
+
+ <xi:include href="gcc.xml"/>
+ <xi:include href="gdb.xml"/>
+ <xi:include href="dll.xml"/>
+ <xi:include href="windres.xml"/>
+</chapter>
--- /dev/null
+<?xml version="1.0" encoding='UTF-8'?>
+<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+
+<sect1 id="setup-env"><title>Environment Variables</title>
+
+<sect2 id="setup-env-ov"><title>Overview</title>
+
+<para>
+All Windows environment variables are imported when Cygwin starts.
+Apart from that, you may wish to specify settings of several important
+environment variables that affect Cygwin's operation.</para>
+
+<para>
+The <envar>CYGWIN</envar> variable is used to configure a few global
+settings for the Cygwin runtime system. Typically you can leave
+<envar>CYGWIN</envar> unset, but if you want to set one ore more
+options, you can set it using a syntax like this, depending on the shell
+in which you're setting it. Here is an example in CMD syntax:</para>
+
+<screen>
+<prompt>C:\></prompt> <userinput>set CYGWIN=error_start:C:\cygwin\bin\gdb.exe glob</userinput>
+</screen>
+
+<para>
+This is, of course, just an example. For the recognized settings of the
+<envar>CYGWIN</envar> environment variable, see
+<xref linkend="using-cygwinenv"></xref>.
+</para>
+
+<para>
+Locale support is controlled by the <envar>LANG</envar> and
+<envar>LC_xxx</envar> environment variables. Since Cygwin 1.7.2, all of
+them are honored and have a meaning. For a more detailed description see
+<xref linkend="setup-locale"></xref>.
+</para>
+
+<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:\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. It's usually set in the shell
+profile scripts in the /etc directory.
+</para>
+
+<para>
+The <envar>TERM</envar> environment variable specifies your terminal
+type. It is automatically set to <literal>cygwin</literal> if you have
+not set it to something else.
+</para>
+
+<para>The <envar>LD_LIBRARY_PATH</envar> environment variable is used by
+the Cygwin function <function>dlopen ()</function> as a list of
+directories to search for .dll files to load. This environment variable
+is converted from Windows format to UNIX format when a Cygwin process
+first starts. Most Cygwin applications do not make use of the
+<function>dlopen ()</function> call and do not need this variable.
+</para>
+
+<para>
+In addition to <envar>PATH</envar>, <envar>HOME</envar>,
+and <envar>LD_LIBRARY_PATH</envar>, there are three other environment
+variables which, if they exist in the Windows environment, are
+converted to UNIX format: <envar>TMPDIR</envar>, <envar>TMP</envar>,
+and <envar>TEMP</envar>. The first is not set by default in the
+Windows environment but the other two are, and they point to the
+default Windows temporary directory. If set, these variables will be
+used by some Cygwin applications, possibly with unexpected results.
+You may therefore want to unset them by adding the following two lines
+to your <filename>~/.bashrc</filename> file:
+
+<screen>
+unset TMP
+unset TEMP
+</screen>
+
+This is done in the default <filename>~/.bashrc</filename> file.
+Alternatively, you could set <envar>TMP</envar>
+and <envar>TEMP</envar> to point to <filename>/tmp</filename> or to
+any other temporary directory of your choice. For example:
+
+<screen>
+export TMP=/tmp
+export TEMP=/tmp
+</screen>
+</para>
+
+</sect2>
+
+<sect2 id="setup-env-win32"><title>Restricted Win32 environment</title>
+
+<para>There is a restriction when calling Win32 API functions which
+require a fully set up application environment. Cygwin maintains its own
+environment in POSIX style. The Win32 environment is usually stripped
+to a bare minimum and not at all kept in sync with the Cygwin POSIX
+environment.</para>
+
+<para>If you need the full Win32 environment set up in a Cygwin process,
+you have to call</para>
+
+<screen>
+#include <sys/cygwin.h>
+
+cygwin_internal (CW_SYNC_WINENV);
+</screen>
+
+<para>to synchronize the Win32 environment with the Cygwin environment.
+Note that this only synchronizes the Win32 environment once with the
+Cygwin environment. Later changes using the <function>setenv</function>
+or <function>putenv</function> calls are not reflected in the Win32
+environment. In these cases, you have to call the aforementioned
+<function>cygwin_internal</function> call again.</para>
+
+</sect2>
+
+</sect1>
--- /dev/null
+<?xml version="1.0" encoding='UTF-8'?>
+<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+
+<sect1 id="setup-files"><title>Customizing bash</title>
+
+<para>
+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
+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>. 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
+page) contains bash commands. It is executed when bash is started as login
+shell, e.g. from the command <command>bash --login</command>.
+This is a useful place to define and
+export environment variables and bash functions that will be used by bash
+and the programs invoked by bash. It is a good place to redefine
+<envar>PATH</envar> if needed. We recommend adding a ":." to the end of
+<envar>PATH</envar> to also search the current working directory (contrary
+to DOS, the local directory is not searched by default). Also to avoid
+delays you should either <command>unset</command> <envar>MAILCHECK</envar>
+or define <envar>MAILPATH</envar> to point to your existing mail inbox.
+</para>
+
+<para>
+<filename>.bashrc</filename> is similar to
+<filename>.profile</filename> but is executed each time an interactive
+bash shell is launched. It serves to define elements that are not
+inherited through the environment, such as aliases. If you do not use
+login shells, you may want to put the contents of
+<filename>.profile</filename> as discussed above in this file
+instead.
+</para>
+
+<para>
+<screen>
+shopt -s nocaseglob
+</screen>
+will allow bash to glob filenames in a case-insensitive manner.
+Note that <filename>.bashrc</filename> is not called automatically for login
+shells. You can source it from <filename>.profile</filename>.
+</para>
+
+<para>
+<filename>.inputrc</filename> controls how programs using the readline
+library (including <command>bash</command>) behave. It is loaded
+automatically. For full details see the <literal>Function and Variable
+Index</literal> section of the GNU <systemitem>readline</systemitem> manual.
+Consider the following settings:
+<screen>
+# Ignore case while completing
+set completion-ignore-case on
+# Make Bash 8bit clean
+set meta-flag on
+set convert-meta off
+set output-meta on
+</screen>
+The first command makes filename completion case insensitive, which can
+be convenient in a Windows environment. The next three commands allow
+<command>bash</command> to display 8-bit characters, useful for
+languages with accented characters. Note that tools that do not use
+<systemitem>readline</systemitem> for display, such as
+<command>less</command> and <command>ls</command>, require additional
+settings, which could be put in your <filename>.bashrc</filename>:
+<screen>
+alias less='/bin/less -r'
+alias ls='/bin/ls -F --color=tty --show-control-chars'
+</screen>
+</para>
+
+</sect1>
+
-<sect1 id="setup-env"><title>Environment Variables</title>
-
-<sect2 id="setup-env-ov"><title>Overview</title>
-
-<para>
-All Windows environment variables are imported when Cygwin starts.
-Apart from that, you may wish to specify settings of several important
-environment variables that affect Cygwin's operation.</para>
-
-<para>
-The <envar>CYGWIN</envar> variable is used to configure a few global
-settings for the Cygwin runtime system. Typically you can leave
-<envar>CYGWIN</envar> unset, but if you want to set one ore more
-options, you can set it using a syntax like this, depending on the shell
-in which you're setting it. Here is an example in CMD syntax:</para>
-
-<screen>
-<prompt>C:\></prompt> <userinput>set CYGWIN=error_start:C:\cygwin\bin\gdb.exe glob</userinput>
-</screen>
-
-<para>
-This is, of course, just an example. For the recognized settings of the
-<envar>CYGWIN</envar> environment variable, see
-<xref linkend="using-cygwinenv"></xref>.
-</para>
-
-<para>
-Locale support is controlled by the <envar>LANG</envar> and
-<envar>LC_xxx</envar> environment variables. Since Cygwin 1.7.2, all of
-them are honored and have a meaning. For a more detailed description see
-<xref linkend="setup-locale"></xref>.
-</para>
-
-<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:\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. It's usually set in the shell
-profile scripts in the /etc directory.
-</para>
-
-<para>
-The <envar>TERM</envar> environment variable specifies your terminal
-type. It is automatically set to <literal>cygwin</literal> if you have
-not set it to something else.
-</para>
-
-<para>The <envar>LD_LIBRARY_PATH</envar> environment variable is used by
-the Cygwin function <function>dlopen ()</function> as a list of
-directories to search for .dll files to load. This environment variable
-is converted from Windows format to UNIX format when a Cygwin process
-first starts. Most Cygwin applications do not make use of the
-<function>dlopen ()</function> call and do not need this variable.
-</para>
-
-<para>
-In addition to <envar>PATH</envar>, <envar>HOME</envar>,
-and <envar>LD_LIBRARY_PATH</envar>, there are three other environment
-variables which, if they exist in the Windows environment, are
-converted to UNIX format: <envar>TMPDIR</envar>, <envar>TMP</envar>,
-and <envar>TEMP</envar>. The first is not set by default in the
-Windows environment but the other two are, and they point to the
-default Windows temporary directory. If set, these variables will be
-used by some Cygwin applications, possibly with unexpected results.
-You may therefore want to unset them by adding the following two lines
-to your <filename>~/.bashrc</filename> file:
-
-<screen>
-unset TMP
-unset TEMP
-</screen>
-
-This is done in the default <filename>~/.bashrc</filename> file.
-Alternatively, you could set <envar>TMP</envar>
-and <envar>TEMP</envar> to point to <filename>/tmp</filename> or to
-any other temporary directory of your choice. For example:
-
-<screen>
-export TMP=/tmp
-export TEMP=/tmp
-</screen>
-</para>
-
-</sect2>
-
-<sect2 id="setup-env-win32"><title>Restricted Win32 environment</title>
-
-<para>There is a restriction when calling Win32 API functions which
-require a fully set up application environment. Cygwin maintains its own
-environment in POSIX style. The Win32 environment is usually stripped
-to a bare minimum and not at all kept in sync with the Cygwin POSIX
-environment.</para>
-
-<para>If you need the full Win32 environment set up in a Cygwin process,
-you have to call</para>
-
-<screen>
-#include <sys/cygwin.h>
-
-cygwin_internal (CW_SYNC_WINENV);
-</screen>
-
-<para>to synchronize the Win32 environment with the Cygwin environment.
-Note that this only synchronizes the Win32 environment once with the
-Cygwin environment. Later changes using the <function>setenv</function>
-or <function>putenv</function> calls are not reflected in the Win32
-environment. In these cases, you have to call the aforementioned
-<function>cygwin_internal</function> call again.</para>
-
-</sect2>
-
-</sect1>
-
-<sect1 id="setup-maxmem"><title>Changing Cygwin's Maximum Memory</title>
-
-<para>
-Cygwin's heap is extensible. However, it does start out at a fixed size
-and attempts to extend it may run into memory which has been previously
-allocated by Windows. In some cases, this problem can be solved by
-changing a field in the file header which is utilized by Cygwin since
-version 1.7.10 to keep the initial size of the application heap. If the
-field contains 0, which is the default, the application heap defaults to
-a size of 384 Megabyte. If the field is set to any other value between 4 and
-2048, Cygwin tries to reserve as much Megabytes for the application heap.
-The field used for this is the "LoaderFlags" field in the NT-specific
-PE header structure (<literal>(IMAGE_NT_HEADER)->OptionalHeader.LoaderFlags</literal>).</para>
-
-<para>
-This value can be changed for any executable by using a more recent version
-of the <command>peflags</command> tool from the <literal>rebase</literal>
-Cygwin package. Example:
-
-<screen>
-$ peflags --cygwin-heap foo.exe
-foo.exe: initial Cygwin heap size: 0 (0x0) MB
-$ peflags --cygwin-heap=500 foo.exe
-foo.exe: initial Cygwin heap size: 500 (0x1f4) MB
-</screen>
-</para>
-
-<para>
-Heap memory can be allocated up to the size of the biggest available free
-block in the processes virtual memory (VM). By default, the VM per process
-is 2 GB for 32 processes. To get more VM for a process, the executable
-must have the "large address aware" flag set in the file header. You can
-use the aforementioned <command>peflags</command> tool to set this flag.
-On 64 bit systems this results in a 4 GB VM for a process started from that
-executable. On 32 bit systems you also have to prepare the system to allow
-up to 3 GB per process. See the Microsoft article
-<ulink url="http://msdn.microsoft.com/en-us/library/bb613473%28VS.85%29.aspx">4-Gigabyte Tuning</ulink>
-for more information.
-</para>
-
-<note>
-<para>
-Older Cygwin releases only supported a global registry setting to
-change the initial heap size for all Cygwin processes. This setting is
-not used anymore. However, if you're running an older Cygwin release
-than 1.7.10, you can add the <literal>DWORD</literal> value
-<literal>heap_chunk_in_mb</literal> and set it to the desired memory limit
-in decimal MB. You have to stop all Cygwin processes for this setting to
-have any effect. It is preferred to do this in Cygwin using the
-<command>regtool</command> program included in the Cygwin package.
-(see <xref linkend="regtool"></xref>) This example sets the memory limit
-to 1024 MB for all Cygwin processes (use HKCU instead of HKLM if you
-want to set this only for the current user):
-
-<screen>
-$ regtool -i set /HKLM/Software/Cygwin/heap_chunk_in_mb 1024
-$ regtool -v list /HKLM/Software/Cygwin
-</screen>
-</para>
-</note>
-
-</sect1>
+<?xml version="1.0" encoding='UTF-8'?>
+<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<sect1 id="setup-locale"><title>Internationalization</title>
</sect2>
</sect1>
-
-<sect1 id="setup-files"><title>Customizing bash</title>
-
-<para>
-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
-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>. 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
-page) contains bash commands. It is executed when bash is started as login
-shell, e.g. from the command <command>bash --login</command>.
-This is a useful place to define and
-export environment variables and bash functions that will be used by bash
-and the programs invoked by bash. It is a good place to redefine
-<envar>PATH</envar> if needed. We recommend adding a ":." to the end of
-<envar>PATH</envar> to also search the current working directory (contrary
-to DOS, the local directory is not searched by default). Also to avoid
-delays you should either <command>unset</command> <envar>MAILCHECK</envar>
-or define <envar>MAILPATH</envar> to point to your existing mail inbox.
-</para>
-
-<para>
-<filename>.bashrc</filename> is similar to
-<filename>.profile</filename> but is executed each time an interactive
-bash shell is launched. It serves to define elements that are not
-inherited through the environment, such as aliases. If you do not use
-login shells, you may want to put the contents of
-<filename>.profile</filename> as discussed above in this file
-instead.
-</para>
-
-<para>
-<screen>
-shopt -s nocaseglob
-</screen>
-will allow bash to glob filenames in a case-insensitive manner.
-Note that <filename>.bashrc</filename> is not called automatically for login
-shells. You can source it from <filename>.profile</filename>.
-</para>
-
-<para>
-<filename>.inputrc</filename> controls how programs using the readline
-library (including <command>bash</command>) behave. It is loaded
-automatically. For full details see the <literal>Function and Variable
-Index</literal> section of the GNU <systemitem>readline</systemitem> manual.
-Consider the following settings:
-<screen>
-# Ignore case while completing
-set completion-ignore-case on
-# Make Bash 8bit clean
-set meta-flag on
-set convert-meta off
-set output-meta on
-</screen>
-The first command makes filename completion case insensitive, which can
-be convenient in a Windows environment. The next three commands allow
-<command>bash</command> to display 8-bit characters, useful for
-languages with accented characters. Note that tools that do not use
-<systemitem>readline</systemitem> for display, such as
-<command>less</command> and <command>ls</command>, require additional
-settings, which could be put in your <filename>.bashrc</filename>:
-<screen>
-alias less='/bin/less -r'
-alias ls='/bin/ls -F --color=tty --show-control-chars'
-</screen>
-</para>
-
-</sect1>
-
--- /dev/null
+<?xml version="1.0" encoding='UTF-8'?>
+<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+
+<sect1 id="setup-maxmem"><title>Changing Cygwin's Maximum Memory</title>
+
+<para>
+Cygwin's heap is extensible. However, it does start out at a fixed size
+and attempts to extend it may run into memory which has been previously
+allocated by Windows. In some cases, this problem can be solved by
+changing a field in the file header which is utilized by Cygwin since
+version 1.7.10 to keep the initial size of the application heap. If the
+field contains 0, which is the default, the application heap defaults to
+a size of 384 Megabyte. If the field is set to any other value between 4 and
+2048, Cygwin tries to reserve as much Megabytes for the application heap.
+The field used for this is the "LoaderFlags" field in the NT-specific
+PE header structure (<literal>(IMAGE_NT_HEADER)->OptionalHeader.LoaderFlags</literal>).</para>
+
+<para>
+This value can be changed for any executable by using a more recent version
+of the <command>peflags</command> tool from the <literal>rebase</literal>
+Cygwin package. Example:
+
+<screen>
+$ peflags --cygwin-heap foo.exe
+foo.exe: initial Cygwin heap size: 0 (0x0) MB
+$ peflags --cygwin-heap=500 foo.exe
+foo.exe: initial Cygwin heap size: 500 (0x1f4) MB
+</screen>
+</para>
+
+<para>
+Heap memory can be allocated up to the size of the biggest available free
+block in the processes virtual memory (VM). By default, the VM per process
+is 2 GB for 32 processes. To get more VM for a process, the executable
+must have the "large address aware" flag set in the file header. You can
+use the aforementioned <command>peflags</command> tool to set this flag.
+On 64 bit systems this results in a 4 GB VM for a process started from that
+executable. On 32 bit systems you also have to prepare the system to allow
+up to 3 GB per process. See the Microsoft article
+<ulink url="http://msdn.microsoft.com/en-us/library/bb613473%28VS.85%29.aspx">4-Gigabyte Tuning</ulink>
+for more information.
+</para>
+
+<note>
+<para>
+Older Cygwin releases only supported a global registry setting to
+change the initial heap size for all Cygwin processes. This setting is
+not used anymore. However, if you're running an older Cygwin release
+than 1.7.10, you can add the <literal>DWORD</literal> value
+<literal>heap_chunk_in_mb</literal> and set it to the desired memory limit
+in decimal MB. You have to stop all Cygwin processes for this setting to
+have any effect. It is preferred to do this in Cygwin using the
+<command>regtool</command> program included in the Cygwin package.
+(see <xref linkend="regtool"></xref>) This example sets the memory limit
+to 1024 MB for all Cygwin processes (use HKCU instead of HKLM if you
+want to set this only for the current user):
+
+<screen>
+$ regtool -i set /HKLM/Software/Cygwin/heap_chunk_in_mb 1024
+$ regtool -v list /HKLM/Software/Cygwin
+</screen>
+</para>
+</note>
+
+</sect1>
-<chapter id="setup-net"><title>Setting Up Cygwin</title>
+<?xml version="1.0" encoding='UTF-8'?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+
+<chapter id="setup-net" xmlns:xi="http://www.w3.org/2001/XInclude">
+<title>Setting Up Cygwin</title>
<sect1 id="internet-setup">
<title>Internet Setup</title>
</sect1>
-DOCTOOL-INSERT-setup-env
-DOCTOOL-INSERT-setup-maxmem
-DOCTOOL-INSERT-setup-locale
-DOCTOOL-INSERT-setup-files
+<xi:include href="setup-env.xml"/>
+<xi:include href="setup-maxmem.xml"/>
+<xi:include href="setup-locale.xml"/>
+<xi:include href="setup-files.xml"/>
</chapter>
-<chapter id="setup"><title>Setting Up Cygwin</title>
+<?xml version="1.0" encoding='UTF-8'?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+
+<chapter id="setup" xmlns:xi="http://www.w3.org/2001/XInclude">
+<title>Setting Up Cygwin</title>
<sect1><title>Cygwin Contents</title>
</sect1>
-DOCTOOL-INSERT-setup-dir
-DOCTOOL-INSERT-setup-env
-DOCTOOL-INSERT-ntsec
-DOCTOOL-INSERT-setup-reg
-DOCTOOL-INSERT-setup-mount
+<xi:include href="setup-dir.xml"/>
+<xi:include href="setup-env.xml"/>
+<xi:include href="ntsec.xml"/>
+<xi:include href="setup-reg.xml"/>
+<xi:include href="setup-mount.xml"/>
</chapter>
--- /dev/null
+<?xml version="1.0" encoding='UTF-8'?>
+<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+
+<sect1 id="using-specialnames"><title>Special filenames</title>
+
+<sect2 id="pathnames-etc"><title>Special files in /etc</title>
+
+<para>Certain files in Cygwin's <filename>/etc</filename> directory are
+read by Cygwin before the mount table has been established. The list
+of files is</para>
+
+<screen>
+ /etc/fstab
+ /etc/fstab.d/$USER
+ /etc/passwd
+ /etc/group
+</screen>
+
+<para>These file are read using native Windows NT functions which have
+no notion of Cygwin symlinks or POSIX paths. For that reason
+there are a few requirements as far as <filename>/etc</filename> is
+concerned.</para>
+
+<para>To access these files, the Cygwin DLL evaluates it's own full
+Windows path, strips off the innermost directory component and adds
+"\etc". Let's assume the Cygwin DLL is installed as
+<filename>C:\cygwin\bin\cygwin1.dll</filename>. First the DLL name as
+well as the innermost directory (<filename>bin</filename>) is stripped
+off: <filename>C:\cygwin\</filename>. Then "etc" and the filename to
+look for is attached: <filename>C:\cygwin\etc\fstab</filename>. So the
+/etc directory must be parallel to the directory in which the cygwin1.dll
+exists and <filename>/etc</filename> must not be a Cygwin symlink
+pointing to another directory. Consequentially none of the files from
+the above list, including the directory <filename>/etc/fstab.d</filename>
+is allowed to be a Cygwin symlink either.</para>
+
+<para>However, native NTFS symlinks and reparse points are transparent
+when accessing the above files so all these files as well as
+<filename>/etc</filename> itself may be NTFS symlinks or reparse
+points.</para>
+
+<para>Last but not least, make sure that these files are world-readable.
+Every process of any user account has to read these files potentially,
+so world-readability is essential. The only exception are the user
+specific files <filename>/etc/fstab.d/$USER</filename>, which only have
+to be readable by the $USER user account itself.</para>
+
+</sect2>
+
+<sect2 id="pathnames-dosdevices"><title>Invalid filenames</title>
+
+<para>Filenames invalid under Win32 are not necessarily invalid
+under Cygwin since release 1.7.0. There are a few rules which
+apply to Windows filenames. Most notably, DOS device names like
+<filename>AUX</filename>, <filename>COM1</filename>,
+<filename>LPT1</filename> or <filename>PRN</filename> (to name a few)
+cannot be used as filename or extension in a native Win32 application.
+So filenames like <filename>prn.txt</filename> or <filename>foo.aux</filename>
+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 applications.</para>
+
+</sect2>
+
+<sect2 id="pathnames-specialchars">
+<title>Forbidden characters in filenames</title>
+
+<para>Some characters are disallowed in filenames on Windows filesystems.
+These forbidden characters are the ASCII control characters from ASCII
+value 1 to 31, plus the following characters which have a special meaning
+in the Win32 API:</para>
+
+<screen>
+ " * : < > ? | \
+</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>
+
+<para>The backslash has to be exempt from this conversion, because Cygwin
+accepts Win32 filenames including backslashes as path separators on input.
+Converting backslashes using the above method would make this impossible.</para>
+
+<para>Additionally Win32 filenames can't contain trailing dots and spaces
+for DOS backward compatibility. When trying to create files with trailing
+dots or spaces, 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>An exception from this rule are some network filesystems (NetApp,
+NWFS) which choke on these filenames. They return with an error like
+"No such file or directory" when trying to create such files. Starting
+with Cygwin 1.7.6, Cygwin recognizes these filesystems and works around
+this problem by applying the same rule as for the other forbidden characters.
+Leading spaces and trailing dots and spaces will be converted to UNICODE
+characters in the private use area. This behaviour can be switched on
+explicitely for a filesystem or a directory tree by using the mount option
+<literal>dos</literal>.</para>
+
+</sect2>
+
+<sect2 id="pathnames-unusual">
+<title>Filenames with unusual (foreign) characters</title>
+
+<para> Windows filesystems use Unicode encoded as UTF-16
+to store filename information. If you don't use the UTF-8
+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>
+
+<note><para>In the default "C" locale, Cygwin creates filenames using
+the UTF-8 charset. This will always result in some valid filename by
+default, but again might impose problems when switching to a non-"C"
+or non-"UTF-8" charset.</para></note>
+
+<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
+reason, you will nevertheless be able to access the file. How does that
+work? When Cygwin converts the filename from UTF-16 to your character
+set, it recognizes characters which can't be converted. If that occurs,
+Cygwin replaces the non-convertible character with a special character
+sequence. The sequence starts with an ASCII CAN character (hex code
+0x18, equivalent Control-X), followed by the UTF-8 representation of the
+character. The result is a filename containing some ugly looking
+characters. While it doesn't <emphasis role='bold'>look</emphasis> nice, it
+<emphasis role='bold'>is</emphasis> nice, because Cygwin knows how to convert
+this filename back to UTF-16. The filename will be converted using your
+usual character set. However, when Cygwin recognizes an ASCII CAN
+character, it skips over the ASCII CAN and handles the following bytes as
+a UTF-8 character. Thus, the filename is symmetrically converted back to
+UTF-16 and you can access the file.</para>
+
+<note><para>Please be aware that this method is not entirely foolproof.
+In some character set combinations it might not work for certain native
+characters.</para>
+
+<para>Only by using the UTF-8 charset you can avoid this problem safely.
+</para></note>
+
+</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 can not be 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.</para>
+
+<note>
+<para>
+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. However, there are limitations:
+while two <emphasis role='bold'>programs</emphasis> <filename>Abc.exe</filename>
+and <filename>aBc.exe</filename> can be created and accessed like other files,
+starting applications is still case-insensitive due to Windows limitations
+and so the program you try to launch may not be the one actually started. Also,
+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
+<filename>/etc/fstab</filename>, or your <filename>/etc/fstab.d/$USER</filename>
+file.</para>
+
+<para><filename>/cygdrive</filename> paths are case-insensitive by default.
+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>
+path is case-insensitive by default and you have to use the "posix=1" setting
+explicitly in <filename>/etc/fstab</filename> or
+<filename>/etc/fstab.d/$USER</filename> to switch it to case-sensitivity,
+or you have to make sure that the native Win32 %PATH% environment variable
+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 subdirectories 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>While there is no need to create a POSIX <filename>/dev</filename>
+directory, the directory is automatically created as part of a Cygwin
+installation. It's existence is often a prerequisit to run certain
+applications which create symbolic links, fifos, or UNIX sockets in
+<filename>/dev</filename>. Also, the directories <filename>/dev/shm</filename>
+and <filename>/dev/mqueue</filename> are required to exist to use named POSIX
+semaphores, shared memory, and message queues, so a system without a real
+<filename>/dev</filename> directory is functionally crippled.
+</para>
+
+<para>Apart from that, Cygwin automatically simulates POSIX devices
+internally. Up to Cygwin 1.7.11, these devices couldn't be seen with the
+command <command>ls /dev/</command> although commands such as
+<command>ls /dev/tty</command> worked fine. Starting with Cygwin 1.7.12,
+the <filename>/dev</filename> directory is automagically populated with
+existing POSIX devices by Cygwin in a way comparable with a
+<ulink url="http://en.wikipedia.org/wiki/Udev">udev</ulink> based virtual
+<filename>/dev</filename> directory under Linux.</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 current console window of a session.
+ Up to Cygwin 1.7.9, this was the only name for a console.
+ Different consoles were indistinguishable.
+ Cygwin's /dev/console is not quite comparable with the console
+ device on UNIX machines.
+
+/dev/cons0 Starting with Cygwin 1.7.10, Console sessions are numbered from
+/dev/cons1 /dev/cons0 upwards. Console device names are pseudo device
+... names, only accessible from processes within this very console
+ session. This is due to a restriction in Windows.
+
+/dev/tty The current controlling tty of a session.
+
+/dev/ptmx Pseudo tty master device.
+
+/dev/pty0 Pseudo ttys are numbered from /dev/pty0 upwards as they are
+/dev/pty1 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 also has several Windows-specific devices:
+</para>
+
+<screen>
+/dev/com1 The serial ports, starting with COM1 which is the same as ttyS0.
+/dev/com2 Please use /dev/ttySx instead.
+...
+
+/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>
+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.</para>
+
+<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" 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 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
+<command>df</command> output, you should be able to figure out which
+external drive corresponds to which raw disk device name.</para>
+
+<note><para>Apart from tape devices which are not block devices and are
+by default accessed directly, accessing mass storage devices raw
+is something you should only do if you know what you're doing and know how to
+handle the information. <emphasis role='bold'>Writing</emphasis> to a raw
+mass storage device you should only do if you
+<emphasis role='bold'>really</emphasis> know what you're doing and are aware
+of the fact that any mistake can destroy important information, for the
+device, and for you. So, please, handle this ability with care.
+<emphasis role='bold'>You have been warned.</emphasis></para></note>
+
+<para>
+Last but not least, the mapping from POSIX /dev namespace to internal
+NT namespace is as follows:
+</para>
+
+<screen>
+POSIX device name Internal NT device name
+
+/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/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)
+...
+/dev/sda15 \device\harddisk0\partition15 (fifteenth partition)
+
+/dev/sdb \device\harddisk1\partition0
+/dev/sdb1 \device\harddisk1\partition1
+
+[up to]
+
+/dev/sddx \device\harddisk127\partition0
+/dev/sddx1 \device\harddisk127\partition1
+...
+/dev/sddx15 \device\harddisk127\partition15
+</screen>
+
+<para>
+if you don't like these device names, feel free to create symbolic
+links as they are created on Linux systems for convenience:
+</para>
+
+<screen>
+ln -s /dev/sr0 /dev/cdrom
+ln -s /dev/nst0 /dev/tape
+...
+</screen>
+
+</sect2>
+
+<sect2 id="pathnames-exe"><title>The .exe extension</title>
+
+<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
+cannot omit the extension. </para>
+
+<para>As a side effect, the <command> ls filename</command> gives
+information about <filename>filename.exe</filename> if
+<filename>filename.exe</filename> exists and <filename>filename</filename>
+does not. In the same situation the function call
+<function>stat("filename",..)</function> gives information about
+<filename>filename.exe</filename>. The two files can be distinguished
+by examining their inodes, as demonstrated below.
+<screen>
+<prompt>bash$</prompt> <userinput>ls * </userinput>
+a a.exe b.exe
+<prompt>bash$</prompt> <userinput>ls -i a a.exe</userinput>
+445885548 a 435996602 a.exe
+<prompt>bash$</prompt> <userinput>ls -i b b.exe</userinput>
+432961010 b 432961010 b.exe
+</screen>
+If a shell script <filename>myprog</filename> and a program
+<filename>myprog.exe</filename> coexist in a directory, the shell
+script has precedence and is selected for execution of
+<command>myprog</command>. Note that this was quite the reverse up to
+Cygwin 1.5.19. It has been changed for consistency with the rest of Cygwin.
+</para>
+
+<para>The <command>gcc</command> compiler produces an executable named
+<filename>filename.exe</filename> when asked to produce
+<filename>filename</filename>. This allows many makefiles written
+for UNIX systems to work well under Cygwin.</para>
+
+</sect2>
+
+<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
+directory are representations of various aspects of your system,
+for example the command <userinput>cat /proc/cpuinfo</userinput>
+displays information such as what model and speed processor you have.
+</para>
+<para>
+One unique aspect of the Cygwin <filename>/proc</filename> filesystem
+is <filename>/proc/registry</filename>, see next section.
+</para>
+<para>
+The Cygwin <filename>/proc</filename> is not as complete as the
+one in Linux, but it provides significant capabilities. The
+<systemitem>procps</systemitem> package contains several utilities
+that use it.
+</para>
+</sect2>
+
+<sect2 id="pathnames-proc-registry"><title>The /proc/registry filesystem</title>
+<para>
+The <filename>/proc/registry</filename> filesystem provides read-only
+access to the Windows registry. It displays 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. 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>
+Reserved characters ('/', '\', ':', and '%') or reserved names
+(<filename>.</filename> and <filename>..</filename>) are converted by
+percent-encoding:
+<screen>
+<prompt>bash$</prompt> <userinput>regtool list -v '\HKEY_LOCAL_MACHINE\SYSTEM\MountedDevices'</userinput>
+...
+\DosDevices\C: (REG_BINARY) = cf a8 97 e8 00 08 fe f7
+...
+<prompt>bash$</prompt> <userinput>cd /proc/registry/HKEY_LOCAL_MACHINE/SYSTEM</userinput>
+<prompt>bash$</prompt> <userinput>ls -l MountedDevices</userinput>
+...
+-r--r----- 1 Admin SYSTEM 12 Dec 10 11:20 %5CDosDevices%5CC%3A
+...
+<prompt>bash$</prompt> <userinput>od -t x1 MountedDevices/%5CDosDevices%5CC%3A</userinput>
+0000000 cf a8 97 e8 00 08 fe f7 01 00 00 00
+</screen>
+The unnamed (default) value of a key can be accessed using the filename
+<filename>@</filename>.
+</para>
+<para>
+If a registry key contains a subkey and a value with the same name
+<filename>foo</filename>, Cygwin displays the subkey as
+<filename>foo</filename> and the value as <filename>foo%val</filename>.
+</para>
+</sect2>
+
+<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, when invoked by non-Cygwin processes, expand their arguments
+starting with "@" in a special way. If a file
+<filename>pathname</filename> exists, the argument
+<filename>@pathname</filename> expands recursively to the content of
+<filename>pathname</filename>. Double quotes can be used inside the
+file to delimit strings containing blank space.
+In the following example compare the behaviors
+<command>/bin/echo</command> when run from bash and from the Windows command prompt.</para>
+
+<example id="pathnames-at-ex"><title> Using @pathname</title>
+<screen>
+<prompt>bash$</prompt> <userinput>/bin/echo 'This is "a long" line' > mylist</userinput>
+<prompt>bash$</prompt> <userinput>/bin/echo @mylist</userinput>
+@mylist
+<prompt>bash$</prompt> <userinput>cmd</userinput>
+<prompt>c:\></prompt> <userinput>c:\cygwin\bin\echo @mylist</userinput>
+This is a long line
+</screen>
+</example>
+</sect2>
+</sect1>
+<?xml version="1.0" encoding='UTF-8'?>
+<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+
<sect1 id="using-textbinary"><title>Text and Binary modes</title>
<sect2 id="textbin-issue"> <title>The Issue</title>
--- /dev/null
+<?xml version="1.0" encoding='UTF-8'?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+
+<bookinfo xmlns:xi="http://www.w3.org/2001/XInclude">
+ <date>2001-22-03</date>
+ <title>Cygwin User's Guide</title>
+ <authorgroup>
+ <author>
+ <firstname>Joshua Daniel</firstname>
+ <surname>Franklin</surname>
+ </author>
+ <author>
+ <firstname>Corinna</firstname>
+ <surname>Vinschen</surname>
+ </author>
+ <author>
+ <firstname>Christopher</firstname>
+ <surname>Faylor</surname>
+ </author>
+ <author>
+ <firstname>DJ</firstname>
+ <surname>Delorie</surname>
+ </author>
+ <author>
+ <firstname>Pierre</firstname>
+ <surname>Humblet</surname>
+ </author>
+ <author>
+ <firstname>Geoffrey</firstname>
+ <surname>Noer</surname>
+ </author>
+ </authorgroup>
+
+ <xi:include href="legal.xml"/>
+</bookinfo>
+++ /dev/null
-<chapter id="using"><title>Using Cygwin</title>
-
-<para>This chapter explains some key differences between the Cygwin
-environment and traditional UNIX systems. It assumes a working
-knowledge of standard UNIX commands.</para>
-
-DOCTOOL-INSERT-using-pathnames
-
-DOCTOOL-INSERT-using-textbinary
-
-DOCTOOL-INSERT-using-filemodes
-
-DOCTOOL-INSERT-using-specialnames
-
-DOCTOOL-INSERT-using-cygwinenv
-
-DOCTOOL-INSERT-ntsec
-
-DOCTOOL-INSERT-using-cygserver
-
-DOCTOOL-INSERT-using-utils
-
-DOCTOOL-INSERT-using-effectively
-
-</chapter>
--- /dev/null
+<?xml version="1.0" encoding='UTF-8'?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+
+<chapter id="using" xmlns:xi="http://www.w3.org/2001/XInclude">
+<title>Using Cygwin</title>
+
+<para>This chapter explains some key differences between the Cygwin
+environment and traditional UNIX systems. It assumes a working
+knowledge of standard UNIX commands.</para>
+
+ <xi:include href="pathnames.xml"/>
+ <xi:include href="textbinary.xml"/>
+ <xi:include href="filemodes.xml"/>
+ <xi:include href="specialnames.xml"/>
+ <xi:include href="cygwinenv.xml"/>
+ <xi:include href="ntsec.xml"/>
+ <xi:include href="cygserver.xml"/>
+ <xi:include href="../utils/utils.xml"/>
+ <xi:include href="effectively.xml"/>
+</chapter>
+<?xml version="1.0" encoding='UTF-8'?>
+<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<sect1 id="windres"><title>Defining Windows Resources</title>
--- /dev/null
+<sect1 id="using-utils"><title>Cygwin Utilities</title>
+
+<para>Cygwin comes with a number of command-line utilities that are
+used to manage the UNIX emulation portion of the Cygwin environment.
+While many of these reflect their UNIX counterparts, each was written
+specifically for Cygwin. You may use the long or short option names
+interchangeably; for example, <literal>--help</literal> and
+<literal>-h</literal> function identically. All of the Cygwin
+command-line utilities support the <literal>--help</literal> and
+<literal>--version</literal> options.
+</para>
+
+<sect2 id="cygcheck"><title>cygcheck</title>
+
+<screen>
+Usage: cygcheck [-v] [-h] PROGRAM
+ cygcheck -c [-d] [PACKAGE]
+ cygcheck -s [-r] [-v] [-h]
+ cygcheck -k
+ cygcheck -f FILE [FILE]...
+ cygcheck -l [PACKAGE]...
+ cygcheck -p REGEXP
+ cygcheck --delete-orphaned-installation-keys
+ cygcheck --enable-unique-object-names Cygwin-DLL
+ cygcheck --disable-unique-object-names Cygwin-DLL
+ cygcheck --show-unique-object-names Cygwin-DLL
+ cygcheck -h
+
+List system information, check installed packages, or query package database.
+
+At least one command option or a PROGRAM is required, as shown above.
+
+ PROGRAM list library (DLL) dependencies of PROGRAM
+ -c, --check-setup show installed version of PACKAGE and verify integrity
+ (or for all installed packages if none specified)
+ -d, --dump-only just list packages, do not verify (with -c)
+ -s, --sysinfo produce diagnostic system information (implies -c -d)
+ -r, --registry also scan registry for Cygwin settings (with -s)
+ -k, --keycheck perform a keyboard check session (must be run from a
+ plain console only, not from a pty/rxvt/xterm)
+ -f, --find-package find the package to which FILE belongs
+ -l, --list-package list contents of PACKAGE (or all packages if none given)
+ -p, --package-query search for REGEXP in the entire cygwin.com package
+ repository (requires internet connectivity)
+ --delete-orphaned-installation-keys
+ Delete installation keys of old, now unused
+ installations from the registry. Requires the right
+ to change the registry.
+ --enable-unique-object-names Cygwin-DLL
+ --disable-unique-object-names Cygwin-DLL
+ --show-unique-object-names Cygwin-DLL
+ Enable, disable, or show the setting of the
+ \"unique object names\" setting in the Cygwin DLL
+ given as argument to this option. The DLL path must
+ be given as valid Windows(!) path.
+ See the users guide for more information.
+ If you don't know what this means, don't change it.
+ -v, --verbose produce more verbose output
+ -h, --help annotate output with explanatory comments when given
+ with another command, otherwise print this help
+ -V, --version print the version of cygcheck and exit
+
+Note: -c, -f, and -l only report on packages that are currently installed. To
+ search all official Cygwin packages use -p instead. The -p REGEXP matches
+ package names, descriptions, and names of files/paths within all packages.
+</screen>
+
+<para>
+The <command>cygcheck</command> program is a diagnostic utility for
+dealing with Cygwin programs. If you are familiar with
+<command>dpkg</command> or <command>rpm</command>,
+<command>cygcheck</command> is similar in many ways. (The major difference
+is that <command>setup.exe</command> handles installing and uninstalling
+packages; see <xref linkend="internet-setup"></xref> for more information.)
+</para>
+<para>
+The <literal>-c</literal> option checks the version and status of
+installed Cygwin packages. If you specify one or more package names,
+<command>cygcheck</command> will limit its output to those packages,
+or with no arguments it lists all packages. A package will be marked
+<literal>Incomplete</literal> if files originally installed are no longer
+present. The best thing to do in that situation is reinstall the package
+with <command>setup.exe</command>. To see which files are missing, use the
+<literal>-v</literal> option. If you do not need to know the status
+of each package and want <command>cygcheck</command> to run faster, add the
+<literal>-d</literal> option and <command>cygcheck</command> will only
+output the name and version for each package.
+</para>
+<para>
+If you list one or more programs on the command line,
+<command>cygcheck</command> will diagnose the runtime environment of that
+program or programs, providing the names of DLL files on which the program
+depends. If you specify the <literal>-s</literal> option,
+<command>cygcheck</command> will give general system information. If you
+list one or more programs on the command line and specify
+<literal>-s</literal>, <command>cygcheck</command> will report on
+both.</para>
+<para>
+The <literal>-f</literal> option helps you to track down which package a
+file came from, and <literal>-l</literal> lists all files in a package.
+For example, to find out about <filename>/usr/bin/less</filename> and its
+package:
+<example id="utils-cygcheck-ex"><title>Example <command>cygcheck</command> usage</title>
+<screen>
+$ cygcheck -f /usr/bin/less
+less-381-1
+
+$ cygcheck -l less
+/usr/bin/less.exe
+/usr/bin/lessecho.exe
+/usr/bin/lesskey.exe
+/usr/man/man1/less.1
+/usr/man/man1/lesskey.1
+</screen>
+</example>
+</para>
+
+<para>The <literal>-h</literal> option prints additional helpful
+messages in the report, at the beginning of each section. It also
+adds table column headings. While this is useful information, it also
+adds some to the size of the report, so if you want a compact report
+or if you know what everything is already, just leave this out.</para>
+
+<para>The <literal>-v</literal> option causes the output to be more
+verbose. What this means is that additional information will be
+reported which is usually not interesting, such as the internal
+version numbers of DLLs, additional information about recursive DLL
+usage, and if a file in one directory in the PATH also occurs in other
+directories on the PATH. </para>
+
+<para>The <literal>-r</literal> option causes
+<command>cygcheck</command> to search your registry for information
+that is relevant to Cygwin programs. These registry entries are the
+ones that have "Cygwin" in the name. If you are paranoid about
+privacy, you may remove information from this report, but please keep
+in mind that doing so makes it harder to diagnose your problems.</para>
+
+<para>In contrast to the other options that search the packages that are
+installed on your local system, the <literal>-p</literal> option can be used
+to search the entire official Cygwin package repository. It takes as argument
+a Perl-compatible regular expression which is used to match package names,
+package descriptions, and path/filenames of the contents of packages. This
+feature requires an active internet connection, since it must query the
+<literal>cygwin.com</literal> web site. In fact, it is equivalent to the
+search that is available on the <ulink url="http://cygwin.com/packages/">Cygwin
+package listing</ulink> page.</para>
+
+<para>For example, perhaps you are getting an error because you are missing a
+certain DLL and you want to know which package includes that file:
+<example id="utils-search-ex"><title>Searching all packages for a file</title>
+<screen>
+$ cygcheck -p 'cygintl-2\.dll'
+Found 1 matches for 'cygintl-2\.dll'.
+
+libintl2-0.12.1-3 GNU Internationalization runtime library
+
+$ cygcheck -p 'libexpat.*\.a'
+Found 2 matches for 'libexpat.*\.a'.
+
+expat-1.95.7-1 XML parser library written in C
+expat-1.95.8-1 XML parser library written in C
+
+$ cygcheck -p '/ls\.exe'
+Found 2 matches for '/ls\.exe'.
+
+coreutils-5.2.1-5 GNU core utilities (includes fileutils, sh-utils and textutils)
+coreutils-5.3.0-6 GNU core utilities (includes fileutils, sh-utils and textutils)
+</screen>
+</example>
+</para>
+
+<para>Note that this option takes a regular expression, not a glob or wildcard.
+This means that you need to use <literal>.*</literal> if you want something
+similar to the wildcard <literal>*</literal> commonly used in filename globbing.
+Similarly, to match the period character you should use <literal>\.</literal>
+since the <literal>.</literal> character in a regexp is a metacharacter that
+will match any character. Also be aware that the characters such as
+<literal>\</literal> and <literal>*</literal> are shell metacharacters, so
+they must be either escaped or quoted, as in the example above.</para>
+
+<para>The third example above illustrates that if you want to match a whole
+filename, you should include the <literal>/</literal> path seperator. In the
+given example this ensures that filenames that happen to end in
+<literal>ls.exe</literal> such as <literal>ncftpls.exe</literal> are not shown.
+Note that this use does not mean "look for packages with <literal>ls</literal>
+in the root directory," since the <literal>/</literal> can match anywhere in the
+path. It's just there to anchor the match so that it matches a full
+filename.</para>
+
+<para>By default the matching is case-sensitive. To get a case insensitive
+match, begin your regexp with <literal>(?i)</literal> which is a PCRE-specific
+feature. For complete documentation on Perl-compatible regular expression
+syntax and options, read the <command>perlre</command> manpage, or one of many
+websites such as <literal>perldoc.com</literal> that document the Perl
+language.</para>
+
+<para>The <command>cygcheck</command> program should be used to send
+information about your system for troubleshooting when requested.
+When asked to run this command save the output so that you can email it,
+for example:</para>
+
+<screen>
+<prompt>$</prompt> <userinput>cygcheck -s -v -r -h > cygcheck_output.txt</userinput>
+</screen>
+
+<para>
+Each Cygwin DLL stores its path and installation key in the registry.
+This allows troubleshooting of problems which could be a result of having
+multiple concurrent Cygwin installations. However, if you're experimenting
+a lot with different Cygwin installation paths, your registry could
+accumulate a lot of old Cygwin installation entries for which the
+installation doesn't exist anymore. To get rid of these orphaned registry
+entries, use the <command>cygcheck --delete-orphaned-installation-keys</command>
+command.</para>
+
+<para>
+Each Cygwin DLL generates a key value from its installation path. This
+value is not only stored in the registry, it's also used to generate
+global object names used for interprocess communication. This keeps
+different Cygwin installations separate. Processes running under a
+Cygwin DLL installed in C:\cygwin don't see processes running under a
+Cygwin DLL installed in C:\Program Files\cygwin. This allows
+running multiple versions of Cygwin DLLs without these versions to
+interfere with each other, or to run small third-party installations
+for a specific purpose independently from a Cygwin net distribution.
+</para>
+
+<para>
+For debugging purposes it could be desired that the various Cygwin DLLs
+use the same key, independently from their installation paths. If the
+DLLs have different versions, trying to run processes under these DLLs
+concurrently will result in error messages like this one:</para>
+
+<screen>
+*** shared version mismatch detected - 0x8A88009C/0x75BE0074.
+This problem is probably due to using incompatible versions of the Cygwin DLL.
+Search for cygwin1.dll using the Windows Start->Find/Search facility
+and delete all but the most recent version. The most recent version *should*
+reside in x:\\cygwin\\bin, where 'x' is the drive on which you have
+installed the cygwin distribution. Rebooting is also suggested if you
+are unable to find another Cygwin DLL.
+</screen>
+
+<para>
+To disable the usage of a unique key value of a certain Cygwin DLL, use
+the <command>cygcheck --disable-unique-object-names Cygwin-DLL</command>
+command. <literal>Cygwin-DLL</literal> is the Windows path (*not* a
+Cygwin POSIX path) to the DLL for which you want to disable this feature.
+Note that you have to stop all Cygwin processes running under this DLL,
+before you're allowed to change this setting. For instance, run
+<command>cygcheck</command> from a DOS command line for this purpose.</para>
+
+<para>To re-enable the usage of a unique key, use the
+<command>cygcheck --enable-unique-object-names Cygwin-DLL</command> command.
+This option has the same characteristics as the
+<literal>--disable-unique-object-names</literal> option</para>
+
+<para>Finally, you can use
+<command>cygcheck --show-unique-object-names Cygwin-DLL</command> to find out
+if the given Cygwin DLL use unique object names or not. In contrast to the
+<literal>--disable-...</literal> and <literal>--enable-...</literal> options,
+the <literal>--show-unique-object-names</literal> option also works for
+Cygwin DLLs which are currently in use.</para>
+
+</sect2>
+
+<sect2 id="cygpath"><title>cygpath</title>
+
+<screen>
+Usage: cygpath (-d|-m|-u|-w|-t TYPE) [-f FILE] [OPTION]... NAME...
+ cygpath [-c HANDLE]
+ cygpath [-ADHOPSW]
+ cygpath [-F ID]
+
+Convert Unix and Windows format paths, or output system path information
+
+Output type options:
+
+ -d, --dos print DOS (short) form of NAMEs (C:\PROGRA~1\)
+ -m, --mixed like --windows, but with regular slashes (C:/WINNT)
+ -M, --mode report on mode of file (currently binmode or textmode)
+ -u, --unix (default) print Unix form of NAMEs (/cygdrive/c/winnt)
+ -w, --windows print Windows form of NAMEs (C:\WINNT)
+ -t, --type TYPE print TYPE form: 'dos', 'mixed', 'unix', or 'windows'
+
+Path conversion options:
+
+ -a, --absolute output absolute path
+ -l, --long-name print Windows long form of NAMEs (with -w, -m only)
+ -p, --path NAME is a PATH list (i.e., '/bin:/usr/bin')
+ -s, --short-name print DOS (short) form of NAMEs (with -w, -m only)
+ -C, --codepage CP print DOS, Windows, or mixed pathname in Windows
+ codepage CP. CP can be a numeric codepage identifier,
+ or one of the reserved words ANSI, OEM, or UTF8.
+ If this option is missing, cygpath defaults to the
+ character set defined by the current locale.
+
+System information:
+
+ -A, --allusers use `All Users' instead of current user for -D, -P
+ -D, --desktop output `Desktop' directory and exit
+ -H, --homeroot output `Profiles' directory (home root) and exit
+ -O, --mydocs output `My Documents' directory and exit
+ -P, --smprograms output Start Menu `Programs' directory and exit
+ -S, --sysdir output system directory and exit
+ -W, --windir output `Windows' directory and exit
+ -F, --folder ID output special folder with numeric ID and exit
+
+Other options:
+
+ -f, --file FILE read FILE for input; use - to read from STDIN
+ -o, --option read options from FILE as well (for use with --file)
+ -c, --close HANDLE close HANDLE (for use in captured process)
+ -i, --ignore ignore missing argument
+ -h, --help output usage information and exit
+ -V, --version output version information and exit
+</screen>
+
+<para>The <command>cygpath</command> program is a utility that
+converts Windows native filenames to Cygwin POSIX-style pathnames and
+vice versa. It can be used when a Cygwin program needs to pass a file
+name to a native Windows program, or expects to get a file name from a
+native Windows program. Alternatively, <command>cygpath</command> can
+output information about the location of important system directories
+in either format.
+</para>
+
+<para>The <literal>-u</literal> and <literal>-w</literal> options
+indicate whether you want a conversion to UNIX (POSIX) format
+(<literal>-u</literal>) or to Windows format (<literal>-w</literal>).
+Use the <literal>-d</literal> to get DOS-style (8.3) file and path names.
+The <literal>-m</literal> option will output Windows-style format
+but with forward slashes instead of backslashes. This option is
+especially useful in shell scripts, which use backslashes as an escape
+character.</para>
+
+<para> In combination with the <literal>-w</literal> option, you can use
+the <literal>-l</literal> and <literal>-s</literal> options to use normal
+(long) or DOS-style (short) form. The <literal>-d</literal> option is
+identical to <literal>-w</literal> and <literal>-s</literal> together.
+</para>
+
+<para>The <literal>-C</literal> option allows to specify a Windows codepage
+to print DOS and Windows paths created with one of the <literal>-d</literal>,
+<literal>-m</literal>, or <literal>-w</literal> options. The default is to
+use the character set of the current locale defined by one of the
+internationalization environment variables <envar>LC_ALL</envar>,
+<envar>LC_CTYPE</envar>, or <envar>LANG</envar>, see
+<xref linkend="setup-locale"></xref>. This is sometimes not sufficient for
+interaction with native Windows tools, which might expect native, non-ASCII
+characters in a specific Windows codepage. Console tools, for instance, might
+expect pathnames in the current OEM codepage, while graphical tools like
+Windows Explorer might expect pathnames in the current ANSI codepage.</para>
+
+<para>The <literal>-C</literal> option takes a single parameter:</para>
+<itemizedlist spacing="compact">
+<listitem><para><literal>ANSI</literal>, to specify the current ANSI codepage</para></listitem>
+<listitem><para><literal>OEM</literal>, to specify the current OEM (console) codepage</para></listitem>
+<listitem><para><literal>UTF8</literal>, to specify UTF-8.</para></listitem>
+<listitem><para>A numerical, decimal codepage number, for instance 936 for GBK,
+28593 for ISO-8859-3, etc. A full list of supported codepages is listed on the
+Microsoft MSDN page
+<ulink url="http://msdn.microsoft.com/en-us/library/dd317756(VS.85).aspx">Code Page Identifiers</ulink>. A codepage of 0 is the same as if the
+<literal>-C</literal> hasn't been specified at all.</para></listitem>
+</itemizedlist>
+
+<para>The <literal>-p</literal> option means that you want to convert
+a path-style string rather than a single filename. For example, the
+PATH environment variable is semicolon-delimited in Windows, but
+colon-delimited in UNIX. By giving <literal>-p</literal> you are
+instructing <command>cygpath</command> to convert between these
+formats.</para>
+
+<para>The <literal>-i</literal> option supresses the print out of the
+usage message if no filename argument was given. It can be used in
+make file rules converting variables that may be omitted
+to a proper format. Note that <command>cygpath</command> output may
+contain spaces (C:\Program Files) so should be enclosed in quotes.
+</para>
+
+
+<example id="utils-cygpath-ex"><title>Example <command>cygpath</command> usage</title>
+<screen>
+<![CDATA[
+#!/bin/sh
+if [ "${1}" = "" ];
+ then
+ XPATH=".";
+ else
+ XPATH="$(cygpath -C ANSI -w "${1}")";
+fi
+explorer $XPATH &
+]]>
+</screen>
+</example>
+
+<para>The capital options
+<literal>-D</literal>, <literal>-H</literal>, <literal>-P</literal>,
+<literal>-S</literal>, and <literal>-W</literal> output directories used
+by Windows that are not the same on all systems, for example
+<literal>-S</literal> might output C:\WINNT\system32 or C:\Windows\System32.
+The <literal>-H</literal> shows the Windows profiles directory that can
+be used as root of home. The <literal>-A</literal> option forces use of
+the "All Users" directories instead of the current user for the
+<literal>-D</literal>, <literal>-O</literal> and <literal>-P</literal>
+options.
+The <literal>-F</literal> outputs other special folders specified by
+their internal numeric code (decimal or 0x-prefixed hex). For valid codes and
+symbolic names, see the CSIDL_* definitions in the include file
+/usr/include/w32api/shlobj.h from package w32api. The current valid
+range of codes for folders is 0 (Desktop) to 59 (CDBurn area).
+By default the output is in UNIX (POSIX) format;
+use the <literal>-w</literal> or <literal>-d</literal> options to get
+other formats.</para>
+
+</sect2>
+
+<sect2 id="dumper"><title>dumper</title>
+
+<screen>
+Usage: dumper [OPTION] FILENAME WIN32PID
+
+Dump core from WIN32PID to FILENAME.core
+
+-d, --verbose be verbose while dumping
+-h, --help output help information and exit
+-q, --quiet be quiet while dumping (default)
+-V, --version output version information and exit
+</screen>
+
+<para>The <command>dumper</command> utility can be used to create a
+core dump of running Windows process. This core dump can be later loaded
+to <command>gdb</command> and analyzed. One common way to use
+<command>dumper</command> is to plug it into cygwin's Just-In-Time
+debugging facility by adding
+
+<screen>
+error_start=x:\path\to\dumper.exe
+</screen>
+
+to the <emphasis>CYGWIN</emphasis> environment variable. Please note that
+<literal>x:\path\to\dumper.exe</literal> is Windows-style and not cygwin
+path. If <literal>error_start</literal> is set this way, then dumper will
+be started whenever some program encounters a fatal error.
+</para>
+
+<para>
+<command>dumper</command> can be also be started from the command line to
+create a core dump of any running process. Unfortunately, because of a Windows
+API limitation, when a core dump is created and <command>dumper</command>
+exits, the target process is terminated too.
+</para>
+
+<para>
+To save space in the core dump, <command>dumper</command> doesn't write those
+portions of target process' memory space that are loaded from executable and
+dll files and are unchangeable, such as program code and debug info. Instead,
+<command>dumper</command> saves paths to files which contain that data. When a
+core dump is loaded into gdb, it uses these paths to load appropriate files.
+That means that if you create a core dump on one machine and try to debug it on
+another, you'll need to place identical copies of the executable and dlls in
+the same directories as on the machine where the core dump was created.
+</para>
+
+</sect2>
+
+<sect2 id="getconf"><title>getconf</title>
+
+<screen>
+Usage: getconf [-v specification] variable_name [pathname]
+ getconf -a [pathname]
+
+Get configuration values
+
+ -v specification Indicate specific version for which configuration
+ values shall be fetched.
+ -a, --all Print all known configuration values
+
+Other options:
+
+ -h, --help This text
+ -V, --version Print program version and exit
+</screen>
+
+<para>The <command>getconf</command> utility prints the value of the
+configuration variable specified by <literal>variable_name</literal>.
+If no <literal>pathname</literal> is given, <command>getconf</command>
+serves as a wrapper for the <literal>confstr</literal> and
+<literal>sysconf</literal> functions, supporting the symbolic constants
+defined in the <literal>limits.h</literal> and <literal>unistd.h</literal>
+headers, without their respective <literal>_CS_</literal> or
+<literal>_SC_</literal> prefixes.
+</para>
+
+<para>If <literal>pathname</literal> is given, <command>getconf</command>
+prints the value of the configuration variable for the specified pathname.
+In this form, <command>getconf</command> serves as a wrapper for the
+<literal>pathconf</literal> function, supporting the symbolic constants defined
+in the <literal>unistd.h</literal> header, without the <literal>_PC_</literal>
+prefix. </para>
+
+<para>If you specify the <literal>-v</literal> option, the parameter
+denotes a specification for which the value of the configuration variable
+should be printed. Note that the only specifications supported by Cygwin
+are <literal>POSIX_V7_ILP32_OFFBIG</literal> and the legacy
+<literal>POSIX_V6_ILP32_OFFBIG</literal> and
+<literal>XBS5_ILP32_OFFBIG</literal> equivalents.</para>
+
+<para>Use the <literal>-a</literal> option to print a list of all available
+configuration variables for the system, or given <literal>pathname</literal>,
+and their values.</para>
+
+</sect2>
+
+<sect2 id="getfacl"><title>getfacl</title>
+
+<screen>
+Usage: getfacl [-adn] FILE [FILE2...]
+
+Display file and directory access control lists (ACLs).
+
+ -a, --all display the filename, the owner, the group, and
+ the ACL of the file
+ -d, --dir display the filename, the owner, the group, and
+ the default ACL of the directory, if it exists
+ -h, --help output usage information and exit
+ -n, --noname display user and group IDs instead of names
+ -V, --version output version information and exit
+
+When multiple files are specified on the command line, a blank
+line separates the ACLs for each file.
+</screen>
+
+<para>
+For each argument that is a regular file, special file or
+directory, <command>getfacl</command> displays the owner, the group, and the
+ACL. For directories <command>getfacl</command> displays additionally the
+default ACL. With no options specified, <command>getfacl</command> displays
+the filename, the owner, the group, and both the ACL and the default ACL, if
+it exists. For more information on Cygwin and Windows ACLs, see
+<xref linkend="ntsec"></xref> in the Cygwin User's Guide.
+The format for ACL output is as follows:
+<screen>
+ # file: filename
+ # owner: name or uid
+ # group: name or uid
+ user::perm
+ user:name or uid:perm
+ group::perm
+ group:name or gid:perm
+ mask:perm
+ other:perm
+ default:user::perm
+ default:user:name or uid:perm
+ default:group::perm
+ default:group:name or gid:perm
+ default:mask:perm
+ default:other:perm
+</screen>
+</para>
+</sect2>
+
+<sect2 id="kill"><title>kill</title>
+
+<screen>
+Usage: kill [-f] [-signal] [-s signal] pid1 [pid2 ...]
+ kill -l [signal]
+
+Send signals to processes
+
+ -f, --force force, using win32 interface if necessary
+ -l, --list print a list of signal names
+ -s, --signal send signal (use kill --list for a list)
+ -h, --help output usage information and exit
+ -V, --version output version information and exit
+</screen>
+
+<para>The <command>kill</command> program allows you to send arbitrary
+signals to other Cygwin programs. The usual purpose is to end a
+running program from some other window when ^C won't work, but you can
+also send program-specified signals such as SIGUSR1 to trigger actions
+within the program, like enabling debugging or re-opening log files.
+Each program defines the signals they understand.</para>
+
+<para>You may need to specify the full path to use <command>kill</command>
+from within some shells, including <command>bash</command>, the default Cygwin
+shell. This is because <command>bash</command> defines a
+<command>kill</command> builtin function; see the <command>bash</command>
+man page under <emphasis>BUILTIN COMMANDS</emphasis> for more information.
+To make sure you are using the Cygwin version, try
+
+<screen>
+$ /bin/kill --version
+</screen>
+
+which should give the Cygwin <command>kill</command> version number and
+copyright information.
+</para>
+
+<para>Unless you specific the <literal>-f</literal> option, the "pid" values
+used by <command>kill</command> are the Cygwin pids, not the Windows pids.
+To get a list of running programs and their Cygwin pids, use the Cygwin
+<command>ps</command> program. <command>ps -W</command> will display
+<emphasis>all</emphasis> windows pids.</para>
+
+<para>The <command>kill -l</command> option prints the name of the
+given signal, or a list of all signal names if no signal is given.</para>
+
+<para>To send a specific signal, use the <literal>-signN</literal>
+option, either with a signal number or a signal name (minus the "SIG"
+part), as shown in these examples:</para>
+
+<example id="utils-kill-ex"><title>Using the kill command</title>
+<screen>
+<prompt>$</prompt> <userinput>kill 123</userinput>
+<prompt>$</prompt> <userinput>kill -1 123</userinput>
+<prompt>$</prompt> <userinput>kill -HUP 123</userinput>
+<prompt>$</prompt> <userinput>kill -f 123</userinput>
+</screen>
+</example>
+
+<para>Here is a list of available signals, their numbers, and some
+commentary on them, from the file
+<literal><sys/signal.h></literal>, which should be considered
+the official source of this information.</para>
+
+<screen>
+SIGHUP 1 hangup
+SIGINT 2 interrupt
+SIGQUIT 3 quit
+SIGILL 4 illegal instruction (not reset when caught)
+SIGTRAP 5 trace trap (not reset when caught)
+SIGABRT 6 used by abort
+SIGEMT 7 EMT instruction
+SIGFPE 8 floating point exception
+SIGKILL 9 kill (cannot be caught or ignored)
+SIGBUS 10 bus error
+SIGSEGV 11 segmentation violation
+SIGSYS 12 bad argument to system call
+SIGPIPE 13 write on a pipe with no one to read it
+SIGALRM 14 alarm clock
+SIGTERM 15 software termination signal from kill
+SIGURG 16 urgent condition on IO channel
+SIGSTOP 17 sendable stop signal not from tty
+SIGTSTP 18 stop signal from tty
+SIGCONT 19 continue a stopped process
+SIGCHLD 20 to parent on child stop or exit
+SIGCLD 20 System V name for SIGCHLD
+SIGTTIN 21 to readers pgrp upon background tty read
+SIGTTOU 22 like TTIN for output if (tp->t_local&LTOSTOP)
+SIGIO 23 input/output possible
+SIGPOLL 23 System V name for SIGIO
+SIGXCPU 24 exceeded CPU time limit
+SIGXFSZ 25 exceeded file size limit
+SIGVTALRM 26 virtual time alarm
+SIGPROF 27 profiling time alarm
+SIGWINCH 28 window changed
+SIGLOST 29 resource lost (eg, record-lock lost)
+SIGPWR 29 power failure
+SIGUSR1 30 user defined signal 1
+SIGUSR2 31 user defined signal 2
+</screen>
+
+</sect2>
+
+<sect2 id="ldd"><title>ldd</title>
+
+<screen>
+Usage: ldd [OPTION]... FILE...
+
+Print shared library dependencies
+
+ -h, --help print this help and exit
+ -V, --version print version information and exit
+ -r, --function-relocs process data and function relocations
+ (currently unimplemented)
+ -u, --unused print unused direct dependencies
+ (currently unimplemented)
+ -v, --verbose print all information
+ (currently unimplemented)
+</screen>
+
+<para><command>ldd</command> prints the shared libraries (DLLs) an executable
+or DLL is linked against. No modifying option is implemented yet.</para>
+
+</sect2>
+
+<sect2 id="locale"><title>locale</title>
+
+<screen>
+Usage: locale [-amvhV]
+ or: locale [-ck] NAME
+ or: locale [-usfnU]
+
+Get locale-specific information.
+
+System information:
+
+ -a, --all-locales List all available supported locales
+ -m, --charmaps List all available character maps
+ -v, --verbose More verbose output
+
+Modify output format:
+
+ -c, --category-name List information about given category NAME
+ -k, --keyword-name Print information about given keyword NAME
+
+Default locale information:
+
+ -u, --user Print locale of user's default UI language
+ -s, --system Print locale of system default UI language
+ -f, --format Print locale of user's regional format settings
+ (time, numeric & monetary)
+ -n, --no-unicode Print system default locale for non-Unicode programs
+ -U, --utf Attach \".UTF-8\" to the result
+
+Other options:
+
+ -h, --help This text
+ -V, --version Print program version and exit
+</screen>
+
+<para><command>locale</command> without parameters prints information about
+the current locale environment settings.</para>
+
+<para>The <literal>-u</literal>, <literal>-s</literal>, <literal>-f</literal>,
+and <literal>-n</literal> options can be used to request the various Windows
+locale settings. The purpose is to use this command in scripts to set the
+POSIX locale variables.</para>
+
+<para>The <literal>-u</literal> option prints the current user's Windows
+UI locale to stdout. In Windows Vista and Windows 7 this setting is called
+the "Display Language"; there was no corresponding user setting in Windows XP.
+The <literal>-s</literal> option prints the systems default instead.
+The <literal>-f</literal> option prints the user's setting for time, date,
+number and currency. That's equivalent to the setting in the "Formats" or
+"Regional Options" tab in the "Region and Language" or "Regional and Language
+Options" dialog. With the <literal>-U</literal> option
+<command>locale</command> appends a ".UTF-8".</para>
+
+<para>Usage example:</para>
+
+<screen>
+bash$ export LANG=$(locale -uU)
+bash$ echo $LANG
+en_US.UTF-8
+bash$ export LC_TIME=$(locale -fU)
+bash$ echo $LC_TIME
+de_DE.UTF-8
+</screen>
+
+<para>The <literal>-a</literal> option is helpful to learn which locales
+are supported by your Windows machine. It prints all available locales
+and the allowed modifiers. Example:</para>
+
+<screen>
+bash$ locale -a
+C
+C.utf8
+POSIX
+af_ZA
+af_ZA.utf8
+am_ET
+am_ET.utf8
+...
+be_BY
+be_BY.utf8
+be_BY@latin
+...
+ca_ES
+ca_ES.utf8
+ca_ES@euro
+catalan
+...
+</screen>
+
+<para>The <literal>-v</literal> option prints more detailed information about
+each available locale. Example:</para>
+
+<screen>
+bash$ locale -av
+locale: af_ZA archive: /cygdrive/c/Windows/system32/kernel32.dll
+-------------------------------------------------------------------------------
+ language | Afrikaans
+territory | South Africa
+ codeset | ISO-8859-1
+
+locale: af_ZA.utf8 archive: /cygdrive/c/Windows/system32/kernel32.dll
+-------------------------------------------------------------------------------
+ language | Afrikaans
+territory | South Africa
+ codeset | UTF-8
+
+...
+
+locale: ca_ES@euro archive: /cygdrive/c/Windows/system32/kernel32.dll
+-------------------------------------------------------------------------------
+ language | Catalan
+territory | Spain
+ codeset | ISO-8859-15
+
+locale: catalan archive: /usr/share/locale/locale.alias
+-------------------------------------------------------------------------------
+ language | Catalan
+territory | Spain
+ codeset | ISO-8859-1
+
+...
+</screen>
+
+<para>The <literal>-m</literal> option prints the names of the available
+charmaps supported by Cygwin to stdout.</para>
+
+<para>Otherwise, if arguments are given, <command>locale</command> prints
+the values assigned to these arguments. Arguments can be names of locale
+categories (for instance: LC_CTYPE, LC_MONETARY), or names of keywords
+supported in the locale categories (for instance: thousands_sep, charmap).
+The <literal>-c</literal> option prints additionally the name of the category.
+The <literal>-k</literal> option prints additionally the name of the keyword.
+Example:</para>
+
+<screen>
+bash$ locale -ck LC_MESSAGES
+LC_MESSAGES
+yesexpr="^[yY]"
+noexpr="^[nN]"
+yesstr="yes"
+nostr="no"
+messages-codeset="UTF-8"
+bash$ locale noexpr
+^[nN]
+</screen>
+
+</sect2>
+
+<sect2 id="mkgroup"><title>mkgroup</title>
+
+<screen>
+Usage: mkgroup [OPTION]...
+
+Print /etc/group file to stdout
+
+Options:
+
+ -l,--local [machine[,offset]]
+ print local groups with gid offset offset
+ (from local machine if no machine specified)
+ -L,--Local [machine[,offset]]
+ ditto, but generate groupname with machine prefix
+ -d,--domain [domain[,offset]]
+ print domain groups with gid offset offset
+ (from current domain if no domain specified)
+ -D,--Domain [domain[,offset]]
+ ditto, but generate groupname with machine prefix
+ -c,--current print current group
+ -C,--Current ditto, but generate groupname with machine or
+ domain prefix
+ -S,--separator char for -L, -D, -C use character char as domain\group
+ separator in groupname instead of the default '\'
+ -o,--id-offset offset change the default offset (10000) added to gids
+ in domain or foreign server accounts.
+ -g,--group groupname only return information for the specified group
+ one of -l, -L, -d, -D must be specified, too
+ -b,--no-builtin don't print BUILTIN groups
+ -U,--unix grouplist additionally print UNIX groups when using -l or -L
+ on a UNIX Samba server
+ grouplist is a comma-separated list of groupnames
+ or gid ranges (root,-25,50-100).
+ (enumerating large ranges can take a long time!)
+ -s,--no-sids (ignored)
+ -u,--users (ignored)
+ -h,--help print this message
+ -V,--version print version information and exit
+
+Default is to print local groups on stand-alone machines, plus domain
+groups on domain controllers and domain member machines.
+</screen>
+
+<para>The <command>mkgroup</command> program can be used to help
+configure Cygwin by creating a <filename>/etc/group</filename>
+file. Its use is essential to include Windows security information.</para>
+
+<para>The command is initially called by <command>setup.exe</command> to
+create a default <filename>/etc/group</filename>. This should be
+sufficient in most circumstances. However, especially when working
+in a multi-domain environment, you can use <command>mkgroup</command>
+manually to create a more complete <filename>/etc/group</filename> file for
+all domains. Especially when you have the same group name used on
+multiple machines or in multiple domains, you can use the <literal>-D</literal>,
+<literal>-L</literal> and <literal>-C</literal> options to create unique
+domain\group style groupnames.</para>
+
+<para>Note that this information is static. If you change the group
+information in your system, you'll need to regenerate the group file
+for it to have the new information.</para>
+
+<para>The <literal>-d/-D</literal> and <literal>-l/-L</literal> options
+allow you to specify where the information comes from, the
+local SAM of a machine or from the domain, or both.
+With the <literal>-d/-D</literal> options the program contacts a Domain
+Controller, which my be unreachable or have restricted access.
+Comma-separated from the machine or domain, you can specify an offset
+which is used as base added to the group's RID to compute the gid
+(offset + RID = gid). This allows you to create the same gids every time you
+re-run <command>mkgroup</command>.
+For very simple needs, an entry for the current user's group can be
+created by using the option <literal>-c</literal> or <literal>-C</literal>.
+If you want to use one of the <literal>-D</literal>, <literal>-L</literal>
+or <literal>-C</literal> options, but you don't like the backslash as
+domain/group separator, you can specify another separator using the
+<literal>-S</literal> option, for instance:</para>
+
+<example id="utils-mkgroup-ex"><title>Setting up group entry for current user with different domain/group separator</title>
+<screen>
+<prompt>$</prompt> <userinput>mkgroup -C -S+ > /etc/group</userinput>
+<prompt>$</prompt> <userinput>cat /etc/group</userinput>
+DOMAIN+my_group:S-1-5-21-2913048732-1697188782-3448811101-1144:11144:
+</screen>
+</example>
+
+<para>The <literal>-o</literal> option allows for special cases
+(such as multiple domains) where the GIDs might match otherwise.
+The <literal>-g</literal> option only prints the information for one group.
+The <literal>-U</literal> option allows you to enumerate the standard UNIX
+groups on a Samba machine. It's used together with
+<literal>-l samba-server</literal> or <literal>-L samba-server</literal>.
+The normal UNIX groups are usually not enumerated, but they can show
+up as a group in <command>ls -l</command> output.
+</para>
+
+</sect2>
+
+<sect2 id="mkpasswd"><title>mkpasswd</title>
+
+<screen>
+Usage: mkpasswd [OPTIONS]...
+
+Print /etc/passwd file to stdout
+
+Options:
+
+ -l,--local [machine[,offset]]
+ print local user accounts with uid offset offset
+ (from local machine if no machine specified)
+ -L,--Local [machine[,offset]]
+ ditto, but generate username with machine prefix
+ -d,--domain [domain[,offset]]
+ print domain accounts with uid offset offset
+ (from current domain if no domain specified)
+ -D,--Domain [domain[,offset]]
+ ditto, but generate username with domain prefix
+ -c,--current print current user
+ -C,--Current ditto, but generate username with machine or
+ domain prefix
+ -S,--separator char for -L, -D, -C use character char as domain\user
+ separator in username instead of the default '\'
+ -o,--id-offset offset change the default offset (10000) added to uids
+ in domain or foreign server accounts.
+ -u,--username username only return information for the specified user
+ one of -l, -L, -d, -D must be specified, too
+ -p,--path-to-home path use specified path instead of user account home dir
+ or /home prefix
+ -U,--unix userlist additionally print UNIX users when using -l or -L\
+ on a UNIX Samba server
+ userlist is a comma-separated list of usernames
+ or uid ranges (root,-25,50-100).
+ (enumerating large ranges can take a long time!)
+ -s,--no-sids (ignored)
+ -m,--no-mount (ignored)
+ -g,--local-groups (ignored)
+ -h,--help displays this message
+ -V,--version version information and exit
+
+Default is to print local accounts on stand-alone machines, domain accounts
+on domain controllers and domain member machines.
+</screen>
+
+<para>The <command>mkpasswd</command> program can be used to help
+configure Cygwin by creating a <filename>/etc/passwd</filename> from
+your system information.
+Its use is essential to include Windows security information. However,
+the actual passwords are determined by Windows, not by the content of
+<filename>/etc/passwd</filename>.</para>
+
+<para>The command is initially called by <command>setup.exe</command> to
+create a default <filename>/etc/passwd</filename>. This should be
+sufficient in most circumstances. However, especially when working
+in a multi-domain environment, you can use <command>mkpasswd</command>
+manually to create a more complete <filename>/etc/passwd</filename> file for
+all domains. Especially when you have the same user name used on
+multiple machines or in multiple domains, you can use the <literal>-D</literal>,
+<literal>-L</literal> and <literal>-C</literal> options to create unique
+domain\user style usernames.</para>
+
+<para>Note that this information is static. If you change the user
+information in your system, you'll need to regenerate the passwd file
+for it to have the new information.</para>
+
+<para>The <literal>-d/-D</literal> and <literal>-l/-L</literal> options
+allow you to specify where the information comes from, the
+local machine or the domain (default or given), or both.
+With the <literal>-d/-D</literal> options the program contacts the Domain
+Controller, which may be unreachable or have restricted access.
+Comma-separated from the machine or domain, you can specify an offset
+which is used as base added to the user's RID to compute the uid
+(offset + RID = uid). This allows to create the same uids every time you
+re-run <command>mkpasswd</command>.
+An entry for the current user can be created by using the
+option <literal>-c</literal> or <literal>-C</literal>.
+If you want to use one of the <literal>-D</literal>, <literal>-L</literal>
+or <literal>-C</literal> options, but you don't like the backslash as
+domain/group separator, you can specify another separator using the
+<literal>-S</literal> option, similar to the <command>mkgroup</command>.
+The <literal>-o</literal> option allows for special cases
+(such as multiple domains) where the UIDs might match otherwise.
+The <literal>-p</literal> option causes <command>mkpasswd</command> to
+use the specified prefix instead of the account home dir or <literal>/home/
+</literal>. For example, this command:
+
+<example id="utils-althome-ex"><title>Using an alternate home root</title>
+<screen>
+<prompt>$</prompt> <userinput>mkpasswd -l -p "$(cygpath -H)" > /etc/passwd</userinput>
+</screen>
+</example>
+
+would put local users' home directories in the Windows 'Profiles' directory.
+The <literal>-u</literal> option creates just an entry for
+the specified user.
+The <literal>-U</literal> option allows you to enumerate the standard UNIX
+users on a Samba machine. It's used together with
+<literal>-l samba-server</literal> or <literal>-L samba-server</literal>.
+The normal UNIX users are usually not enumerated, but they can show
+up as file owners in <command>ls -l</command> output.
+</para>
+
+</sect2>
+
+<sect2 id="mount"><title>mount</title>
+
+<screen>
+Usage: mount [OPTION] [<win32path> <posixpath>]
+ mount -a
+ mount <posixpath>
+
+Display information about mounted filesystems, or mount a filesystem
+
+ -a, --all mount all filesystems mentioned in fstab
+ -c, --change-cygdrive-prefix change the cygdrive path prefix to <posixpath>
+ -f, --force force mount, don't warn about missing mount
+ point directories
+ -h, --help output usage information and exit
+ -m, --mount-entries write fstab entries to replicate mount points
+ and cygdrive prefixes
+ -o, --options X[,X...] specify mount options
+ -p, --show-cygdrive-prefix show user and/or system cygdrive path prefix
+ -V, --version output version information and exit
+</screen>
+
+<para>The <command>mount</command> program is used to map your drives
+and shares onto Cygwin's simulated POSIX directory tree, much like as is
+done by mount commands on typical UNIX systems. However, in contrast to
+mount points given in <filename>/etc/fstab</filename>, mount points
+created or changed with <command>mount</command> are not persistent. They
+disappear immediately after the last process of the current user exited.
+Please see <xref linkend="mount-table"></xref> for more information on the
+concepts behind the Cygwin POSIX file system and strategies for using
+mounts. To remove mounts temporarily, use <command>umount</command></para>
+
+<sect3 id="utils-mount"><title>Using mount</title>
+
+<para>If you just type <command>mount</command> with no parameters, it
+will display the current mount table for you.</para>
+
+<example id="utils-mount-ex">
+<title>Displaying the current set of mount points</title>
+<screen>
+<prompt>$</prompt> <userinput>mount</userinput>
+C:/cygwin/bin on /usr/bin type ntfs (binary)
+C:/cygwin/lib on /usr/lib type ntfs (binary)
+C:/cygwin on / type ntfs (binary)
+C: on /mnt/c type ntfs (binary,user,noumount)
+D: on /mnt/d type fat (binary,user,noumount)
+</screen>
+</example>
+
+<para>In this example, c:/cygwin is the POSIX root and the D drive is
+mapped to <filename>/mnt/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>/mnt/d</filename> mount is only
+visible to the current user.</para>
+
+<para>The <command>mount</command> utility is also the mechanism for
+adding new mounts to the mount table in memory. The following example
+demonstrates how to mount the directory
+<filename>//pollux/home/joe/data</filename> to <filename>/data</filename>
+for the duration of the current session.
+</para>
+
+<example id="utils-mount-add-ex">
+<title>Adding mount points</title>
+<screen>
+<prompt>$</prompt> <userinput>ls /data</userinput>
+ls: /data: No such file or directory
+<prompt>$</prompt> <userinput>mount //pollux/home/joe/data /data</userinput>
+mount: warning - /data does not exist!
+<prompt>$</prompt> <userinput>mount</userinput>
+//pollux/home/joe/data on /data type smbfs (binary)
+C:/cygwin/bin on /usr/bin type ntfs (binary)
+C:/cygwin/lib on /usr/lib type ntfs (binary)
+C:/cygwin on / type ntfs (binary)
+C: on /c type ntfs (binary,user,noumount)
+D: on /d type fat (binary,user,noumount)
+</screen>
+</example>
+
+<para>A given POSIX path may only exist once in the mount table. Attempts to
+replace the mount will fail with a busy error. The <literal>-f</literal>
+(force) option causes the old mount to be silently replaced with the new one,
+provided the old mount point was a user mount point. It's not valid to
+replace system-wide mount points. Additionally, the <literal>-f</literal>
+option will silence warnings about the non-existence of directories at the
+Win32 path location.</para>
+
+<para>
+The <literal>-o</literal> option is the method via which various options about
+the mount point may be recorded. The following options are available (note that
+most of the options are duplicates of other mount flags):</para>
+
+<screen>
+ acl - Use the filesystem's access control lists (ACLs) to
+ implement real POSIX permissions (default).
+ binary - Files default to binary mode (default).
+ bind - Allows to remount part of the file hierarchy somewhere else.
+ Different from other mount calls, the first argument
+ specifies an absolute POSIX path, rather than a Win32 path.
+ This POSIX path is remounted to the POSIX path specified as
+ the second parameter. The conversion to a Win32 path is done
+ within Cygwin immediately at the time of the call. Note that
+ symlinks are ignored while performing this path conversion.
+ cygexec - Treat all files below mount point as cygwin executables.
+ dos - Always convert leading spaces and trailing dots and spaces to
+ characters in the UNICODE private use area. This allows to use
+ broken filesystems which only allow DOS filenames, even if they
+ are not recognized as such by Cygwin.
+ exec - Treat all files below mount point as executable.
+ ihash - Always fake inode numbers rather than using the ones returned
+ by the filesystem. This allows to use broken filesystems which
+ don't return unambiguous inode numbers, even if they are not
+ recognized as such by Cygwin.
+ noacl - Ignore ACLs and fake POSIX permissions.
+ nosuid - No suid files are allowed (currently unimplemented)
+ notexec - Treat all files below mount point as not executable.
+ override - Override immutable mount points.
+ 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).
+ sparse - Switch on support for sparse files. This option only makes
+ sense on NTFS and then only if you really need sparse files.
+ text - Files default to CRLF text mode line endings.
+</screen>
+
+<para>For a more complete description of the mount options and the
+<filename>/etc/fstab</filename> file, see
+<xref linkend="mount-table"></xref>.</para>
+
+<para>Note that all mount points added with <command>mount</command> are
+user mount points. System mount points can only be specified in
+the <filename>/etc/fstab</filename> file.</para>
+
+<para>If you added mount points to <filename>/etc/fstab</filename> or your
+<filename>/etc/fstab.d/<username></filename> file, you can add these
+mount points to your current user session using the <literal>-a/--all</literal>
+option, or by specifing the posix path alone on the command line. As an
+example, consider you added a mount point with the POSIX path
+<filename>/my/mount</filename>. You can add this mount point with either
+one of the following two commands to your current user session.</para>
+
+<screen>
+<prompt>$</prompt> <userinput>mount /my/mount</userinput>
+<prompt>$</prompt> <userinput>mount -a</userinput>
+</screen>
+
+<para>The first command just adds the <filename>/my/mount</filename> mount
+point to your current session, the <command>mount -a</command> adds all
+new mount points to your user session.</para>
+
+<para>If you change a mount point to point to another native path, or
+if you changed the flags of a mount point, you have to <command>umount</command>
+the mount point first, before you can add it again. Please note that
+all such added mount points are added as user mount points, and that the
+rule that system mount points can't be removed or replaced in a running
+session still applies.</para>
+
+<para>To bind a POSIX path to another POSIX path, use the
+<literal>bind</literal> mount flag.</para>
+
+<screen>
+<prompt>$</prompt> <userinput>mount -o bind /var /usr/var</userinput>
+</screen>
+
+<para>This command makes the file hirarchy under <filename>/var</filename>
+additionally available under <filename>/usr/var</filename>.</para>
+
+<para>
+The <literal>-m</literal> option causes the <command>mount</command> utility
+to output the current mount table in a series of fstab entries.
+You can save this output as a backup when experimenting with the mount table.
+Copy the output to <filename>/etc/fstab</filename> to restore the old state.
+It also makes moving your settings to a different machine much easier.</para>
+
+</sect3>
+
+<sect3 id="utils-cygdrive"><title>Cygdrive mount points</title>
+
+<para>Whenever Cygwin cannot use any of the existing mounts to convert
+from a particular Win32 path to a POSIX one, Cygwin will, instead,
+convert to a POSIX path using a default mount point:
+<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> will be accessible as
+<filename>/cygdrive/z</filename>. The <command>mount</command> utility
+can be used to change this default automount prefix through the use of the
+"--change-cygdrive-prefix" option. In the following example, we will
+set the automount prefix to <filename>/mnt</filename>:</para>
+
+<example id="utils-cygdrive-ex">
+<title>Changing the default prefix</title>
+<screen>
+<prompt>$</prompt> <userinput>mount --change-cygdrive-prefix /mnt</userinput>
+</screen>
+</example>
+
+<para>Note that the cygdrive prefix can be set both per-user and system-wide,
+and that as with all mounts, a user-specific mount takes precedence over the
+system-wide setting. The <command>mount</command> utility creates system-wide
+mounts by default if you do not specify a type.
+You can always see the user and system cygdrive prefixes with the
+<literal>-p</literal> option. Using the <literal>--options</literal>
+flag with <literal>--change-cygdrive-prefix</literal> makes all new
+automounted filesystems default to this set of options. For instance
+(using the short form of the command line flags)</para>
+
+<example id="utils-cygdrive-ex2">
+<title>Changing the default prefix with specific mount options</title>
+<screen>
+<prompt>$</prompt> <userinput>mount -c /mnt -o binary,noacl</userinput>
+</screen>
+</example>
+
+
+</sect3>
+
+<sect3 id="utils-limitations"><title>Limitations</title>
+
+<para>Limitations: there is a hard-coded limit of 64 mount points
+(up to Cygwin 1.7.9: 30 mount points). Also, although you can mount
+to pathnames that do not start with "/", there is no way to make use
+of such mount points.</para>
+
+<para>Normally the POSIX mount point in Cygwin is an existing empty
+directory, as in standard UNIX. If this is the case, or if there is a
+place-holder for the mount point (such as a file, a symbolic link
+pointing anywhere, or a non-empty directory), you will get the expected
+behavior. Files present in a mount point directory before the mount
+become invisible to Cygwin programs.
+</para>
+
+<para>It is sometimes desirable to mount to a non-existent directory,
+for example to avoid cluttering the root directory with names
+such as
+<filename>a</filename>, <filename>b</filename>, <filename>c</filename>
+pointing to disks.
+Although <command>mount</command> will give you a warning, most
+everything will work properly when you refer to the mount point
+explicitly. Some strange effects can occur however.
+For example if your current working directory is
+<filename>/dir</filename>,
+say, and <filename>/dir/mtpt</filename> is a mount point, then
+<filename>mtpt</filename> will not show up in an <command>ls</command>
+or
+<command>echo *</command> command and <command>find .</command> will
+not
+find <filename>mtpt</filename>.
+</para>
+
+</sect3>
+
+</sect2>
+
+<sect2 id="passwd"><title>passwd</title>
+
+<screen>
+Usage: passwd [OPTION] [USER]
+
+Change USER's password or password attributes.
+
+User operations:
+ -l, --lock lock USER's account.
+ -u, --unlock unlock USER's account.
+ -c, --cannot-change USER can't change password.
+ -C, --can-change USER can change password.
+ -e, --never-expires USER's password never expires.
+ -E, --expires USER's password expires according to system's
+ password aging rule.
+ -p, --pwd-not-required no password required for USER.
+ -P, --pwd-required password is required for USER.
+ -R, --reg-store-pwd enter password to store it in the registry for
+ later usage by services to be able to switch
+ to this user context with network credentials.
+
+System operations:
+ -i, --inactive NUM set NUM of days before inactive accounts are disabled
+ (inactive accounts are those with expired passwords).
+ -n, --minage DAYS set system minimum password age to DAYS days.
+ -x, --maxage DAYS set system maximum password age to DAYS days.
+ -L, --length LEN set system minimum password length to LEN.
+
+Other options:
+ -d, --logonserver SERVER connect to SERVER (e.g. domain controller).
+ Default server is the local system, unless
+ changing the current user, in which case the
+ default is the content of $LOGONSERVER.
+ -S, --status display password status for USER (locked, expired,
+ etc.) plus global system password settings.
+ -h, --help output usage information and exit.
+ -V, --version output version information and exit.
+
+If no option is given, change USER's password. If no user name is given,
+operate on current user. System operations must not be mixed with user
+operations. Don't specify a USER when triggering a system operation.
+
+Don't specify a user or any other option together with the -R option.
+Non-Admin users can only store their password if cygserver is running.
+Note that storing even obfuscated passwords in the registry is not overly
+secure. Use this feature only if the machine is adequately locked down.
+Don't use this feature if you don't need network access within a remote
+session. You can delete your stored password by using `passwd -R' and
+specifying an empty password.
+</screen>
+
+<para> <command>passwd</command> changes passwords for user accounts.
+A normal user may only change the password for their own account,
+but administrators may change passwords on any account.
+<command>passwd</command> also changes account information, such as
+password expiry dates and intervals.</para>
+
+<para>For password changes, the user is first prompted for their old
+password, if one is present. This password is then encrypted and
+compared against the stored password. The user has only one chance to
+enter the correct password. The administrators are permitted to
+bypass this step so that forgotten passwords may be changed.</para>
+
+<para>The user is then prompted for a replacement password.
+<command>passwd</command> will prompt twice for this replacement and
+compare the second entry against the first. Both entries are required to
+match in order for the password to be changed.</para>
+
+<para>After the password has been entered, password aging information
+is checked to see if the user is permitted to change their password
+at this time. If not, <command>passwd</command> refuses to change the
+password and exits.</para>
+
+<para>
+To get current password status information, use the
+<literal>-S</literal> option. Administrators can use
+<command>passwd</command> to perform several account maintenance
+functions (users may perform some of these functions on their own
+accounts). Accounts may be locked with the <literal>-l</literal> flag
+and unlocked with the <literal>-u</literal> flag. Similarly,
+<literal>-c</literal> disables a user's ability to change passwords, and
+<literal>-C</literal> allows a user to change passwords. For password
+expiry, the <literal>-e</literal> option disables expiration, while the
+<literal>-E</literal> option causes the password to expire according to
+the system's normal aging rules. Use <literal>-p</literal> to disable
+the password requirement for a user, or <literal>-P</literal> to require
+a password.
+</para>
+
+<para>Administrators can also use <command>passwd</command> to change
+system-wide password expiry and length requirements with the
+<literal>-i</literal>, <literal>-n</literal>, <literal>-x</literal>,
+and <literal>-L</literal> options. The <literal>-i</literal>
+option is used to disable an account after the password has been expired
+for a number of days. After a user account has had an expired password
+for <emphasis>NUM</emphasis> days, the user may no longer sign on to
+the account. The <literal>-n</literal> option is
+used to set the minimum number of days before a password may be changed.
+The user will not be permitted to change the password until
+<emphasis>MINDAYS</emphasis> days have elapsed. The
+<literal>-x</literal> option is used to set the maximum number of days
+a password remains valid. After <emphasis>MAXDAYS</emphasis> days, the
+password is required to be changed. Allowed values for the above options
+are 0 to 999. The <literal>-L</literal> option sets the minimum length of
+allowed passwords for users who don't belong to the administrators group
+to <emphasis>LEN</emphasis> characters. Allowed values for the minimum
+password length are 0 to 14. In any of the above cases, a value of 0
+means `no restrictions'.</para>
+
+<para>
+All operations affecting the current user are by default run against
+the logon server of the current user (taken from the environment
+variable <envar>LOGONSERVER</envar>. When password or account information
+of other users should be changed, the default server is the local system.
+To change a user account on a remote machine, use the <literal>-d</literal>
+option to specify the machine to run the command against. Note that the
+current user must be a valid member of the administrators group on the remote
+machine to perform such actions.
+</para>
+
+<para>Users can use the <command>passwd -R</command> to enter
+a password which then gets stored in a special area of the registry on the
+local system, which is also used by Windows to store passwords of accounts
+running Windows services. When a privileged Cygwin application calls the
+<command>set{e}uid(user_id)</command> system call, Cygwin checks if a
+password for that user has been stored in this registry area. If so, it
+uses this password to switch to this user account using that password.
+This allows you to logon through, for instance, <command>ssh</command> with
+public key authentication and get a full qualified user token with
+all credentials for network access. However, the method has some
+drawbacks security-wise. This is explained in more detail in
+<xref linkend="ntsec"></xref>.</para>
+
+<para>Please note that storing passwords in that registry area is a
+privileged operation which only administrative accounts are allowed to
+do. Administrators can enter the password for other user accounts into
+the registry by specifying the username on the commandline. If normal,
+non-admin users should be allowed to enter their passwords using
+<command>passwd -R</command>, it's required to run <command>cygserver</command>
+as a service under the LocalSystem account before running
+<command>passwd -R</command>. This only affects storing passwords. Using
+passwords in privileged processes does not require <command>cygserver</command>
+to run.</para>
+
+<para>Limitations: Users may not be able to change their password on
+some systems.</para>
+
+</sect2>
+
+<sect2 id="pldd"><title>pldd</title>
+
+<screen>
+Usage: pldd [OPTION...] PID
+
+List dynamic shared objects loaded into a process.
+
+ -?, --help Give this help list
+ --usage Give a short usage message
+ -V, --version Print program version
+</screen>
+
+<para><command>pldd</command> prints the shared libraries (DLLs) loaded
+by the process with the given PID.</para>
+
+</sect2>
+
+<sect2 id="ps"><title>ps</title>
+
+<screen>
+Usage: ps [-aefls] [-u UID]
+
+Report process status
+
+ -a, --all show processes of all users
+ -e, --everyone show processes of all users
+ -f, --full show process uids, ppids
+ -h, --help output usage information and exit
+ -l, --long show process uids, ppids, pgids, winpids
+ -p, --process show information for specified PID
+ -s, --summary show process summary
+ -u, --user list processes owned by UID
+ -V, --version output version information and exit
+ -W, --windows show windows as well as cygwin processes
+With no options, ps outputs the long format by default
+</screen>
+
+<para>The <command>ps</command> program gives the status of all the
+Cygwin processes running on the system (ps = "process status"). Due
+to the limitations of simulating a POSIX environment under Windows,
+there is little information to give.
+</para>
+
+<para>
+The PID column is the process ID you need to give to the
+<command>kill</command> command. The PPID is the parent process ID,
+and PGID is the process group ID. The WINPID column is the process
+ID displayed by NT's Task Manager program. The TTY column gives which
+pseudo-terminal a process is running on, or a <literal>'?'</literal>
+for services. The UID column shows which user owns each process.
+STIME is the time the process was started, and COMMAND gives the name
+of the program running. Listings may also have a status flag in
+column zero; <literal>S</literal> means stopped or suspended (in other
+words, in the background), <literal>I</literal> means waiting for
+input or interactive (foreground), and <literal>O</literal> means
+waiting to output.
+</para>
+
+<para>
+By default, <command>ps</command> will only show processes owned by the
+current user. With either the <literal>-a</literal> or <literal>-e</literal>
+option, all user's processes (and system processes) are listed. There are
+historical UNIX reasons for the synonomous options, which are functionally
+identical. The <literal>-f</literal> option outputs a "full" listing with
+usernames for UIDs. The <literal>-l</literal> option is the default display
+mode, showing a "long" listing with all the above columns. The other display
+option is <literal>-s</literal>, which outputs a shorter listing of just
+PID, TTY, STIME, and COMMAND. The <literal>-u</literal> option allows you
+to show only processes owned by a specific user. The <literal>-p</literal>
+option allows you to show information for only the process with the
+specified PID. The <literal>-W</literal>
+option causes <command>ps</command> show non-Cygwin Windows processes as
+well as Cygwin processes. The WINPID is also the PID, and they can be killed
+with the Cygwin <command>kill</command> command's <literal>-f</literal>
+option.
+</para>
+
+</sect2>
+
+<sect2 id="regtool"><title>regtool</title>
+
+<screen>
+Usage: regtool [OPTION] (add|check|get|list|remove|unset|load|unload|save) KEY
+
+View or edit the Win32 registry
+
+Actions:
+
+ add KEY\SUBKEY add new SUBKEY
+ check KEY exit 0 if KEY exists, 1 if not
+ get KEY\VALUE prints VALUE to stdout
+ list KEY list SUBKEYs and VALUEs
+ remove KEY remove KEY
+ set KEY\VALUE [data ...] set VALUE
+ unset KEY\VALUE removes VALUE from KEY
+ load KEY\SUBKEY PATH load hive from PATH into new SUBKEY
+ unload KEY\SUBKEY unload hive and remove SUBKEY
+ save KEY\SUBKEY PATH save SUBKEY into new hive PATH
+
+Options for 'list' Action:
+
+ -k, --keys print only KEYs
+ -l, --list print only VALUEs
+ -p, --postfix like ls -p, appends '\' postfix to KEY names
+
+Options for 'get' Action:
+
+ -b, --binary print REG_BINARY data as hex bytes
+ -n, --none print data as stream of bytes as stored in registry
+ -x, --hex print numerical data as hex numbers
+
+Options for 'set' Action:
+
+ -b, --binary set type to REG_BINARY (hex args or '-')
+ -D, --dword-be set type to REG_DWORD_BIG_ENDIAN
+ -e, --expand-string set type to REG_EXPAND_SZ
+ -i, --integer set type to REG_DWORD
+ -m, --multi-string set type to REG_MULTI_SZ
+ -n, --none set type to REG_NONE
+ -Q, --qword set type to REG_QWORD
+ -s, --string set type to REG_SZ
+
+Options for 'set' and 'unset' Actions:
+
+ -K<c>, --key-separator[=]<c> set key separator to <c> instead of '\'
+
+Other Options:
+
+ -h, --help output usage information and exit
+ -q, --quiet no error output, just nonzero return if KEY/VALUE missing
+ -v, --verbose verbose output, including VALUE contents when applicable
+ -w, --wow64 access 64 bit registry view (ignored on 32 bit Windows)
+ -W, --wow32 access 32 bit registry view (ignored on 32 bit Windows)
+ -V, --version output version information and exit
+
+KEY is in the format [host]\prefix\KEY\KEY\VALUE, where host is optional
+remote host in either \\hostname or hostname: format and prefix is any of:
+ root HKCR HKEY_CLASSES_ROOT (local only)
+ config HKCC HKEY_CURRENT_CONFIG (local only)
+ user HKCU HKEY_CURRENT_USER (local only)
+ machine HKLM HKEY_LOCAL_MACHINE
+ users HKU HKEY_USERS
+
+You can use forward slash ('/') as a separator instead of backslash, in
+that case backslash is treated as escape character
+Example: regtool.exe get '\user\software\Microsoft\Clock\iFormat'
+</screen>
+
+<para>The <command>regtool</command> program allows shell scripts
+to access and modify the Windows registry. Note that modifying the
+Windows registry is dangerous, and carelessness here can result
+in an unusable system. Be careful.</para>
+
+<para>The <literal>-v</literal> option means "verbose". For most
+commands, this causes additional or lengthier messages to be printed.
+Conversely, the <literal>-q</literal> option supresses error messages,
+so you can use the exit status of the program to detect if a key
+exists or not (for example).</para>
+
+<para>The <literal>-w</literal> option allows you to access the 64 bit view
+of the registry. Several subkeys exist in a 32 bit and a 64 bit version
+when running on Windows 64. Since Cygwin is running in 32 bit mode, it
+only has access to the 32 bit view of these registry keys. When using
+the <literal>-w</literal> switch, the 64 bit view is used and
+<command>regtool</command> can access the entire registry.
+This option is simply ignored when running on 32 bit Windows versions.
+</para>
+
+<para>The <literal>-W</literal> option allows you to access the 32 bit view
+on the registry. The purpose of this option is mainly for symmetry. It
+permits creation of OS agnostic scripts which would also work in a hypothetical
+64 bit version of Cygwin.</para>
+
+<para>You must provide <command>regtool</command> with an
+<emphasis>action</emphasis> following options (if any). Currently,
+the action must be <literal>add</literal>, <literal>set</literal>,
+<literal>check</literal>, <literal>get</literal>, <literal>list</literal>,
+<literal>remove</literal>, <literal>set</literal>, or <literal>unset</literal>.
+</para>
+
+<para>The <literal>add</literal> action adds a new key. The
+<literal>check</literal> action checks to see if a key exists (the
+exit code of the program is zero if it does, nonzero if it does not).
+The <literal>get</literal> action gets the value of a key,
+and prints it (and nothing else) to stdout. Note: if the value
+doesn't exist, an error message is printed and the program returns a
+non-zero exit code. If you give <literal>-q</literal>, it doesn't
+print the message but does return the non-zero exit code.</para>
+
+<para>
+The <literal>list</literal> action lists the subkeys and values
+belonging to the given key. With <literal>list</literal>, the
+<literal>-k</literal> option instructs <command>regtool</command>
+to print only KEYs, and the <literal>-l</literal> option to print
+only VALUEs. The <literal>-p</literal> option postfixes a
+<literal>'/'</literal> to each KEY, but leave VALUEs with no
+postfix. The <literal>remove</literal> action
+removes a key. Note that you may need to remove everything in the key
+before you may remove it, but don't rely on this stopping you from
+accidentally removing too much.
+</para>
+
+<para>The <literal>get</literal> action prints a value within a key.
+With the <literal>-b</literal> option, data is printed as hex bytes.
+<literal>-n</literal> allows to print the data as a typeless stream of
+bytes. Integer values (REG_DWORD, REG_QWORD) are usually printed
+as decimal values. The <literal>-x</literal> option allows to print
+the numbers as hexadecimal values.</para>
+
+<para>The <literal>set</literal> action sets a value within a key.
+<literal>-b</literal> means it's binary data (REG_BINARY).
+The binary values are specified as hex bytes in the argument list.
+If the argument is <literal>'-'</literal>, binary data is read
+from stdin instead.
+<literal>-d</literal> or <literal>-i</literal> means the value is a 32 bit
+integer value (REG_DWORD).
+<literal>-D</literal> means the value is a 32 bit integer value in
+Big Endian representation (REG_DWORD_BIG_ENDIAN).
+<literal>-Q</literal> means the value is a 64 bit integer value (REG_QWORD).
+<literal>-s</literal> means the value is a string (REG_SZ).
+<literal>-e</literal> means it's an expanding string (REG_EXPAND_SZ)
+that contains embedded environment variables.
+<literal>-m</literal> means it's a multi-string (REG_MULTI_SZ).
+If you don't specify one of these, <command>regtool</command> tries to
+guess the type based on the value you give. If it looks like a
+number, it's a DWORD, unless it's value doesn't fit into 32 bit, in which
+case it's a QWORD. If it starts with a percent, it's an expanding
+string. If you give multiple values, it's a multi-string. Else, it's
+a regular string.</para>
+
+<para>The <literal>unset</literal> action removes a value from a key.</para>
+
+<para>The <literal>load</literal> action adds a new subkey and loads
+the contents of a registry hive into it.
+The parent key must be HKEY_LOCAL_MACHINE or HKEY_USERS.
+The <literal>unload</literal> action unloads the file and removes
+the subkey.
+</para>
+
+<para>The <literal>save</literal> action saves a subkey into a
+registry hive.
+</para>
+
+<para>
+By default, the last "\" or "/" is assumed to be the separator between the
+key and the value. You can use the <literal>-K</literal> option to provide
+an alternate key/value separator character.
+</para>
+
+</sect2>
+
+<sect2 id="setfacl"><title>setfacl</title>
+
+<screen>
+Usage: setfacl [-r] (-f ACL_FILE | -s acl_entries) FILE...
+ setfacl [-r] ([-d acl_entries] [-m acl_entries]) FILE...
+
+Modify file and directory access control lists (ACLs)
+
+ -d, --delete delete one or more specified ACL entries
+ -f, --file set ACL entries for FILE to ACL entries read
+ from a ACL_FILE
+ -m, --modify modify one or more specified ACL entries
+ -r, --replace replace mask entry with maximum permissions
+ needed for the file group class
+ -s, --substitute substitute specified ACL entries for the
+ ACL of FILE
+ -h, --help output usage information and exit
+ -V, --version output version information and exit
+
+At least one of (-d, -f, -m, -s) must be specified
+</screen>
+
+<para>
+For each file given as parameter, <command>setfacl</command> will
+either replace its complete ACL (<literal>-s</literal>, <literal>-f</literal>),
+or it will add, modify, or delete ACL entries.
+For more information on Cygwin and Windows ACLs, see
+see <xref linkend="ntsec"></xref> in the Cygwin User's Guide.
+</para>
+
+<para>
+Acl_entries are one or more comma-separated ACL entries
+from the following list:
+<screen>
+ u[ser]::perm
+ u[ser]:uid:perm
+ g[roup]::perm
+ g[roup]:gid:perm
+ m[ask]::perm
+ o[ther]::perm
+</screen>
+Default entries are like the above with the additional
+default identifier. For example:
+<screen>
+ d[efault]:u[ser]:uid:perm
+</screen>
+</para>
+
+<para>
+<emphasis>perm</emphasis> is either a 3-char permissions string in the form
+"rwx" with the character <literal>'-'</literal> for no permission
+or it is the octal representation of the permissions, a
+value from 0 (equivalent to "---") to 7 ("rwx").
+<emphasis>uid</emphasis> is a user name or a numerical uid.
+<emphasis>gid</emphasis> is a group name or a numerical gid.
+</para>
+
+<para>
+The following options are supported:
+</para>
+
+<para>
+<literal>-d</literal>
+Delete one or more specified entries from the file's ACL.
+The owner, group and others entries must not be deleted.
+Acl_entries to be deleted should be specified without
+permissions, as in the following list:
+<screen>
+ u[ser]:uid
+ g[roup]:gid
+ d[efault]:u[ser]:uid
+ d[efault]:g[roup]:gid
+ d[efault]:m[ask]:
+ d[efault]:o[ther]:
+</screen>
+</para>
+
+<para>
+<literal>-f</literal>
+Take the Acl_entries from ACL_FILE one per line. Whitespace
+characters are ignored, and the character "#" may be used
+to start a comment. The special filename "-" indicates
+reading from stdin. Note that you can use this with
+<command>getfacl</command> and <command>setfacl</command> to copy
+ACLs from one file to another:
+<screen>
+$ getfacl source_file | setfacl -f - target_file
+</screen>
+</para>
+
+<para>
+Required entries are:
+one user entry for the owner of the file,
+one group entry for the group of the file, and
+one other entry.
+</para>
+
+<para>
+If additional user and group entries are given:
+a mask entry for the file group class of the file, and
+no duplicate user or group entries with the same uid/gid.
+</para>
+
+<para>
+If it is a directory:
+one default user entry for the owner of the file,
+one default group entry for the group of the file,
+one default mask entry for the file group class, and
+one default other entry.
+</para>
+
+<para>
+<literal>-m</literal>
+Add or modify one or more specified ACL entries. Acl_entries is a
+comma-separated list of entries from the same list as above.
+</para>
+
+<para>
+<literal>-r</literal>
+Causes the permissions specified in the mask
+entry to be ignored and replaced by the maximum permissions needed for
+the file group class.
+</para>
+
+<para>
+<literal>-s</literal>
+Like <literal>-f</literal>, but substitute the
+file's ACL with Acl_entries specified in a comma-separated list on the
+command line.
+</para>
+
+<para>
+While the <literal>-d</literal> and <literal>-m</literal> options may be used
+in the same command, the <literal>-f</literal> and <literal>-s</literal>
+options may be used only exclusively.
+</para>
+
+<para>
+Directories may contain default ACL entries. Files created
+in a directory that contains default ACL entries will have
+permissions according to the combination of the current umask,
+the explicit permissions requested and the default ACL entries
+</para>
+
+<para>
+Limitations: Under Cygwin, the default ACL entries are not taken into
+account currently.
+</para>
+
+</sect2>
+
+<sect2 id="setmetamode"><title>setmetamode</title>
+
+<screen>
+Usage: setmetamode [metabit|escprefix]
+
+Get or set keyboard meta mode
+
+ Without argument, it shows the current meta key mode.
+ metabit|meta|bit The meta key sets the top bit of the character.
+ escprefix|esc|prefix The meta key sends an escape prefix.
+
+Other options:
+
+ -h, --help This text
+ -V, --version Print program version and exit
+</screen>
+
+<para><command>setmetamode</command> can be used to determine and set the
+key code sent by the meta (aka <literal>Alt</literal>) key.</para>
+
+</sect2>
+
+<sect2 id="ssp"><title>ssp</title>
+
+<screen>
+Usage: ssp [options] low_pc high_pc command...
+
+Single-step profile COMMAND
+
+ -c, --console-trace trace every EIP value to the console. *Lots* slower.
+ -d, --disable disable single-stepping by default; use
+ OutputDebugString ("ssp on") to enable stepping
+ -e, --enable enable single-stepping by default; use
+ OutputDebugString ("ssp off") to disable stepping
+ -h, --help output usage information and exit
+ -l, --dll enable dll profiling. A chart of relative DLL usage
+ is produced after the run.
+ -s, --sub-threads trace sub-threads too. Dangerous if you have
+ race conditions.
+ -t, --trace-eip trace every EIP value to a file TRACE.SSP. This
+ gets big *fast*.
+ -v, --verbose output verbose messages about debug events.
+ -V, --version output version information and exit
+
+Example: ssp 0x401000 0x403000 hello.exe
+</screen>
+
+<para>
+SSP - The Single Step Profiler
+</para>
+
+<para>
+Original Author: DJ Delorie
+</para>
+
+<para>
+The SSP is a program that uses the Win32 debug API to run a program
+one ASM instruction at a time. It records the location of each
+instruction used, how many times that instruction is used, and all
+function calls. The results are saved in a format that is usable by
+the profiling program <command>gprof</command>, although
+<command>gprof</command> will claim the values
+are seconds, they really are instruction counts. More on that later.
+</para>
+
+<para>
+Because the SSP was originally designed to profile the Cygwin DLL, it
+does not automatically select a block of code to report statistics on.
+You must specify the range of memory addresses to keep track of
+manually, but it's not hard to figure out what to specify. Use the
+"objdump" program to determine the bounds of the target's ".text"
+section. Let's say we're profiling cygwin1.dll. Make sure you've
+built it with debug symbols (else <command>gprof</command> won't run)
+and run objdump like this:
+
+<screen>
+$ objdump -h cygwin1.dll
+</screen>
+
+It will print a report like this:
+<screen>
+cygwin1.dll: file format pei-i386
+
+Sections:
+Idx Name Size VMA LMA File off Algn
+ 0 .text 0007ea00 61001000 61001000 00000400 2**2
+ CONTENTS, ALLOC, LOAD, READONLY, CODE, DATA
+ 1 .data 00008000 61080000 61080000 0007ee00 2**2
+ CONTENTS, ALLOC, LOAD, DATA
+ . . .
+</screen>
+</para>
+
+<para>
+The only information we're concerned with are the VMA of
+the .text section and the VMA of the section after it
+(sections are usually contiguous; you can also add the
+Size to the VMA to get the end address). In this case,
+the VMA is 0x61001000 and the ending address is either
+0x61080000 (start of .data method) or 0x0x6107fa00 (VMA+Size
+method).
+</para>
+
+<para>
+There are two basic ways to use SSP - either profiling a whole
+program, or selectively profiling parts of the program.
+</para>
+
+<para>
+To profile a whole program, just run <command>ssp</command> without options.
+By default, it will step the whole program. Here's a simple example, using
+the numbers above:
+
+<screen>
+$ ssp 0x61001000 0x61080000 hello.exe
+</screen>
+
+This will step the whole program. It will take at least 8 minutes on
+a PII/300 (yes, really). When it's done, it will create a file called
+"gmon.out". You can turn this data file into a readable report with
+<command>gprof</command>:
+
+<screen>
+$ gprof -b cygwin1.dll
+</screen>
+
+The "-b" means 'skip the help pages'. You can omit this until you're
+familiar with the report layout. The <command>gprof</command> documentation
+explains a lot about this report, but <command>ssp</command> changes a few
+things. For example, the first part of the report reports the amount of time
+spent in each function, like this:
+
+<screen>
+Each sample counts as 0.01 seconds.
+ % cumulative self self total
+ time seconds seconds calls ms/call ms/call name
+ 10.02 231.22 72.43 46 1574.57 1574.57 strcspn
+ 7.95 288.70 57.48 130 442.15 442.15 strncasematch
+</screen>
+
+The "seconds" columns are really CPU opcodes, 1/100 second per opcode.
+So, "231.22" above means 23,122 opcodes. The ms/call values are 10x
+too big; 1574.57 means 157.457 opcodes per call. Similar adjustments
+need to be made for the "self" and "children" columns in the second
+part of the report.
+</para>
+
+<para>
+OK, so now we've got a huge report that took a long time to generate,
+and we've identified a spot we want to work on optimizing. Let's say
+it's the time() function. We can use SSP to selectively profile this
+function by using OutputDebugString() to control SSP from within the
+program. Here's a sample program:
+
+<screen>
+ #include <windows.h>
+ main()
+ {
+ time_t t;
+ OutputDebugString("ssp on");
+ time(&t);
+ OutputDebugString("ssp off");
+ }
+</screen>
+</para>
+
+<para>
+Then, add the <literal>-d</literal> option to ssp to default to
+*disabling* profiling. The program will run at full speed until the first
+OutputDebugString, then step until the second.
+You can then use <command>gprof</command> (as usual) to see the performance
+profile for just that portion of the program's execution.
+</para>
+
+<para>
+There are many options to ssp. Since step-profiling makes your
+program run about 1,000 times slower than normal, it's best to
+understand all the options so that you can narrow down the parts
+of your program you need to single-step.
+</para>
+
+<para>
+<literal>-v</literal> - verbose. This prints messages about threads
+starting and stopping, OutputDebugString calls, DLLs loading, etc.
+</para>
+
+<para>
+<literal>-t</literal> and <literal>-c</literal> - tracing.
+With <literal>-t</literal>, *every* step's address is written
+to the file "trace.ssp". This can be used to help debug functions,
+since it can trace multiple threads. Clever use of scripts can match
+addresses with disassembled opcodes if needed. Warning: creates
+*huge* files, very quickly. <literal>-c</literal> prints each address to
+the console, useful for debugging key chunks of assembler. Use
+<literal>addr2line -C -f -s -e foo.exe < trace.ssp > lines.ssp</literal>
+and then <literal>perl cvttrace</literal> to convert to symbolic traces.
+</para>
+
+<para>
+<literal>-s</literal> - subthreads. Usually, you only need to trace the
+main thread, but sometimes you need to trace all threads, so this enables that.
+It's also needed when you want to profile a function that only a
+subthread calls. However, using OutputDebugString automatically
+enables profiling on the thread that called it, not the main thread.
+</para>
+
+<para>
+<literal>-l</literal> - dll profiling. Generates a pretty table of how much
+time was spent in each dll the program used. No sense optimizing a function in
+your program if most of the time is spent in the DLL.
+I usually use the <literal>-v</literal>, <literal>-s</literal>, and
+<literal>-l</literal> options:
+
+<screen>
+$ ssp <literal>-v</literal> <literal>-s</literal> <literal>-l</literal> <literal>-d</literal> 0x61001000 0x61080000 hello.exe
+</screen>
+</para>
+</sect2>
+
+<sect2 id="strace"><title>strace</title>
+
+<screen>
+Usage: strace.exe [OPTIONS] <command-line>
+Usage: strace.exe [OPTIONS] -p <pid>
+
+Trace system calls and signals
+
+ -b, --buffer-size=SIZE set size of output file buffer
+ -d, --no-delta don't display the delta-t microsecond timestamp
+ -f, --trace-children trace child processes (toggle - default true)
+ -h, --help output usage information and exit
+ -m, --mask=MASK set message filter mask
+ -n, --crack-error-numbers output descriptive text instead of error
+ numbers for Windows errors
+ -o, --output=FILENAME set output file to FILENAME
+ -p, --pid=n attach to executing program with cygwin pid n
+ -q, --quiet toggle "quiet" flag. Defaults to on if "-p",
+ off otherwise.
+ -S, --flush-period=PERIOD flush buffered strace output every PERIOD secs
+ -t, --timestamp use an absolute hh:mm:ss timestamp insted of
+ the default microsecond timestamp. Implies -d
+ -T, --toggle toggle tracing in a process already being
+ traced. Requires -p <pid>
+ -u, --usecs toggle printing of microseconds timestamp
+ -V, --version output version information and exit
+ -w, --new-window spawn program under test in a new window
+
+ MASK can be any combination of the following mnemonics and/or hex values
+ (0x is optional). Combine masks with '+' or ',' like so:
+
+ --mask=wm+system,malloc+0x00800
+
+ Mnemonic Hex Corresponding Def Description
+ =========================================================================
+ all 0x000001 (_STRACE_ALL) All strace messages.
+ flush 0x000002 (_STRACE_FLUSH) Flush output buffer after each message.
+ inherit 0x000004 (_STRACE_INHERIT) Children inherit mask from parent.
+ uhoh 0x000008 (_STRACE_UHOH) Unusual or weird phenomenon.
+ syscall 0x000010 (_STRACE_SYSCALL) System calls.
+ startup 0x000020 (_STRACE_STARTUP) argc/envp printout at startup.
+ debug 0x000040 (_STRACE_DEBUG) Info to help debugging.
+ paranoid 0x000080 (_STRACE_PARANOID) Paranoid info.
+ termios 0x000100 (_STRACE_TERMIOS) Info for debugging termios stuff.
+ select 0x000200 (_STRACE_SELECT) Info on ugly select internals.
+ wm 0x000400 (_STRACE_WM) Trace Windows msgs (enable _strace_wm).
+ sigp 0x000800 (_STRACE_SIGP) Trace signal and process handling.
+ minimal 0x001000 (_STRACE_MINIMAL) Very minimal strace output.
+ pthread 0x002000 (_STRACE_PTHREAD) Pthread calls.
+ exitdump 0x004000 (_STRACE_EXITDUMP) Dump strace cache on exit.
+ system 0x008000 (_STRACE_SYSTEM) Serious error; goes to console and log.
+ nomutex 0x010000 (_STRACE_NOMUTEX) Don't use mutex for synchronization.
+ malloc 0x020000 (_STRACE_MALLOC) Trace malloc calls.
+ thread 0x040000 (_STRACE_THREAD) Thread-locking calls.
+ special 0x100000 (_STRACE_SPECIAL) Special debugging printfs for
+ non-checked-in code
+</screen>
+
+<para>The <command>strace</command> program executes a program, and
+optionally the children of the program, reporting any Cygwin DLL output
+from the program(s) to stdout, or to a file with the <literal>-o</literal>
+option. With the <literal>-w</literal> option, you can start an strace
+session in a new window, for example:
+
+<screen>
+$ strace -o tracing_output -w sh -c 'while true; do echo "tracing..."; done' &
+</screen>
+This is particularly useful for <command>strace</command> sessions that
+take a long time to complete.
+</para>
+
+<para>
+Note that <command>strace</command> is a standalone Windows program and so does
+not rely on the Cygwin DLL itself (you can verify this with
+<command>cygcheck</command>). As a result it does not understand symlinks.
+This program is mainly useful for debugging the Cygwin DLL itself.</para>
+
+</sect2>
+
+<sect2 id="tzset"><title>tzset</title>
+
+<screen>
+Usage: tzset [OPTION]
+
+Print POSIX-compatible timezone ID from current Windows timezone setting
+
+Options:
+ -h, --help output usage information and exit.
+ -V, --version output version information and exit.
+
+Use tzset to set your TZ variable. In POSIX-compatible shells like bash,
+dash, mksh, or zsh:
+
+ export TZ=$(tzset)
+
+In csh-compatible shells like tcsh:
+
+ setenv TZ `tzset`
+</screen>
+
+<para>The <command>tzset</command> tool reads the current timezone from Windows
+and generates a POSIX-compatible timezone information for the TZ environment
+variable from that information. That's all there is to it. For the way how
+to use it, see the above usage information.</para>
+
+</sect2>
+
+<sect2 id="umount"><title>umount</title>
+
+<screen>
+Usage: umount.exe [OPTION] [<posixpath>]
+
+Unmount filesystems
+
+ -h, --help output usage information and exit
+ -U, --remove-user-mounts remove all user mounts
+ -V, --version output version information and exit
+</screen>
+
+<para>The <command>umount</command> program removes mounts from the
+mount table in the current session. If you specify a POSIX path that
+corresponds to a current mount point, <command>umount</command> will
+remove it from the current mount table. Note that you can only remove
+user mount points. The <literal>-U</literal> flag may be used to
+specify removing all user mount points from the current user session.</para>
+
+<para>See <xref linkend="mount-table"></xref> for more information on the mount
+table.</para>
+</sect2>
+
+</sect1>
git://sourceware.org / newlib-cygwin.git / commitdiff