diff options
Diffstat (limited to 'winsup/doc')
| -rw-r--r-- | winsup/doc/.cvsignore | 14 | ||||
| -rw-r--r-- | winsup/doc/ChangeLog | 167 | ||||
| -rw-r--r-- | winsup/doc/Makefile.in | 72 | ||||
| -rw-r--r-- | winsup/doc/Wishlist | 111 | ||||
| -rwxr-xr-x | winsup/doc/bodysnatcher.pl | 44 | ||||
| -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.xsl (renamed from winsup/doc/cygwin.dsl) | 0 | ||||
| -rw-r--r-- | winsup/doc/cygwinenv.xml (renamed from winsup/doc/cygwinenv.sgml) | 35 | ||||
| -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) | 17 | ||||
| -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 | 333 | ||||
| -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 | 12 | ||||
| -rw-r--r-- | winsup/doc/faq-using.xml | 16 | ||||
| -rw-r--r-- | winsup/doc/faq-what.xml | 20 | ||||
| -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) | 126 | ||||
| -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) | 40 | ||||
| -rw-r--r-- | winsup/doc/ntsec.xml (renamed from winsup/doc/ntsec.sgml) | 12 | ||||
| -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) | 23 | ||||
| -rw-r--r-- | winsup/doc/pathnames.xml (renamed from winsup/doc/pathnames.sgml) | 598 | ||||
| -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.sgml | 47 | ||||
| -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 | ||||
| -rwxr-xr-x | winsup/doc/xidepend | 34 |
51 files changed, 2094 insertions, 1446 deletions
diff --git a/winsup/doc/.cvsignore b/winsup/doc/.cvsignore new file mode 100644 index 000000000..288848833 --- /dev/null +++ b/winsup/doc/.cvsignore @@ -0,0 +1,14 @@ +Makefile +Makefile.dep + +autom4te.cache +config.log +config.status + +cygwin-api +cygwin-api.xml + +cygwin-ug-net +cygwin-ug-net.html + +faq diff --git a/winsup/doc/ChangeLog b/winsup/doc/ChangeLog index 223261304..0e12f8b74 100644 --- a/winsup/doc/ChangeLog +++ b/winsup/doc/ChangeLog @@ -1,3 +1,170 @@ +2013-06-05 Corinna Vinschen <corinna@vinschen.de> + + * faq-programming.xml: Convert url to refer to new flat faq.html file. + * faq-setup.xml: Ditto. + * faq-using.xml: Ditto. + * highlights.xml: Ditto. + +2013-06-05 Corinna Vinschen <corinna@vinschen.de> + + * new-features.xml (ov-new1.7.19): Revert mandatory locking support to + "preliminary". + +2013-06-04 Corinna Vinschen <corinna@vinschen.de> + + * Makefile.in: Add rule to rebuild Makefile if Makefile.in changes. + Include Makefile.dep last. + (Makefile.dep): Run xidepend within source dir. Temporarily drop + faq.xml from dependencies. + * xidepend: Fix creating base filename to accommodate VPATH. + +2013-06-04 Corinna Vinschen <corinna@vinschen.de> + + * new-features.xml (ov-new1.7.19): Align mandatory locking text to + today's changes. + +2013-06-03 Corinna Vinschen <corinna@vinschen.de> + + * new-features.xml (ov-new1.7.19): Add mandatory locking. + +2013-05-23 Warren Young <warren@etr-usa.com> + + * xidepend: New script, generates Makefile.dep from top-level XML + * .cvsignore: Ignoring Makefile.dep output + * Makefile: Creating Makefile.dep if it doesn't exist, including it + if it does, and removing it on 'make clean' + * Wishlist: Knocked autodependency generation off the list + +2013-05-23 Corinna Vinschen <corinna@vinschen.de> + + * cygwinenv.xml (cygwinenv-implemented-options): Explain new + winsymliks:nativestrict option. Strip out description of symlink types + and refer to new pathnames-symlinks section. + * highlights.xml (ov-hi-files): Rip out most of symlink description and + refer to new pathnames-symlinks section instead. + * new-features.xml (ov-new1.7.19): Add CYGWIN=winsymlinks:nativestrict. + * pathnames.xml (pathnames-symlinks): New section describing symbolic + link handling. + +2013-05-21 Corinna Vinschen <corinna@vinschen.de> + + * new-features.xml (ov-new1.7.19): Add arc4random, + arc4random_addrandom, arc4random_buf, arc4random_stir and + arc4random_uniform. + +2013-05-21 Corinna Vinschen <corinna@vinschen.de> + + * new-features.xml (ov-new1.7.19): Add __b64_ntop and __b64_pton. + +2013-05-13 Warren Young <warren@etr-usa.com> + + * cygwin-ug.xml setup.xml: Removed; unused. + * Wishlist: Created, with initial content based on a -patches + mailing list post. + +2013-05-06 Warren Young <warren@etr-usa.com> + + * cygwin-api.in.xml (bookinfo): Reverted XInclude for legal.xml + fragment to a DOCTOOL include. + +2013-05-03 Christopher Faylor <me.cygwin2013@cgf.cx> + + * Makefile (FAQ_SOURCES): Use wildcard function to find sources in + srcdir. + +2013-05-01 Warren Young <warren@etr-usa.com> + + * bodysnatcher.pl: Created + * Makefile.in (faq/faq.body): Added target to create this file from + faq/faq.html using new bodysnatcher.pl script. + +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. + +2013-04-24 Corinna Vinschen <corinna@vinschen.de> + + * faq-programming.xml (faq.programming.64bitporting): Extend entry. + (faq.programming.64bitporting-fail): New entry. + (faq.programming.64bitporting-cygwin64): New entry. + +2013-04-24 Corinna Vinschen <corinna@vinschen.de> + Christian Franke <Christian.Franke@t-online.de> + + * faq-programming.xml (faq.programming.64bitporting): Mention the + -Wformat and -Wall gcc options. + +2013-04-24 Corinna Vinschen <corinna@vinschen.de> + + * faq-programming.xml (faq.programming.64bitporting): New FAQ entry. + (faq.programming.objective-c): Include gcc4. + (faq.programming.make-execvp): Drop text discouraging usage of -j. + (faq.programming.undeclared-functions): Drop entry. + (faq.programming.x86-assembly): Ditto. + (faq.programming.djgpp): Ditto. + +2013-04-24 Corinna Vinschen <corinna@vinschen.de> + + * cygwinenv.sgml (cygwinenv-implemented-options): Change description + for winsymlink option to explain new implementation. + * new-features.sgml (ov-new1.7.19): Add support for native symlinks and + AFS. + +2013-04-23 Corinna Vinschen <corinna@vinschen.de> + + * Throughout, eliminate Windows 2000 from the documentation. + * overview.sgml (brief-history): Mention native AMD64 support. + +2013-04-23 Corinna Vinschen <corinna@vinschen.de> + + * Makefile.in (SGMLDIRS): Accommodate dropping utils_source and + cygwin_source from ../Makefile.common. + * new-features.sgml (ov-new1.7.19): New section. Document dropped + support for pre-XP SP3 and added support for 64 bit Cygwin. + +2013-04-23 Corinna Vinschen <corinna@vinschen.de> + + * faq-what.xml (faq.what.supported): Change to accommodate existence + of 64 bit version. + 2013-03-27 Corinna Vinschen <corinna@vinschen.de> * faq-what.xml (faq.what.supported): Mention Windows 8 and Server 2012. diff --git a/winsup/doc/Makefile.in b/winsup/doc/Makefile.in index 5ea8fd529..48bf50472 100644 --- a/winsup/doc/Makefile.in +++ b/winsup/doc/Makefile.in @@ -1,5 +1,6 @@ # -*- Makefile -*- for winsup/doc -# Copyright (c) 1998-2000,2001 Red Hat, Inc. +# Copyright (c) 1998-2000, 2001, 2002, 2004, 2005, 2006, 2008, 2009, 2010, +# 2013 Red Hat, Inc. # # This file is part of Cygwin. # @@ -11,7 +12,7 @@ SHELL = @SHELL@ srcdir = @srcdir@ VPATH = @srcdir@ -SGMLDIRS = -d $(srcdir) -d $(utils_source) -d $(cygwin_source) +DBXDIRS = -d $(srcdir) -d $(srcdir)/../utils -d $(srcdir)/../cygwin CC:=@CC@ CC_FOR_TARGET:=@CC@ @@ -21,73 +22,76 @@ 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:= $(wildcard ${srcdir}/faq*.xml) -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 +.SUFFIXES: .html .body -.SUFFIXES: +.html.body: + $(srcdir)/bodysnatcher.pl $< -all : \ +all: Makefile Makefile.dep \ 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.body faq/faq.html \ cygwin-ug-net/cygwin-ug-net.pdf \ cygwin-api/cygwin-api.pdf +Makefile: ${srcdir}/Makefile.in + /bin/sh ./config.status + clean: - rm -Rf $(TOCLEAN) + rm -f Makefile.dep + 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 tarball : cygwin-docs.tar.bz2 cygwin-docs.tar.bz2 : $(TBFILES) $(TBDEPS) find $(TBFILES) $(TBDIRS) \! -type d | sort | tar -T - -cf - | bzip2 > cygwin-docs.tar.bz2 + +Makefile.dep: cygwin-ug-net.xml + builddir=`pwd` \ + && cd $(srcdir) \ + && $(srcdir)/xidepend $^ > "$${builddir}/$@" + +-include Makefile.dep diff --git a/winsup/doc/Wishlist b/winsup/doc/Wishlist new file mode 100644 index 000000000..9e7aa4ca1 --- /dev/null +++ b/winsup/doc/Wishlist @@ -0,0 +1,111 @@ +- Change the '-' prefixes on Makefile.in commands to '@'. We only want + to avoid echoing the commands, not keep on trucking past build + errors. + +- Cygwin API docs update: + + - Either: + + - Convert existing SGML code embedded in Cygwin source code + to Doxygen format, then set up HTML and PDF reference manual + generation in doc/Makefile.in. Then, remove vestiges of doctool. + + The Cygwin User Manual reportedly references pieces of the + current SGML that makes up the API Manual, which if true means + we have a challenge to make the Doxygen process continue to feed + the user manual. + + - Or, move all SGML from winsup/cygwin into winsup/doc/api. + + - Current POSIX documentation is nonexistent. Either: + + - Fork the current POSIX/Linux manpages. Downside of this is that + it's in nroff format and the license demands that nroff sources + continue to be made available. This is a challenge for PDF + manual integration. + + - Switch to Doxygen, which lets us have skeletal POSIX docs almost + for free. Each can point to web docs for more complete info, such + that the Cygwin man pages only need to provide parameter lists and + document Cygwinisms in the implementation. + + - Write our own man pages in DocBook <refentry> form. Such files + should be XInclude-able in regular API/user manuals, and only have + to have the same mininal info as in the Doxygen case above. It + just requires a more verbose markup format. + +- Remove autotools outputs from repo. (configure, Makefile, etc.) + Create a bootstrap script to generate them. Make sure top-level + "make" process knows how to call the bootstrap script at need. + +- There are absolute HTTP <ulinks> which should be transformed to + relative links so that they do the right thing when you move the docs + around. Maybe they'll never live somewhere else on cygwin.com, but if + nothing else, they currently do the wrong thing when you open one of the + generated .html files from the local filesystem: hyperlinks take you off + to cygwin.com instead of to the relevant local file. + +- Convert remaining code snippets from HTML entity form (&, + <...) to raw C/C++ code in CDATA sections. Easier to read and + edit in XML form. + +- Pretty code snippets. Search for a DocBook aware automatic code + formatter that will take raw example code in and mark it up, as exists + for HTML. If one can't be found or created -- e.g. by lashing an HTML + code formatter to a sed script then whipping them until they sing -- do + the markup by hand. + +- Move to DocBook 5. + +- Files are often named with less detail than the ID of the top-level + XML element it contains. For example, specialnames.xml contains + <sect1 id="using-specialnames">. The ID scheme seems hierarchical, so + maybe the files should go into subdirectories; e.g. + using/specialnames.xml. This would help with the proliferation of files + this "patch" created. + +- "Tidy" the XML files. + +- Remove --skip-validation from XMLTO flags variable in Makefile.in, + then fix any errors and warnings that result. + +- Replace the hard-coded dates in <bookinfo><date> tags with DocBook + time stamps. (http://www.sagehill.net/docbookxsl/Datetime.html) + +- cygwin-ug-net/cygwin-ug-net-nochunks.html.gz build rules can probably + be reduced to a one-liner by moving from xmlto wrapper to a raw + xsltproc call. + +- Is xmlto pulling its own weight for the HTML case? It *might* have + some value for the PDF-via-dblatex case, but an xsltproc call for HTML + is also a one-liner. + +- Switch from xmlto/dblatex to xsltproc/FOP for PDF? Might be a + prerequisite to the font changes below if dblatex doesn't allow + one to specify fonts through the xmlto layer. + +- Typography improvements: curl all the quotation marks, replace "--" + with em dashes, check proper names for missing accents, etc. + +- Adapt top-level cygwin.com CSS to DocBook HTML output so the user + guide blends with the rest of the site. (Something like this has + been done to cygwin.com/faq.html already.) + +- Improve PDF styling: + + - Wider margins, section indenting, etc. (i.e. Fix the "wall of text" + problem.) + + - Current fonts are Business Blah at best. Most severe to least: + + - Courier for code is just plain ugly, and is apparently a bitmap + font in some people's PDF output besides. Switch to Deja Vu, + Inconsolata, or Adobe Source Code Pro. + + - Times. Sigh. There must be something better in the free world, + something more in the Palatino or Garamond mold. Bitstream Vera + Serif? Linux Libertine? + + - Arial/Helvetica/whatever. Not a serious issue, but we can do + better, even if it's just a minor shake-up, like switching to a + condensed face. diff --git a/winsup/doc/bodysnatcher.pl b/winsup/doc/bodysnatcher.pl new file mode 100755 index 000000000..1db30aad4 --- /dev/null +++ b/winsup/doc/bodysnatcher.pl @@ -0,0 +1,44 @@ +#!/usr/bin/perl -w +# Copyright © 2013 by Red Hat, Inc. +# +# This file is part of Cygwin. +# +# This software is a copyrighted work licensed under the terms of the +# Cygwin license. Please consult the file "CYGWIN_LICENSE" for +# details. + +use strict; + +if (@ARGV) { + my $infile = $ARGV[0]; + my $outfile = $infile; + $outfile =~ s/\.html$/.body/; + if ($infile ne $outfile) { + open my $input, '<', $infile or die "Failed to open $infile: $!\n"; + my $html = do { local $/; <$input> }; # slurp! + my ($body) = $html =~ m|<body[^>]*>(.*)</body>|is; + if ($body) { + open my $output, '>', $outfile + or die "Failed to write $outfile: $!\n"; + print $output $body; + } + else { + print STDERR "Could not find <body> element in $infile!\n\n"; + exit 3; + } + } + else { + print STDERR "Input file name must end in .html!\n\n"; + exit 2; + } +} +else { + print STDERR <<USAGE; +usage: $0 <input.html> + + Transforms input.html to input.body by extracting whatever is + between <body> and </body> in input.html. + +USAGE + exit 1; +} 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..3fee468dc 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 - +DOCTOOL-INSERT-legal </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.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 3a05e9ba3..a6d0eaac9 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> @@ -78,16 +82,27 @@ time and when handles are inherited. Defaults to set.</para> </listitem> <listitem> -<para><envar>(no)winsymlinks</envar> - if set, Cygwin creates -symlinks as Windows shortcuts with a special header and the R/O attribute -set. If not set, Cygwin creates symlinks as plain files with a magic number, -a path and the system attribute set. Defaults to not set since plain -file symlinks are faster to write and faster to read.</para> - -<para>Please note that symlinks created under Cygwin 1.7 or later are -not readable by older Cygwin releases because the new symlinks use UTF-16 -to encode the target filename, while the old symlinks used the current -ANSI or OEM charset.</para> +<para><envar>winsymlinks:{lnk,native,nativestrict}</envar> - if set to just +<literal>winsymlinks</literal> or <literal>winsymlinks:lnk</literal>, +Cygwin creates symlinks as Windows shortcuts with a special header and +the R/O attribute set.</para> + +<para>If set to <literal>winsymlinks:native</literal> or +<literal>winsymlinks:nativestrict</literal>, Cygwin creates symlinks as +native Windows symlinks on filesystems and OS versions supporting them. +If the OS is known not to support native symlinks (Windows XP, Windows +Server 2003), a warning message is produced once per session.</para> + +<para>The difference between <literal>winsymlinks:native</literal> and +<literal>winsymlinks:nativestrict</literal> is this: If the filesystem +supports native symlinks and Cygwin fails to create a native symlink for +some reason, it will fall back to creating Cygwin default symlinks +with <literal>winsymlinks:native</literal>, while with +<literal>winsymlinks:nativestrict</literal> the <literal>symlink(2)</literal> +system call will immediately fail.</para> + +<para>For more information on symbolic links, see +<xref linkend="pathnames-symlinks"></xref>.</para> </listitem> </itemizedlist> 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 41a97f8b5..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> @@ -17,12 +21,9 @@ support the <literal>/?</literal> switch to display usage information. <para> Unfortunately, no standard set of tools included with all versions of -Windows exists. If you are unfamiliar with the tools available -on your system, here is a general guide. Windows 2000 has only a basic -set of tools, which later versions of Windows expanded. Microsoft also -provides free downloads for Windows 2000 (the Resource Kit Tools), and XP -(the Windows Support Tools). Generally, the younger the Windows version, -the more complete are the on-board tools. Additionally, many independent +Windows exists. Generally, the younger the Windows version, the more +complete are the on-board tools. Microsoft also provides free downloads +for Windows XP (the Windows Support Tools). Additionally, many independent sites such as <ulink url="http://download.com">download.com</ulink>, <ulink url="http://simtel.net">simtel.net</ulink>, @@ -85,8 +86,8 @@ If your system does not have an always-on network connection, you may be interested in <command>rasdial.exe</command> for automating dialup connections. Users who frequently change their network -configuration can script these changes with <command>netsh.exe</command> -(Windows 2000 and later). For proxy users, the open source +configuration can script these changes with <command>netsh.exe</command>. +For proxy users, the open source <ulink url="http://apserver.sourceforge.net"> NTLM Authorization Proxy Server</ulink> or the no-charge <ulink url="http://www.hummingbird.com/products/nc/socks/index.html"> 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 bfc27fac7..c01a127e6 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> @@ -48,6 +54,287 @@ package. Or compile with the <literal>-s</literal> option to gcc. </para> </answer></qandaentry> +<qandaentry id="faq.programming.64bitporting"> +<question><para>What do I have to look out for when porting applications to 64 bit Cygwin?</para></question> +<answer> + +<para>The Cygwin x86_64 toolchain is using the +<ulink url="http://en.wikipedia.org/wiki/LLP64#64-bit_data_models">LP64</ulink> +data model. That means, in contrast to Windows, which uses an +<ulink url="http://en.wikipedia.org/wiki/LLP64#64-bit_data_models">LLP64</ulink> +data model, sizeof(long) != sizeof(int), just as on Linux.</para> + +<para>For comparison:</para> + +<screen> + Cygwin Windows Cygwin + Linux x86_64 Linux + Windows x86_64 + i686 + +sizeof(int) 4 4 4 +sizeof(long) 4 4 8 +sizeof(size_t) 4 8 8 +sizeof(void*) 4 8 8 +</screen> + +<para>This difference can result in interesting problems, especially when +using Win32 functions, especially when using pointers to Windows +datatypes like LONG, ULONG, DWORD. Given that Windows is LLP64, all of +the aforementioned types are 4 byte in size, on 32 as well as on 64 bit +Windows, while `long' on 64 bit Cygwin is 8 bytes.</para> + +<para>Take the example ReadFile:</para> + +<screen> + ReadFile (HANDLE, LPVOID, DWORD, LPDWORD, LPOVERLAPPED); +</screen> + +<para>In the 32 bit Cygwin and Mingw environments, as well as in the 64 bit +Mingw environment, it is no problem to substitute DWORD with unsigned +long:</para> + +<screen> + unsigned long number_of_bytes_read; + [...] + ReadFile (fhdl, buf, buflen, &number_of_bytes_read, NULL); +</screen> + +<para>However, in 64 bit Cygwin, using LP64, number_of_bytes_read is 8 bytes +in size. But since ReadFile expects a pointer to a 4 byte type, the function +will only change the lower 4 bytes of number_of_bytes_read on return, while +the content of the upper 4 bytes stays undefined.</para> + +<para>Here are a few <emphasis>donts</emphasis> which should help porting +applications from the known ILP32 data model of 32 bit Cygwin, to the LP64 +data model of 64 bit Cygwin. Note that these are not Cygwin-only problems. +Many Linux applications suffered the same somewhat liberal handling of +datatypes when the AMD64 CPU was new.</para> + +<itemizedlist mark="bullet"> + +<listitem><para> +<emphasis>Don't</emphasis> mix up int and long in printf/scanf. This: + +<screen> + int i; long l; + printf ("%d %ld\n", l, i); +</screen> + +may not print what you think it should. Enable the gcc options -Wformat or +-Wall, which warn about type mismatches in printf/scanf functions. + +<note>Using -Wall (optionally with -Werror to drive the point home) makes a +lot of sense in general, not only when porting code to a new platform.</note> +</para></listitem> + +<listitem><para> +<emphasis>Don't</emphasis> mix int and long pointers. + +<screen> + long *long_ptr = (long *) &my_int; /* Uh oh! */ + *long_ptr = 42; +</screen> + +The assignment will write 8 bytes to the address of my_int. Since my_int +is only 4 bytes, <emphasis>something else</emphasis> gets randomly overwritten. +Finding this kind of bug is very hard, because you will often see a problem +which has no immediate connection to the actual bug. +</para></listitem> + +<listitem><para> +<emphasis>Don't</emphasis> mix int and pointers at all! This will +<emphasis>not</emphasis> work as expected anymore: + +<screen> + void *ptr; + printf ("Pointer value is %x\n", ptr); +</screen> + +%x denotes an int argument. The value printed by printf is a 4 byte value, +so on x86_64 the printed pointer value is missing its upper 4 bytes; the output +is very likely wrong. Use %p instead, which portable across architectures: + +<screen> + void *ptr; + printf ("Pointer value is %p\n", ptr); +</screen> +</para></listitem> + +<listitem><para> +Along the same lines <emphasis>don't</emphasis> use the type int in +pointer arithmetic. Don't cast pointers to int, don't cast pointer +differences to int, and don't store pointer differences in an int type. +Use the types <literal>intptr_t</literal>, <literal>uintptr_t</literal> +and <literal>ptrdiff_t</literal> instead, they are designed for performing +architecture-independent pointer arithmetic. +</para></listitem> + +<listitem><para> +<emphasis>Don't</emphasis> make blind assumptions about the size of a POSIX +type. For instance, <literal>time_t</literal> is 8 bytes on 64 bit Cygwin, +while it is (still, at the time of writing this) 4 bytes on 32 bit Cygwin, +since time_t is based on the type long. +</para></listitem> + +<listitem><para> +<emphasis>Don't</emphasis> use functions returning pointers without declaration. +For instance + +<screen> + printf ("Error message is: %s\n", strerror (errno)); +</screen> + +This code will <emphasis>crash</emphasis>, unless you included +<filename>string.h</filename>. The implicit rule in C is that an undeclared +function is of type int. But int is 4 byte and pointers are 8 byte, so the +string pointer given to printf is missing the upper 4 bytes. +</para></listitem> + +<listitem><para> +<emphasis>Don't</emphasis> use C base types together with Win32 functions. +Keep in mind that DWORD, LONG, ULONG are <emphasis>not</emphasis> the same +as long and unsigned long. Try to use only Win32 datatypes in conjunction +with Win32 API function calls to avoid type problems. See the above +ReadFile example. Windows functions in printf calls should be treated +carefully as well. This code is common for 32 bit code, but probably prints +the wrong value on 64 bit: + +<screen> + printf ("Error message is: %lu\n", GetLastError ()); +</screen> + +Using gcc's -Wformat option would warn about this. Casting to the requested +base type helps in this case: + +<screen> + printf ("Error message is: %lu\n", (unsigned long) GetLastError ()); +</screen> +</para></listitem> + +<listitem><para> +<emphasis>Don't</emphasis> mix Windows datatypes with POSIX type-specific +MIN/MAX values. + +<screen> + unsigned long l_max = ULONG_MAX; /* That's right. */ + ULONG w32_biggest = ULONG_MAX; /* Hey, wait! What? */ + ULONG w32_biggest = UINT_MAX; /* Ok, but borderline. */ +</screen> + +Again, keep in mind that ULONG (or DWORD) is <emphasis>not</emphasis> unsigned +long but rather unsigned int on 64 bit. +</para></listitem> + +</itemizedlist> + +</answer></qandaentry> + +<qandaentry id="faq.programming.64bitporting-fail"> +<question><para>My project doesn't build at all on 64 bit Cygwin. What's up?</para></question> +<answer> + +<para>Typically reasons for that are:</para> + +<itemizedlist mark="bullet"> + +<listitem><para><literal>__CYGWIN32__</literal> is not defined in the +64 bit toolchain. This may hit a few projects which are around since before +Y2K. Check your project for occurences of <literal>__CYGWIN32__</literal> +and change them to <literal>__CYGWIN__</literal>, which is defined in the +Cygwin toolchain since 1998, to get the same Cygwin-specific code changes done. +</para></listitem> + +<listitem><para>The project maintainers took it for granted that Cygwin is +running only on i686 CPUs and the code is making this assumption blindly. +You have to check the code for such assumptions and fix them. +</para></listitem> + +<listitem><para>The project is using autotools, the +<filename>config.sub</filename> and <filename>config.guess</filename> files +are hopelessly outdated and don't recognize +<literal>x86_64-{pc,unknown}-cygwin</literal> as valid target. Update the +project configury (cygport will do this by default) and try again. +</para></listitem> + +<listitem><para>The project uses Windows functions on Cygwin and it's suffering +from the problems described in the preceeding FAQ entry. +</para></listitem> + +</itemizedlist> + +<para>In all of this cases, please make sure to fix that upstream, or send +your patches to the upstream maintainers, so the problems get fixed for the +future.</para> + +</answer></qandaentry> + +<qandaentry id="faq.programming.64bitporting-cygwin64"> +<question><para>Why is __CYGWIN64__ not defined for 64 bit?</para></question> +<answer> + +<para>There is no <literal>__CYGWIN64__</literal> because we would like to +have a unified way to handle Cygwin code in portable projects. Using +<literal>__CYGWIN32__</literal> and <literal>__CYGWIN64__</literal> only +complicates the code for no good reason. Along the same lines you won't +find predefined macros <literal>__linux32__</literal> and +<literal>__linux64__</literal> on Linux.</para> + +<para>If you really have to differ between 32 and 64 bit in some way, you have +three choices.</para> + +<itemizedlist mark="bullet"> + +<listitem><para>If your code depends on the CPU architecture, use the +predefined compiler definition for the architecture, like this:</para> + +<screen> +#ifdef __CYGWIN__ +# ifdef __x86_64__ /* Alternatively __x86_64, __amd64__, __amd64 */ + /* Code specific for AMD64 CPU */ +# elif __X86__ + /* Code specific for ix86 CPUs */ +# else +# error Unsupported Architecture +# endif +#endif +</screen></listitem> + +<listitem><para>If your code depends on differences in the data model, you +should consider to use the <literal>__LP64__</literal> definition +instead:</para> + +<screen> +#ifdef __CYGWIN__ +# ifdef __LP64__ /* Alternatively _LP64 */ + /* Code specific for 64 bit CPUs */ +# else + /* Code specific for 32 bit CPUs */ +# endif +#endif +</screen></listitem> + +<listitem><para>If your code uses Windows functions, and some of the +functionality is 64 bit Windows-specific, use <literal>_WIN64</literal>, +which is defined on 64 bit Cygwin, as soon as you include +<filename>windows.h</filename>. This should only be used in the most +desperate of occasions, though, and <emphasis>only</emphasis> if it's +really about a difference in Windows API functionality!</para> + +<screen> +#ifdef __CYGWIN__ +# ifdef _WIN64 + /* Code specific for 64 bit Windows */ +# else + /* Code specific for 32 bit Windows */ +# endif +#endif +</screen></listitem> + +</itemizedlist> + +</answer></qandaentry> + <qandaentry id="faq.programming.glibc"> <question><para>Where is glibc?</para></question> <answer> @@ -62,7 +349,7 @@ would be difficult. <question><para>Where is Objective C?</para></question> <answer> -<para>Support for compiling Objective C is available in the <literal>gcc4-objc</literal> +<para>Support for compiling Objective C is available in the <literal>gcc{4}-objc</literal> package; resulting binaries will depend on the <literal>libobjc2</literal> package at runtime. </para> @@ -72,10 +359,8 @@ package at runtime. <question><para>Why does my make fail on Cygwin with an execvp error? </para></question> <answer> -<para>First of all, if you are using <literal>make -j[N]</literal>, then stop. It doesn't -work well. Also beware of using non-portable shell features in your -Makefiles (see tips at <ulink -url="http://cygwin.com/faq/faq.using.html#faq.using.shell-scripts" />). +<para>Beware of using non-portable shell features in your Makefiles (see tips +at <ulink url="http://cygwin.com/faq/faq.html#faq.using.shell-scripts" />). </para> <para>Errors of <literal>make: execvp: /bin/sh: Illegal Argument</literal> or <literal>make: execvp: /bin/sh: Argument list too long</literal> are often @@ -461,7 +746,7 @@ recommend trying the latest snapshot from <ulink url="http://cygwin.com/snapshots/" /> or building the DLL from CVS. </para> <para>To build a debugging version of the Cygwin DLL, you will need to follow -the instructions at <ulink url="http://cygwin.com/faq/faq-nochunks.html#faq.programming.building-cygwin" />. +the instructions at <ulink url="http://cygwin.com/faq/faq.html#faq.programming.building-cygwin" />. You can also contact the mailing list for pointers (a simple test case that demonstrates the bug is always welcome). </para> @@ -681,15 +966,6 @@ This is right <literal>gcc hello.cc -lstdc++</literal>. use <literal>struct stat</literal>. It's 64 bit aware.</para> </answer></qandaentry> -<qandaentry id="faq.programming.undeclared-functions"> -<question><para>I use a function I know is in the API, but I still get a link error.</para></question> -<answer> - -<para>The function probably isn't declared in the header files, or -the UNICODE stuff for it isn't filled in. -</para> -</answer></qandaentry> - <qandaentry id="faq.programming.libc"> <question><para>Can you make DLLs that are linked against libc ?</para></question> <answer> @@ -758,17 +1034,6 @@ data types, line numbers, local variables etc. </para> </answer></qandaentry> -<qandaentry id="faq.programming.x86-assembly"> -<question><para>Where can I find info on x86 assembly?</para></question> -<answer> - -<para>CPU reference manuals for Intel's current chips are available in -downloadable PDF form on Intel's web site: -</para> -<para><ulink url="http://developer.intel.com/">http://developer.intel.com/</ulink> -</para> -</answer></qandaentry> - <qandaentry id="faq.programming.make-scripts"> <question><para>Shell scripts aren't running properly from my makefiles?</para></question> <answer> @@ -849,18 +1114,4 @@ linker flag.</para></listitem> </orderedlist></listitem></orderedlist> </answer></qandaentry> -<qandaentry id="faq.programming.djgpp"> -<question><para>Why not use DJGPP ?</para></question> -<answer> - -<para>DJGPP is a similar idea, but for DOS instead of Win32. DJGPP uses a -"DOS extender" to provide a more reasonable operating interface for its -applications. The Cygwin toolset doesn't have to do this since all of -the applications are native WIN32. Applications compiled with the -Cygwin tools can access the Win32 API functions, so you can write -programs which use the Windows GUI. -</para> -<para>You can get more info on DJGPP by following -<ulink url="http://www.delorie.com/">http://www.delorie.com/</ulink>. -</para></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..8339b61f3 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> @@ -180,7 +187,7 @@ disk if you are paranoid. <para>This should be safe, but only if Cygwin Setup is not substituted by something malicious, and no mirror has been compromised. </para> -<para>See also <ulink url="http://cygwin.com/faq/faq.using.html#faq.using.bloda" /> +<para>See also <ulink url="http://cygwin.com/faq/faq.html#faq.using.bloda" /> for a list of applications that have been known, at one time or another, to interfere with the normal functioning of Cygwin. </para> @@ -452,7 +459,7 @@ of Cygwin is as follows: <orderedlist> <listitem><para>If you have any Cygwin services running, remove by repeating the instructions in <ulink -url="http://cygwin.com/faq/faq.setup.html#faq.setup.uninstall-service" /> for +url="http://cygwin.com/faq/faq.html#faq.setup.uninstall-service" /> for all services that you installed. Common services that might have been installed are <literal>sshd</literal>, <literal>cron</literal>, <literal>cygserver</literal>, <literal>inetd</literal>, <literal>apache</literal>, @@ -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 f478d84b6..36c898014 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> @@ -621,7 +628,7 @@ of poorly written firewall-type software that causes things to break. Note that with many of these products, simply disabling the firewall does not remove these changes; it must be completely uninstalled. </para> -<para>See also <ulink url="http://cygwin.com/faq/faq.using.html#faq.using.bloda" /> +<para>See also <ulink url="http://cygwin.com/faq/faq.html#faq.using.bloda" /> for a list of applications that have been known, at one time or another, to interfere with the normal functioning of Cygwin. </para> @@ -771,7 +778,7 @@ contents are exempt from scanning. In a default installation, this would be <literal>C:\cygwin\bin</literal>. Obviously, this could be exploited by a hostile non-Cygwin program, so do this at your own risk. </para> -<para>See also <ulink url="http://cygwin.com/faq/faq.using.html#faq.using.bloda" /> +<para>See also <ulink url="http://cygwin.com/faq/faq.html#faq.using.bloda" /> for a list of applications that have been known, at one time or another, to interfere with the normal functioning of Cygwin. </para> @@ -1101,10 +1108,6 @@ IPv6-capable and that's why you see the "Address family not supported" error message. Note, however, that the IPv6 stack on these systems don't fully support all features of IPv6.</para> -<para>There's also a very experimental IPv6 stack for Windows 2000, and -Cygwin will try its best to support it, but it's not recommended to install -it.</para> - <para>For more information about IPv6 on Windows and how to install the IPv6 stack, see the <ulink url="http://www.microsoft.com/technet/network/ipv6/ipv6faq.mspx">Microsoft TechNet IPv6 FAQ article</ulink> </para></answer></qandaentry> @@ -1247,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 ff1134042..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> @@ -26,13 +33,12 @@ sad reason. <question><para>What versions of Windows are supported?</para></question> <answer> -<para>Cygwin can be expected to run on all modern 32 bit versions of -Windows This includes, as of the time of writing this, Windows 2000, -Windows XP, Windows Server 2003, Windows Vista, Windows Server 2008, -Windows 7, Windows Server 2012, Windows 8, as well as the WOW64 32 bit +<para>Cygwin can be expected to run on all modern versions of Windows. +This includes, as of the time of writing this, Windows XP SP3, Windows +Server 2003, Windows Vista, Windows Server 2008, Windows 7, Windows +Server 2012, Windows 8. The 32 bit version also runs in the WOW64 32 bit environment on released 64 bit versions of Windows (XP/2003/Vista/2008/7/2008 R2/8/2012). -A native 64 bit Cygwin version is in the works. Since Cygwin is a community-supported free software project, patches to provide support for other versions would be thoughtfully considered. Paid support contracts or enhancements are available through Red Hat. For @@ -153,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..5de789a8c 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> @@ -204,30 +113,9 @@ supporting that. Since Windows XP, the OS only supports case sensitivity when a specific registry value is changed. Therefore, case sensitivity is not usually the default.</para> -<para>Symbolic links are not present and supported on Windows up to and -including Windows Server 2003 R2. Native symlinks are available starting -with Windows Vista. Due to their strange implementation, however, -they are not useful in a POSIX emulation layer. Cygwin recognizes -native symlinks, but does not create them.</para> - -<para>Symbolic links are potentially created in two different ways. -The file style symlinks are files containing a magic cookie followed by -the path to which the link points. They are marked with the System DOS -attribute so that only files with that attribute have to be read to -determine whether or not the file is a symbolic link. The shortcut style -symlinks are Windows shortcut files with a special header and the -Readonly DOS attribute set. The advantage of file symlinks is speed, -the advantage of shortcut symlinks is the fact that they can be utilized -by non-Cygwin Win32 tools as well.</para> - -<para>Starting with Cygwin 1.7, symbolic links are using UTF-16 to encode -the filename of the target file, to better support internationalization. -Symlinks created by older Cygwin releases can be read just fine. However, -you could run into problems with them if you're now using another character -set than the one you used when creating these symlinks -(see <xref linkend="setup-locale-problems"></xref>. Please note that this -new UTF-16 style of symlinks is not compatible with older Cygwin release, -which can't read the target filename correctly.</para> +<para>Cygwin supports creating and reading symbolic links, even on Windows +filesystems and OS versions which don't support them. +See <xref linkend="pathnames-symlinks"></xref> for details.</para> <para>Hard links are fully supported on NTFS and NFS file systems. On FAT and other file systems which don't support hardlinks, the call returns with @@ -383,7 +271,7 @@ location, Cygwin can do nothing to compensate (though it will retry a few times automatically).</listitem> <listitem>DLL injection by -<ulink url="http://cygwin.com/faq/faq.using.html#faq.using.bloda"> +<ulink url="http://cygwin.com/faq/faq.html#faq.using.bloda"> BLODA</ulink>. Badly-behaved applications which inject dlls into other processes often manage to clobber important sections of the child's address space, leading to base address 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 ab0e452d1..8ae6858bf 100644 --- a/winsup/doc/new-features.sgml +++ b/winsup/doc/new-features.xml @@ -1,5 +1,45 @@ +<?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> + +<itemizedlist mark="bullet"> + +<listitem><para> +Drop support for Windows 2000 and Windows XP pre-SP3. +</para></listitem> + +<listitem><para> +Add support for building a 64 bit version of Cygwin on x86_64 natively. +</para></listitem> + +<listitem><para> +Add support for creating native NTFS symlinks starting with Windows Vista +by setting the CYGWIN=winsymlinks:native or CYGWIN=winsymlinks:nativestrict +option. +</para></listitem> + +<listitem><para> +Add support for AFS filesystem. +</para></listitem> + +<listitem><para> +Preliminary support for mandatory locking via fcntl/flock/lockf, using Windows +locking semantics. New F_LCK_MANDATORY fcntl command. +</para></listitem> + +<listitem><para> +New APIs: __b64_ntop, __b64_pton, arc4random, arc4random_addrandom, +arc4random_buf, arc4random_stir, arc4random_uniform. +</para></listitem> + +</itemizedlist> + +</sect2> + <sect2 id="ov-new1.7.18"><title>What's new and what changed from 1.7.17 to 1.7.18</title> <itemizedlist mark="bullet"> diff --git a/winsup/doc/ntsec.sgml b/winsup/doc/ntsec.xml index 8804cceac..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 @@ -497,7 +501,7 @@ OthersAllow: 110 </screen> <para>Again: This works on all existing versions of Windows NT, at the -time of writing from at least Windows 2000 up to Server 2008 R2. Only +time of writing from at least Windows XP up to Server 2012. Only the GUIs aren't able (or willing) to deal with that order.</para> </sect2> @@ -507,9 +511,9 @@ the GUIs aren't able (or willing) to deal with that order.</para> <para>Since Windows XP, Windows users have been accustomed to the "Switch User" feature, which switches the entire desktop to another user while leaving the original user's desktop "suspended". Another Windows -feature (since Windows 2000) is the "Run as..." context menu entry, -which allows you to start an application using another user account when -right-clicking on applications and shortcuts.</para> +feature is the "Run as..." context menu entry, which allows you to start +an application using another user account when right-clicking on applications +and shortcuts.</para> <para>On POSIX systems, this operation can be performed by processes running under the privileged user accounts (usually the "root" user 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 3dce16707..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> @@ -8,7 +13,7 @@ Cygwin is a Linux-like environment for Windows. It consists of a DLL providing substantial <ulink url="http://www.pasc.org/#POSIX">POSIX</ulink> (Portable Operating System Interface) system call functionality, and a collection of tools, which provide a Linux look and feel. The Cygwin DLL -works with all x86 and AMD64 versions of Windows NT since Windows 2000. +works with all x86 and AMD64 versions of Windows NT since Windows XP SP3. The API follows the <ulink url="http://www.opengroup.org/onlinepubs/009695399/nfindex.html">Single Unix Specification</ulink> as much as possible, and then Linux practice. @@ -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> @@ -108,15 +113,19 @@ have seen continuous development. </para> <para> -The latest major improvement in this development is the 1.7 release in +The biggest major improvement in this development is the 1.7 release in 2009, which dropped Windows 95/98/Me support in favor of using Windows NT features more extensively. It adds a lot of new features like case-sensitive filenames, NFS interoperability, IPv6 support and much more.</para> +<para>The latest big improvement is the 64 bit Cygwin DLL which +allows to run natively on AMD64 Windows machines. The first release +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 96b0077af..3647253e2 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> @@ -351,6 +355,81 @@ the cygdrive prefix, use a distinct path prefix:</para> </sect2> +<sect2 id="pathnames-symlinks"><title>Symbolic links</title> + +<para>Symbolic links are not present and supported on Windows until Windows +Vista/Server 2008, and then only on some filesystems. Since POSIX applications +are rightfully expecting to use symlinks and the +<literal>symlink(2)</literal> system call, Cygwin had to find a +workaround for this Windows flaw.</para> + +<para>Cygwin creates symbolic links potentially in multiple different +ways:</para> + +<itemizedlist mark="bullet"> + +<listitem> +<para>The default symlinks are plain files containing a magic cookie +followed by the path to which the link points. They are marked with the +DOS SYSTEM attribute so that only files with that attribute have to be +read to determine whether or not the file is a symbolic link.</para> + +<note><para>Starting with Cygwin 1.7, symbolic links are using UTF-16 to encode +the filename of the target file, to better support internationalization. +Symlinks created by older Cygwin releases can be read just fine. However, +you could run into problems with them if you're now using another character +set than the one you used when creating these symlinks +(see <xref linkend="setup-locale-problems"></xref>). Please note that this +new UTF-16 style of symlinks is not compatible with older Cygwin release, +which can't read the target filename correctly.</para></note> +</listitem> + +<listitem> +<para>The shortcut style symlinks are Windows <literal>.lnk</literal> +shortcut files with a special header and the DOS READONLY attribute set. +This symlink type is created if the environment variable +<literal>CYGWIN</literal> (see <xref linkend="using-cygwinenv"></xref>) +is set to contain the string <literal>winsymlinks</literal> or +<literal>winsymlinks:lnk</literal>. On the MVFS filesystem, which does +not support the DOS SYSTEM attribute, this is the one and only supported +symlink type, independently from the <literal>winsymlinks</literal> +setting.</para> +</listitem> + +<listitem> +<para>Native Windows symlinks are only created on Windows Vista/2008 and later, +and only on filesystems supporting reparse points. Due to to their weird +restrictions and behaviour, they are only created if the user +explicitely requests creating them. This is done by setting the +environment variable <literal>CYGWIN</literal> to contain the string +<literal>winsymlinks:native</literal> or +<literal>winsymlinks:nativestrict</literal>. For the difference between +these two settings, see <xref linkend="using-cygwinenv"></xref>. +On AFS, native symlinks are the only supported type of symlink due to +AFS lacking support for DOS attributes. This is independent from the +<literal>winsymlinks</literal> setting.</para> +</listitem> + +<listitem> +<para>On the NFS filesystem, Cygwin always creates real NFS symlinks.</para> +</listitem> + +</itemizedlist> + +<para>All of the above four symlink types are recognized and used as symlinks +under all circumstances. However, if the default plain file symlink type +is lacking its DOS SYSTEM bit, or if the shortcut file is lacking the DOS +READONLY attribute, they are not recognized as symlink.</para> + +<para>Apart from these four types, there's also a fifth type, which is +recognized as symlink but never generated by Cygwin, directory +junctions. This is an older reparse point type, supported by Windows +since Windows 2000. Filesystem junctions on the other hand are not +handled as symlinks, since otherwise they would not be recognized as +filesystem borders by commands like <command>find -xdev</command>.</para> + +</sect2> + <sect2 id="pathnames-win32"><title>Using native Win32 paths</title> <para>Using native Win32 paths in Cygwin, while possible, is generally @@ -489,522 +568,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. For least surprise, Cygwin expects -this registry value also on Windows 2000, which usually doesn't know this -registry key. If you want case-sensitivity on Windows 2000, just create -that registry value and set it to 0. <emphasis role='bold'>Only</emphasis> -on Windows 2000 you don't have to reboot to bring it into effect, rather -stopping all Cygwin processes and then restarting them is sufficient.</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.sgml deleted file mode 100644 index 1ba28abb5..000000000 --- a/winsup/doc/setup.sgml +++ /dev/null @@ -1,47 +0,0 @@ -<chapter id="setup"><title>Setting Up Cygwin</title> - -<sect1><title>Cygwin Contents</title> - -<para>The following packages are included in the native Win32 -release of GNUPro:</para> - -<para>GNUPro development tools: binutils, bison, byacc, dejagnu, -diff, expect, flex, gas, gcc, gdb, itcl, ld, libstdc++, make, patch, -tcl, tix, tk</para> - -<para>GNUPro unsupported tools: ash, bash, bzip2, diff, fileutils, -findutils, gawk, grep, gzip, m4, sed, shellutils, tar, textutils, -time</para> - -</sect1> - -<sect1 id="installing-binaries"><title>Installing the binary release</title> - -<para>Load the GNUPro CD-ROM and run the installer. It will -take you through the installation process, starting with asking for -your install location. Once the installation is complete, there will -be a new Program Files folder that you can use to obtain a shell -from which you can run the tools.</para> - -<para>There are two remaining thing you should do from this -prompt. First, you need to type <command>mkdir -p /tmp</command> to -ensure that a temp directory exists for programs that expect to find -one there.</para> - -<para>Second, depending on how you intend to use the tools, various -programs may need to be able to find `/bin/sh'. You should `mkdir -p -/bin' and put a copy of `sh.exe' there, removing the older version, if -present. Note that you can use the `mount' utility to select which -drive letter is mounted as `/'.</para> - -<para>If you should ever want to uninstall the tools, you may do so -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 -</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/doc/xidepend b/winsup/doc/xidepend new file mode 100755 index 000000000..2a1fc831d --- /dev/null +++ b/winsup/doc/xidepend @@ -0,0 +1,34 @@ +#!/bin/sh +if [ "$1" = "-r" ] +then + # We're being called recursively by another xidepend instance, so + # suppress outputs that only happen at the top level. + shift + subproc=1 +else + subproc=0 +fi + +for f in "$@" +do + if fgrep -q 'xi:include' "$f" + then + # This file uses XIncludes. Let's chase its deps recursively. + base=`basename "$f" .xml` + if [ $subproc -eq 0 ] ; then echo -n "$base/$base.html:" ; fi + + deps=`grep 'xi:include.*href' "$f" | cut -f2 -d\" | tr '\n' ' '` + echo -n " $deps" + for d in $deps + do + # Call ourselves recursively to continue to collect deps. + # The -r flag tells our subprocess that it is merely + # contributing to a dependency line in progress. + $0 -r $d + done + + # If we're at the top recursion level, we have nothing else to + # add to this dependency line other than the newline. + if [ $subproc -eq 0 ] ; then echo ; fi + fi +done |