diff options
| -rw-r--r-- | winsup/doc/ChangeLog | 38 | ||||
| -rw-r--r-- | winsup/doc/Makefile.in | 55 | ||||
| -rwxr-xr-x | winsup/doc/configure | 189 | ||||
| -rw-r--r-- | winsup/doc/configure.ac | 2 | ||||
| -rw-r--r-- | winsup/doc/cygserver.xml (renamed from winsup/doc/cygserver.sgml) | 4 | ||||
| -rw-r--r-- | winsup/doc/cygwin-api.in.xml (renamed from winsup/doc/cygwin-api.in.sgml) | 12 | ||||
| -rw-r--r-- | winsup/doc/cygwin-ug-net.in.sgml | 25 | ||||
| -rw-r--r-- | winsup/doc/cygwin-ug-net.xml | 16 | ||||
| -rw-r--r-- | winsup/doc/cygwin-ug.in.sgml | 64 | ||||
| -rw-r--r-- | winsup/doc/cygwin-ug.xml | 11 | ||||
| -rw-r--r-- | winsup/doc/cygwin.xsl (renamed from winsup/doc/cygwin.dsl) | 0 | ||||
| -rw-r--r-- | winsup/doc/cygwinenv.xml (renamed from winsup/doc/cygwinenv.sgml) | 4 | ||||
| -rw-r--r-- | winsup/doc/dll.xml (renamed from winsup/doc/dll.sgml) | 4 | ||||
| -rw-r--r-- | winsup/doc/effectively.xml (renamed from winsup/doc/effectively.sgml) | 4 | ||||
| -rw-r--r-- | winsup/doc/faq-api.xml | 9 | ||||
| -rw-r--r-- | winsup/doc/faq-copyright.xml | 17 | ||||
| -rw-r--r-- | winsup/doc/faq-programming.xml | 8 | ||||
| -rw-r--r-- | winsup/doc/faq-resources.xml | 9 | ||||
| -rw-r--r-- | winsup/doc/faq-sections.xml | 75 | ||||
| -rw-r--r-- | winsup/doc/faq-setup.xml | 8 | ||||
| -rw-r--r-- | winsup/doc/faq-using.xml | 8 | ||||
| -rw-r--r-- | winsup/doc/faq-what.xml | 11 | ||||
| -rw-r--r-- | winsup/doc/faq.xml | 80 | ||||
| -rw-r--r-- | winsup/doc/filemodes.xml (renamed from winsup/doc/filemodes.sgml) | 4 | ||||
| -rw-r--r-- | winsup/doc/gcc.xml (renamed from winsup/doc/gcc.sgml) | 4 | ||||
| -rw-r--r-- | winsup/doc/gdb.xml (renamed from winsup/doc/gdb.sgml) | 3 | ||||
| -rw-r--r-- | winsup/doc/highlights.xml (renamed from winsup/doc/overview2.sgml) | 97 | ||||
| -rw-r--r-- | winsup/doc/legal.xml (renamed from winsup/doc/legal.sgml) | 4 | ||||
| -rw-r--r-- | winsup/doc/new-features.xml (renamed from winsup/doc/new-features.sgml) | 4 | ||||
| -rw-r--r-- | winsup/doc/ntsec.xml (renamed from winsup/doc/ntsec.sgml) | 4 | ||||
| -rw-r--r-- | winsup/doc/ov-ex-unix.xml | 54 | ||||
| -rw-r--r-- | winsup/doc/ov-ex-win.xml | 47 | ||||
| -rw-r--r-- | winsup/doc/overview.xml (renamed from winsup/doc/overview.sgml) | 15 | ||||
| -rw-r--r-- | winsup/doc/pathnames.xml (renamed from winsup/doc/pathnames.sgml) | 518 | ||||
| -rw-r--r-- | winsup/doc/programming.sgml | 11 | ||||
| -rw-r--r-- | winsup/doc/programming.xml | 12 | ||||
| -rw-r--r-- | winsup/doc/setup-env.xml | 129 | ||||
| -rw-r--r-- | winsup/doc/setup-files.xml | 85 | ||||
| -rw-r--r-- | winsup/doc/setup-locale.xml (renamed from winsup/doc/setup2.sgml) | 273 | ||||
| -rw-r--r-- | winsup/doc/setup-maxmem.xml | 66 | ||||
| -rw-r--r-- | winsup/doc/setup-net.xml (renamed from winsup/doc/setup-net.sgml) | 15 | ||||
| -rw-r--r-- | winsup/doc/setup.xml (renamed from winsup/doc/setup.sgml) | 17 | ||||
| -rw-r--r-- | winsup/doc/specialnames.xml | 517 | ||||
| -rw-r--r-- | winsup/doc/textbinary.xml (renamed from winsup/doc/textbinary.sgml) | 4 | ||||
| -rw-r--r-- | winsup/doc/ug-info.xml | 36 | ||||
| -rw-r--r-- | winsup/doc/using.sgml | 25 | ||||
| -rw-r--r-- | winsup/doc/using.xml | 21 | ||||
| -rw-r--r-- | winsup/doc/windres.xml (renamed from winsup/doc/windres.sgml) | 3 | ||||
| -rw-r--r-- | winsup/utils/utils.xml | 2190 |
49 files changed, 3515 insertions, 1296 deletions
diff --git a/winsup/doc/ChangeLog b/winsup/doc/ChangeLog index 0f001ba1d..aeb214ebf 100644 --- a/winsup/doc/ChangeLog +++ b/winsup/doc/ChangeLog @@ -1,3 +1,41 @@ +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. diff --git a/winsup/doc/Makefile.in b/winsup/doc/Makefile.in index 5ef5d3416..c81de1058 100644 --- a/winsup/doc/Makefile.in +++ b/winsup/doc/Makefile.in @@ -12,7 +12,7 @@ SHELL = @SHELL@ 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@ @@ -22,70 +22,59 @@ XMLTO:=xmlto --skip-validation --with-dblatex 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 diff --git a/winsup/doc/configure b/winsup/doc/configure index 352dfdca9..996722fc1 100755 --- a/winsup/doc/configure +++ b/winsup/doc/configure @@ -1,11 +1,9 @@ #! /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 @@ -134,6 +132,31 @@ export LANGUAGE # 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 @@ -167,7 +190,8 @@ if ( set x; as_fn_ret_success y && test x = \"\$1\" ); then : 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'\" && @@ -211,21 +235,25 @@ IFS=$as_save_IFS 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 : @@ -327,6 +355,14 @@ $as_echo X"$as_dir" | } # 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 @@ -448,6 +484,10 @@ as_cr_alnum=$as_cr_Letters$as_cr_digits 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). @@ -482,16 +522,16 @@ if (echo >conf$$.file) 2>/dev/null; then # ... 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 @@ -503,28 +543,8 @@ else 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'" @@ -561,7 +581,7 @@ PACKAGE_STRING= 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 @@ -1090,8 +1110,6 @@ target=$target_alias 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 @@ -1321,9 +1339,9 @@ test -n "$ac_init_help" && exit $ac_status 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 @@ -1376,7 +1394,7 @@ This file contains any messages produced by compilers while 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 $@ @@ -1883,7 +1901,7 @@ do 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 @@ -1923,7 +1941,7 @@ do 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 @@ -1981,7 +1999,7 @@ do 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 @@ -2021,7 +2039,7 @@ do 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 @@ -2074,7 +2092,7 @@ do 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 @@ -2115,7 +2133,7 @@ do 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 @@ -2173,7 +2191,7 @@ do 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 @@ -2217,7 +2235,7 @@ do 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 @@ -2739,8 +2757,7 @@ cat confdefs.h - <<_ACEOF >conftest.$ac_ext /* 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); @@ -3275,16 +3292,16 @@ if (echo >conf$$.file) 2>/dev/null; then # ... 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 @@ -3344,28 +3361,16 @@ else 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'" @@ -3387,7 +3392,7 @@ cat >>$CONFIG_STATUS <<\_ACEOF || ac_write_fail=1 # 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 @@ -3440,10 +3445,10 @@ cat >>$CONFIG_STATUS <<_ACEOF || ac_write_fail=1 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." @@ -3520,7 +3525,7 @@ fi _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' diff --git a/winsup/doc/configure.ac b/winsup/doc/configure.ac index 0a2bb8562..ea5d61074 100644 --- a/winsup/doc/configure.ac +++ b/winsup/doc/configure.ac @@ -10,7 +10,7 @@ dnl details. 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 diff --git a/winsup/doc/cygserver.sgml b/winsup/doc/cygserver.xml index cef73b201..6a4ec4ec5 100644 --- a/winsup/doc/cygserver.sgml +++ b/winsup/doc/cygserver.xml @@ -1,3 +1,7 @@ +<?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> diff --git a/winsup/doc/cygwin-api.in.sgml b/winsup/doc/cygwin-api.in.xml index 15e663e97..726798ef2 100644 --- a/winsup/doc/cygwin-api.in.sgml +++ b/winsup/doc/cygwin-api.in.xml @@ -1,15 +1,13 @@ -<?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> diff --git a/winsup/doc/cygwin-ug-net.in.sgml b/winsup/doc/cygwin-ug-net.in.sgml deleted file mode 100644 index 542457859..000000000 --- a/winsup/doc/cygwin-ug-net.in.sgml +++ /dev/null @@ -1,25 +0,0 @@ -<?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> diff --git a/winsup/doc/cygwin-ug-net.xml b/winsup/doc/cygwin-ug-net.xml new file mode 100644 index 000000000..89526d721 --- /dev/null +++ b/winsup/doc/cygwin-ug-net.xml @@ -0,0 +1,16 @@ +<?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> diff --git a/winsup/doc/cygwin-ug.in.sgml b/winsup/doc/cygwin-ug.in.sgml deleted file mode 100644 index 976f23f1c..000000000 --- a/winsup/doc/cygwin-ug.in.sgml +++ /dev/null @@ -1,64 +0,0 @@ -<?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> diff --git a/winsup/doc/cygwin-ug.xml b/winsup/doc/cygwin-ug.xml new file mode 100644 index 000000000..5647fa435 --- /dev/null +++ b/winsup/doc/cygwin-ug.xml @@ -0,0 +1,11 @@ +<?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> diff --git a/winsup/doc/cygwin.dsl b/winsup/doc/cygwin.xsl index 23512934a..23512934a 100644 --- a/winsup/doc/cygwin.dsl +++ b/winsup/doc/cygwin.xsl diff --git a/winsup/doc/cygwinenv.sgml b/winsup/doc/cygwinenv.xml index 27c3e4eb2..0ba5def35 100644 --- a/winsup/doc/cygwinenv.sgml +++ b/winsup/doc/cygwinenv.xml @@ -1,3 +1,7 @@ +<?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> diff --git a/winsup/doc/dll.sgml b/winsup/doc/dll.xml index 2575c6858..f0369760f 100644 --- a/winsup/doc/dll.sgml +++ b/winsup/doc/dll.xml @@ -1,3 +1,7 @@ +<?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 diff --git a/winsup/doc/effectively.sgml b/winsup/doc/effectively.xml index fa5b2b6ca..cb25628fd 100644 --- a/winsup/doc/effectively.sgml +++ b/winsup/doc/effectively.xml @@ -1,3 +1,7 @@ +<?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> diff --git a/winsup/doc/faq-api.xml b/winsup/doc/faq-api.xml index a515d1cd9..de2d31cc6 100644 --- a/winsup/doc/faq-api.xml +++ b/winsup/doc/faq-api.xml @@ -1,3 +1,10 @@ +<?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> @@ -319,4 +326,4 @@ In a Windows console window you can enable and capture mouse events using the xterm escape sequences for mouse events. </para> </answer></qandaentry> - +</qandadiv> diff --git a/winsup/doc/faq-copyright.xml b/winsup/doc/faq-copyright.xml new file mode 100644 index 000000000..e73692fd9 --- /dev/null +++ b/winsup/doc/faq-copyright.xml @@ -0,0 +1,17 @@ +<?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> diff --git a/winsup/doc/faq-programming.xml b/winsup/doc/faq-programming.xml index 559c3b525..4e8d54864 100644 --- a/winsup/doc/faq-programming.xml +++ b/winsup/doc/faq-programming.xml @@ -1,5 +1,11 @@ +<?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> @@ -1107,3 +1113,5 @@ executable.</para></listitem> linker flag.</para></listitem> </orderedlist></listitem></orderedlist> </answer></qandaentry> + +</qandadiv> diff --git a/winsup/doc/faq-resources.xml b/winsup/doc/faq-resources.xml index 9bf42f722..128b713a3 100644 --- a/winsup/doc/faq-resources.xml +++ b/winsup/doc/faq-resources.xml @@ -1,3 +1,10 @@ +<?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> @@ -48,4 +55,4 @@ for a list of them.) <para>Comprehensive information about reporting problems with Cygwin can be found at <ulink url="http://cygwin.com/problems.html" />. </para> </answer></qandaentry> - +</qandadiv> diff --git a/winsup/doc/faq-sections.xml b/winsup/doc/faq-sections.xml deleted file mode 100644 index 896a9661b..000000000 --- a/winsup/doc/faq-sections.xml +++ /dev/null @@ -1,75 +0,0 @@ -<?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> diff --git a/winsup/doc/faq-setup.xml b/winsup/doc/faq-setup.xml index 4daa39b37..52373f1e4 100644 --- a/winsup/doc/faq-setup.xml +++ b/winsup/doc/faq-setup.xml @@ -1,3 +1,10 @@ +<?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> @@ -604,4 +611,5 @@ this up for Cygwin 1.7, we might add this information here. 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> diff --git a/winsup/doc/faq-using.xml b/winsup/doc/faq-using.xml index 87f1be1bf..c3a878743 100644 --- a/winsup/doc/faq-using.xml +++ b/winsup/doc/faq-using.xml @@ -1,3 +1,10 @@ +<?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> @@ -1243,3 +1250,4 @@ such as virtual memory paging and file caching.</para> difficult to make <literal>fork()</literal> work reliably.</para> </answer> </qandaentry> +</qandadiv> diff --git a/winsup/doc/faq-what.xml b/winsup/doc/faq-what.xml index 166338d99..f973b3f2c 100644 --- a/winsup/doc/faq-what.xml +++ b/winsup/doc/faq-what.xml @@ -1,5 +1,12 @@ +<?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> @@ -152,4 +159,4 @@ function, so some email will have to go unanswered. <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> diff --git a/winsup/doc/faq.xml b/winsup/doc/faq.xml index a48783410..498558907 100644 --- a/winsup/doc/faq.xml +++ b/winsup/doc/faq.xml @@ -1,71 +1,21 @@ -<?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> diff --git a/winsup/doc/filemodes.sgml b/winsup/doc/filemodes.xml index 2a644db51..e4cbd448f 100644 --- a/winsup/doc/filemodes.sgml +++ b/winsup/doc/filemodes.xml @@ -1,3 +1,7 @@ +<?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 diff --git a/winsup/doc/gcc.sgml b/winsup/doc/gcc.xml index 6a9d1055b..b9039db96 100644 --- a/winsup/doc/gcc.sgml +++ b/winsup/doc/gcc.xml @@ -1,3 +1,7 @@ +<?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> diff --git a/winsup/doc/gdb.sgml b/winsup/doc/gdb.xml index 42d31284c..af0c0dd8a 100644 --- a/winsup/doc/gdb.sgml +++ b/winsup/doc/gdb.xml @@ -1,3 +1,6 @@ +<?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> diff --git a/winsup/doc/overview2.sgml b/winsup/doc/highlights.xml index 81e55c47e..6b0a736ee 100644 --- a/winsup/doc/overview2.sgml +++ b/winsup/doc/highlights.xml @@ -1,97 +1,6 @@ -<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> diff --git a/winsup/doc/legal.sgml b/winsup/doc/legal.xml index e3722af6a..f909f4915 100644 --- a/winsup/doc/legal.sgml +++ b/winsup/doc/legal.xml @@ -1,3 +1,7 @@ +<?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> diff --git a/winsup/doc/new-features.sgml b/winsup/doc/new-features.xml index a4a9f8099..09ae7ab1f 100644 --- a/winsup/doc/new-features.sgml +++ b/winsup/doc/new-features.xml @@ -1,3 +1,7 @@ +<?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> diff --git a/winsup/doc/ntsec.sgml b/winsup/doc/ntsec.xml index 4d78cde45..72cf7bb89 100644 --- a/winsup/doc/ntsec.sgml +++ b/winsup/doc/ntsec.xml @@ -1,3 +1,7 @@ +<?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 diff --git a/winsup/doc/ov-ex-unix.xml b/winsup/doc/ov-ex-unix.xml new file mode 100644 index 000000000..e1debabdd --- /dev/null +++ b/winsup/doc/ov-ex-unix.xml @@ -0,0 +1,54 @@ +<?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> diff --git a/winsup/doc/ov-ex-win.xml b/winsup/doc/ov-ex-win.xml new file mode 100644 index 000000000..c9371a971 --- /dev/null +++ b/winsup/doc/ov-ex-win.xml @@ -0,0 +1,47 @@ +<?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> diff --git a/winsup/doc/overview.sgml b/winsup/doc/overview.xml index d07ec5834..f43a69719 100644 --- a/winsup/doc/overview.sgml +++ b/winsup/doc/overview.xml @@ -1,4 +1,9 @@ -<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> @@ -29,8 +34,8 @@ distribution). </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> @@ -120,7 +125,7 @@ available in a 64 bit version is 1.7.19.</para> </sect1> -DOCTOOL-INSERT-highlights -DOCTOOL-INSERT-ov-new1.7 +<xi:include href="highlights.xml"/> +<xi:include href="new-features.xml"/> </chapter> diff --git a/winsup/doc/pathnames.sgml b/winsup/doc/pathnames.xml index e8d19ad0f..3a85f00ff 100644 --- a/winsup/doc/pathnames.sgml +++ b/winsup/doc/pathnames.xml @@ -1,3 +1,7 @@ +<?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> @@ -489,517 +493,3 @@ not by default, for example).</para> </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> diff --git a/winsup/doc/programming.sgml b/winsup/doc/programming.sgml deleted file mode 100644 index 45f26f4fa..000000000 --- a/winsup/doc/programming.sgml +++ /dev/null @@ -1,11 +0,0 @@ -<chapter id="programming"><title>Programming with Cygwin</title> - -DOCTOOL-INSERT-gcc - -DOCTOOL-INSERT-gdb - -DOCTOOL-INSERT-dll - -DOCTOOL-INSERT-windres - -</chapter> diff --git a/winsup/doc/programming.xml b/winsup/doc/programming.xml new file mode 100644 index 000000000..4b65c4090 --- /dev/null +++ b/winsup/doc/programming.xml @@ -0,0 +1,12 @@ +<?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> diff --git a/winsup/doc/setup-env.xml b/winsup/doc/setup-env.xml new file mode 100644 index 000000000..ab3d50bdc --- /dev/null +++ b/winsup/doc/setup-env.xml @@ -0,0 +1,129 @@ +<?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> diff --git a/winsup/doc/setup-files.xml b/winsup/doc/setup-files.xml new file mode 100644 index 000000000..3fc4d0ccb --- /dev/null +++ b/winsup/doc/setup-files.xml @@ -0,0 +1,85 @@ +<?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> + diff --git a/winsup/doc/setup2.sgml b/winsup/doc/setup-locale.xml index bafecef89..de0532f62 100644 --- a/winsup/doc/setup2.sgml +++ b/winsup/doc/setup-locale.xml @@ -1,191 +1,6 @@ -<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> @@ -615,85 +430,3 @@ of the "CPxxx" style charsets, always use them with the trailing "CP".</para> </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> - diff --git a/winsup/doc/setup-maxmem.xml b/winsup/doc/setup-maxmem.xml new file mode 100644 index 000000000..1f5ee31a6 --- /dev/null +++ b/winsup/doc/setup-maxmem.xml @@ -0,0 +1,66 @@ +<?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> diff --git a/winsup/doc/setup-net.sgml b/winsup/doc/setup-net.xml index 4694eb330..877489b9c 100644 --- a/winsup/doc/setup-net.sgml +++ b/winsup/doc/setup-net.xml @@ -1,4 +1,9 @@ -<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> @@ -257,8 +262,8 @@ Problems with Cygwin</ulink>. </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> diff --git a/winsup/doc/setup.sgml b/winsup/doc/setup.xml index 1ba28abb5..bea7d3fe3 100644 --- a/winsup/doc/setup.sgml +++ b/winsup/doc/setup.xml @@ -1,4 +1,9 @@ -<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> @@ -39,9 +44,9 @@ via the "Add/Remove Programs" control panel.</para> </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> diff --git a/winsup/doc/specialnames.xml b/winsup/doc/specialnames.xml new file mode 100644 index 000000000..71491deac --- /dev/null +++ b/winsup/doc/specialnames.xml @@ -0,0 +1,517 @@ +<?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> diff --git a/winsup/doc/textbinary.sgml b/winsup/doc/textbinary.xml index 6e6e83025..112042f82 100644 --- a/winsup/doc/textbinary.sgml +++ b/winsup/doc/textbinary.xml @@ -1,3 +1,7 @@ +<?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> diff --git a/winsup/doc/ug-info.xml b/winsup/doc/ug-info.xml new file mode 100644 index 000000000..c5b4a67c8 --- /dev/null +++ b/winsup/doc/ug-info.xml @@ -0,0 +1,36 @@ +<?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> diff --git a/winsup/doc/using.sgml b/winsup/doc/using.sgml deleted file mode 100644 index 4a802e6c8..000000000 --- a/winsup/doc/using.sgml +++ /dev/null @@ -1,25 +0,0 @@ -<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> diff --git a/winsup/doc/using.xml b/winsup/doc/using.xml new file mode 100644 index 000000000..1795acccd --- /dev/null +++ b/winsup/doc/using.xml @@ -0,0 +1,21 @@ +<?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> diff --git a/winsup/doc/windres.sgml b/winsup/doc/windres.xml index 82c537dff..4b2a13ef7 100644 --- a/winsup/doc/windres.sgml +++ b/winsup/doc/windres.xml @@ -1,3 +1,6 @@ +<?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> diff --git a/winsup/utils/utils.xml b/winsup/utils/utils.xml new file mode 100644 index 000000000..8c0b838c6 --- /dev/null +++ b/winsup/utils/utils.xml @@ -0,0 +1,2190 @@ +<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> |