diff options
Diffstat (limited to 'winsup/doc')
| -rw-r--r-- | winsup/doc/.cvsignore | 14 | ||||
| -rw-r--r-- | winsup/doc/ChangeLog | 173 | ||||
| -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 | 18 | ||||
| -rw-r--r-- | winsup/doc/faq-what.xml | 24 | ||||
| -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, 2103 insertions, 1449 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..024abbe00 100644 --- a/winsup/doc/ChangeLog +++ b/winsup/doc/ChangeLog @@ -1,3 +1,176 @@ +2013-06-05 Corinna Vinschen <corinna@vinschen.de> + + * faq-copyright.xml: Fix link to license. + * faq-using.xml: Ditto. + * faq-what.xml: Ditto. + +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..95abaa2b4 --- /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/licensing.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..1a0727ff6 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> @@ -432,7 +439,7 @@ Can I bundle Cygwin with my product for free? </para></question> <answer><para> Only if you comply with Cygwin's <ulink -url="http://cygwin.com/license.html">license</ulink> very carefully. If you +url="http://cygwin.com/licensing.html">license</ulink> very carefully. If you choose to distribute cygwin1.dll, you must be willing to distribute the exact source code used to build that copy of cygwin1.dll as per the terms of the GPL. If you ship applications that link with cygwin1.dll, @@ -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..6960c687e 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,18 +33,17 @@ 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 information about getting a Red Hat support contract, see -<ulink url="http://cygwin.com/license.html" />. +<ulink url="http://cygwin.com/licensing.html" />. </para> <para>Keep in mind that Cygwin can only do as much as the underlying OS supports. Because of this, Cygwin will behave differently, and @@ -79,7 +85,7 @@ these tools. <para>In particular, if you intend to port a proprietary (non-GPL'd) application using Cygwin, you will need the proprietary-use license for the Cygwin library. This is available for purchase from Red Hat; -please visit <ulink url="http://cygwin.com/license.html" /> for more +please visit <ulink url="http://cygwin.com/licensing.html" /> for more information. All other questions should be sent to the public project mailing list cygwin@cygwin.com. </para> @@ -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 |