diff options
Diffstat (limited to 'winsup/doc')
40 files changed, 0 insertions, 9822 deletions
diff --git a/winsup/doc/ChangeLog b/winsup/doc/ChangeLog deleted file mode 100644 index 2f33669cf..000000000 --- a/winsup/doc/ChangeLog +++ /dev/null @@ -1,656 +0,0 @@ -2006-03-13 Christopher Faylor <cgf@timesys.com> - - * cygwinenv.sgml: Explain about new fork_retry CYGWIN environment - variable setting. - -2006-03-07 Bas van Gompel <cygwin-patch.buzz<at>bavag.tmfweb.nl> - - * cygwinenv.sgml: Add missing </para> at transparent_exe. - -2006-02-05 Corinna Vinschen <corinna@vinschen.de> - - * cygwinenv.sgml: Explain transparent_exe option. - -2006-02-01 Joshua Daniel Franklin <joshuadfranklin@yahoo.com> - - * faq-setup.xml (faq.setup.what-packages): - Mention new cygcheck -p option. - -2006-01-27 Joshua Daniel Franklin <joshuadfranklin@yahoo.com> - - * faq-programming.xml (faq.programming.building-cygwin): - Move cocom to the build requirements. - -2006-01-26 Joshua Daniel Franklin <joshuadfranklin@yahoo.com> - - * faq-programming.xml (faq.programming.building-cygwin): - Simplify instructions, and remove tar usage basics. - -2006-01-26 Joshua Daniel Franklin <joshuadfranklin@yahoo.com> - - * faq-programming.xml (faq.programming.ipc): Add new FAQ about - cygserver and its relation to the "Bad system call" error. - * faq-setup.xml (faq.setup.uninstall-all): Mention postgresql. - * overview2.sgml: Update security info on shared memory. - -2006-01-25 Joshua Daniel Franklin <joshuadfranklin@yahoo.com> - - * faq-programming.xml (faq.programming.building-cygwin): Add - list of packages required for building and exact check instructions. - * faq-setup.xml (faq.setup.uninstall-service): New instructions - on uninstalling a cygwin service. - (faq.setup.uninstall-all): Reference new service uninstall FAQ. - -2006-01-25 Igor Peshansky <pechtcha@cs.nyu.edu> - - * faq-setup.xml (faq.setup.snapshots): Rename DLL using Windows tools. - -2006-01-18 Joshua Daniel Franklin <joshuadfranklin@yahoo.com> - - * Makefile.in : Remove references to old texinfo FAQ. - * calls.texinfo : Remove. - * changes.texinfo : Remove. - * copy.texinfo : Remove. - * faq.texinfo : Remove. - * history.texinfo : Remove. - * how-api.texinfo : Remove. - * how-programming.texinfo : Remove. - * how-resources.texinfo : Remove. - * how-using.texinfo : Remove. - * how.texinfo : Remove. - * install.texinfo : Remove. - * readme.texinfo : Remove. - * relnotes.texinfo : Remove. - * what.texinfo : Remove. - * who.texinfo : Remove. - -2006-01-12 Igor Peshansky <pechtcha@cs.nyu.edu> - - * doctool.c (scan_directory): Ignore "CVS" directories. - * faq-setup.xml (faq.setup.setup): Correct URL typo. - (faq.setup.snapshots): Clarify. - -2005-12-30 Christopher Faylor <cgf@timesys.com> - - * relnotes.texinfo: Remove entry about hyperthreaded processor. - -2005-12-30 Christopher Faylor <cgf@timesys.com> - - * faq-problems.html: Remove entry about hyperthreaded processor. - -2005-12-12 Joshua Daniel Franklin <joshuadfranklin@yahoo.com> - - * faq-programming.xml: Add note about struct stat64. - -2005-12-03 Joshua Daniel Franklin <joshuadfranklin@yahoo.com> - - * faq-setup.xml: Add note about clean_setup.pl. - * faq-using.xml: Remove unnecessary line of elisp. - -2005-10-02 Joshua Daniel Franklin <joshuadfranklin@yahoo.com> - - * faq-what.xml: Add 2003 and WOW64 to "supported" FAQ. - * faq-programming.xml: Fix cygexec FAQ, building link. - -2005-09-25 Joshua Daniel Franklin <joshuadfranklin@yahoo.com> - - * faq.xml: Remove copyright section, link to license.html - * faq-sections.xml: Remove copyright section, link to license.html - * faq-programming.xml: Remove confusing reference to Red Hat. - * faq-what.xml: Reword "supported" FAQ. - -2005-09-15 Corinna Vinschen <corinna@vinschen.de> - - * cygwinenv.sgml (ntea): Add some wording to scare people away - from using this option. - -2005-08-26 Brian Dessent <brian@dessent.net> - - * faq-using.xml: Add 'net use' hint to network shares FAQ. - -2005-08-26 Joshua Daniel Franklin <joshuadfranklin@yahoo.com> - - * Makefile.in: Remove extra anchor to make NN4 happy. - * faq.xml: Link to cygwin.com/license.html - * faq-resources.xml: Link instead of duplicating info. - * faq-using.xml: Split out services and network shares FAQ. - * faq-what.xml: Link to cygwin.com/license.html - -2005-08-17 Christopher Faylor <cgf@timesys.com> - - * textbinary.sgml: Correct incorrect information about ability to - specify text mode in fopen(). - -2005-08-05 Joshua Daniel Franklin <joshuadfranklin@yahoo.com> - - * cygwin.dsl: Add default DOCTYPE and output filename. - * Makefile: Update to switch FAQ from texinfo to DocBook. - * faq.xml: New file. - * faq-api.xml: New file. - * faq-problems.xml: New file. - * faq-programming.xml: New file. - * faq-resources.xml: New file. - * faq-sections.xml: New file. - * faq-setup.xml: New file. - * faq-using.xml: New file. - * faq-what.xml: New file. - -2005-07-10 Joshua Daniel Franklin <joshuadfranklin@yahoo.com> - - * cygwinenv.sgml: Update tty section to mention rxvt and xterm. - * how-programming.texinfo: Update GPL section of CVS FAQ. - * how-using.texinfo: Expand FAQ about out of date packages. - * setup-net.sgml: Add troubleshooting setup.exe section. - -2005-07-08 Corinna Vinschen <corinna@vinschen.de> - - * how-using.texinfo: Fix typos. - -2005-06-20 Joshua Daniel Franklin <joshuadfranklin@yahoo.com> - - * how-resources.texinfo: Update section on cygwin-developers. - * how-using.texinfo: Add FAQ about firewall software. Update - section on mounting and specifically note using managed mounts. - -2005-06-03 Max Kaehn <slothman@electric-cloud.com> - - * how-programming.texinfo: Add "How do I load cygwin1.dll dynamically - from a Visual Studio or MinGW application?" - -2005-05-28 Joshua Daniel Franklin <joshuadfranklin@yahoo.com> - - * how-using.texinfo : Update the mkdir -p section to reflect - changes in handling network drives. - -2005-05-18 Brian Dessent <brian@dessent.net> - - * install.texinfo ("How do I uninstall..."): Rewrite to cover - removing services, dealing with permissions, and other common - tasks for removing Cygwin completely. - -2005-05-08 Joshua Daniel Franklin <joshuadfranklin@yahoo.com> - - * how-programming.texinfo: Replace MAKE_MODE entry with FAQ about - execvp errors and cygexec. - -2005-04-20 Brian Dessent <brian@dessent.net> - - * pathnames.sgml (mount-table): Indicate that user-specific - mounts override system-wide. - -2005-04-20 Gerd Spalink <Gerd.Spalink@t-online.de> - - * fhandler-tut.txt: Update description to cygwin 1.5.13 - -2005-04-19 Corinna Vinschen <corinna@vinschen.de> - - * cygwinenv.sgml: Mention that check_case is deprecated. - -2005-04-16 Corinna Vinschen <corinna@vinschen.de> - - * cygwinenv.sgml: Add new words for (no)traverse option. - -2005-03-30 Christopher Faylor <cgf@timesys.com> - - * how-using.texinfo: Add more words to the "multiple DLL" section. - -2005-03-25 Joshua Daniel Franklin <joshuadfranklin@yahoo.com> - - * how-programming.texinfo: Mention generic-build-script in - packaging FAQ. - -2005-03-19 Joshua Daniel Franklin <joshuadfranklin@yahoo.com> - - * how-programming.texinfo: Remove incorrect libm.a note. - -2005-03-05 Christopher Faylor <cgf@timesys.com> - - * pathnames.sgml: Clarify binmode/textmode behavior slightly. - * textbinary.sgml: Ditto. - -2005-03-03 Joshua Daniel Franklin <joshuadfranklin@yahoo.com> - - * how-api.texinfo: Add Pierre's security text. - -2005-02-23 Joshua Daniel Franklin <joshuadfranklin@yahoo.com> - - * README: New file. - -2005-01-31 Corinna Vinschen <corinna@vinschen.de> - - * cygwinenv.sgml: Add words for (no)traverse option. - -2005-01-29 Joshua Daniel Franklin <joshuadfranklin@yahoo.com> - - * install.texinfo: Update setup.exe snapshot URL. - * ntsec.sgml: Add Pierre's Windows 2003 text. - -2005-01-28 Corinna Vinschen <corinna@vinschen.de> - - * how-using.texinfo: Change text about using shortcuts. - -2005-01-22 Joshua Daniel Franklin <joshuadfranklin@yahoo.com> - - * how-api.texinfo: Make snapshot URL an HTML link. - * how-programming.texinfo: Add details about building a - debugging version of the DLL. - * how-using.texinfo: Correct rxvt README location. - * install.texinfo: Add mount -m note to uninstall instructions. - -2005-01-21 Christopher Faylor <cgf@timesys.com> - - * how-programming.texinfo: Remove obsolete w32api instructions and add - some words about unpacking net release .tar.bz2. - -2004-12-30 Joshua Daniel Franklin <joshuadfranklin@yahoo.com> - - * path.sgml: Encode programming example with CDATA. - * overview.sgml: Add notes about SUS, newlib, and ash. - * overview2.sgml: Add notes about /usr/share/doc/Cygwin. - -2004-12-27 Joshua Daniel Franklin <joshuadfranklin@yahoo.com> - - * Makefile.in: Update to use xmlto. - * cygwin.dsl: Change into DocBook XSL stylesheet for xmlto. - * pathnames.sgml: Correct documentation of mount behavior. - -2004-12-24 Joshua Daniel Franklin <joshuadfranklin@yahoo.com> - - * cygserver.sgml: Cleanup markup for XML validity. - * cygwin-api.in.sgml: Cleanup markup for XML validity. - * cygwin-ug-net.in.sgml: Cleanup markup for XML validity. - * cygwin-ug.in.sgml: Cleanup markup for XML validity. - * cygwinenv.sgml: Cleanup markup for XML validity. - * dll.sgml: Cleanup markup for XML validity. - * effectively.sgml: Cleanup markup for XML validity. - * filemodes.sgml: Cleanup markup for XML validity. - * legal.sgml: Cleanup markup for XML validity. - * ntsec.sgml: Cleanup markup for XML validity. - * overview.sgml: Cleanup markup for XML validity. - * overview2.sgml: Cleanup markup for XML validity. - * pathnames.sgml: Cleanup markup for XML validity. - * setup-net.sgml: Cleanup markup for XML validity. - * setup2.sgml: Cleanup markup for XML validity. - * textbinary.sgml: Cleanup markup for XML validity. - * utils.sgml: Cleanup markup for XML validity. - -2004-12-02 Joshua Daniel Franklin <joshuadfranklin@yahoo.com> - - * cygserver.sgml: Cleanup minor markup problem. - * how-resources.texinfo: Add man and info to documentation FAQ. - * how-using.texinfo: Add more detail to Unicode FAQ. - * install.texinfo: Finally apply Pierre's patch from 2003-03-03. - * relnotes.texinfo: Add note about hyperthreading reports. - -2004-09-30 Joshua Daniel Franklin <joshuadfranklin@yahoo.com> - - * how-using.texinfo: Fix typo. Add note about "Install For All Users" - -2004-09-30 Joshua Daniel Franklin <joshuadfranklin@yahoo.com> - - * how-programming.texinfo: Add gcj note to WinMain@16 FAQ. - * how-using.texinfo: Add FAQ about network shares and authentication. - * install.texinfo: Add "Where is make" to FAQ subtitle. - -2004-09-24 Corinna Vinschen <corinna@vinschen.de> - - * cygwinenv.sgml: smbntsec is not on by default. - -2004-09-14 Christopher Faylor <cgf@timesys.com> - - * what.texinfo: Fix two typos reported on cygwin list. - -2004-09-02 Corinna Vinschen <corinna@vinschen.de> - - * textbinary.sgml: Change default mode for non-mounted paths to binary. - -2004-07-16 Joshua Daniel Franklin <joshuadfranklin@yahoo.com> - - * how-resources.texinfo: Update documentation to /usr/share/doc. - * how-using.texinfo: Add paragraph about find -noleaf. - -2004-06-14 Joshua Daniel Franklin <joshuadfranklin@yahoo.com> - - * how-programming.texinfo: Add section about Visual Studio linking. - -2004-06-13 Joshua Daniel Franklin <joshuadfranklin@yahoo.com> - - * faq.texinfo: Move outdated calls.texinfo to readme.texinfo. - * how-api.texinfo: Fix typos. - * how-programming.texinfo: Fix typos. - * how-resources.texinfo: Fix typos. - * how-using.texinfo: Fix typos. - * install.texinfo: Fix typos. - * readme.texinfo: Move outdated calls.texinfo to readme.texinfo. - -2004-05-21 Brian Ford <ford@vss.fsi.com> - - * pathnames.sgml: Remove /dev/kmem from the supported POSIX - device list. - - * cygwinenv.sgml: Fix typo in check_case description. - -2004-03-30 Joshua Daniel Franklin <joshuadfranklin@yahoo.com> - - * ntsec.sgml: Replace chapter numbers with <link>s, - replace release-numbers in <title>s with descriptions. - -2004-03-30 Ronald Landheer-Cieslak <ronald@landheer.com> - - * ntsec.sgml: Fix typos, correct chapter numbers. - -2004-03-29 Corinna Vinschen <corinna@vinschen.de> - - * pathnames.sgml: Fix /dev/srX description. - -2004-03-28 Joshua Daniel Franklin <joshuadfranklin@yahoo.com> - - * how-programming.texinfo: Make list in .lib FAQ enumerative. - -2004-03-28 Joshua Daniel Franklin <joshuadfranklin@yahoo.com> - - * how-programming.texinfo: Add note about gcc .lib linking. - * pathnames.sgml: Mention create_devices.sh for /dev/ creation. - -2004-03-27 Corinna Vinschen <corinna@vinschen.de> - - * cygserver.sgml: New file. - * using.sgml: Include Cygserver docs. - -2004-03-26 Joshua Daniel Franklin <joshuadfranklin@yahoo.com> - - * cygwinenv.sgml: Add example for CYGWIN=error_start. - * pathnames.sgml: Update list of /dev/ devices. - -2004-02-22 Joshua Daniel Franklin <joshuadfranklin@yahoo.com> - - * Makefile.in: Fix problem links in faq0.html file. - * what.texinfo: Remove outdated 'recent' history. - -2004-02-19 Joshua Daniel Franklin <joshuadfranklin@yahoo.com> - - * cygwinenv.sgml: Remove incorrect ^Z information. Add - some tags to server option description. - * textbinary.sgml: Remove incorrect ^Z information. - -2004-02-16 Corinna Vinschen <corinna@vinschen.de> - - * cygwinenv.sgml: Add server option description. - -2004-02-04 Joshua Daniel Franklin <joshuadfranklin@yahoo.com> - - * Makefile.in: Generate monolithic faq0.html file. - -2004-01-24 Joshua Daniel Franklin <joshuadfranklin@yahoo.com> - - * cygwinenv.sgml: Cleanup minor markup problems. - * dll.sgml: Cleanup minor markup problems. - * effectively.sgml: Cleanup minor markup problems. - * gcc.sgml: Cleanup minor markup problems. - * ntsec.sgml: Cleanup minor markup problems. - * pathnames.sgml: Cleanup minor markup problems. - * setup-net.sgml: Cleanup minor markup problems. - * textbinary.sgml: Cleanup minor markup problems. - * windres.sgml: Cleanup minor markup problems. - -2004-01-20 Joshua Daniel Franklin <joshuadfranklin@yahoo.com> - - * Makefile.in: Remove unused cygwin-ug and cygwin-api-int - targets from default build. - * how-using.texinfo: Add information about 8-bit character - display to FAQ. - * setup2.sgml: Add information about 8-bit character display - to "Setting up Cygwin". - -2004-01-15 Joshua Daniel Franklin <joshuadfranklin@yahoo.com> - - * setup-net.sgml: Add "internet-setup" id anchor. - * overview.sgml: Update "What is it?" section. Add links to - "Is it free software?" section. Update "Brief History" section. - * overview2.sgml: Rewrite "Expectations for {Windows,Unix}" - as "Quick Start for those more experienced with {Windows,Unix}". - -2004-01-11 Joshua Daniel Franklin <joshuadfranklin@yahoo.com> - - * Makefile.in: Add new target for single-file User's Guide, use new - cygwin.dsl for output. - * cygwin.dsl: New file, DSSSL stylesheet for custom Cygwin output. - * cygwin-api.in.sgml: Update to DocBook SGML 4.2 DTD. - * cygwin-ug-net.in.sgml: Update to DocBook SGML 4.2 DTD. - * cygwin-ug.in.sgml: Update to DocBook SGML 4.2 DTD. - * cygwinenv.sgml: Correct some tags. Add description of default values - to ntsec, export, and error_start items. - * dll.sgml: Add explanation of cyg prefix for DLLs. - * effectively.sgml: Use systemitem tag for names of Cygwin packages. - * how-programming.texinfo: Add example to FAQ entry. - * pathnames.sgml: Add discussion of /proc filesystem. - * setup-net.sgml: Correct some typos and grammar. - -2003-09-01 Corinna Vinschen <corinna@vinschen.de> - - * pathnames.sgml: Remove description how to mount raw devices and - dicourage it. Desparately try to make usage of raw devices a bit - clearer. - -2003-07-31 Joshua Daniel Franklin <joshuadfranklin@yahoo.com> - - * effectively.sgml: New file, "Using Cygwin Effectively with Windows". - * legal.sgml: Update year in copyright notice. - * using.sgml: Include "Using Cygwin Effectively with Windows" section. - -2003-07-15 Christopher Faylor <cgf@redhat.com> - - * pathnames.sgml: Use correct registry key. Clarify '@' operation. - -2003-07-03 Christopher Faylor <cgf@redhat.com> - - * ntsec.sgml: Reword references to "ntsec patch". - -2003-05-08 Joshua Daniel Franklin <joshuadfranklin@yahoo.com> - - * cygwin-ug-net.in.sgml: Remove outdated revision information and - author's names. - -2003-04-26 Joshua Daniel Franklin <joshuadfranklin@yahoo.com> - - * gcc.sgml: Remove outdated "WinMainCRTStartup" references. Add a - hellogui.c example. - -2003-03-26 Joshua Daniel Franklin <joshuadfranklin@yahoo.com> - - * setup-net.sgml: Make suggested additions to setup.exe documentation - -2003-03-23 Joshua Daniel Franklin <joshuadfranklin@yahoo.com> - - * setup-net.sgml: Improve setup.exe documentation - -2003-03-22 Joshua Daniel Franklin <joshuadfranklin@yahoo.com> - - * setup-net.sgml: Document setup.exe - -2003-02-07 Christopher Faylor <cgf@redhat.com> - - * how.texinfo: Add more w32api words. - -2003-02-07 Igor Pechtchanski <pechtcha@cs.nyu.edu> - - * ntsec.sgml: Add note on special names for missing user/group. - -2002-12-18 Christopher Faylor <cgf@redhat.com> - - * overview2.sgml: Remove CTRL-Z discussion. - * cygwinenv.sgml: Expand on CYGWIN=binmode. - -2002-11-10 Christopher Faylor <cgf@redhat.com> - - * how-programming.texinfo: Document _WIN32 more fully. - -2002-10-22 Joshua Daniel Franklin <joshuadfranklin@yahoo.com> - - * ntsec.sgml: Correct some minor grammatical errors. - -2002-10-22 Joshua Daniel Franklin <joshuadfranklin@yahoo.com> - - * dll.sgml: Simplify dll build instructions. - -2002-09-11 Corinna Vinschen <corinna@vinschen.de> - - * ntsec.html: Add chapter for switching user context w/o password. - -2002-08-29 Christopher Faylor <cgf@redhat.com> - - * how-api.texinfo: Remove a line from the CRLF discussion about lseek - not working. Answer thread safe question more simply. - -2002-08-27 Nicholas Wourms <nwourms@netscape.net> - - * calls.texinfo: Add getc_unlocked, getchar_unlocked, putc_unlocked - and putchar_unlocked. - -2002-08-21 Christopher Faylor <cgf@redhat.com> - - * dll.sgml: Remove indirect reference to older gccs. - -2002-06-22 Joshua Daniel Franklin <joshuadfranklin@yahoo.com> - - * dll.sgml: Refine dll build instructions. - -2002-08-21 Christopher Faylor <cgf@redhat.com> - - * ntsec.html: Correct some typos. - -2002-07-23 Nicholas Wourms <nwourms@netscape.net> - - * calls.texinfo: Add fcloseall and fcloseall_r. - -2002-06-24 Corinna Vinschen <corinna@vinschen.de> - - * ntsec.sgml: Clean up text for examples of /etc/passwd and /etc/group. - Add examples with SIDs. Warn about changing them crudely. - -2002-06-21 Christopher Faylor <cgf@redhat.com> - - * what.texinfo: Fix typo. - -2002-06-02 Christopher Faylor <cgf@redhat.com> - - * how-programming.texinfo: Add more words to the "how to build". - -2002-03-01 Christopher Faylor <cgf@redhat.com> - - * overview.sgml: Fix 'more more' typo. - -2002-01-12 Christopher Faylor <cgf@redhat.com> - - * overview.sgml: Fix Red Hat cygwin contract link. - * what.texinfo: Ditto. - -2002-01-01 Christopher Faylor <cgf@redhat.com> - - * Makefile.in: Duh. Actually use bzip2 to create the tarball. Don't - just change the name. - -2002-01-01 Christopher Faylor <cgf@redhat.com> - - * Makefile.in: Make .bz2 tarball. - -2001-12-11 Christopher Faylor <cgf@redhat.com> - - * what.texinfo: Clarify XP. - -2001-12-03 Christopher Faylor <cgf@redhat.com> - - Cleanup copyrights and Cygnus'isms throughout. - * setup.sgml: Nuke ancient instructions. - -Tue Oct 16 18:02:00 2001 Corinna Vinschen <corinna@vinschen.de> - - * pathnames.sgml: Cleanup raw device text to be more coherent. - -Tue Oct 16 17:14:00 2001 Corinna Vinschen <corinna@vinschen.de> - - * pathnames.sgml: Add description for new fixed device paths. - -Fri Sep 7 12:47:47 2001 Michael Schaap <cygwin@mscha.com> - - * how-resources.texinfo: Add some additional words about where to find - documentation. - -Wed Jun 13 13:54:35 2001 Christopher Faylor <cgf@cygnus.com> - - * who.texinfo: Oops. Add a couple of important folk. - -Wed Jun 13 13:45:44 2001 Christopher Faylor <cgf@cygnus.com> - - * who.texinfo: Remove email addresses. Modernize. - -Tue May 29 21:30:07 2001 Christopher Faylor <cgf@cygnus.com> - - * Makefile.in: Tweak to attempt to accomodate older texi2html. - -Tue May 29 16:24:46 2001 Christopher Faylor <cgf@cygnus.com> - - * Makefile.in: Accomodate newer versions of docbook and openjade. - -Thu Apr 12 23:52:00 2001 Corinna Vinschen <corinna@vinschen.de> - - * cygwinenv.sgml: Add text for `check_case' option. - -Fri Mar 2 12:42:00 2001 Corinna Vinschen <corinna@vinschen.de> - - * cygwinenv.sgml: Add text for `winsymlinks' option. - * how-api.texinfo: Add text to explain new symlinks==shortcuts - and the CYGWIN setting `(no)winsymlinks'. - * how-using.texinfo: Add text that Cygwin now treats shortcuts - as symlinks. - -2001-02-07 Eric M. Monsler <emonsler@beamreachnetworks.com> - - * setup2.sgml: Add docs about domain accounts. - -Thu Dec 21 15:03:29 2000 Edward M. Lee <tailbert@yahoo.com> - - * cygwinenv.sgml: Fix typo in <filename>. Add missing </para>. - -Tue Dec 19 21:06:00 2000 Corinna Vinschen <corinna@vinschen.de> - - * cygwinenv.sgml: Add text for `smbntsec' option. - -Sat Nov 18 23:50:12 2000 Christopher Faylor <cgf@cygnus.com> - - * cygwinenv.sgml: Remove CYGWIN=strace option. Update CYGWIN options. - * setup2.sgml: Remove CYGWIN=strace example. - * how-programming.texinfo: Remove stuff about CYGWIN=strace. - -Thu Oct 26 10:00:00 2000 Corinna Vinschen <corinna@vinschen.de> - - * ntsec.sgml: Slight changes. Fix some errors. - -Thu Oct 26 9:35:00 2000 Corinna Vinschen <corinna@vinschen.de> - - * ntsec.sgml: Changed the (now incorrect) hint that ntsec only - uses access allowed ACEs. - -Fri Sep 29 23:52:00 2000 Corinna Vinschen <corinna@vinschen.de> - - * pathnames.sgml: Add documentation about raw block special - devices and tape devices to the "POSIX devices" chapter. - -Fri Aug 18 15:51:06 2000 Christopher Faylor <cgf@cygnus.com> - - * fhandler-tut.txt: hinfo -> dtable. - -Thu Jul 20 13:01:00 2000 Corinna Vinschen <corinna@vinschen.de> - - * ntsec.sgml: Add description for the new setuid ability - of Cygwin since release 1.1.3. - * overview2.sgml: Add description for new chroot functionality. - * calls.texinfo: Add missing calls. Change comments for - setuid, setgid, seteuid, setegid, chroot. - -Tue May 3 0:25:00 2000 Corinna Vinschen <corinna@vinschen.de> - - * ntsec.sgml: Revisited description of `ntsec' according to - the changes in release 1.1. - * setup.sgml: Include ntsec. - * setup-net.sgml: Ditto. diff --git a/winsup/doc/Makefile.in b/winsup/doc/Makefile.in deleted file mode 100644 index 7e8e29e43..000000000 --- a/winsup/doc/Makefile.in +++ /dev/null @@ -1,79 +0,0 @@ -# -*- Makefile -*- for winsup/doc -# Copyright (c) 1998-2000,2001 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. - -SHELL = @SHELL@ -srcdir = @srcdir@ -VPATH = @srcdir@ - -SGMLDIRS = -d $(srcdir) -d $(utils_source) -d $(cygwin_source) - -CC:=@CC@ -CC_FOR_TARGET:=@CC@ -exeext:=@build_exeext@ - -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 - -.SUFFIXES: - -all : \ - cygwin-ug-net/cygwin-ug-net.html \ - cygwin-ug-net/cygwin-ug-net.html.gz \ - cygwin-api/cygwin-api.html \ - faq/faq.html faq/faq-nochunks.html - -clean: - rm -Rf $(TOCLEAN) - -install: all - -cygwin-ug-net/cygwin-ug-net.html.gz : cygwin-ug-net.sgml doctool - -xmlto html-nochunks -m $(srcdir)/cygwin.dsl $< - -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.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.sgml : cygwin-api.in.sgml ./doctool Makefile - -./doctool -m $(SGMLDIRS) -s $(srcdir) -o $@ $< - -faq/faq.html : - -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 : - -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 - -./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-api.dvi cygwin-api.rtf cygwin-api.ps \ - cygwin-api.pdf cygwin-api.sgml -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 diff --git a/winsup/doc/README b/winsup/doc/README deleted file mode 100644 index 1f1e15419..000000000 --- a/winsup/doc/README +++ /dev/null @@ -1,30 +0,0 @@ -The cygwin-doc source files are kept in CVS. Please see -http://cygwin.com/cvs.html for more information. - -BUILD REQUIREMENTS: - -ash -bzip2 -coreutils -cygwin -docbook-xml42 -docbook-xsl -gzip -make -texinfo -perl -xmlto - - -OTHER NOTES: - -You may use docbook2X to convert the DocBook files into info pages. -I have not been able to get a working docbook2X installation on Cygwin, -so currently I convert the files on a machine running GNU/Linux. PDF -generation is also problematic; I use 'jw -b pdf' right now but have -also used 'xmlto pdf' and jade. - -A few handmade files (cygwin.texi, intro.3, etc.) are found in the -cygwin-doc-x.y-z-src.tar.bz2 package. It also contains the utilities for -building the cygwin-doc-x.y-z "binary" package--simply run each step in -the cygwin-doc-x.y-z.sh script. diff --git a/winsup/doc/configure b/winsup/doc/configure deleted file mode 100755 index eea87df57..000000000 --- a/winsup/doc/configure +++ /dev/null @@ -1,1067 +0,0 @@ -#! /bin/sh - -# Guess values for system-dependent variables and create Makefiles. -# Generated automatically using autoconf version 2.13 -# Copyright (C) 1992, 93, 94, 95, 96 Free Software Foundation, Inc. -# -# This configure script is free software; the Free Software Foundation -# gives unlimited permission to copy, distribute and modify it. - -# Defaults: -ac_help= -ac_default_prefix=/usr/local -# Any additions from configure.in: - -# Initialize some variables set by options. -# The variables have the same names as the options, with -# dashes changed to underlines. -build=NONE -cache_file=./config.cache -exec_prefix=NONE -host=NONE -no_create= -nonopt=NONE -no_recursion= -prefix=NONE -program_prefix=NONE -program_suffix=NONE -program_transform_name=s,x,x, -silent= -site= -srcdir= -target=NONE -verbose= -x_includes=NONE -x_libraries=NONE -bindir='${exec_prefix}/bin' -sbindir='${exec_prefix}/sbin' -libexecdir='${exec_prefix}/libexec' -datadir='${prefix}/share' -sysconfdir='${prefix}/etc' -sharedstatedir='${prefix}/com' -localstatedir='${prefix}/var' -libdir='${exec_prefix}/lib' -includedir='${prefix}/include' -oldincludedir='/usr/include' -infodir='${prefix}/info' -mandir='${prefix}/man' - -# Initialize some other variables. -subdirs= -MFLAGS= MAKEFLAGS= -SHELL=${CONFIG_SHELL-/bin/sh} -# Maximum number of lines to put in a shell here document. -ac_max_here_lines=12 - -ac_prev= -for ac_option -do - - # If the previous option needs an argument, assign it. - if test -n "$ac_prev"; then - eval "$ac_prev=\$ac_option" - ac_prev= - continue - fi - - case "$ac_option" in - -*=*) ac_optarg=`echo "$ac_option" | sed 's/[-_a-zA-Z0-9]*=//'` ;; - *) ac_optarg= ;; - esac - - # Accept the important Cygnus configure options, so we can diagnose typos. - - case "$ac_option" in - - -bindir | --bindir | --bindi | --bind | --bin | --bi) - ac_prev=bindir ;; - -bindir=* | --bindir=* | --bindi=* | --bind=* | --bin=* | --bi=*) - bindir="$ac_optarg" ;; - - -build | --build | --buil | --bui | --bu) - ac_prev=build ;; - -build=* | --build=* | --buil=* | --bui=* | --bu=*) - build="$ac_optarg" ;; - - -cache-file | --cache-file | --cache-fil | --cache-fi \ - | --cache-f | --cache- | --cache | --cach | --cac | --ca | --c) - ac_prev=cache_file ;; - -cache-file=* | --cache-file=* | --cache-fil=* | --cache-fi=* \ - | --cache-f=* | --cache-=* | --cache=* | --cach=* | --cac=* | --ca=* | --c=*) - cache_file="$ac_optarg" ;; - - -datadir | --datadir | --datadi | --datad | --data | --dat | --da) - ac_prev=datadir ;; - -datadir=* | --datadir=* | --datadi=* | --datad=* | --data=* | --dat=* \ - | --da=*) - datadir="$ac_optarg" ;; - - -disable-* | --disable-*) - ac_feature=`echo $ac_option|sed -e 's/-*disable-//'` - # Reject names that are not valid shell variable names. - if test -n "`echo $ac_feature| sed 's/[-a-zA-Z0-9_]//g'`"; then - { echo "configure: error: $ac_feature: invalid feature name" 1>&2; exit 1; } - fi - ac_feature=`echo $ac_feature| sed 's/-/_/g'` - eval "enable_${ac_feature}=no" ;; - - -enable-* | --enable-*) - ac_feature=`echo $ac_option|sed -e 's/-*enable-//' -e 's/=.*//'` - # Reject names that are not valid shell variable names. - if test -n "`echo $ac_feature| sed 's/[-_a-zA-Z0-9]//g'`"; then - { echo "configure: error: $ac_feature: invalid feature name" 1>&2; exit 1; } - fi - ac_feature=`echo $ac_feature| sed 's/-/_/g'` - case "$ac_option" in - *=*) ;; - *) ac_optarg=yes ;; - esac - eval "enable_${ac_feature}='$ac_optarg'" ;; - - -exec-prefix | --exec_prefix | --exec-prefix | --exec-prefi \ - | --exec-pref | --exec-pre | --exec-pr | --exec-p | --exec- \ - | --exec | --exe | --ex) - ac_prev=exec_prefix ;; - -exec-prefix=* | --exec_prefix=* | --exec-prefix=* | --exec-prefi=* \ - | --exec-pref=* | --exec-pre=* | --exec-pr=* | --exec-p=* | --exec-=* \ - | --exec=* | --exe=* | --ex=*) - exec_prefix="$ac_optarg" ;; - - -gas | --gas | --ga | --g) - # Obsolete; use --with-gas. - with_gas=yes ;; - - -help | --help | --hel | --he) - # Omit some internal or obsolete options to make the list less imposing. - # This message is too long to be a string in the A/UX 3.1 sh. - cat << EOF -Usage: configure [options] [host] -Options: [defaults in brackets after descriptions] -Configuration: - --cache-file=FILE cache test results in FILE - --help print this message - --no-create do not create output files - --quiet, --silent do not print \`checking...' messages - --version print the version of autoconf that created configure -Directory and file names: - --prefix=PREFIX install architecture-independent files in PREFIX - [$ac_default_prefix] - --exec-prefix=EPREFIX install architecture-dependent files in EPREFIX - [same as prefix] - --bindir=DIR user executables in DIR [EPREFIX/bin] - --sbindir=DIR system admin executables in DIR [EPREFIX/sbin] - --libexecdir=DIR program executables in DIR [EPREFIX/libexec] - --datadir=DIR read-only architecture-independent data in DIR - [PREFIX/share] - --sysconfdir=DIR read-only single-machine data in DIR [PREFIX/etc] - --sharedstatedir=DIR modifiable architecture-independent data in DIR - [PREFIX/com] - --localstatedir=DIR modifiable single-machine data in DIR [PREFIX/var] - --libdir=DIR object code libraries in DIR [EPREFIX/lib] - --includedir=DIR C header files in DIR [PREFIX/include] - --oldincludedir=DIR C header files for non-gcc in DIR [/usr/include] - --infodir=DIR info documentation in DIR [PREFIX/info] - --mandir=DIR man documentation in DIR [PREFIX/man] - --srcdir=DIR find the sources in DIR [configure dir or ..] - --program-prefix=PREFIX prepend PREFIX to installed program names - --program-suffix=SUFFIX append SUFFIX to installed program names - --program-transform-name=PROGRAM - run sed PROGRAM on installed program names -EOF - cat << EOF -Host type: - --build=BUILD configure for building on BUILD [BUILD=HOST] - --host=HOST configure for HOST [guessed] - --target=TARGET configure for TARGET [TARGET=HOST] -Features and packages: - --disable-FEATURE do not include FEATURE (same as --enable-FEATURE=no) - --enable-FEATURE[=ARG] include FEATURE [ARG=yes] - --with-PACKAGE[=ARG] use PACKAGE [ARG=yes] - --without-PACKAGE do not use PACKAGE (same as --with-PACKAGE=no) - --x-includes=DIR X include files are in DIR - --x-libraries=DIR X library files are in DIR -EOF - if test -n "$ac_help"; then - echo "--enable and --with options recognized:$ac_help" - fi - exit 0 ;; - - -host | --host | --hos | --ho) - ac_prev=host ;; - -host=* | --host=* | --hos=* | --ho=*) - host="$ac_optarg" ;; - - -includedir | --includedir | --includedi | --included | --include \ - | --includ | --inclu | --incl | --inc) - ac_prev=includedir ;; - -includedir=* | --includedir=* | --includedi=* | --included=* | --include=* \ - | --includ=* | --inclu=* | --incl=* | --inc=*) - includedir="$ac_optarg" ;; - - -infodir | --infodir | --infodi | --infod | --info | --inf) - ac_prev=infodir ;; - -infodir=* | --infodir=* | --infodi=* | --infod=* | --info=* | --inf=*) - infodir="$ac_optarg" ;; - - -libdir | --libdir | --libdi | --libd) - ac_prev=libdir ;; - -libdir=* | --libdir=* | --libdi=* | --libd=*) - libdir="$ac_optarg" ;; - - -libexecdir | --libexecdir | --libexecdi | --libexecd | --libexec \ - | --libexe | --libex | --libe) - ac_prev=libexecdir ;; - -libexecdir=* | --libexecdir=* | --libexecdi=* | --libexecd=* | --libexec=* \ - | --libexe=* | --libex=* | --libe=*) - libexecdir="$ac_optarg" ;; - - -localstatedir | --localstatedir | --localstatedi | --localstated \ - | --localstate | --localstat | --localsta | --localst \ - | --locals | --local | --loca | --loc | --lo) - ac_prev=localstatedir ;; - -localstatedir=* | --localstatedir=* | --localstatedi=* | --localstated=* \ - | --localstate=* | --localstat=* | --localsta=* | --localst=* \ - | --locals=* | --local=* | --loca=* | --loc=* | --lo=*) - localstatedir="$ac_optarg" ;; - - -mandir | --mandir | --mandi | --mand | --man | --ma | --m) - ac_prev=mandir ;; - -mandir=* | --mandir=* | --mandi=* | --mand=* | --man=* | --ma=* | --m=*) - mandir="$ac_optarg" ;; - - -nfp | --nfp | --nf) - # Obsolete; use --without-fp. - with_fp=no ;; - - -no-create | --no-create | --no-creat | --no-crea | --no-cre \ - | --no-cr | --no-c) - no_create=yes ;; - - -no-recursion | --no-recursion | --no-recursio | --no-recursi \ - | --no-recurs | --no-recur | --no-recu | --no-rec | --no-re | --no-r) - no_recursion=yes ;; - - -oldincludedir | --oldincludedir | --oldincludedi | --oldincluded \ - | --oldinclude | --oldinclud | --oldinclu | --oldincl | --oldinc \ - | --oldin | --oldi | --old | --ol | --o) - ac_prev=oldincludedir ;; - -oldincludedir=* | --oldincludedir=* | --oldincludedi=* | --oldincluded=* \ - | --oldinclude=* | --oldinclud=* | --oldinclu=* | --oldincl=* | --oldinc=* \ - | --oldin=* | --oldi=* | --old=* | --ol=* | --o=*) - oldincludedir="$ac_optarg" ;; - - -prefix | --prefix | --prefi | --pref | --pre | --pr | --p) - ac_prev=prefix ;; - -prefix=* | --prefix=* | --prefi=* | --pref=* | --pre=* | --pr=* | --p=*) - prefix="$ac_optarg" ;; - - -program-prefix | --program-prefix | --program-prefi | --program-pref \ - | --program-pre | --program-pr | --program-p) - ac_prev=program_prefix ;; - -program-prefix=* | --program-prefix=* | --program-prefi=* \ - | --program-pref=* | --program-pre=* | --program-pr=* | --program-p=*) - program_prefix="$ac_optarg" ;; - - -program-suffix | --program-suffix | --program-suffi | --program-suff \ - | --program-suf | --program-su | --program-s) - ac_prev=program_suffix ;; - -program-suffix=* | --program-suffix=* | --program-suffi=* \ - | --program-suff=* | --program-suf=* | --program-su=* | --program-s=*) - program_suffix="$ac_optarg" ;; - - -program-transform-name | --program-transform-name \ - | --program-transform-nam | --program-transform-na \ - | --program-transform-n | --program-transform- \ - | --program-transform | --program-transfor \ - | --program-transfo | --program-transf \ - | --program-trans | --program-tran \ - | --progr-tra | --program-tr | --program-t) - ac_prev=program_transform_name ;; - -program-transform-name=* | --program-transform-name=* \ - | --program-transform-nam=* | --program-transform-na=* \ - | --program-transform-n=* | --program-transform-=* \ - | --program-transform=* | --program-transfor=* \ - | --program-transfo=* | --program-transf=* \ - | --program-trans=* | --program-tran=* \ - | --progr-tra=* | --program-tr=* | --program-t=*) - program_transform_name="$ac_optarg" ;; - - -q | -quiet | --quiet | --quie | --qui | --qu | --q \ - | -silent | --silent | --silen | --sile | --sil) - silent=yes ;; - - -sbindir | --sbindir | --sbindi | --sbind | --sbin | --sbi | --sb) - ac_prev=sbindir ;; - -sbindir=* | --sbindir=* | --sbindi=* | --sbind=* | --sbin=* \ - | --sbi=* | --sb=*) - sbindir="$ac_optarg" ;; - - -sharedstatedir | --sharedstatedir | --sharedstatedi \ - | --sharedstated | --sharedstate | --sharedstat | --sharedsta \ - | --sharedst | --shareds | --shared | --share | --shar \ - | --sha | --sh) - ac_prev=sharedstatedir ;; - -sharedstatedir=* | --sharedstatedir=* | --sharedstatedi=* \ - | --sharedstated=* | --sharedstate=* | --sharedstat=* | --sharedsta=* \ - | --sharedst=* | --shareds=* | --shared=* | --share=* | --shar=* \ - | --sha=* | --sh=*) - sharedstatedir="$ac_optarg" ;; - - -site | --site | --sit) - ac_prev=site ;; - -site=* | --site=* | --sit=*) - site="$ac_optarg" ;; - - -srcdir | --srcdir | --srcdi | --srcd | --src | --sr) - ac_prev=srcdir ;; - -srcdir=* | --srcdir=* | --srcdi=* | --srcd=* | --src=* | --sr=*) - srcdir="$ac_optarg" ;; - - -sysconfdir | --sysconfdir | --sysconfdi | --sysconfd | --sysconf \ - | --syscon | --sysco | --sysc | --sys | --sy) - ac_prev=sysconfdir ;; - -sysconfdir=* | --sysconfdir=* | --sysconfdi=* | --sysconfd=* | --sysconf=* \ - | --syscon=* | --sysco=* | --sysc=* | --sys=* | --sy=*) - sysconfdir="$ac_optarg" ;; - - -target | --target | --targe | --targ | --tar | --ta | --t) - ac_prev=target ;; - -target=* | --target=* | --targe=* | --targ=* | --tar=* | --ta=* | --t=*) - target="$ac_optarg" ;; - - -v | -verbose | --verbose | --verbos | --verbo | --verb) - verbose=yes ;; - - -version | --version | --versio | --versi | --vers) - echo "configure generated by autoconf version 2.13" - exit 0 ;; - - -with-* | --with-*) - ac_package=`echo $ac_option|sed -e 's/-*with-//' -e 's/=.*//'` - # Reject names that are not valid shell variable names. - if test -n "`echo $ac_package| sed 's/[-_a-zA-Z0-9]//g'`"; then - { echo "configure: error: $ac_package: invalid package name" 1>&2; exit 1; } - fi - ac_package=`echo $ac_package| sed 's/-/_/g'` - case "$ac_option" in - *=*) ;; - *) ac_optarg=yes ;; - esac - eval "with_${ac_package}='$ac_optarg'" ;; - - -without-* | --without-*) - ac_package=`echo $ac_option|sed -e 's/-*without-//'` - # Reject names that are not valid shell variable names. - if test -n "`echo $ac_package| sed 's/[-a-zA-Z0-9_]//g'`"; then - { echo "configure: error: $ac_package: invalid package name" 1>&2; exit 1; } - fi - ac_package=`echo $ac_package| sed 's/-/_/g'` - eval "with_${ac_package}=no" ;; - - --x) - # Obsolete; use --with-x. - with_x=yes ;; - - -x-includes | --x-includes | --x-include | --x-includ | --x-inclu \ - | --x-incl | --x-inc | --x-in | --x-i) - ac_prev=x_includes ;; - -x-includes=* | --x-includes=* | --x-include=* | --x-includ=* | --x-inclu=* \ - | --x-incl=* | --x-inc=* | --x-in=* | --x-i=*) - x_includes="$ac_optarg" ;; - - -x-libraries | --x-libraries | --x-librarie | --x-librari \ - | --x-librar | --x-libra | --x-libr | --x-lib | --x-li | --x-l) - ac_prev=x_libraries ;; - -x-libraries=* | --x-libraries=* | --x-librarie=* | --x-librari=* \ - | --x-librar=* | --x-libra=* | --x-libr=* | --x-lib=* | --x-li=* | --x-l=*) - x_libraries="$ac_optarg" ;; - - -*) { echo "configure: error: $ac_option: invalid option; use --help to show usage" 1>&2; exit 1; } - ;; - - *) - if test -n "`echo $ac_option| sed 's/[-a-z0-9.]//g'`"; then - echo "configure: warning: $ac_option: invalid host type" 1>&2 - fi - if test "x$nonopt" != xNONE; then - { echo "configure: error: can only configure for one host and one target at a time" 1>&2; exit 1; } - fi - nonopt="$ac_option" - ;; - - esac -done - -if test -n "$ac_prev"; then - { echo "configure: error: missing argument to --`echo $ac_prev | sed 's/_/-/g'`" 1>&2; exit 1; } -fi - -trap 'rm -fr conftest* confdefs* core core.* *.core $ac_clean_files; exit 1' 1 2 15 - -# File descriptor usage: -# 0 standard input -# 1 file creation -# 2 errors and warnings -# 3 some systems may open it to /dev/tty -# 4 used on the Kubota Titan -# 6 checking for... messages and results -# 5 compiler messages saved in config.log -if test "$silent" = yes; then - exec 6>/dev/null -else - exec 6>&1 -fi -exec 5>./config.log - -echo "\ -This file contains any messages produced by compilers while -running configure, to aid debugging if configure makes a mistake. -" 1>&5 - -# Strip out --no-create and --no-recursion so they do not pile up. -# Also quote any args containing shell metacharacters. -ac_configure_args= -for ac_arg -do - case "$ac_arg" in - -no-create | --no-create | --no-creat | --no-crea | --no-cre \ - | --no-cr | --no-c) ;; - -no-recursion | --no-recursion | --no-recursio | --no-recursi \ - | --no-recurs | --no-recur | --no-recu | --no-rec | --no-re | --no-r) ;; - *" "*|*" "*|*[\[\]\~\#\$\^\&\*\(\)\{\}\\\|\;\<\>\?]*) - ac_configure_args="$ac_configure_args '$ac_arg'" ;; - *) ac_configure_args="$ac_configure_args $ac_arg" ;; - esac -done - -# NLS nuisances. -# Only set these to C if already set. These must not be set unconditionally -# because not all systems understand e.g. LANG=C (notably SCO). -# Fixing LC_MESSAGES prevents Solaris sh from translating var values in `set'! -# Non-C LC_CTYPE values break the ctype check. -if test "${LANG+set}" = set; then LANG=C; export LANG; fi -if test "${LC_ALL+set}" = set; then LC_ALL=C; export LC_ALL; fi -if test "${LC_MESSAGES+set}" = set; then LC_MESSAGES=C; export LC_MESSAGES; fi -if test "${LC_CTYPE+set}" = set; then LC_CTYPE=C; export LC_CTYPE; fi - -# confdefs.h avoids OS command line length limits that DEFS can exceed. -rm -rf conftest* confdefs.h -# AIX cpp loses on an empty file, so make sure it contains at least a newline. -echo > confdefs.h - -# A filename unique to this package, relative to the directory that -# configure is in, which we can look for to find out if srcdir is correct. -ac_unique_file=cygwin-api.in.sgml - -# Find the source files, if location was not specified. -if test -z "$srcdir"; then - ac_srcdir_defaulted=yes - # Try the directory containing this script, then its parent. - ac_prog=$0 - ac_confdir=`echo $ac_prog|sed 's%/[^/][^/]*$%%'` - test "x$ac_confdir" = "x$ac_prog" && ac_confdir=. - srcdir=$ac_confdir - if test ! -r $srcdir/$ac_unique_file; then - srcdir=.. - fi -else - ac_srcdir_defaulted=no -fi -if test ! -r $srcdir/$ac_unique_file; then - if test "$ac_srcdir_defaulted" = yes; then - { echo "configure: error: can not find sources in $ac_confdir or .." 1>&2; exit 1; } - else - { echo "configure: error: can not find sources in $srcdir" 1>&2; exit 1; } - fi -fi -srcdir=`echo "${srcdir}" | sed 's%\([^/]\)/*$%\1%'` - -# Prefer explicitly selected file to automatically selected ones. -if test -z "$CONFIG_SITE"; then - if test "x$prefix" != xNONE; then - CONFIG_SITE="$prefix/share/config.site $prefix/etc/config.site" - else - CONFIG_SITE="$ac_default_prefix/share/config.site $ac_default_prefix/etc/config.site" - fi -fi -for ac_site_file in $CONFIG_SITE; do - if test -r "$ac_site_file"; then - echo "loading site script $ac_site_file" - . "$ac_site_file" - fi -done - -if test -r "$cache_file"; then - echo "loading cache $cache_file" - . $cache_file -else - echo "creating cache $cache_file" - > $cache_file -fi - -ac_ext=c -# CFLAGS is not in ac_cpp because -g, -O, etc. are not valid cpp options. -ac_cpp='$CPP $CPPFLAGS' -ac_compile='${CC-cc} -c $CFLAGS $CPPFLAGS conftest.$ac_ext 1>&5' -ac_link='${CC-cc} -o conftest${ac_exeext} $CFLAGS $CPPFLAGS $LDFLAGS conftest.$ac_ext $LIBS 1>&5' -cross_compiling=$ac_cv_prog_cc_cross - -ac_exeext= -ac_objext=o -if (echo "testing\c"; echo 1,2,3) | grep c >/dev/null; then - # Stardent Vistra SVR4 grep lacks -e, says ghazi@caip.rutgers.edu. - if (echo -n testing; echo 1,2,3) | sed s/-n/xn/ | grep xn >/dev/null; then - ac_n= ac_c=' -' ac_t=' ' - else - ac_n=-n ac_c= ac_t= - fi -else - ac_n= ac_c='\c' ac_t= -fi - - - - - -ac_aux_dir= -for ac_dir in $srcdir $srcdir/.. $srcdir/../..; do - if test -f $ac_dir/install-sh; then - ac_aux_dir=$ac_dir - ac_install_sh="$ac_aux_dir/install-sh -c" - break - elif test -f $ac_dir/install.sh; then - ac_aux_dir=$ac_dir - ac_install_sh="$ac_aux_dir/install.sh -c" - break - fi -done -if test -z "$ac_aux_dir"; then - { echo "configure: error: can not find install-sh or install.sh in $srcdir $srcdir/.. $srcdir/../.." 1>&2; exit 1; } -fi -ac_config_guess=$ac_aux_dir/config.guess -ac_config_sub=$ac_aux_dir/config.sub -ac_configure=$ac_aux_dir/configure # This should be Cygnus configure. - - -# Do some error checking and defaulting for the host and target type. -# The inputs are: -# configure --host=HOST --target=TARGET --build=BUILD NONOPT -# -# The rules are: -# 1. You are not allowed to specify --host, --target, and nonopt at the -# same time. -# 2. Host defaults to nonopt. -# 3. If nonopt is not specified, then host defaults to the current host, -# as determined by config.guess. -# 4. Target and build default to nonopt. -# 5. If nonopt is not specified, then target and build default to host. - -# The aliases save the names the user supplied, while $host etc. -# will get canonicalized. -case $host---$target---$nonopt in -NONE---*---* | *---NONE---* | *---*---NONE) ;; -*) { echo "configure: error: can only configure for one host and one target at a time" 1>&2; exit 1; } ;; -esac - - -# Make sure we can run config.sub. -if ${CONFIG_SHELL-/bin/sh} $ac_config_sub sun4 >/dev/null 2>&1; then : -else { echo "configure: error: can not run $ac_config_sub" 1>&2; exit 1; } -fi - -echo $ac_n "checking host system type""... $ac_c" 1>&6 -echo "configure:575: checking host system type" >&5 - -host_alias=$host -case "$host_alias" in -NONE) - case $nonopt in - NONE) - if host_alias=`${CONFIG_SHELL-/bin/sh} $ac_config_guess`; then : - else { echo "configure: error: can not guess host type; you must specify one" 1>&2; exit 1; } - fi ;; - *) host_alias=$nonopt ;; - esac ;; -esac - -host=`${CONFIG_SHELL-/bin/sh} $ac_config_sub $host_alias` -host_cpu=`echo $host | sed 's/^\([^-]*\)-\([^-]*\)-\(.*\)$/\1/'` -host_vendor=`echo $host | sed 's/^\([^-]*\)-\([^-]*\)-\(.*\)$/\2/'` -host_os=`echo $host | sed 's/^\([^-]*\)-\([^-]*\)-\(.*\)$/\3/'` -echo "$ac_t""$host" 1>&6 - -echo $ac_n "checking target system type""... $ac_c" 1>&6 -echo "configure:596: checking target system type" >&5 - -target_alias=$target -case "$target_alias" in -NONE) - case $nonopt in - NONE) target_alias=$host_alias ;; - *) target_alias=$nonopt ;; - esac ;; -esac - -target=`${CONFIG_SHELL-/bin/sh} $ac_config_sub $target_alias` -target_cpu=`echo $target | sed 's/^\([^-]*\)-\([^-]*\)-\(.*\)$/\1/'` -target_vendor=`echo $target | sed 's/^\([^-]*\)-\([^-]*\)-\(.*\)$/\2/'` -target_os=`echo $target | sed 's/^\([^-]*\)-\([^-]*\)-\(.*\)$/\3/'` -echo "$ac_t""$target" 1>&6 - -echo $ac_n "checking build system type""... $ac_c" 1>&6 -echo "configure:614: checking build system type" >&5 - -build_alias=$build -case "$build_alias" in -NONE) - case $nonopt in - NONE) build_alias=$host_alias ;; - *) build_alias=$nonopt ;; - esac ;; -esac - -build=`${CONFIG_SHELL-/bin/sh} $ac_config_sub $build_alias` -build_cpu=`echo $build | sed 's/^\([^-]*\)-\([^-]*\)-\(.*\)$/\1/'` -build_vendor=`echo $build | sed 's/^\([^-]*\)-\([^-]*\)-\(.*\)$/\2/'` -build_os=`echo $build | sed 's/^\([^-]*\)-\([^-]*\)-\(.*\)$/\3/'` -echo "$ac_t""$build" 1>&6 - -test "$host_alias" != "$target_alias" && - test "$program_prefix$program_suffix$program_transform_name" = \ - NONENONEs,x,x, && - program_prefix=${target_alias}- - - -if test $host != $build; then - ac_tool_prefix=${host_alias}- -else - ac_tool_prefix= -fi - -# Extract the first word of "${ac_tool_prefix}gcc", so it can be a program name with args. -set dummy ${ac_tool_prefix}gcc; ac_word=$2 -echo $ac_n "checking for $ac_word""... $ac_c" 1>&6 -echo "configure:646: checking for $ac_word" >&5 -if eval "test \"`echo '$''{'ac_cv_prog_CC'+set}'`\" = set"; then - echo $ac_n "(cached) $ac_c" 1>&6 -else - if test -n "$CC"; then - ac_cv_prog_CC="$CC" # Let the user override the test. -else - IFS="${IFS= }"; ac_save_ifs="$IFS"; IFS=":" - ac_dummy="$PATH" - for ac_dir in $ac_dummy; do - test -z "$ac_dir" && ac_dir=. - if test -f $ac_dir/$ac_word; then - ac_cv_prog_CC="${ac_tool_prefix}gcc" - break - fi - done - IFS="$ac_save_ifs" -fi -fi -CC="$ac_cv_prog_CC" -if test -n "$CC"; then - echo "$ac_t""$CC" 1>&6 -else - echo "$ac_t""no" 1>&6 -fi - - -if test -z "$ac_cv_prog_CC"; then -if test -n "$ac_tool_prefix"; then - # Extract the first word of "gcc", so it can be a program name with args. -set dummy gcc; ac_word=$2 -echo $ac_n "checking for $ac_word""... $ac_c" 1>&6 -echo "configure:678: checking for $ac_word" >&5 -if eval "test \"`echo '$''{'ac_cv_prog_CC'+set}'`\" = set"; then - echo $ac_n "(cached) $ac_c" 1>&6 -else - if test -n "$CC"; then - ac_cv_prog_CC="$CC" # Let the user override the test. -else - IFS="${IFS= }"; ac_save_ifs="$IFS"; IFS=":" - ac_dummy="$PATH" - for ac_dir in $ac_dummy; do - test -z "$ac_dir" && ac_dir=. - if test -f $ac_dir/$ac_word; then - ac_cv_prog_CC="gcc" - break - fi - done - IFS="$ac_save_ifs" - test -z "$ac_cv_prog_CC" && ac_cv_prog_CC="gcc" -fi -fi -CC="$ac_cv_prog_CC" -if test -n "$CC"; then - echo "$ac_t""$CC" 1>&6 -else - echo "$ac_t""no" 1>&6 -fi - -else - CC="gcc" -fi -fi - -if test -z "$CC"; then - # Extract the first word of "cc", so it can be a program name with args. -set dummy cc; ac_word=$2 -echo $ac_n "checking for $ac_word""... $ac_c" 1>&6 -echo "configure:714: checking for $ac_word" >&5 -if eval "test \"`echo '$''{'ac_cv_prog_CC'+set}'`\" = set"; then - echo $ac_n "(cached) $ac_c" 1>&6 -else - if test -n "$CC"; then - ac_cv_prog_CC="$CC" # Let the user override the test. -else - IFS="${IFS= }"; ac_save_ifs="$IFS"; IFS=":" - ac_prog_rejected=no - ac_dummy="$PATH" - for ac_dir in $ac_dummy; do - test -z "$ac_dir" && ac_dir=. - if test -f $ac_dir/$ac_word; then - if test "$ac_dir/$ac_word" = "/usr/ucb/cc"; then - ac_prog_rejected=yes - continue - fi - ac_cv_prog_CC="cc" - break - fi - done - IFS="$ac_save_ifs" -if test $ac_prog_rejected = yes; then - # We found a bogon in the path, so make sure we never use it. - set dummy $ac_cv_prog_CC - shift - if test $# -gt 0; then - # We chose a different compiler from the bogus one. - # However, it has the same basename, so the bogon will be chosen - # first if we set CC to just the basename; use the full file name. - shift - set dummy "$ac_dir/$ac_word" "$@" - shift - ac_cv_prog_CC="$@" - fi -fi -fi -fi -CC="$ac_cv_prog_CC" -if test -n "$CC"; then - echo "$ac_t""$CC" 1>&6 -else - echo "$ac_t""no" 1>&6 -fi - - test -z "$CC" && { echo "configure: error: no acceptable cc found in \$PATH" 1>&2; exit 1; } -fi - -if test $ac_cv_prog_gcc = yes; then - GCC=yes - ac_test_CFLAGS="${CFLAGS+set}" - ac_save_CFLAGS="$CFLAGS" - CFLAGS= - echo $ac_n "checking whether ${CC-cc} accepts -g""... $ac_c" 1>&6 -echo "configure:768: checking whether ${CC-cc} accepts -g" >&5 -if eval "test \"`echo '$''{'ac_cv_prog_cc_g'+set}'`\" = set"; then - echo $ac_n "(cached) $ac_c" 1>&6 -else - echo 'void f(){}' > conftest.c -if test -z "`${CC-cc} -g -c conftest.c 2>&1`"; then - ac_cv_prog_cc_g=yes -else - ac_cv_prog_cc_g=no -fi -rm -f conftest* - -fi - -echo "$ac_t""$ac_cv_prog_cc_g" 1>&6 - if test "$ac_test_CFLAGS" = set; then - CFLAGS="$ac_save_CFLAGS" - elif test $ac_cv_prog_cc_g = yes; then - CFLAGS="-g -O2" - else - CFLAGS="-O2" - fi - if test "$ac_test_CXXFLAGS" != set; then - CXXFLAGS='$(CFLAGS)' - fi -else - GCC= - test "${CFLAGS+set}" = set || CFLAGS="-g" -fi - - - - -trap '' 1 2 15 -cat > confcache <<\EOF -# This file is a shell script that caches the results of configure -# tests run on this system so they can be shared between configure -# scripts and configure runs. It is not useful on other systems. -# If it contains results you don't want to keep, you may remove or edit it. -# -# By default, configure uses ./config.cache as the cache file, -# creating it if it does not exist already. You can give configure -# the --cache-file=FILE option to use a different cache file; that is -# what configure does when it calls configure scripts in -# subdirectories, so they share the cache. -# Giving --cache-file=/dev/null disables caching, for debugging configure. -# config.status only pays attention to the cache file if you give it the -# --recheck option to rerun configure. -# -EOF -# The following way of writing the cache mishandles newlines in values, -# but we know of no workaround that is simple, portable, and efficient. -# So, don't put newlines in cache variables' values. -# Ultrix sh set writes to stderr and can't be redirected directly, -# and sets the high bit in the cache file unless we assign to the vars. -(set) 2>&1 | - case `(ac_space=' '; set | grep ac_space) 2>&1` in - *ac_space=\ *) - # `set' does not quote correctly, so add quotes (double-quote substitution - # turns \\\\ into \\, and sed turns \\ into \). - sed -n \ - -e "s/'/'\\\\''/g" \ - -e "s/^\\([a-zA-Z0-9_]*_cv_[a-zA-Z0-9_]*\\)=\\(.*\\)/\\1=\${\\1='\\2'}/p" - ;; - *) - # `set' quotes correctly as required by POSIX, so do not add quotes. - sed -n -e 's/^\([a-zA-Z0-9_]*_cv_[a-zA-Z0-9_]*\)=\(.*\)/\1=${\1=\2}/p' - ;; - esac >> confcache -if cmp -s $cache_file confcache; then - : -else - if test -w $cache_file; then - echo "updating cache $cache_file" - cat confcache > $cache_file - else - echo "not updating unwritable cache $cache_file" - fi -fi -rm -f confcache - -trap 'rm -fr conftest* confdefs* core core.* *.core $ac_clean_files; exit 1' 1 2 15 - -test "x$prefix" = xNONE && prefix=$ac_default_prefix -# Let make expand exec_prefix. -test "x$exec_prefix" = xNONE && exec_prefix='${prefix}' - -# Any assignment to VPATH causes Sun make to only execute -# the first set of double-colon rules, so remove it if not needed. -# If there is a colon in the path, we need to keep it. -if test "x$srcdir" = x.; then - ac_vpsub='/^[ ]*VPATH[ ]*=[^:]*$/d' -fi - -trap 'rm -f $CONFIG_STATUS conftest*; exit 1' 1 2 15 - -# Transform confdefs.h into DEFS. -# Protect against shell expansion while executing Makefile rules. -# Protect against Makefile macro expansion. -cat > conftest.defs <<\EOF -s%#define \([A-Za-z_][A-Za-z0-9_]*\) *\(.*\)%-D\1=\2%g -s%[ `~#$^&*(){}\\|;'"<>?]%\\&%g -s%\[%\\&%g -s%\]%\\&%g -s%\$%$$%g -EOF -DEFS=`sed -f conftest.defs confdefs.h | tr '\012' ' '` -rm -f conftest.defs - - -# Without the "./", some shells look in PATH for config.status. -: ${CONFIG_STATUS=./config.status} - -echo creating $CONFIG_STATUS -rm -f $CONFIG_STATUS -cat > $CONFIG_STATUS <<EOF -#! /bin/sh -# Generated automatically by configure. -# Run this file to recreate the current configuration. -# This directory was configured as follows, -# on host `(hostname || uname -n) 2>/dev/null | sed 1q`: -# -# $0 $ac_configure_args -# -# Compiler output produced by configure, useful for debugging -# configure, is in ./config.log if it exists. - -ac_cs_usage="Usage: $CONFIG_STATUS [--recheck] [--version] [--help]" -for ac_option -do - case "\$ac_option" in - -recheck | --recheck | --rechec | --reche | --rech | --rec | --re | --r) - echo "running \${CONFIG_SHELL-/bin/sh} $0 $ac_configure_args --no-create --no-recursion" - exec \${CONFIG_SHELL-/bin/sh} $0 $ac_configure_args --no-create --no-recursion ;; - -version | --version | --versio | --versi | --vers | --ver | --ve | --v) - echo "$CONFIG_STATUS generated by autoconf version 2.13" - exit 0 ;; - -help | --help | --hel | --he | --h) - echo "\$ac_cs_usage"; exit 0 ;; - *) echo "\$ac_cs_usage"; exit 1 ;; - esac -done - -ac_given_srcdir=$srcdir - -trap 'rm -fr `echo "Makefile" | sed "s/:[^ ]*//g"` conftest*; exit 1' 1 2 15 -EOF -cat >> $CONFIG_STATUS <<EOF - -# Protect against being on the right side of a sed subst in config.status. -sed 's/%@/@@/; s/@%/@@/; s/%g\$/@g/; /@g\$/s/[\\\\&%]/\\\\&/g; - s/@@/%@/; s/@@/@%/; s/@g\$/%g/' > conftest.subs <<\\CEOF -$ac_vpsub -$extrasub -s%@SHELL@%$SHELL%g -s%@CFLAGS@%$CFLAGS%g -s%@CPPFLAGS@%$CPPFLAGS%g -s%@CXXFLAGS@%$CXXFLAGS%g -s%@FFLAGS@%$FFLAGS%g -s%@DEFS@%$DEFS%g -s%@LDFLAGS@%$LDFLAGS%g -s%@LIBS@%$LIBS%g -s%@exec_prefix@%$exec_prefix%g -s%@prefix@%$prefix%g -s%@program_transform_name@%$program_transform_name%g -s%@bindir@%$bindir%g -s%@sbindir@%$sbindir%g -s%@libexecdir@%$libexecdir%g -s%@datadir@%$datadir%g -s%@sysconfdir@%$sysconfdir%g -s%@sharedstatedir@%$sharedstatedir%g -s%@localstatedir@%$localstatedir%g -s%@libdir@%$libdir%g -s%@includedir@%$includedir%g -s%@oldincludedir@%$oldincludedir%g -s%@infodir@%$infodir%g -s%@mandir@%$mandir%g -s%@host@%$host%g -s%@host_alias@%$host_alias%g -s%@host_cpu@%$host_cpu%g -s%@host_vendor@%$host_vendor%g -s%@host_os@%$host_os%g -s%@target@%$target%g -s%@target_alias@%$target_alias%g -s%@target_cpu@%$target_cpu%g -s%@target_vendor@%$target_vendor%g -s%@target_os@%$target_os%g -s%@build@%$build%g -s%@build_alias@%$build_alias%g -s%@build_cpu@%$build_cpu%g -s%@build_vendor@%$build_vendor%g -s%@build_os@%$build_os%g -s%@CC@%$CC%g -s%@build_exeext@%$build_exeext%g - -CEOF -EOF - -cat >> $CONFIG_STATUS <<\EOF - -# Split the substitutions into bite-sized pieces for seds with -# small command number limits, like on Digital OSF/1 and HP-UX. -ac_max_sed_cmds=90 # Maximum number of lines to put in a sed script. -ac_file=1 # Number of current file. -ac_beg=1 # First line for current file. -ac_end=$ac_max_sed_cmds # Line after last line for current file. -ac_more_lines=: -ac_sed_cmds="" -while $ac_more_lines; do - if test $ac_beg -gt 1; then - sed "1,${ac_beg}d; ${ac_end}q" conftest.subs > conftest.s$ac_file - else - sed "${ac_end}q" conftest.subs > conftest.s$ac_file - fi - if test ! -s conftest.s$ac_file; then - ac_more_lines=false - rm -f conftest.s$ac_file - else - if test -z "$ac_sed_cmds"; then - ac_sed_cmds="sed -f conftest.s$ac_file" - else - ac_sed_cmds="$ac_sed_cmds | sed -f conftest.s$ac_file" - fi - ac_file=`expr $ac_file + 1` - ac_beg=$ac_end - ac_end=`expr $ac_end + $ac_max_sed_cmds` - fi -done -if test -z "$ac_sed_cmds"; then - ac_sed_cmds=cat -fi -EOF - -cat >> $CONFIG_STATUS <<EOF - -CONFIG_FILES=\${CONFIG_FILES-"Makefile"} -EOF -cat >> $CONFIG_STATUS <<\EOF -for ac_file in .. $CONFIG_FILES; do if test "x$ac_file" != x..; then - # Support "outfile[:infile[:infile...]]", defaulting infile="outfile.in". - case "$ac_file" in - *:*) ac_file_in=`echo "$ac_file"|sed 's%[^:]*:%%'` - ac_file=`echo "$ac_file"|sed 's%:.*%%'` ;; - *) ac_file_in="${ac_file}.in" ;; - esac - - # Adjust a relative srcdir, top_srcdir, and INSTALL for subdirectories. - - # Remove last slash and all that follows it. Not all systems have dirname. - ac_dir=`echo $ac_file|sed 's%/[^/][^/]*$%%'` - if test "$ac_dir" != "$ac_file" && test "$ac_dir" != .; then - # The file is in a subdirectory. - test ! -d "$ac_dir" && mkdir "$ac_dir" - ac_dir_suffix="/`echo $ac_dir|sed 's%^\./%%'`" - # A "../" for each directory in $ac_dir_suffix. - ac_dots=`echo $ac_dir_suffix|sed 's%/[^/]*%../%g'` - else - ac_dir_suffix= ac_dots= - fi - - case "$ac_given_srcdir" in - .) srcdir=. - if test -z "$ac_dots"; then top_srcdir=. - else top_srcdir=`echo $ac_dots|sed 's%/$%%'`; fi ;; - /*) srcdir="$ac_given_srcdir$ac_dir_suffix"; top_srcdir="$ac_given_srcdir" ;; - *) # Relative path. - srcdir="$ac_dots$ac_given_srcdir$ac_dir_suffix" - top_srcdir="$ac_dots$ac_given_srcdir" ;; - esac - - - echo creating "$ac_file" - rm -f "$ac_file" - configure_input="Generated automatically from `echo $ac_file_in|sed 's%.*/%%'` by configure." - case "$ac_file" in - *Makefile*) ac_comsub="1i\\ -# $configure_input" ;; - *) ac_comsub= ;; - esac - - ac_file_inputs=`echo $ac_file_in|sed -e "s%^%$ac_given_srcdir/%" -e "s%:% $ac_given_srcdir/%g"` - sed -e "$ac_comsub -s%@configure_input@%$configure_input%g -s%@srcdir@%$srcdir%g -s%@top_srcdir@%$top_srcdir%g -" $ac_file_inputs | (eval "$ac_sed_cmds") > $ac_file -fi; done -rm -f conftest.s* - -EOF -cat >> $CONFIG_STATUS <<EOF - -EOF -cat >> $CONFIG_STATUS <<\EOF - -exit 0 -EOF -chmod +x $CONFIG_STATUS -rm -fr confdefs* $ac_clean_files -test "$no_create" = yes || ${CONFIG_SHELL-/bin/sh} $CONFIG_STATUS || exit 1 - diff --git a/winsup/doc/configure.in b/winsup/doc/configure.in deleted file mode 100644 index 503777724..000000000 --- a/winsup/doc/configure.in +++ /dev/null @@ -1,54 +0,0 @@ -dnl Autoconf configure script for winsup/regexp -dnl Copyright 1997,1998,1999,2000,2001 Red Hat, Inc. -dnl -dnl This file is part of Cygwin. -dnl -dnl This software is a copyrighted work licensed under the terms of the -dnl Cygwin license. Please consult the file "CYGWIN_LICENSE" for -dnl details. - -dnl Process this file with autoconf to produce a configure script. - -AC_PREREQ(2.12) -AC_INIT(cygwin-api.in.sgml) - -AC_DEFUN(LIB_AC_PROG_CC, -[AC_BEFORE([$0], [AC_PROG_CPP])dnl -AC_CHECK_TOOL(CC, gcc, gcc) -if test -z "$CC"; then - AC_CHECK_PROG(CC, cc, cc, , , /usr/ucb/cc) - test -z "$CC" && AC_MSG_ERROR([no acceptable cc found in \$PATH]) -fi - -if test $ac_cv_prog_gcc = yes; then - GCC=yes -dnl Check whether -g works, even if CFLAGS is set, in case the package -dnl plays around with CFLAGS (such as to build both debugging and -dnl normal versions of a library), tasteless as that idea is. - ac_test_CFLAGS="${CFLAGS+set}" - ac_save_CFLAGS="$CFLAGS" - CFLAGS= - AC_PROG_CC_G - if test "$ac_test_CFLAGS" = set; then - CFLAGS="$ac_save_CFLAGS" - elif test $ac_cv_prog_cc_g = yes; then - CFLAGS="-g -O2" - else - CFLAGS="-O2" - fi - if test "$ac_test_CXXFLAGS" != set; then - CXXFLAGS='$(CFLAGS)' - fi -else - GCC= - test "${CFLAGS+set}" = set || CFLAGS="-g" -fi -]) - -AC_CANONICAL_SYSTEM - -LIB_AC_PROG_CC - -AC_SUBST(build_exeext) - -AC_OUTPUT(Makefile) diff --git a/winsup/doc/cygserver.sgml b/winsup/doc/cygserver.sgml deleted file mode 100644 index 27e538b2a..000000000 --- a/winsup/doc/cygserver.sgml +++ /dev/null @@ -1,274 +0,0 @@ -<sect1 id="using-cygserver"><title>Cygserver</title> - -<sect2 id="what-is-cygserver"><title>What is Cygserver?</title> - -<para> - Cygserver is a program which is designed to run as a background service. - It provides Cygwin applications with services which require security - arbitration or which need to persist while no other cygwin application - is running. -</para> -<para> - The implemented services so far are: -</para> -<itemizedlist mark="bullet"> - <listitem><para>Control slave tty/pty handle dispersal from tty owner to other - processes without compromising the owner processes' security.</para></listitem> - <listitem><para>XSI IPC Message Queues.</para></listitem> - <listitem><para>XSI IPC Semaphores.</para></listitem> - <listitem><para>XSI IPC Shared Memory.</para></listitem> -</itemizedlist> - -</sect2> - -<sect2 id="cygserver-command-line"><title>Cygserver command line options</title> - -<para> - Options to Cygserver take the normal UNIX-style `-X' or `--longoption' form. - Nearly all options have a counterpart in the configuration file (see below) - so setting them on the command line isn't really necessary. Command line - options override settings from the Cygserver configuration file. -</para> -<para> - The one-character options are prepended by a single dash, the long variants - are prepended with two dashes. Arguments to options are marked in angle - brackets below. These are not part of the actual syntax but are used only to - denote the arguments. Note that all arguments are required. Cygserver - has no options with optional arguments. -</para> -<para> - The recognized options are: -</para> - -<itemizedlist spacing="compact"> - <screen>-f, --config-file <file></screen> - <para> - Use <file> as configuration file instead of the default configuration - line. The default configuration file is /etc/cygserver.conf, typically. - The --help and --version options will print the default configuration - pathname. - </para> - <para> - This option has no counterpart in the configuration file, for obvious - reasons. - </para> -<listitem> - <screen>-c, --cleanup-threads <num></screen> - <para> - Number of threads started to perform cleanup tasks. Default is 2. - Configuration file option: kern.srv.cleanup_threads - </para> -</listitem> -<listitem> - <screen>-r, --request-threads <num></screen> - <para> - Number of threads started to serve application requests. Default is 10. - The -c and -r options can be used to play with Cygserver's performance - under heavy load conditions or on slow machines. - Configuration file option: kern.srv.request_threads - </para> -</listitem> -<listitem> - <screen>-d, --debug</screen> - <para> - Log debug messages to stderr. These will clutter your stderr output with - a lot of information, typically only useful to developers. - </para> -</listitem> -<listitem> - <screen>-e, --stderr</screen> - <para> - Force logging to stderr. This is the default if stderr is connected to - a tty. Otherwise, the default is logging to the system log. By using - the -e, -E, -y, -Y options (or the appropriate settings in the - configuration file), you can explicitely set the logging output as you - like, even to both, stderr and syslog. - Configuration file option: kern.log.stderr - </para> -</listitem> -<listitem> - <screen>-E, --no-stderr</screen> - <para> - Don't log to stderr. Configuration file option: kern.log.stderr - </para> -</listitem> -<listitem> - <screen>-y, --syslog</screen> - <para> - Force logging to the system log. This is the default, if stderr is not - connected to a tty, e. g. redirected to a file. Note, that on 9x/Me - systems the syslog is faked by a file C:\CYGWIN_SYSLOG.TXT. - Configuration file option: kern.log.syslog - </para> -</listitem> -<listitem> - <screen>-Y, --no-syslog</screen> - <para> - Don't log to syslog. Configuration file option: kern.log.syslog - </para> -</listitem> -<listitem> - <screen>-l, --log-level <level></screen> - <para> - Set the verbosity level of the logging output. Valid values are between - 1 and 7. The default level is 6, which is relatively chatty. If you set - it to 1, you will get only messages which are printed under severe conditions, - which will result in stopping Cygserver itself. - Configuration file option: kern.log.level - </para> -</listitem> -<listitem> - <screen>-m, --no-sharedmem</screen> - <para> - Don't start XSI IPC Shared Memory support. If you don't need XSI IPC - Shared Memory support, you can switch it off here. - Configuration file option: kern.srv.sharedmem - </para> -</listitem> -<listitem> - <screen>-q, --no-msgqueues</screen> - <para> - Don't start XSI IPC Message Queues. - Configuration file option: kern.srv.msgqueues - </para> -</listitem> -<listitem> - <screen>-s, --no-semaphores</screen> - <para> - Don't start XSI IPC Semaphores. - Configuration file option: kern.srv.semaphores - </para> -</listitem> -<listitem> - <screen>-S, --shutdown</screen> - <para> - Shutdown a running daemon and exit. Other methods are sending a SIGHUP - to the Cygserver PID or, if running as service under NT, calling - `net stop cygserver' or `cygrunsrv -E cygserver'. - </para> -</listitem> -<listitem> - <screen>-h, --help</screen> - <para> - Output usage information and exit. - </para> -</listitem> -<listitem> - <screen>-v, --version</screen> - <para> - Output version information and exit. - </para> -</listitem> -</itemizedlist> - -</sect2> - -<sect2 id="start-cygserver"><title>How to start Cygserver</title> - -<para> - Before you run Cygserver for the first time, you should run the - /usr/bin/cygserver-config script once. It creates the default - configuration file and, upon request, installs Cygserver as service - when running under NT. The script only performs a default install, - with no further options given to Cygserver when running as service. - Due to the wide configurability by changing the configuration file, - that's typically not necessary. -</para> -<para> - On Windows 9x/Me, just start Cygserver in any console window. It's - advisable to redirect stderr to a file of choice (e. g. - /var/log/cygserver.log) and to use the -e and -Y options or the - set the appropriate settings in the configuration file (see below). -</para> -<para> - On Windows NT/2000/XP or 2003, you should always run Cygserver as a - service under LocalSystem account. This is the way it is installed - for you by the /usr/bin/cygserver-config script. -</para> - -</sect2> - -<sect2 id="use-cygserver"><title>How to use the Cygserver services</title> - -<para> - The Cygserver services are used by Cygwin applications only if you - set the environment variable CYGWIN to contain the string "server". - You must do this before starting the application. -</para> -<para> - Typically, you don't need any other option, so it's ok to set CYGWIN - just to "server". It is not necessary to set the CYGWIN environment - variable prior to starting the Cygserver process itself, but it won't - hurt to do so. -</para> -<para> - The easiest way is to set the environment variable CYGWIN to the values - you want in the Windows system environment and to reboot the machine. - This is advisable, since it allows you to set the variable once and - then forget about it. It also ensures that services as well as desktop - applications have the same setting. -</para> -<para> - If you don't want that for whatever reason, you can set the - variable in the /cygwin.bat file which is used in the net distribution, - to start a Cygwin bash from the desktop. In that file, you can set - the CYGWIN variable using Windows command line interpreter syntax, e. g.: -</para> -<para> - <screen> - set CYGWIN=server - </screen> -</para> -<para> - If you don't set CYGWIN in the system environment, but you're running - other Cygwin services, these services need to get that CYGWIN value by - setting the environment using the appropriate cygrunsrv option '-e' when - installing the service. Example installing a service 'foo': -</para> -<para> - <screen> - cygrunsrv -I foo -p /usr/sbin/foo -e "CYGWIN=server" - </screen> -</para> - -</sect2> - -<sect2 id="cygserver-config"><title>The Cygserver configuration file</title> - -<para> - Cygserver has many options, which allow to customize the server - to your needs. Customization is accomplished by editing the configuration - file, which is by default /etc/cygserver.conf. This file is read only - once on startup of Cygserver. There's no option to re-read the file on - runtime by, say, sending a signal to Cygserver. -</para> -<para> - The configuration file determines how Cygserver operates. There are - options which set the number of threads running in parallel, options - for setting how and what to log and options to set various maximum - values for the IPC services. -</para> -<para> - The default configuration file delivered with Cygserver is installed - to /etc/defaults/etc. The /usr/bin/cygserver-config script copies it to - /etc, giving you the option to overwrite an already existing file or to - leave it alone. Therefore, the /etc file is safe to be changed by you, - since it will not be overwritten by a later update installation. -</para> -<para> - The default configuration file contains many comments which describe - everything needed to understand the settings. A comment at the start of the - file describes the syntax rules for the file. The default options are shown - in the file but are commented out. -</para> -<para> - It is generally a good idea to uncomment only options which you intend to - change from the default values. Since reading the options file on Cygserver - startup doesn't take much time, it's also considered good practice to keep - all other comments in the file. This keeps you from searching for clues - in other sources. -</para> - -</sect2> - -</sect1> diff --git a/winsup/doc/cygwin-api.in.sgml b/winsup/doc/cygwin-api.in.sgml deleted file mode 100644 index 08589402e..000000000 --- a/winsup/doc/cygwin-api.in.sgml +++ /dev/null @@ -1,58 +0,0 @@ -<?xml version="1.0"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" -"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"[]> - -<book id="cygwin-api"> - - <bookinfo> - <date>1998-08-31</date> - <title>Cygwin API Reference</title> - <authorgroup> - <author> - <firstname>DJ</firstname> - <surname>Delorie</surname> - </author> - <author> - <firstname>Geoffrey</firstname> - <surname>Noer</surname> - </author> - </authorgroup> - - DOCTOOL-INSERT-legal - - <revhistory> - <revision> - <revnumber>0.0</revnumber> - <date>1998-08-31</date> - <authorinitials>dj</authorinitials> - <revremark>Initial revision</revremark> - </revision> - <revision> - <revnumber>0.5.0</revnumber> - <date>1998-12-17</date> - <authorinitials>noer</authorinitials> - <revremark>Add pthread, sem calls. Change revnumber to - three-part number: Cygwin API major, Cygwin API minor, Doc rev - number. Starts out at 0.5.0.</revremark> - </revision> - </revhistory> - </bookinfo> - - <toc></toc> - -<chapter id="compatibility"><title>Compatibility</title> -DOCTOOL-INSERT-std-ansi -DOCTOOL-INSERT-std-posix -DOCTOOL-INSERT-std-misc -</chapter> - -<chapter id="cygwin-functions"><title>Cygwin Functions</title> - -<para>These functions are specific to Cygwin itself, and probably -won't be found anywhere else. </para> - -DOCTOOL-INSERT-func- - -</chapter> - -</book> diff --git a/winsup/doc/cygwin-ug-net.in.sgml b/winsup/doc/cygwin-ug-net.in.sgml deleted file mode 100644 index c56ad8e14..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.2//EN" -"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"[]> - -<book id="cygwin-ug-net"> - - <bookinfo> - <date>2003-04-08</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.in.sgml b/winsup/doc/cygwin-ug.in.sgml deleted file mode 100644 index 284d56bd1..000000000 --- a/winsup/doc/cygwin-ug.in.sgml +++ /dev/null @@ -1,72 +0,0 @@ -<?xml version="1.0"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"[ - <!ENTITY cygnus-copyright "<year>1999,2000,2001</year> - <holder>Red Hat, Inc.</holder>"> - <!ENTITY cygnus-code-copyright " -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -Copyright (C) 1998, 1999, 2000, 2001 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>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 - - <revhistory> - <revision> - <revnumber>0.0</revnumber> - <date>1998-08-31</date> - <authorinitials>dj</authorinitials> - <revremark>Initial revision</revremark> - </revision> - <revision> - <revnumber>20.1.0</revnumber> - <date>1999-02-08</date> - <authorinitials>Pierre.Humblet@eurecom.fr</authorinitials> - <revremark>Expand, describe Cygwin 20.1</revremark> - </revision> - </revhistory> - </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.dsl deleted file mode 100644 index 35156d73f..000000000 --- a/winsup/doc/cygwin.dsl +++ /dev/null @@ -1,16 +0,0 @@ -<?xml version='1.0'?> -<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" - xmlns:fo="http://www.w3.org/1999/XSL/Format" - version='1.0'> - -<!-- See /usr/share/docbook-xsl/params/ --> -<xsl:param name="chunker.output.doctype-public" - select="'-//W3C//DTD HTML 4.01 Transitional//EN'" /> -<xsl:param name="html.stylesheet" select="'docbook.css'"/> -<xsl:param name="use.id.as.filename" select="1" /> -<xsl:param name="root.filename" select="@id" /> - -<!-- TODO: make URLs and paths wrap with PDF output --> - -</xsl:stylesheet> - diff --git a/winsup/doc/cygwinenv.sgml b/winsup/doc/cygwinenv.sgml deleted file mode 100644 index 63f927e73..000000000 --- a/winsup/doc/cygwinenv.sgml +++ /dev/null @@ -1,218 +0,0 @@ -<sect1 id="using-cygwinenv"><title>The <envar>CYGWIN</envar> environment -variable</title> - -<para>The <envar>CYGWIN</envar> environment variable is used to configure -many global settings for the Cygwin runtime system. It contains the options -listed below, separated by blank characters. Many options can be turned off -by prefixing with <literal>no </literal>.</para> - -<itemizedlist mark="bullet"> -<listitem> -<para><envar>(no)binmode</envar> - if set, non-disk -(e.g. pipe and COM ports) file opens default to binary mode -(no CRLF translation) instead of text mode. Defaults to set (binary -mode). By default, devices are opened in binary mode, so this option -has little effect on normal cygwin operations. - -It does affect two things, however. For non-NTFS filesystems, this -option will control the line endings for standard output/input/error -for redirection from the Windows command shell. It will also affect -the default translation mode of a pipe, although most shells set the -pipe to binary by default. -</para> -</listitem> -<listitem> -<para><envar>check_case:level</envar> - THIS OPTION IS DEPRECATED. -Don't use it unless you know what you're doing and don't see any way -around it. And even then, this option is error prone, slows down Cygwin -and not well maintained. This option controls the behavior of -Cygwin when a user tries to open or create a file using a case different from -the case of the path as saved on the disk. -<literal>level</literal> is one of <literal>relaxed</literal>, -<literal>adjust</literal> and <literal>strict</literal>.</para> -<itemizedlist mark="bullet"> -<listitem> -<para><envar>relaxed</envar> which is the default behaviour simply -ignores case. That's the default for native Windows applications as well.</para> -</listitem> -<listitem> -<para><envar>adjust</envar> behaves mostly invisible. The POSIX input -path is internally adjusted in case, so that the resulting DOS path uses the -correct case throughout. You can see the result when changing the directory -using a wrong case and calling <command>/bin/pwd</command> afterwards.</para> -</listitem> -<listitem> -<para><envar>strict</envar> results in a error message if the case -isn't correct. Trying to open a file <filename>Foo</filename> while a file -<filename>fOo</filename> exists results in a "no such file or directory" -error. Trying to create a file <filename>BAR</filename> while a file -<filename>Bar</filename> exists results in a "Filename exists with different -case" error.</para> -</listitem> -</itemizedlist> -</listitem> - -<listitem> -<para><envar>codepage:[ansi|oem]</envar> - Windows console -applications can use different character sets (codepages) for drawing -characters. The first setting, called "ansi", is the default. -This character set contains various forms of latin characters used -in European languages. The name originates from the ANSI Latin1 -(ISO 8859-1) standard, used in Windows 1.0, though the character -sets have since diverged from any standard. The second setting -selects an older, DOS-based character set, containing various line -drawing and special characters. It is called "oem" since it was -originally encoded in the firmware of IBM PCs by original -equipment manufacturers (OEMs). If you find that some characters -(especially non-US or 'graphical' ones) do not display correctly in -Cygwin, you can use this option to select an appropriate codepage. -</para> -</listitem> - -<listitem> -<para><envar>(no)envcache</envar> - If set, environment variable -conversions (between Win32 and POSIX) are cached. Note that this is may -cause problems if the mount table changes, as the cache is not invalidated -and may contain values that depend on the previous mount table -contents. Defaults to set.</para> -</listitem> -<listitem> -<para><envar>(no)export</envar> - if set, the final values of these -settings are re-exported to the environment as <envar>CYGWIN</envar> again. -Defaults to off.</para> -</listitem> -<listitem> -<para> -<envar>error_start:Win32filepath</envar> - if set, runs -<filename>Win32filepath</filename> when cygwin encounters a fatal error, -which is useful for debugging. <filename>Win32filepath</filename> is -usually set to the path to <command>gdb</command> or -<command>dumper</command>, for example -<filename>C:\cygwin\bin\gdb.exe</filename>. -There is no default set. -</para> -</listitem> -<listitem> -<para><envar>forkchunk:32768</envar> - causes the <function>fork()</function> -to copy memory some number of bytes at a time, in the above example -32768 bytes (32Kb) at a time. The default is to copy as many bytes as -possible, which is preferable in most cases but may slow some older systems -down. -</para> -</listitem> -<listitem> -<para><envar>fork_retry:n</envar> - causes the <function>fork()</function> -to retry n times when a child process fails due to certain specific errors. -</para> -</listitem> -<listitem> -<para><envar>(no)glob[:ignorecase]</envar> - if set, command line arguments -containing UNIX-style file wildcard characters (brackets, question mark, -asterisk, escaped with \) are expanded into lists of files that match -those wildcards. -This is applicable only to programs running from a DOS command line prompt. -Default is set.</para> -<para>This option also accepts an optional <literal>[no]ignorecase</literal> modifer. -If supplied, wildcard matching is case insensitive. The default is <literal>noignorecase</literal></para> -</listitem> -<listitem> -<para><envar>(no)ntea</envar> - if set, use NT Extended Attributes to -store UNIX-like inode information. -This option only operates under Windows NT. Defaults to not set. -Only FAT and NTFS support Extended Attributes, not FAT32, so it's -of no use there. Furthermore, on NTFS partitions ntsec, which provides -real permissions, overrides ntea, which only provides faked permissions. -So setting ntea only makes sense if you either have FAT partitions, -or if you switch off ntsec explicitely. </para> -<warning><title>Warning!</title> <para>This may create additional -<emphasis>large</emphasis> files on FAT partitions.</para></warning> -</listitem> -<listitem> -<para><envar>(no)ntsec</envar> - if set, use the NT security -model to set UNIX-like permissions on files and processes. The -file permissions can only be set on NTFS partitions. FAT/FAT32 don't -support the NT file security. Defaults to set. For more information, read -the documentation in <xref linkend="ntsec"></xref>.</para> -</listitem> -<listitem> -<para><envar>(no)smbntsec</envar> - if set, use <envar>ntsec</envar> on remote -drives as well (default is "nosmbntesc"). When setting "smbntsec" there's -a chance that you get problems with Samba shares so you should use this -option with care. One reason for a non working <envar>ntsec</envar> on -remote drives could be insufficient permissions of the users. The requires -user rights are somewhat dangerous (SeRestorePrivilege), so it's not always -an option to grant that rights to users. However, this shouldn't be a -problem in NT domain environments.</para> -</listitem> -<listitem> -<para><envar>(no)reset_com</envar> - if set, serial ports are reset -to 9600-8-N-1 with no flow control when used. This is done at open -time and when handles are inherited. Defaults to set.</para> -</listitem> -<listitem> -<para><envar>(no)server</envar> - if set, allows client applications -to use the Cygserver facilities. This option must be enabled explicitely -on the client side, otherwise your applications won't be able to use the -XSI IPC function calls (<function>msgget</function>, -<function>semget</function>, <function>shmget</function>, and friends) -successfully. These function calls will return with -<literal>ENOSYS</literal>, "Bad system call". -</para> -</listitem> -<listitem> -<para><envar>(no)strip_title</envar> - if set, strips the directory -part off the window title, if any. Default is not set.</para> -</listitem> -<listitem> -<para><envar>(no)title</envar> - if set, the title bar -reflects the name of the program currently running. Default is not -set. Note that under Win9x the title bar is always enabled and it is -stripped by default, but this is because of the way Win9x works. In -order not to strip, specify <literal>title</literal> or <literal>title -nostrip_title</literal>.</para> -</listitem> -<listitem> -<para><envar>(no)transparent_exe</envar> - EXPERIMENTAL. Only use this -option if you're confident to be able to live with the consequences. If -set, several additional functions in Cygwin will handle files with .exe -suffix transparently. These functions are <function>link(2)</function>, -<function>open(2)</function>, <function>rename(2)</function>, -<function>symlink(2)</function>, <function>unlink(2)</function>, -<function>pathconf(3)</function>. So far, these functions have been -treated as too dangerous to act on files with .exe suffix if the .exe -suffix wasn't given explicitely in the file name argument, and this is -still the case if the transparent_exe option is not set. Default is not -set.</para> -</listitem> -<listitem> -<para><envar>(no)traverse</envar> - This option only affects NT systems. -If set, Cygwin handles file permissions so that the parent directories' -permissions are checked, as it's default on POSIX systems. If not set, -only the file's own permissions are taken into account. This is the -default on Windows and called "bypass traverse checking". Default was -"traverse" in version 1.5.13 and 1.5.14. Beginning with 1.5.15, traverse -checking is disabled again since it's not correctly implemented by Microsoft -and it's behaviour is getting worse with each new OS version. Unprivileged -terminal server sessions are practically impossible with traverse checking -switched on. So, use at your own risk.</para> -</listitem> -<listitem> -<para><envar>(no)tty</envar> - if set, Cygwin enables extra support -(i.e., termios) for UNIX-like ttys in the Windows console. -It is not compatible with some Windows programs. -Defaults to not set, in which case the tty is opened in text mode. -Note that this has been changed such that ^D works as -expected instead of ^Z, and is settable via <command>stty</command>. -This option must be specified before starting a Cygwin shell -and it cannot be changed in the shell. It should not be set when using -other terminals (i.e., rxvt or xterm). -</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 set.</para> -</listitem> -</itemizedlist> -</sect1> diff --git a/winsup/doc/dll.sgml b/winsup/doc/dll.sgml deleted file mode 100644 index d5578ff19..000000000 --- a/winsup/doc/dll.sgml +++ /dev/null @@ -1,141 +0,0 @@ -<sect1 id="dll"><title>Building and Using DLLs</title> - -<para>DLLs are Dynamic Link Libraries, which means that they're linked -into your program at run time instead of build time. There are three -parts to a DLL:</para> - -<itemizedlist spacing="compact"> -<listitem><para> the exports </para></listitem> -<listitem><para> the code and data </para></listitem> -<listitem><para> the import library </para></listitem> -</itemizedlist> - -<para>The code and data are the parts you write - functions, -variables, etc. All these are merged together, like if you were -building one big object files, and put into the dll. They are not -put into your .exe at all.</para> - -<para>The exports contains a list of functions and variables that the -dll makes available to other programs. Think of this as the list of -"global" symbols, the rest being hidden. Normally, you'd create this -list by hand with a text editor, but it's possible to do it -automatically from the list of functions in your code. The -<filename>dlltool</filename> program creates the exports section of -the dll from your text file of exported symbols.</para> - -<para>The import library is a regular UNIX-like -<filename>.a</filename> library, but it only contains the tiny bit of -information needed to tell the OS how your program interacts with -("imports") the dll. This information is linked into your -<filename>.exe</filename>. This is also generated by -<filename>dlltool</filename>.</para> - -<sect2 id="dll-build"><title>Building DLLs</title> - -<para>This page gives only a few simple examples of gcc's DLL-building -capabilities. To begin an exploration of the many additional options, -see the gcc documentation and website, currently at -<ulink url="http://gcc.gnu.org/">http://gcc.gnu.org/</ulink> -</para> - -<para>Let's go through a simple example of how to build a dll. -For this example, we'll use a single file -<filename>myprog.c</filename> for the program -(<filename>myprog.exe</filename>) and a single file -<filename>mydll.c</filename> for the contents of the dll -(<filename>mydll.dll</filename>).</para> - -<para>Fortunately, with the latest gcc and binutils the process for building a dll -is now pretty simple. Say you want to build this minimal function in mydll.c:</para> - -<screen> -#include <stdio.h> - -int -hello() -{ - printf ("Hello World!\n"); -} -</screen> - -<para>First compile mydll.c to object code:</para> - -<screen>gcc -c mydll.c</screen> - -<para>Then, tell gcc that it is building a shared library:</para> - -<screen>gcc -shared -o mydll.dll mydll.o</screen> - -<para> -That's it! To finish up the example, you can now link to the -dll with a simple program: -</para> - -<screen> -int -main () -{ - hello (); -} -</screen> - -<para> -Then link to your dll with a command like: -</para> - -<screen>gcc -o myprog myprog.ca -L./ -lmydll</screen> - -<para>However, if you are building a dll as an export library, -you will probably want to use the complete syntax:</para> - -<screen>gcc -shared -o cyg${module}.dll \ - -Wl,--out-implib=lib${module}.dll.a \ - -Wl,--export-all-symbols \ - -Wl,--enable-auto-import \ - -Wl,--whole-archive ${old_libs} \ - -Wl,--no-whole-archive ${dependency_libs}</screen> - -<para> -The name of your library is <literal>${module}</literal>, prefixed with -<literal>cyg</literal> for the DLL and <literal>lib</literal> for the -import library. Cygwin DLLs use the <literal>cyg</literal> prefix to -differentiate them from native-Windows MinGW DLLs, see -<ulink url="http://mingw.org">the MinGW website</ulink> for more details. -<literal>${old_libs}</literal> are all -your object files, bundled together in static libs or single object -files and the <literal>${dependency_libs}</literal> are import libs you -need to link against, e.g -<userinput>'-lpng -lz -L/usr/local/special -lmyspeciallib'</userinput>. -</para> -</sect2> - -<sect2 id="dll-link"><title>Linking Against DLLs</title> - -<para>If you have an existing DLL already, you need to build a -Cygwin-compatible import library. If you have the source to compile -the DLL, see <xref linkend="dll-build"></xref> for details on having -<filename>gcc</filename> build one for you. If you do not have the -source or a supplied working import library, you can get most of -the way by creating a .def file with these commands (you might need to -do this in <filename>bash</filename> for the quoting to work -correctly):</para> - -<screen> -echo EXPORTS > foo.def -nm foo.dll | grep ' T _' | sed 's/.* T _//' >> foo.def -</screen> - -<para>Note that this will only work if the DLL is not stripped. -Otherwise you will get an error message: "No symbols in -foo.dll".</para> - -<para>Once you have the <filename>.def</filename> file, you can create -an import library from it like this:</para> - -<screen> -dlltool --def foo.def --dllname foo.dll --output-lib foo.a -</screen> - -</sect2> - -</sect1> diff --git a/winsup/doc/doctool.c b/winsup/doc/doctool.c deleted file mode 100644 index 0a5060c76..000000000 --- a/winsup/doc/doctool.c +++ /dev/null @@ -1,622 +0,0 @@ -/* doctool.c - - Copyright 1998,1999,2000,2001,2006 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. */ - -#include <stdio.h> -#include <stdlib.h> -#include <string.h> -#include <dirent.h> -#include <sys/types.h> -#include <sys/stat.h> -#include <utime.h> - -/* Building native in a cross-built directory is tricky. Be careful, -and beware that you don't have the full portability stuff available to -you (like libiberty) */ - -/*****************************************************************************/ - -/* The list of extensions that may contain SGML snippets. We check - both cases in case the file system isn't case sensitive enough. */ - -struct { - char *upper; - char *lower; - int is_sgml; -} extensions[] = { - { ".C", ".c", 0 }, - { ".CC", ".cc", 0 }, - { ".H", ".h", 0 }, - { ".SGML", ".sgml", 1 }, - { 0, 0, 0 } -}; - -/*****************************************************************************/ - -void -show_help() -{ - printf("Usage: doctool [-m] [-i] [-d dir] [-o outfile] [-s prefix] \\\n"); - printf(" [-b book_id] infile\n"); - printf(" -m means to adjust Makefile to include new dependencies\n"); - printf(" -i means to include internal snippets\n"); - printf(" -d means to recursively scan directory for snippets\n"); - printf(" -o means to output to file (else stdout)\n"); - printf(" -s means to suppress source dir prefix\n"); - printf(" -b means to change the <book id=\"book_id\">\n"); - printf("\n"); - printf("doctool looks for DOCTOOL-START and DOCTOOL-END lines in source,\n"); - printf("saves <foo id=\"bar\"> blocks, and looks for DOCTOOL-INSERT-bar\n"); - printf("commands to insert selected sections. IDs starting with int-\n"); - printf("are internal only, add- are added at the end of relevant sections\n"); - printf("or add-int- for both. Inserted sections are chosen by prefix,\n"); - printf("and sorted when inserted.\n"); - exit(1); -} - -/*****************************************************************************/ - -typedef struct Section { - struct Section *next; - struct OneFile *file; - char *name; - char internal; - char addend; - char used; - char **lines; - int num_lines; - int max_lines; -} Section; - -typedef struct OneFile { - struct OneFile *next; - char *filename; - int enable_scan; - int used; - Section *sections; -} OneFile; - -OneFile *file_list = 0; - -char *output_name = 0; -FILE *output_file = 0; - -char *source_dir_prefix = ""; -char *book_id = 0; - -int internal_flag = 0; - -/*****************************************************************************/ - -char * -has_string(char *line, char *string) -{ - int i; - while (*line) - { - for (i=0; line[i]; i++) - { - if (!string[i]) - return line; - if (line[i] != string[i]) - break; - } - line++; - } - return 0; -} - -int -starts_with(char *line, char *string) -{ - int i=0; - while (1) - { - if (!string[i]) - return 1; - if (!line[i] || line[i] != string[i]) - return 0; - i++; - } -} - -/*****************************************************************************/ - -#ifdef S_ISLNK -#define STAT lstat -#else -#define STAT stat -#endif - -void -scan_directory(dirname) - char *dirname; -{ - struct stat st; - char *name; - struct dirent *de; - DIR *dir = opendir(dirname); - if (!dir) - return; - while (de = readdir(dir)) - { - if (strcmp(de->d_name, ".") == 0 - || strcmp(de->d_name, "..") == 0) - continue; - - name = (char *)malloc(strlen(dirname)+strlen(de->d_name)+3); - strcpy(name, dirname); - strcat(name, "/"); - strcat(name, de->d_name); - - STAT(name, &st); - - if (S_ISDIR(st.st_mode) && strcmp(de->d_name, "CVS") != 0) - { - scan_directory(name); - } - - else if (S_ISREG(st.st_mode)) - { - char *dot = strrchr(de->d_name, '.'); - int i; - - if (dot) - { - for (i=0; extensions[i].upper; i++) - if (strcmp(dot, extensions[i].upper) == 0 - || strcmp(dot, extensions[i].lower) == 0) - { - OneFile *one = (OneFile *)malloc(sizeof(OneFile)); - one->next = file_list; - file_list = one; - one->filename = name; - one->enable_scan = ! extensions[i].is_sgml; - one->used = 0; - one->sections = 0; - } - } - } - } - closedir (dir); -} - -/*****************************************************************************/ - -void -scan_file(OneFile *one) -{ - FILE *f = fopen(one->filename, "r"); - int enabled = ! one->enable_scan; - char line[1000], *tag=0, *id=0, *tmp; - int taglen = 0; - Section *section = 0; - Section **prev_section_ptr = &(one->sections); - - if (!f) - { - perror(one->filename); - return; - } - - while (fgets(line, 1000, f)) - { - if (one->enable_scan) - { - /* source files have comment-embedded docs, check for them */ - if (has_string(line, "DOCTOOL-START")) - enabled = 1; - if (has_string(line, "DOCTOOL-END")) - enabled = 0; - } - if (!enabled) - continue; - - /* DOCTOOL-START - -<sect1 id="dt-tags"> -this is the doctool tags section. -</sect1> - - DOCTOOL-END */ - - if (!tag && line[0] == '<') - { - tag = (char *)malloc(strlen(line)+1); - id = (char *)malloc(strlen(line)+1); - if (sscanf(line, "<%s id=\"%[^\"]\">", tag, id) == 2) - { - if (strcmp(tag, "book") == 0 || strcmp(tag, "BOOK") == 0) - { - /* Don't want to "scan" these */ - return; - } - taglen = strlen(tag); - section = (Section *)malloc(sizeof(Section)); - /* We want chunks within single files to appear in that order */ - section->next = 0; - section->file = one; - *prev_section_ptr = section; - prev_section_ptr = &(section->next); - section->internal = 0; - section->addend = 0; - section->used = 0; - section->name = id; - if (starts_with(section->name, "add-")) - { - section->addend = 1; - section->name += 4; - } - if (starts_with(section->name, "int-")) - { - section->internal = 1; - section->name += 4; - } - section->lines = (char **)malloc(10*sizeof(char *)); - section->num_lines = 0; - section->max_lines = 10; - } - else - { - free(tag); - free(id); - tag = id = 0; - } - } - - if (tag && section) - { - if (section->num_lines >= section->max_lines) - { - section->max_lines += 10; - section->lines = (char **)realloc(section->lines, - section->max_lines * sizeof (char *)); - } - section->lines[section->num_lines] = (char *)malloc(strlen(line)+1); - strcpy(section->lines[section->num_lines], line); - section->num_lines++; - - if (line[0] == '<' && line[1] == '/' - && memcmp(line+2, tag, taglen) == 0 - && (isspace(line[2+taglen]) || line[2+taglen] == '>')) - { - /* last line! */ - tag = 0; - } - } - } - fclose(f); -} - -/*****************************************************************************/ - -Section ** -enumerate_matching_sections(char *name_prefix, int internal, int addend, int *count_ret) -{ - Section **rv = (Section **)malloc(12*sizeof(Section *)); - int count = 0, max=10, prefix_len = strlen(name_prefix); - OneFile *one; - int wildcard = 0; - - if (name_prefix[strlen(name_prefix)-1] == '-') - wildcard = 1; - - for (one=file_list; one; one=one->next) - { - Section *s; - for (s=one->sections; s; s=s->next) - { - int matches = 0; - if (wildcard) - { - if (starts_with(s->name, name_prefix)) - matches = 1; - } - else - { - if (strcmp(s->name, name_prefix) == 0) - matches = 1; - } - if (s->internal <= internal - && s->addend == addend - && matches - && ! s->used) - { - s->used = 1; - if (count >= max) - { - max += 10; - rv = (Section **)realloc(rv, max*sizeof(Section *)); - } - rv[count++] = s; - rv[count] = 0; - } - } - } - if (count_ret) - *count_ret = count; - return rv; -} - -/*****************************************************************************/ - -#define ID_CHARS "~@$%&()_-+[]{}:." - -void include_section(char *name, int addend); - -char * -unprefix(char *fn) -{ - int l = strlen(source_dir_prefix); - if (memcmp(fn, source_dir_prefix, l) == 0) - { - fn += l; - while (*fn == '/' || *fn == '\\') - fn++; - return fn; - } - return fn; -} - -void -parse_line(char *line, char *filename) -{ - char *cmd = has_string(line, "DOCTOOL-INSERT-"); - char *sname, *send, *id, *save; - if (!cmd) - { - if (book_id - && (starts_with(line, "<book") || starts_with(line, "<BOOK"))) - { - cmd = strchr(line, '>'); - if (cmd) - { - cmd++; - fprintf(output_file, "<book id=\"%s\">", book_id); - fputs(cmd, output_file); - return; - } - } - fputs(line, output_file); - return; - } - if (cmd != line) - fwrite(line, cmd-line, 1, output_file); - save = (char *)malloc(strlen(line)+1); - strcpy(save, line); - line = save; - - sname = cmd + 15; /* strlen("DOCTOOL-INSERT-") */ - for (send = sname; - *send && isalnum(*send) || strchr(ID_CHARS, *send); - send++); - id = (char *)malloc(send-sname+2); - memcpy(id, sname, send-sname); - id[send-sname] = 0; - include_section(id, 0); - - fprintf(output_file, "<!-- %s -->\n", unprefix(filename)); - - fputs(send, output_file); - free(save); -} - -int -section_sort(const void *va, const void *vb) -{ - Section *a = *(Section **)va; - Section *b = *(Section **)vb; - int rv = strcmp(a->name, b->name); - if (rv) - return rv; - return a->internal - b->internal; -} - -void -include_section(char *name, int addend) -{ - Section **sections, *s; - int count, i, l; - - sections = enumerate_matching_sections(name, internal_flag, addend, &count); - - qsort(sections, count, sizeof(sections[0]), section_sort); - for (i=0; i<count; i++) - { - s = sections[i]; - s->file->used = 1; - fprintf(output_file, "<!-- %s -->\n", unprefix(s->file->filename)); - for (l=addend; l<s->num_lines-1; l++) - parse_line(s->lines[l], s->file->filename); - if (!addend) - { - include_section(s->name, 1); - parse_line(s->lines[l], s->file->filename); - } - } - - free(sections); -} - -void -parse_sgml(FILE *in, char *input_name) -{ - static char line[1000]; - while (fgets(line, 1000, in)) - { - parse_line(line, input_name); - } -} - -/*****************************************************************************/ - -void -fix_makefile(char *output_name) -{ - FILE *in, *out; - char line[1000]; - int oname_len = strlen(output_name); - OneFile *one; - int used_something = 0; - struct stat st; - struct utimbuf times; - - stat("Makefile", &st); - - in = fopen("Makefile", "r"); - if (!in) - { - perror("Makefile"); - return; - } - - out = fopen("Makefile.new", "w"); - if (!out) - { - perror("Makefile.new"); - return; - } - - while (fgets(line, 1000, in)) - { - if (starts_with(line, output_name) - && strcmp(line+oname_len, ": \\\n") == 0) - { - /* this is the old dependency */ - while (fgets(line, 1000, in)) - { - if (strcmp(line+strlen(line)-2, "\\\n")) - break; - } - } - else - fputs(line, out); - } - fclose(in); - - for (one=file_list; one; one=one->next) - if (one->used) - { - used_something = 1; - break; - } - - if (used_something) - { - fprintf(out, "%s:", output_name); - for (one=file_list; one; one=one->next) - if (one->used) - fprintf(out, " \\\n\t%s", one->filename); - fprintf(out, "\n"); - } - - fclose(out); - - times.actime = st.st_atime; - times.modtime = st.st_mtime; - utime("Makefile.new", ×); - - if (rename("Makefile", "Makefile.old")) - return; - if (rename("Makefile.new", "Makefile")) - rename("Makefile.old", "Makefile"); -} - -/*****************************************************************************/ - -int -main(argc, argv) - int argc; - char **argv; -{ - int i; - OneFile *one; - FILE *input_file; - int fix_makefile_flag = 0; - - while (argc > 1 && argv[1][0] == '-') - { - if (strcmp(argv[1], "-h") == 0 || strcmp(argv[1], "--help") == 0) - { - show_help(); - } - else if (strcmp(argv[1], "-i") == 0) - { - internal_flag = 1; - } - else if (strcmp(argv[1], "-m") == 0) - { - fix_makefile_flag = 1; - } - else if (strcmp(argv[1], "-d") == 0 && argc > 2) - { - scan_directory(argv[2]); - argc--; - argv++; - } - else if (strcmp(argv[1], "-o") == 0 && argc > 2) - { - output_name = argv[2]; - argc--; - argv++; - } - else if (strcmp(argv[1], "-s") == 0 && argc > 2) - { - source_dir_prefix = argv[2]; - argc--; - argv++; - } - else if (strcmp(argv[1], "-b") == 0 && argc > 2) - { - book_id = argv[2]; - argc--; - argv++; - } - - argc--; - argv++; - } - - for (one=file_list; one; one=one->next) - { - scan_file(one); - } - - input_file = fopen(argv[1], "r"); - if (!input_file) - { - perror(argv[1]); - return 1; - } - - if (output_name) - { - output_file = fopen(output_name, "w"); - if (!output_file) - { - perror(output_name); - return 1; - } - } - else - { - output_file = stdout; - output_name = "<stdout>"; - } - - parse_sgml(input_file, argv[1]); - - if (output_file != stdout) - fclose(output_file); - - if (fix_makefile_flag) - fix_makefile(output_name); - - return 0; -} diff --git a/winsup/doc/doctool.txt b/winsup/doc/doctool.txt deleted file mode 100644 index c89e39243..000000000 --- a/winsup/doc/doctool.txt +++ /dev/null @@ -1,146 +0,0 @@ -Doctool - -DJ Delorie <dj@cygnus.com> - -These are the instructions for using doctool. Yes, I should have -written them *in* DocBook, but hey, I was in a hurry. - -OK, doctool is a program that gathers snippets of a docbook document and -puts them all together in the right order. There are three -places that it gets snippets from: - -1. The document that you tell it you want "finished" - -2. blocks of SGML in *.sgml files - -3. comments in source code - -The first of these is the template file, which is to say, it's a -normal SGML file (sort of). This file is the first one read, and -includes such things as your <book> tags etc. It contains commands to -doctool to tell it where to put the other parts. - -The second, the *.sgml files, contain one or more blocks of SGML. -To work with doctool, each of these snippets must begin and end -with matching tags, must have an id="" attribute, and the start/end -tags must begin at the beginning of the line. For example: - -<foo id="frob-45"> - stuff goes here -</foo> -<bar id="frob-48"> - stuff goes here -</bar> - -In this example, the file contains two snippets, one marked by "foo" -and one barked by "bar", with id's "from-45" and "from-48". Note that -I made up the foo and bar tags. You'd usually use a <sect1> tag or -something useful like that. Stuff outside the blocks is ignored. - -The third is simply an encapsulation of the second in comments, like this: - -/* DOCTOOL-START -<foo id="frob-45"> - stuff goes here -</foo> -DOCTOOL-END */ - -The DOCTOOL-START and DOCTOOL-END things are special. Doctool uses -those to know which parts of which comments are useful, and which -parts are the useless source code stuff ;-) - - -OK, so now we've got all these snippets of SGML floating around. What -do we do with them? Well, inside the template document (#1 in our -list up there) you'd put text snippets that said "ok, put them -here". Each text snippet looks like this: - -DOCTOOL-INSERT-frob- - -Note that the "frob-" part tells doctool to pull in all the snippets -with IDs that start with "frob-", in alphabetical (well, asciibetical -at the moment) order. So, by saying "DOCTOOL-INSERT-frob-" you'd get -all the "frob-*" snippets, like "frob-45" and "frob-48". - -If you just said DOCTOOL-INSERT-frob, it inserts the snippet named -"frob" and no others. - -Note that no snippet will ever be inserted more than once, no matter -how many DOCTOOL-INSERTs you have. - -There's two other tricks doctool has. If it finds a snippet with an ID -like "int-*" (i.e. int-frob-45) that means that snippet of documentation -is for the "internal" version only. The "int-" is discarded, and if -the -i option is given to doctool, this snippet is treated as if the -int- wasn't there. Without the -i, the int-* snippets are ignored -completely. - -If a snippet has "add-" on it, like "add-frob-45", that's an addendum. -Each time a snippet named without the add- is found, doctool looks for -an addendum with exactly that same name (i.e. frob-45 looks for -add-frob-45). If it finds any, it puts them just before the last line -of the non-add snippet (so that it's *inside* the main snippet's -block, not after it). Example: - -<sect1 id="frob-45"> - some text -</sect1> -<sect1 id="add-frob-45"> - more text -</sect1> - -This would yield: - -<sect1 id="frob-45"> - some text - more text -</sect1> - -You should use the same outermost tags as the main snippet, but only -because it sets the proper nesting rules for what's enclosed. - -You can use add- and int- at the same time, but always do add-int- and -not int-add- (i.e. "add-int-frob-45"). - - -OK, now for doctool command line options. - --m tells doctool to "fix" the Makefile (not makefile) to include the -extra dependencies needed by the file you're generating. You need to -manually include dependencies on the Makefile itself and the template -file; doctool only includes the snippet files (sources etc) that it -actually pulled content from. Note: this isn't perfect! Someone can -come along and add a new snippet to a source file, and doctool would -never know. Sometimes, it's best to just rebuild the docs all the -time. - --i means to include snippets with the "int-" prefix on their IDs. Use -with -b to make internal and public versions from the same sources. - -"-d dir" tells doctool to scan all the files in that directory (and -subdirectories, recursively) for files that might contain snippets of -SGML. These include *.c, *.cc, *.h, and *.sgml. The idea is that -most of the documentation would be in a *.sgml file named after the -source (i.e. foo.c -> foo.sgml) but some commentary within the source -might be useful in the docs as well. SGML files (*.sgml) do not need -the DOCTOOL-START/END tags but the others do. - --o sets the output file. Without -o, the file goes to stdout (ick). - --s tells doctool to supress a "source directory prefix". What this -means is that, in the generated output doctool puts comments that say -where each snippet comes from (for debugging), which includes the full -path sometimes, but if you use -s, you can tell doctool to cut off -that prefix. For example, -/usr/people/dj/src/cygnus/latest/devo/winsup/foo.c might get shortened -to winsup/foo.c if you gave "-s -/usr/people/dj/src/cygnus/latest/devo/". Cygnus makefiles could -just use -s $(srcdir) most of the time. - --b changes the ID for the <book> tag. db2html uses the <book> tag's -ID as the default subdirectory name and/or html file name to create -the book with. You'd need this to generate two books (internal vs -public) from the same source. - -The only other thing you'd add to the command line is the ONE template -file you want to pull in. diff --git a/winsup/doc/effectively.sgml b/winsup/doc/effectively.sgml deleted file mode 100644 index fd0c0d447..000000000 --- a/winsup/doc/effectively.sgml +++ /dev/null @@ -1,211 +0,0 @@ -<sect1 id="using-effectively"> -<title>Using Cygwin effectively with Windows</title> - -<para> -Cygwin is not a full operating system, and so must rely on Windows for -accomplishing some tasks. For example, Cygwin provides a POSIX view -of the Windows filesystem, but does not provide filesystem drivers of -its own. Therefore part of using Cygwin effectively is learning to use -Windows effectively. -Many Windows utilities provide a good way to interact with Cygwin's -predominately command-line environment. For example, -<command>ipconfig.exe</command> provides information about network -configuration, and <command>net.exe</command> views and configures -network file and printer resources. Most of these tools -support the <literal>/?</literal> switch to display usage information. -</para> - -<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 95, 98, and ME have -very limited command-line configuration tools. Windows NT 4.0 has much -better coverage, which Windows 2000 and XP expanded. -Microsoft also provides free downloads for Windows NT 4.0 (the Resource Kit -Support Tools), Windows 2000 (the Resource Kit Tools), and XP (the -Windows Support Tools). Additionally, many independent sites such as -<ulink url="http://download.com.com">download.com</ulink>, -<ulink url="http://simtel.net">simtel.net</ulink>, -and <ulink url="http://sysinternals.com">sysinternals.com</ulink> -provide command-line utilities. A few Windows tools, such as -<command>find.exe</command> and <command>sort.exe</command>, -may conflict with the Cygwin versions; make sure that you use the full -path (<command>/usr/bin/find</command>) or that your Cygwin -<literal>bin</literal> directory comes first in your <envar>PATH</envar>. -</para> - -<sect2> <title>Pathnames</title> - -<para> -Windows programs do not understand POSIX pathnames, so any arguments -that reference the filesystem must be in Windows (or DOS) format or -translated. Cygwin provides the <command>cygpath</command> utility for -converting between Windows and POSIX paths. A complete description of its -options and examples of its usage are in <xref linkend="cygpath"></xref>, -including a shell script for starting Windows Explorer in any directory. -The same format works for most Windows programs, for example -<screen> -<literal>notepad.exe "$(cygpath -aw "Desktop/Phone Numbers.txt")"</literal> -</screen> -A few programs require a Windows-style, semicolon-delimited path list, -which <command>cygpath</command> can translate from a POSIX path with the -<literal>-p</literal> option. For example, a Java compilation from -<command>bash</command> might look like this: -<screen> -<literal>javac -cp "$(cygpath -pw "$CLASSPATH")" hello.java</literal> -</screen> -Since using quoting and subshells is somewhat awkward, it is often -preferable to use <command>cygpath</command> in shell scripts. -</para> - -</sect2> - -<sect2> <title>Console Programs</title> -<para> -Another issue is receiving output from or giving input to the console-based -Windows programs. Unfortunately, interacting with Windows console -applications is not a simple matter of using a translation utility. Windows -console applications and designed to run under <command>command.com</command> -or <command>cmd.exe</command>, and some do not deal gracefully with other -situations. Cygwin can receive console input only if it -is also running in a console (DOS box) since Windows does not provide -any way to attach to the backend of the console device. Another -traditional Unix input/output method, ptys (pseudo-terminals), are -supported by Cygwin but not entirely by Windows. The basic problem is -that a Cygwin pty is a pipe and some Windows applications do not like -having their input or output redirected to pipes. -</para> - -<para> -To help deal with these issues, Cygwin supports customizable levels of -Windows verses Unix compatibility behavior. To be most compatible with -Windows programs, use a DOS prompt, running only the occasional Cygwin -command or script. Next would be to run <command>bash</command> with -the default DOS box. To make Cygwin more Unix compatible in this case, -set <envar>CYGWIN=tty</envar> (see <xref linkend="using-cygwinenv"></xref>). -Alternatively, the optional <systemitem>rxvt</systemitem> package provides -a native-Windows version of the popular X11 terminal emulator (it is not -necessary to set <envar>CYGWIN=tty</envar> with <command>rxvt</command>). -Using <command>rxvt.exe</command> provides the most Unix-like environment, -but expect some compatibility problems with Windows programs. -</para> - -</sect2> - -<sect2> <title>Cygwin and Windows Networking</title> -<para> -Many popular Cygwin packages, such as <systemitem>ncftp</systemitem>, -<systemitem>lynx</systemitem>, and <systemitem>wget</systemitem>, require a -network connection. Since Cygwin relies on Windows for connectivity, -if one of these tools is not working as expected you may need to -troubleshoot using Windows tools. The first test is to see if you -can reach the URL's host with <command>ping.exe</command>, one of the -few utilities included with every Windows version since Windows 95. -If you chose to install the <systemitem>inetutils</systemitem> package, -you may have both -Windows and Cygwin versions of utilities such as <command>ftp</command> -and <command>telnet</command>. If you are having problems using one -of these programs, see if the alternate one works as expected. -</para> - -<para> -There are a variety of other programs available for specific situations. -If your system does not have an always-on network connection, you -may be interested in <command>rasdial.exe</command> (or alternatives for -Windows 95, 98, and ME) for automating dialup connections. -Users who frequently change their network -configuration can script these changes with <command>netsh.exe</command> -(Windows 2000 and XP). 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"> -Hummingbird SOCKS Proxy</ulink> may allow you to use Cygwin network -programs in your environment. -</para> - -</sect2> - -<sect2><title>The cygutils package</title> - -<para> -The optional <systemitem>cygutils</systemitem> package contains miscellaneous tools that are -small enough to not require their own package. It is not included in a -default Cygwin install; select it from the Utils category in -<command>setup.exe</command>. Several of the <systemitem>cygutils</systemitem> tools are useful -for interacting with Windows. -</para> - -<para> -One of the hassles of Unix-Windows interoperability is the different line -endings on text files. As mentioned in <xref linkend="using-textbinary"></xref>, -Unix tools such as <command>tr</command> can convert between CRLF and LF -endings, but <systemitem>cygutils</systemitem> provides several dedicated programs: -<command>conv</command>, <command>d2u</command>, <command>dos2unix</command>, -<command>u2d</command>, and <command>unix2dos</command>. Use the -<literal>--help</literal> switch for usage information. -</para> -</sect2> - -<sect2><title>Creating shortcuts with cygutils</title> -<para> -Another problem area is between Unix-style links, which link one file -to another, and Microsoft .lnk files, which provide a shortcut to a -file. They seem similar at first glance but, in reality, are fairly -different. By default, Cygwin uses a mechanism that creates symbolic -links that are compatible with standard Microsoft .lnk files. However, -they do not include much of the information that is available in a -standard Microsoft shortcut, such as the working directory, an icon, -etc. The <systemitem>cygutils</systemitem> package includes a -<command>mkshortcut</command> -utility for creating standard Microsoft .lnk files. -</para> - -<para> -If Cygwin handled these native shortcuts like any other symlink, -you could not archive Microsoft .lnk files into <command>tar</command> -archives and keep all the information in them. After unpacking, -these shortcuts would have lost all the extra information and would -be no different than standard Cygwin symlinks. Therefore these two types -of links are treated differently. Unfortunately, this means that the -usual Unix way of creating and using symlinks does not work with -Windows shortcuts. -</para> -</sect2> - -<sect2><title>Printing with cygutils</title> -<para> -There are several options for printing from Cygwin, including the -<command>lpr</command> found in <systemitem>cygutils</systemitem> (not to be confused with the -native Windows <command>lpr.exe</command>). The easiest way to use <systemitem>cygutils</systemitem>' -<command>lpr</command> is to specify a default device name in the -<envar>PRINTER</envar> environment variable. You may also specify a device -on the command line with the <literal>-d</literal> or <literal>-P</literal> -options, which will override the environment variable setting. -</para> - -<para> -A device name -may be a UNC path (<literal>\\server_name\printer_name</literal>), a reserved -DOS device name (<literal>prn</literal>, <literal>lpt1</literal>), or a -local port name that is mapped to a printer share. Note that forward slashes -may be used in a UNC path (<literal>//server_name/printer_name</literal>), -which is helpful when using <command>lpr</command> from a shell that uses -the backslash as an escape character. -</para> - -<para> -<command>lpr</command> sends raw data to the printer; no formatting is done. -Many, but not all, printers accept plain text as input. If your printer -supports PostScript, packages such as -<systemitem>a2ps</systemitem> and <systemitem>enscript</systemitem> can prepare -text files for printing. The <systemitem>ghostscript</systemitem> package also -provides some translation -from PostScript to various native printer languages. Additionally, a native -Windows application for printing PostScript, <command>gsprint</command>, is -available from the <ulink url="http://www.cs.wisc.edu/~ghost/">Ghostscript -website</ulink>. -</para> - -</sect2> - -</sect1> diff --git a/winsup/doc/faq-api.xml b/winsup/doc/faq-api.xml deleted file mode 100644 index 1a9c6c517..000000000 --- a/winsup/doc/faq-api.xml +++ /dev/null @@ -1,348 +0,0 @@ -<!-- faq-api.xml --> -<qandaentry id="faq.api.everything"> -<question><para>How does everything work?</para></question> -<answer> - -<para>There's a C library which provides a Unix-style API. The -applications are linked with it and voila - they run on Windows. -</para> -<para>The aim is to add all the goop necessary to make your apps run on -Windows into the C library. Then your apps should run on Unix and -Windows with no changes at the source level. -</para> -<para>The C library is in a DLL, which makes basic applications quite small. -And it allows relatively easy upgrades to the Win32/Unix translation -layer, providing that DLL changes stay backward-compatible. -</para> -<para>For a good overview of Cygwin, you may want to read the paper on Cygwin -published by the Usenix Association in conjunction with the 2d Usenix NT -Symposium in August 1998. It is available in HTML format on the project -WWW site. -</para> -</answer></qandaentry> - -<qandaentry id="faq.api.snapshots"> -<question><para>Are development snapshots for the Cygwin library available?</para></question> -<answer> - -<para>Yes. They're made whenever anything interesting happens inside the -Cygwin library (usually roughly on a nightly basis, depending on how much -is going on). They are only intended for those people who wish to -contribute code to the project. If you aren't going to be happy -debugging problems in a buggy snapshot, avoid these and wait for a real -release. The snapshots are available from -<ulink url="http://cygwin.com/snapshots/">http://cygwin.com/snapshots/</ulink>. -</para> -</answer></qandaentry> - -<qandaentry id="faq.api.cr-lf"> -<question><para>How is the DOS/Unix CR/LF thing handled?</para></question> -<answer> - -<para>Let's start with some background. -</para> -<para>In UNIX, a file is a file and what the file contains is whatever the -program/programmer/user told it to put into it. In Windows, a file is -also a file and what the file contains depends not only on the -program/programmer/user but also the file processing mode. -</para> -<para>When processing in text mode, certain values of data are treated -specially. A \n (new line) written to the file will prepend a \r -(carriage return) so that if you `printf("Hello\n") you in fact get -"Hello\r\n". Upon reading this combination, the \r is removed and the -number of bytes returned by the read is 1 less than was actually read. -This tends to confuse programs dependent on ftell() and fseek(). A -Ctrl-Z encountered while reading a file sets the End Of File flags even -though it truly isn't the end of file. -</para> -<para>One of Cygwin's goals is to make it possible to easily mix Cygwin-ported -Unix programs with generic Windows programs. As a result, Cygwin opens -files in text mode as is normal under Windows. In the accompanying -tools, tools that deal with binaries (e.g. objdump) operate in Unix -binary mode and tools that deal with text files (e.g. bash) operate in -text mode. -</para> -<para>Some people push the notion of globally setting the default processing -mode to binary via mount point options or by setting the CYGWIN -environment variable. But that creates a different problem. In -binary mode, the program receives all of the data in the file, including -a \r. Since the programs will no longer deal with these properly for -you, you would have to remove the \r from the relevant text files, -especially scripts and startup resource files. This is a porter "cop -out", forcing the user to deal with the \r for the porter. -</para> -<para>It is rather easy for the porter to fix the source code by supplying the -appropriate file processing mode switches to the open/fopen functions. -Treat all text files as text and treat all binary files as binary. To be -specific, you can select binary mode by adding <literal>O_BINARY</literal> to -the second argument of an <literal>open</literal> call, or -<literal>"b"</literal> to second argument of an <literal>fopen</literal> call. -You can also call <literal>setmode (fd, O_BINARY)</literal>. -</para> -<para>Note that because the open/fopen switches are defined by ANSI, they -exist under most flavors of Unix; open/fopen will just ignore the switch -since they have no meaning to UNIX. -</para> -<para>Explanation adapted from mailing list email by Earnie Boyd -<earnie_boyd (at) yahoo.com>. -</para> -</answer></qandaentry> - -<qandaentry id="faq.api.threads"> -<question><para>Is the Cygwin library multi-thread-safe?</para></question> -<answer> - -<para>Yes. -</para> -<para>There is also extensive support for 'POSIX threads', see the file -<literal>cygwin.din</literal> for the list of POSIX thread functions provided. -</para> -</answer></qandaentry> - -<qandaentry id="faq.api.winnt"> -<question><para>Why is some functionality only supported in Windows NT?</para></question> -<answer> - -<para>Windows 9x: n. -32 bit extensions and a graphical shell for a 16 bit patch to an -8 bit operating system originally coded for a 4 bit microprocessor, -written by a 2 bit company that can't stand 1 bit of competition. -</para> -<para>But seriously, Windows 9x lacks most of the security-related calls and -has several other deficiencies with respect to its version of the Win32 -API. See the calls.texinfo document for more information as to what -is not supported in Win 9x. -</para> -</answer></qandaentry> - -<qandaentry id="faq.api.fork"> -<question><para>How is fork() implemented?</para></question> -<answer> - -<para>Cygwin fork() essentially works like a non-copy on write version -of fork() (like old Unix versions used to do). Because of this it -can be a little slow. In most cases, you are better off using the -spawn family of calls if possible. -</para> -<para>Here's how it works: -</para> -<para>Parent initializes a space in the Cygwin process table for child. -Parent creates child suspended using Win32 CreateProcess call, giving -the same path it was invoked with itself. Parent calls setjmp to save -its own context and then sets a pointer to this in the Cygwin shared -memory area (shared among all Cygwin tasks). Parent fills in the child's -.data and .bss subsections by copying from its own address space into -the suspended child's address space. Parent then starts the child. -Parent waits on mutex for child to get to safe point. Child starts and -discovers if has been forked and then longjumps using the saved jump -buffer. Child sets mutex parent is waiting on and then blocks on -another mutex waiting for parent to fill in its stack and heap. Parent -notices child is in safe area, copies stack and heap from itself into -child, releases the mutex the child is waiting on and returns from the -fork call. Child wakes from blocking on mutex, recreates any mmapped -areas passed to it via shared area and then returns from fork itself. -</para> -</answer></qandaentry> - -<qandaentry id="faq.api.globbing"> -<question><para>How does wildcarding (globbing) work?</para></question> -<answer> - -<para>If the DLL thinks it was invoked from a DOS style prompt, it runs a -`globber' over the arguments provided on the command line. This means -that if you type <literal>LS *.EXE</literal> from DOS, it will do what you might -expect. -</para> -<para>Beware: globbing uses <literal>malloc</literal>. If your application defines -<literal>malloc</literal>, that will get used. This may do horrible things to you. -</para> -</answer></qandaentry> - -<qandaentry id="faq.api.symlinks"> -<question><para>How do symbolic links work?</para></question> -<answer> - -<para>Cygwin knows of two ways to create symlinks. -</para> -<para>The old method is the only valid one up to but not including version 1.3.0. -If it's enabled (from 1.3.0 on by setting `nowinsymlinks' in the environment -variable CYGWIN) Cygwin generates link files with a magic header. When you -open a file or directory that is a link to somewhere else, it opens the file -or directory listed in the magic header. Because we don't want to have to -open every referenced file to check symlink status, Cygwin marks symlinks -with the system attribute. Files without the system attribute are not -checked. Because remote samba filesystems do not enable the system -attribute by default, symlinks do not work on network drives unless you -explicitly enable this attribute. -</para> -<para>The new method which is introduced with Cygwin version 1.3.0 is enabled -by default or if `winsymlinks' is set in the environment variable CYGWIN. -Using this method, Cygwin generates symlinks by creating Windows shortcuts. -Cygwin created shortcuts have a special header (which is in that way never -created by Explorer) and the R/O attribute set. A DOS path is stored in -the shortcut as usual and the description entry is used to store the POSIX -path. While the POSIX path is stored as is, the DOS path has perhaps to be -rearranged to result in a valid path. This may result in a divergence -between the DOS and the POSIX path when symlinks are moved crossing mount -points. When a user changes the shortcut, this will be detected by Cygwin -and it will only use the DOS path then. While Cygwin shortcuts are shown -without the ".lnk" suffix in `ls' output, non-Cygwin shortcuts are shown -with the suffix. However, both are treated as symlinks. -</para> -<para>Both, the old and the new symlinks can live peacefully together since Cygwin -treats both as symlinks regardless of the setting of `(no)winsymlinks' in -the environment variable CYGWIN. -</para> -</answer></qandaentry> - -<qandaentry id="faq.api.executables"> -<question><para>Why do some files, which are not executables have the 'x' type.</para></question> -<answer> - -<para>When working out the Unix-style attribute bits on a file, the library -has to fill out some information not provided by the WIN32 API. -</para> -<para>It guesses that files ending in .exe and .bat are executable, as are -ones which have a "#!" as their first characters. -</para> -</answer></qandaentry> - -<qandaentry id="faq.api.secure"> -<question><para>How secure is Cygwin in a multi-user environment?</para></question> -<answer> - -<para>As of version 1.5.13, the Cygwin developers are not aware of any feature -in the cygwin dll that would allow users to gain privileges or to access -objects to which they have no rights under Windows. However there is no -guarantee that Cygwin is as secure as the Windows it runs on. Cygwin -processes share some variables and are thus easier targets of denial of -service type of attacks. -</para> -</answer></qandaentry> - -<qandaentry id="faq.api.net-functions"> -<question><para>How do the net-related functions work?</para></question> -<answer> - -<para><emphasis role='bold'>(Please note: This section has not yet been updated for the latest net release.)</emphasis> -</para> -<para>The network support in Cygwin is supposed to provide the Unix API, not -the Winsock API. -</para> -<para>There are differences between the semantics of functions with the same -name under the API. -</para> -<para>E.g., the select system call on Unix can wait on a standard file handles -and handles to sockets. The select call in Winsock can only wait on -sockets. Because of this, cygwin.dll does a lot of nasty stuff behind -the scenes, trying to persuade various Winsock/win32 functions to do what -a Unix select would do. -</para> -<para>If you are porting an application which already uses Winsock, then -using the net support in Cygwin is wrong. -</para> -<para>But you can still use native Winsock, and use Cygwin. The functions -which cygwin.dll exports are called 'cygwin_<name>'. There -are a load of defines which map the standard Unix names to the names -exported by the DLL-- check out include/netdb.h: -</para> -<screen> -..etc.. -void cygwin_setprotoent (int); -void cygwin_setservent (int); -void cygwin_setrpcent (int); -..etc.. -#ifndef __INSIDE_CYGWIN_NET__ -#define endprotoent cygwin_endprotoent -#define endservent cygwin_endservent -#define endrpcent cygwin_endrpcent -..etc.. -</screen> - -<para>The idea is that you'll get the Unix->Cygwin mapping if you include -the standard Unix header files. If you use this, you won't need to -link with libwinsock.a - all the net stuff is inside the DLL. -</para> -<para>The mywinsock.h file is a standard winsock.h which has been hacked to -remove the bits which conflict with the standard Unix API, or are -defined in other headers. E.g., in mywinsock.h, the definition of -struct hostent is removed. This is because on a Unix box, it lives in -netdb. It isn't a good idea to use it in your applications. -</para> -<para>As of the b19 release, this information may be slightly out of date. -</para> -</answer></qandaentry> - -<qandaentry id="faq.api.winsock"> -<question><para>I don't want Unix sockets, how do I use normal Win32 winsock?</para></question> -<answer> - -<para><emphasis role='bold'>(Please note: This section has not yet been updated for the latest net release.)</emphasis> -</para> -<para>To use the vanilla Win32 winsock, you just need to #define Win32_Winsock -and #include "windows.h" at the top of your source file(s). You'll also -want to add -lwsock32 to the compiler's command line so you link against -libwsock32.a. -</para> -</answer></qandaentry> - -<qandaentry id="faq.api.versions"> -<question><para>What version numbers are associated with Cygwin?</para></question> -<answer> - -<para>Cygwin versioning is relatively complicated because of its status as a -shared library. First of all, since October 1998 every Cygwin DLL has -been named <literal>cygwin1.dll</literal> and has a 1 in the release name. -Additionally, there are DLL major and minor numbers that correspond to -the name of the release, and a release number. In other words, -cygwin-1.5.10-2 is <literal>cygwin1.dll</literal>, major version 5, minor version -10, release 2. -</para> -<para>The <literal>cygwin1.dll</literal> major version number gets incremented only when a -change is made that makes existing software incompatible. For example, -the first major version 5 release, cygwin-1.5.0-1, added 64-bit file I/O -operations, which required many libraries to be recompiled and relinked. -The minor version changes every time we make a new backward compatible -Cygwin release available. There is also a <literal>cygwin1.dll</literal> release -version number. The release number is only incremented if we update an -existing release in a way that does not effect the DLL (like a missing -header file). -</para> -<para>There are also Cygwin API major and minor numbers. The major number -tracks important non-backward-compatible interface changes to the API. -An executable linked with an earlier major number will not be compatible -with the latest DLL. The minor number tracks significant API additions -or changes that will not break older executables but may be required by -newly compiled ones. -</para> -<para>Then there is a shared memory region compatibility version number. It is -incremented when incompatible changes are made to the shared memory -region or to any named shared mutexes, semaphores, etc. Finally there -is a mount point registry version number which keeps track -of non-backwards-compatible changes to the registry mount table layout. -This has been <literal>mounts v2</literal> for a long time. For more exciting Cygwin -version number details, check out the <literal>/usr/include/cygwin/version.h</literal> -file. -</para> -</answer></qandaentry> - -<qandaentry id="faq.api.timezone"> -<question><para>Why isn't _timezone set correctly?</para></question> -<answer> - -<para><emphasis role='bold'>(Please note: This section has not yet been updated for the latest net release.)</emphasis> -</para> -<para>Did you explicitly call tzset() before checking the value of _timezone? -If not, you must do so. -</para> -</answer></qandaentry> - -<qandaentry id="faq.api.mouse"> -<question><para>Is there a mouse interface?</para></question> -<answer> - -<para>There is no way to capture mouse events from Cygwin. There are -currently no plans to add support for this. -</para> -</answer></qandaentry> - diff --git a/winsup/doc/faq-problems.xml b/winsup/doc/faq-problems.xml deleted file mode 100644 index 453bae9ad..000000000 --- a/winsup/doc/faq-problems.xml +++ /dev/null @@ -1,32 +0,0 @@ -<!-- faq-problems.xml --> -<para>Aware of the problem, no solution known.</para> - -<qandaentry id="faq.known-problems.pipe-key"> -<question><para>Pipe key (<literal>|</literal>) doesn't work on non-US keyboards in Win9x/ME</para></question> -<answer> - -<para>This might get fixed someday, but meanwhile, just use rxvt, which does -not have this problem. This is no real loss, because rxvt has many -other advantages. (Do not attempt to use the "broken" pipe key -(<literal>&brokenpipe;</literal>) as a substitute, it is a different character.) -</para> -</answer></qandaentry> - -<qandaentry id="faq.known-problems.win9x-tape"> -<question><para>Cannot access tape devices with mt on Win9x</para></question> -<answer> - -<para>Win9x does not support the API used by the Cygwin fhandler_dev_tape -class. Details at -<ulink url="http://sources.redhat.com/ml/cygwin/2000-12/msg00331.html">http://sources.redhat.com/ml/cygwin/2000-12/msg00331.html</ulink>. -</para> -</answer></qandaentry> - -<qandaentry id="faq.known-problems.win9x-scp"> -<question><para>On Win9x, scp leaves ssh processes running.</para></question> -<answer> -<para> -You can stop them by hand with the Task Manager. -</para> -</answer></qandaentry> - diff --git a/winsup/doc/faq-programming.xml b/winsup/doc/faq-programming.xml deleted file mode 100644 index 04c1f5185..000000000 --- a/winsup/doc/faq-programming.xml +++ /dev/null @@ -1,894 +0,0 @@ -<!-- faq-programming.xml --> - -<qandaentry id="faq.programming.packages"> -<question><para>How do I contribute a package?</para></question> -<answer> - -<para>If you are willing to be a package maintainer, great! We urgently need -volunteers to prepare and maintain packages, because the priority of the -Cygwin Team is Cygwin itself. -</para> -<para>The Cygwin Package Contributor's Guide at -<ulink url="http://cygwin.com/setup.html">http://cygwin.com/setup.html</ulink> details everything you need to know -about being a package maintainer. The quickest way to get started is to -read the <emphasis>Initial packaging procedure, script-based</emphasis> section on -that page. The <literal>generic-build-script</literal> found there works well for -most packages. -</para> -<para>For questions about package maintenance, use the cygwin-apps mailing -list (start at <ulink url="http://cygwin.com/lists.html">http://cygwin.com/lists.html</ulink>) <emphasis>after</emphasis> -searching and browsing the cygwin-apps list archives, of course. Be -sure to look at the <emphasis>Submitting a package</emphasis> checklist at -<ulink url="http://cygwin.com/setup.html">http://cygwin.com/setup.html</ulink> before sending an ITP (Intent To -Package) email to cygwin-apps. -</para> -<para>You should also announce your intentions to the general cygwin list, in -case others were thinking the same thing. -</para> -</answer></qandaentry> - -<qandaentry id="faq.programming.contribute"> -<question><para>How do I contribute to Cygwin?</para></question> -<answer> - -<para>If you want to contribute to Cygwin itself, see -<ulink url="http://cygwin.com/contrib.html">http://cygwin.com/contrib.html</ulink>. -</para> -</answer></qandaentry> - -<qandaentry id="faq.programming.huge-executables"> -<question><para>Why are compiled executables so huge?!?</para></question> -<answer> - -<para>By default, gcc compiles in all symbols. You'll also find that gcc -creates large executables on UNIX. -</para> -<para>If that bothers you, just use the 'strip' program, part of the binutils -package. Or compile with the <literal>-s</literal> option to gcc. -</para> -</answer></qandaentry> - -<qandaentry id="faq.programming.glibc"> -<question><para>Where is glibc?</para></question> -<answer> - -<para>Cygwin does not provide glibc. It uses newlib instead, which provides -much (but not all) of the same functionality. Porting glibc to Cygwin -would be difficult. -</para> -</answer></qandaentry> - -<qandaentry id="faq.programming.objective-c"> -<question><para>Where is Objective C?</para></question> -<answer> - -<para>Objective C is not distributed with the Cygwin version of gcc, and there -are no plans to do so. The gcc package maintainer had difficulty -building it, and once built there were problems using it. It appears -that there is only minimal support for the Objective C front-end in the -main GCC distribution, anyway. -</para> -</answer></qandaentry> - -<qandaentry id="faq.programming.make-execvp"> -<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> -<para>Errors of <literal>make: execvp: /bin/sh: Illegal Argument</literal> or -<literal>make: execvp: /bin/sh: Argument list too long</literal> are often -caused by the command-line being to long for the Windows execution model. -To circumvent this, mount the path of the executable using the -X switch -to enable cygexec for all executables in that folder; you will also need -to exclude non-cygwin executables with the -x switch. Enabling cygexec -causes cygwin executables to talk directly to one another, which increases -the command-line limit. To enable cygexec for <literal>/bin</literal> and -<literal>/usr/bin</literal>, you can use these commands in a batch file: -</para> -<screen> -mount -X -b -f c:\cygwin\bin /bin -mount -X -b -f c:\cygwin\bin /usr/bin -mount -x -b -f c:\cygwin\bin\tclsh84.exe /usr/bin/tclsh84.exe -mount -x -b -f c:\cygwin\bin\tclsh84.exe /bin/tclsh84.exe -mount -x -b -f c:\cygwin\bin\wish84.exe /usr/bin/wish84.exe -mount -x -b -f c:\cygwin\bin\wish84.exe /bin/wish84.exe -</screen> - -<para>Note that if you have Tcl/Tk installed, you must specifically exclude -<literal>tclsh84</literal> and <literal>wish84</literal>, which are linked -to the Cygwin DLL but are not actually Cygwin programs. If you have added -other non-Cygwin programs to a path you want to mount cygexec, you can find -them with a script like this: -</para> -<screen> -#!/bin/sh -cd /bin; for f in `find . -type f -name '*.exe'`; do - cygcheck $f | (fgrep -qi cygwin1.dll || echo $f) -done -</screen> - -<para> -See <ulink url="http://www.cygwin.com/cygwin-ug-net/using-utils.html#mount" /> -for more information on using mount. -</para> - -</answer></qandaentry> - -<qandaentry id="faq.programming.ipc"> -<question><para>How can I use IPC, or why do I get a <literal>Bad system call</literal> -error?</para></question> -<answer> - -<para> -Try running cygserver. Read -<ulink url="http://www.cygwin.com/cygwin-ug-net/using-cygserver.html" />. If you're -trying to use PostgreSQL, also read -<literal>/usr/share/doc/Cygwin/postgresql-*.README</literal>. -</para> - -</answer></qandaentry> - -<qandaentry id="faq.programming.winmain"> -<question><para>Why the undefined reference to <literal>WinMain@16</literal>?</para></question> -<answer> - -<para>If you're using <literal>gcc</literal>, try adding an empty main() function to one -of your sources. Or, perhaps you have <literal>-lm</literal> too early in the -link command line. It should be at the end: -</para> -<screen> - bash$ gcc hello.c -lm - bash$ ./a.exe - Hello World! -</screen> - -<para>works, but -</para> -<screen> - bash$ gcc -lm hello.c - /c/TEMP/ccjLEGlU.o(.text+0x10):hello.c: multiple definition of `main' - /usr/lib/libm.a(libcmain.o)(.text+0x0):libcmain.c: first defined here - /usr/lib/libm.a(libcmain.o)(.text+0x6a):libcmain.c: undefined reference to `WinMain@16' - collect2: ld returned 1 exit status -</screen> - -<para>If you're using GCJ, you need to pass a "--main" flag: -</para> -<screen> -gcj --main=Hello Hello.java -</screen> - -</answer></qandaentry> - -<qandaentry id="faq.programming.win32-api"> -<question><para>How do I use Win32 API calls?</para></question> -<answer> - -<para><emphasis role='bold'>(Please note: This section has not yet been updated for the latest net release.)</emphasis> -</para> -<para>It's pretty simple actually. Cygwin tools require that you explicitly -link the import libraries for whatever Win32 API functions that you -are going to use, with the exception of kernel32, which is linked -automatically (because the startup and/or built-in code uses it). -</para> -<para>For example, to use graphics functions (GDI) you must link -with gdi32 like this: -</para> -<para>gcc -o foo.exe foo.o bar.o -lgdi32 -</para> -<para>or (compiling and linking in one step): -</para> -<para>gcc -o foo.exe foo.c bar.c -lgdi32 -</para> -<para>The following libraries are available for use in this way: -</para> -<para>advapi32 largeint ole32 scrnsave vfw32 -cap lz32 oleaut32 shell32 win32spl -comctl32 mapi32 oledlg snmp winmm -comdlg32 mfcuia32 olepro32 svrapi winserve -ctl3d32 mgmtapi opengl32 tapi32 winspool -dlcapi mpr penwin32 th32 winstrm -gdi32 msacm32 pkpd32 thunk32 wow32 -glaux nddeapi rasapi32 url wsock32 -glu32 netapi32 rpcdce4 user32 wst -icmp odbc32 rpcndr uuid -imm32 odbccp32 rpcns4 vdmdbg -kernel32 oldnames rpcrt4 version -</para> -<para>The regular setup allows you to use the option -mwindows on the -command line to include a set of the basic libraries (and also -make your program a GUI program instead of a console program), -including user32, gdi32 and, IIRC, comdlg32. -</para> -<para>Note that you should never include -lkernel32 on your link line -unless you are invoking ld directly. Do not include the same import -library twice on your link line. Finally, it is a good idea to -put import libraries last on your link line, or at least after -all the object files and static libraries that reference them. -</para> -<para>The first two are related to problems the linker has (as of b18 at least) -when import libraries are referenced twice. Tables get messed up and -programs crash randomly. The last point has to do with the fact that -gcc processes the files listed on the command line in sequence and -will only resolve references to libraries if they are given after -the file that makes the reference. -</para> -</answer></qandaentry> - -<qandaentry id="faq.programming.win32-no-cygwin"> -<question><para>How do I compile a Win32 executable that doesn't use Cygwin?</para></question> -<answer> - -<para>The -mno-cygwin flag to gcc makes gcc link against standard Microsoft -DLLs instead of Cygwin. This is desirable for native Windows programs -that don't need a UNIX emulation layer. -</para> -<para>This is not to be confused with 'MinGW' (Minimalist GNU for Windows), -which is a completely separate effort. That project's home page is -<ulink url="http://www.mingw.org/index.shtml">http://www.mingw.org/index.shtml</ulink>. -</para> -</answer></qandaentry> - -<qandaentry id="faq.programming.static-linking"> -<question><para>Can I build a Cygwin program that does not require cygwin1.dll at runtime?</para></question> -<answer> - -<para>No. If your program uses the Cygwin API, then your executable cannot -run without cygwin1.dll. In particular, it is not possible to -statically link with a Cygwin library to obtain an independent, -self-contained executable. -</para> -<para>If this is an issue because you intend to distribute your Cygwin -application, then you had better read and understand -<ulink url="http://cygwin.com/licensing.html">http://cygwin.com/licensing.html</ulink>, which explains the licensing -options. Unless you purchase a special commercial license from Red -Hat, then your Cygwin application must be Open Source. -</para> -</answer></qandaentry> - -<qandaentry id="faq.programming.msvcrt-and-cygwin"> -<question><para>Can I link with both MSVCRT*.DLL and cygwin1.dll?</para></question> -<answer> - -<para>No, you must use one or the other, they are mutually exclusive. -</para> -</answer></qandaentry> - -<qandaentry id="faq.programming.no-console-window"> -<question><para>How do I make the console window go away?</para></question> -<answer> - -<para>The default during compilation is to produce a console application. -It you are writing a GUI program, you should either compile with --mwindows as explained above, or add the string -"-Wl,--subsystem,windows" to the GCC command line. -</para> -</answer></qandaentry> - -<qandaentry id="faq.programming.make-spaces"> -<question><para>Why does make complain about a "missing separator"?</para></question> -<answer> - -<para>This problem usually occurs as a result of someone editing a Makefile -with a text editor that replaces tab characters with spaces. Command -lines must start with tabs. This is not specific to Cygwin. -</para> -</answer></qandaentry> - -<qandaentry id="faq.programming.win32-headers"> -<question><para>Why can't we redistribute Microsoft's Win32 headers?</para></question> -<answer> - -<para>Subsection 2.d.f of the `Microsoft Open Tools License agreement' looks -like it says that one may not "permit further redistribution of the -Redistributables to their end users". We take this to mean that we can -give them to you, but you can't give them to anyone else, which is -something that we can't agree to. Fortunately, we -have our own Win32 headers which are pretty complete. -</para> -</answer></qandaentry> - -<qandaentry id="faq.programming.msvs-mingw"> -<question><para>How do I use <literal>cygwin1.dll</literal> with Visual Studio or MinGW?</para></question> -<answer> - -<para>Before you begin, note that Cygwin is licensed under the GNU GPL (as -indeed are all other Cygwin-based libraries). That means that if your -code links against the cygwin dll (and if your program is calling -functions from Cygwin, it must, as a matter of fact, be linked against -it), you must apply the GPL to your source as well. Of course, this -only matters if you plan to distribute your program in binary form. For -more information, see <ulink url="http://gnu.org/licenses/gpl-faq.html">http://gnu.org/licenses/gpl-faq.html</ulink>. If -that is not a problem, read on. -</para> -<para>If you want to load the DLL dynamically, read -<literal>winsup/cygwin/how-cygtls-works.txt</literal> and the sample code in -<literal>winsup/testsuite/cygload</literal> to understand how this works. -The short version is: -</para> -<orderedlist><listitem><para>Make sure you have 4K of scratch space at the bottom of your stack. -</para></listitem> -<listitem><para>Invoke <literal>cygwin_dll_init()</literal>: -<screen> -HMODULE h = LoadLibrary("cygwin1.dll"); -void (*init)() = GetProcAddress(h, "cygwin_dll_init"); -init(); -</screen> -</para></listitem> -</orderedlist> - -<para>If you want to link statically from Visual Studio, to my knowledge -none of the Cygwin developers have done this, but we have this report -from the mailing list that it can be done this way: -</para> -<orderedlist><listitem><para>Use the impdef program to generate a .def file for the cygwin1.dll -(if you build the cygwin dll from source, you will already have a def -file) -</para> -<screen> -impdef cygwin1.dll > cygwin1.def -</screen> - -</listitem> -<listitem><para>Use the MS VS linker (lib) to generate an import library -</para> -<screen> -lib /def=cygwin1.def /out=cygwin1.lib -</screen> - -</listitem> -<listitem><para>Create a file "my_crt0.c" with the following contents -</para> -<screen> -#include <sys/cygwin.h> -#include <stdlib.h> - -typedef int (*MainFunc) (int argc, char *argv[], char **env); - -void - my_crt0 (MainFunc f) - { - cygwin_crt0(f); - } -</screen> - -</listitem> -<listitem><para>Use gcc in a Cygwin prompt to build my_crt0.c into a DLL - (e.g. my_crt0.dll). Follow steps 1 and 2 to generate .def and - .lib files for the DLL. -</para> -</listitem> -<listitem><para>Download crt0.c from the cygwin website and include it in - your sources. Modify it to call my_crt0() instead of - cygwin_crt0(). -</para> -</listitem> -<listitem><para>Build your object files using the MS VC compiler cl. -</para> -</listitem> -<listitem><para>Link your object files, cygwin1.lib, and my_crt0.lib (or - whatever you called it) into the executable. -</para></listitem> -</orderedlist> - -<para>Note that if you are using any other Cygwin based libraries -that you will probably need to build them as DLLs using gcc and -then generate import libraries for the MS VC linker. -</para> -<para>Thanks to Alastair Growcott (alastair dot growcott at bakbone dot co -dot uk) for this tip. -</para> -</answer></qandaentry> - -<qandaentry id="faq.programming.linking-lib"> -<question><para>How do I link against a <literal>.lib</literal> file?</para></question> -<answer> - -<para>If your <literal>.lib</literal> file is a normal static or import library with -C-callable entry points, you can list <literal>foo.lib</literal> as an object file for -gcc/g++, just like any <literal>*.o</literal> file. Otherwise, here are some steps: -</para> -<orderedlist><listitem><para>Build a C file with a function table. Put all functions you intend -to use in that table. This forces the linker to include all the object -files from the .lib. Maybe there is an option to force LINK.EXE to -include an object file. -</para></listitem> -<listitem><para>Build a dummy 'LibMain'. -</para></listitem> -<listitem><para>Build a .def with all the exports you need. -</para></listitem> -<listitem><para>Link with your .lib using link.exe. -</para></listitem> -</orderedlist> - -<para>or -</para> -<orderedlist><listitem><para>Extract all the object files from the .lib using LIB.EXE. -</para></listitem> -<listitem><para>Build a dummy C file referencing all the functions you need, either - with a direct call or through an initialized function pointer. -</para></listitem> -<listitem><para>Build a dummy LibMain. -</para></listitem> -<listitem><para>Link all the objects with this file+LibMain. -</para></listitem> -<listitem><para>Write a .def. -</para></listitem> -<listitem><para>Link. -</para></listitem> -</orderedlist> - -<para>You can use these methods to use MSVC (and many other runtime libs) -with Cygwin development tools. -</para> -<para>Note that this is a lot of work (half a day or so), but much less than -rewriting the runtime library in question from specs... -</para> -<para>Thanks to Jacob Navia (root at jacob dot remcomp dot fr) for this explanation. -</para> -</answer></qandaentry> - -<qandaentry id="faq.programming.building-cygwin"> -<question><para>How do I build Cygwin on my own?</para></question> -<answer> - -<para>First, you need to make sure you have the necessary build tools -installed; you at least need <literal>gcc</literal>, <literal>make</literal>, -<literal>perl</literal>, and <literal>cocom</literal>. If you want to run -the tests, <literal>dejagnu</literal> is also required, -and you need to have <literal>CYGWIN=server</literal> set as described at -<ulink url="http://www.cygwin.com/cygwin-ug-net/using-cygserver.html" />. -Normally, building ignores any errors in building the documentation, -which requires the <literal>docbook-xml42</literal>, <literal>docbook-xsl</literal>, and -<literal>xmlto</literal> packages. For more information on building the -documentation, see the README included in the <literal>cygwin-doc</literal> package. -</para> - -<para>Next, get the Cygwin source. Ideally, you should check out -what you need from CVS (<ulink url="http://cygwin.com/cvs.html" />). This is the -<emphasis>preferred method</emphasis> for acquiring the sources. Otherwise, if -you are trying to duplicate a cygwin release then you should -download the corresponding source package -(<literal>cygwin-x.y.z-n-src.tar.bz2</literal>). </para> - -<para>You <emphasis>must</emphasis> build cygwin in a separate directory from -the source, so create something like a <literal>build/</literal> directory. -Assuming you checked out the source in <literal>/oss/src/</literal>, and you -also want to install to the temporary location <literal>install</literal>: -</para> -<screen> -mkdir /oss/build -mkdir /oss/install -cd build -(/oss/src/configure --prefix=/oss/install -v; make) >& make.out -make install > install.log 2>&1 -</screen> - -<para>To check a cygwin1.dll, run "make check" in the winsup/testsuite -directory. If that works, install everything <emphasis>except</emphasis> the dll (if -you can). Then, close down all cygwin programs (including bash windows, -inetd, etc.), save your old dll, and copy the new dll to the correct -place. Then start up a bash window, or run a cygwin program from the -Windows command prompt, and see what happens. -</para> -<para>If you get the error "shared region is corrupted" it means that two -different versions of cygwin1.dll are running on your machine at the -same time. Remove all but one. -</para> -</answer></qandaentry> - -<qandaentry id="faq.programming.debugging-cygwin"> -<question><para>I may have found a bug in Cygwin, how can I debug it (the symbols in gdb look funny)?</para></question> -<answer> - -<para>Debugging symbols are stripped from distibuted Cygwin binaries, so any -symbols that you see in gdb are basically meaningless. It is also a good -idea to use the latest code in case the bug has been fixed, so we -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" />. -You can also contact the mailing list for pointers (a simple test case that -demonstrates the bug is always welcome). -</para> -</answer></qandaentry> - -<qandaentry id="faq.programming.compiling-unsupported"> -<question><para>How can I compile Cygwin for an unsupported platform (PowerPC, Alpha, ARM, Itanium)?</para></question> -<answer> - -<para>Unfortunately, this will be difficult. Exception handling and signals -support semantics and args have been designed for x86 so you would need -to write specific support for your platform. We don't know of any other -incompatibilities. Please send us patches if you do this work! -</para> -</answer></qandaentry> - -<qandaentry id="faq.programming.adjusting-heap"> -<question><para>How can I adjust the heap/stack size of an application?</para></question> -<answer> - -<para>If you need to change the maximum amount of memory available to Cygwin, see -<ulink url="http://cygwin.com/cygwin-ug-net/setup-maxmem.html">http://cygwin.com/cygwin-ug-net/setup-maxmem.html</ulink>. Otherwise, -just pass heap/stack linker arguments to gcc. To create foo.exe with -a heap size of 1024 and a stack size of 4096, you would invoke -gcc as: -</para> -<para><literal>gcc -Wl,--heap,1024,--stack,4096 -o foo foo.c</literal> -</para> -</answer></qandaentry> - -<qandaentry id="faq.programming.dll-cygcheck"> -<question><para>How can I find out which DLLs are needed by an executable?</para></question> -<answer> - -<para><literal>objdump -p</literal> provides this information, but is rather verbose. -</para> -<para><literal>cygcheck</literal> will do this much more concisely, and operates -recursively, provided the command is in your path. -</para> -<para>Note there is currently a bug in cygcheck in that it will not report -on a program in a Windows system dir (e.g., C:\Windows or C:\WINNT) even -if it's in your path. To work around this, supply the full Win32 path -to the executable, including the .exe extension: -</para> -<screen> -cygcheck c:\\winnt\\system32\\cmd.exe -</screen> - -<para>(Note the windows path separator must be escaped if this is typed in -bash.) -</para> -</answer></qandaentry> - -<qandaentry id="faq.programming.dll-building"> -<question><para>How do I build a DLL?</para></question> -<answer> - -<para>There's documentation that explains the process in the Cygwin User's -Guide here: <ulink url="http://cygwin.com/cygwin-ug-net/dll.html">http://cygwin.com/cygwin-ug-net/dll.html</ulink> -</para> -</answer></qandaentry> - -<qandaentry id="faq.programming.breakpoint"> -<question><para>How can I set a breakpoint at MainCRTStartup?</para></question> -<answer> - -<para><emphasis role='bold'>(Please note: This section has not yet been updated for the latest net release.)</emphasis> -</para> -<para>Set a breakpoint at *0x401000 in gdb and then run the program in -question. -</para> -</answer></qandaentry> - -<qandaentry id="faq.programming.dll-relocatable"> -<question><para>How can I build a relocatable dll?</para></question> -<answer> - -<para><emphasis role='bold'>(Please note: This section has not yet been updated for the latest net release. However, there was a discussion on the cygwin mailing list recently that addresses this issue. Read <ulink url="http://cygwin.com/ml/cygwin/2000-06/msg00688.html">http://cygwin.com/ml/cygwin/2000-06/msg00688.html</ulink> and related messages.)</emphasis> -</para> -<para>You must execute the following sequence of five commands, in this -order: -</para> -<screen> -$(LD) -s --base-file BASEFILE --dll -o DLLNAME OBJS LIBS -e ENTRY - -$(DLLTOOL) --as=$(AS) --dllname DLLNAME --def DEFFILE \ - --base-file BASEFILE --output-exp EXPFILE - -$(LD) -s --base-file BASEFILE EXPFILE -dll -o DLLNAME OBJS LIBS -e ENTRY - -$(DLLTOOL) --as=$(AS) --dllname DLLNAME --def DEFFILE \ - --base-file BASEFILE --output-exp EXPFILE - -$(LD) EXPFILE --dll -o DLLNAME OBJS LIBS -e ENTRY -</screen> - -<para>In this example, $(LD) is the linker, ld. -</para> -<para>$(DLLTOOL) is dlltool. -</para> -<para>$(AS) is the assembler, as. -</para> -<para>DLLNAME is the name of the DLL you want to create, e.g., tcl80.dll. -</para> -<para>OBJS is the list of object files you want to put into the DLL. -</para> -<para>LIBS is the list of libraries you want to link the DLL against. For -example, you may or may not want -lcygwin. You may want -lkernel32. -Tcl links against -lcygwin -ladvapi32 -luser32 -lgdi32 -lcomdlg32 --lkernel32. -</para> -<para>DEFFILE is the name of your definitions file. A simple DEFFILE would -consist of ``EXPORTS'' followed by a list of all symbols which should -be exported from the DLL. Each symbol should be on a line by itself. -Other programs will only be able to access the listed symbols. -</para> -<para>BASEFILE is a temporary file that is used during this five stage -process, e.g., tcl.base. -</para> -<para>EXPFILE is another temporary file, e.g., tcl.exp. -</para> -<para>ENTRY is the name of the function which you want to use as the entry -point. This function should be defined using the WINAPI attribute, -and should take three arguments: - int WINAPI startup (HINSTANCE, DWORD, LPVOID) -</para> -<para>This means that the actual symbol name will have an appended @12, so if -your entry point really is named <literal>startup</literal>, the string you should -use for ENTRY in the above examples would be <literal>startup@12</literal>. -</para> -<para>If your DLL calls any Cygwin API functions, the entry function will need -to initialize the Cygwin impure pointer. You can do that by declaring -a global variable <literal>_impure_ptr</literal>, and then initializing it in the -entry function. Be careful not to export the global variable -<literal>_impure_ptr</literal> from your DLL; that is, do not put it in DEFFILE. -</para> -<screen> -/* This is a global variable. */ -struct _reent *_impure_ptr; -extern struct _reent *__imp_reent_data; - -int entry (HINSTANT hinst, DWORD reason, LPVOID reserved) -{ - _impure_ptr = __imp_reent_data; - /* Whatever else you want to do. */ -} -</screen> - -<para>You may put an optional `--subsystem windows' on the $(LD) lines. The -Tcl build does this, but I admit that I no longer remember whether -this is important. Note that if you specify a --subsytem <x> flag to ld, -the -e entry must come after the subsystem flag, since the subsystem flag -sets a different default entry point. -</para> -<para>You may put an optional `--image-base BASEADDR' on the $(LD) lines. -This will set the default image base. Programs using this DLL will -start up a bit faster if each DLL occupies a different portion of the -address space. Each DLL starts at the image base, and continues for -whatever size it occupies. -</para> -<para>Now that you've built your DLL, you may want to build a library so -that other programs can link against it. This is not required: you -could always use the DLL via LoadLibrary. However, if you want to be -able to link directly against the DLL, you need to create a library. -Do that like this: -</para> -<para>$(DLLTOOL) --as=$(AS) --dllname DLLNAME --def DEFFILE --output-lib LIBFILE -</para> -<para>$(DLLTOOL), $(AS), DLLNAME, and DEFFILE are the same as above. Make -sure you use the same DLLNAME and DEFFILE, or things won't work right. -</para> -<para>LIBFILE is the name of the library you want to create, e.g., -libtcl80.a. You can then link against that library using something -like -ltcl80 in your linker command. -</para> -</answer></qandaentry> - -<qandaentry id="faq.programming.debug"> -<question><para>How can I debug what's going on?</para></question> -<answer> - -<para>You can debug your application using <literal>gdb</literal>. Make sure you -compile it with the -g flag! If your application calls functions in -MS DLLs, gdb will complain about not being able to load debug information -for them when you run your program. This is normal since these DLLs -don't contain debugging information (and even if they did, that debug -info would not be compatible with gdb). -</para> -</answer></qandaentry> - -<qandaentry id="faq.programming.system-trace"> -<question><para>Can I use a system trace mechanism instead?</para></question> -<answer> - -<para>Yes. You can use the <literal>strace.exe</literal> utility to run other cygwin -programs with various debug and trace messages enabled. For information -on using <literal>strace</literal>, see the Cygwin User's Guide or the file -<literal>winsup/utils/utils.sgml</literal>. -</para> -</answer></qandaentry> - -<qandaentry id="faq.programming.gdb-signals"> -<question><para>Why doesn't gdb handle signals?</para></question> -<answer> - -<para>Unfortunately, there is only minimal signal handling support in gdb -currently. Signal handling only works with Windows-type signals. -SIGINT may work, SIGFPE may work, SIGSEGV definitely does. You cannot -'stop', 'print' or 'nopass' signals like SIGUSR1 or SIGHUP to the -process being debugged. -</para> -</answer></qandaentry> - -<qandaentry id="faq.programming.linker"> -<question><para>The linker complains that it can't find something.</para></question> -<answer> - -<para>A common error is to put the library on the command line before -the thing that needs things from it. -</para> -<para>This is wrong <literal>gcc -lstdc++ hello.cc</literal>. -This is right <literal>gcc hello.cc -lstdc++</literal>. -</para> -</answer></qandaentry> - -<qandaentry id="faq.programming.stat64"> -<question><para>Why do I get an error using <literal>struct stat64</literal>?</para></question> -<answer> - -<para><literal>struct stat64</literal> is not used in Cygwin, just -use <literal>struct stat</literal>.</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> - -<para>Yes. -</para> -</answer></qandaentry> - -<qandaentry id="faq.programming.malloc-h"> -<question><para>Where is malloc.h?</para></question> -<answer> - -<para><emphasis role='bold'>(Please note: This section has not yet been updated for the latest net release.)</emphasis> -</para> -<para>Include stdlib.h instead of malloc.h. -</para> -</answer></qandaentry> - -<qandaentry id="faq.programming.own-malloc"> -<question><para>Can I use my own malloc?</para></question> -<answer> - -<para>If you define a function called <literal>malloc</literal> in your own code, and link -with the DLL, the DLL <emphasis>will</emphasis> call your <literal>malloc</literal>. Needless to -say, you will run into serious problems if your malloc is buggy. -</para> -<para>If you run any programs from the DOS command prompt, rather than from in -bash, the DLL will try and expand the wildcards on the command line. -This process uses <literal>malloc</literal> <emphasis>before</emphasis> your main line is started. -If you have written your own <literal>malloc</literal> to need some initialization -to occur after <literal>main</literal> is called, then this will surely break. -</para> -<para>Moreover, there is an outstanding issue with <literal>_malloc_r</literal> in -<literal>newlib</literal>. This re-entrant version of <literal>malloc</literal> will be called -directly from within <literal>newlib</literal>, by-passing your custom version, and -is probably incompatible with it. But it may not be possible to replace -<literal>_malloc_r</literal> too, because <literal>cygwin1.dll</literal> does not export it and -Cygwin does not expect your program to replace it. This is really a -newlib issue, but we are open to suggestions on how to deal with it. -</para> -</answer></qandaentry> - -<qandaentry id="faq.programming.msvc-gcc-objects"> -<question><para>Can I mix objects compiled with msvc++ and gcc?</para></question> -<answer> - -<para>Yes, but only if you are combining C object files. MSVC C++ uses a -different mangling scheme than GNU C++, so you will have difficulties -combining C++ objects. -</para> -</answer></qandaentry> - -<qandaentry id="faq.programming.gdb-msvc"> -<question><para>Can I use the gdb debugger to debug programs built by VC++?</para></question> -<answer> - -<para>No, not for full (high level source language) debugging. -The Microsoft compilers generate a different type of debugging -symbol information, which gdb does not understand. -</para> -<para>However, the low-level (assembly-type) symbols generated by -Microsoft compilers are coff, which gdb DOES understand. -Therefore you should at least be able to see all of your -global symbols; you just won't have any information about -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/design/pro/manuals/">http://developer.intel.com/design/pro/manuals/</ulink> -</para> -</answer></qandaentry> - -<qandaentry id="faq.programming.make-scripts"> -<question><para>Shell scripts aren't running properly from my makefiles?</para></question> -<answer> - -<para>If your scripts are in the current directory, you must have <literal>.</literal> -(dot) in your $PATH. (It is not normally there by default.) Otherwise, -you would need to add /bin/sh in front of each and every shell script -invoked in your Makefiles. -</para> -</answer></qandaentry> - -<qandaentry id="faq.programming.preprocessor"> -<question><para>What preprocessor do I need to know about?</para></question> -<answer> - -<para>We use _WIN32 to signify access to the Win32 API and __CYGWIN__ for -access to the Cygwin environment provided by the dll. -</para> -<para>We chose _WIN32 because this is what Microsoft defines in VC++ and -we thought it would be a good idea for compatibility with VC++ code -to follow their example. We use _MFC_VER to indicate code that should -be compiled with VC++. -</para> -<para>_WIN32 is only defined when you use either the -mno-cygwin or -mwin32 -gcc command line options. This is because Cygwin is supposed to be a -Unix emulation environment and defining _WIN32 confuses some programs -which think that they have to make special concessions for a Windows -environment which Cygwin handles automatically. -</para> -<para>Note that using -mno-cygwin replaces __CYGWIN__ with __MINGW32__ as to -tell which compiler (or settings) you're running. -Check this out in detail by running, for example -</para> -<screen> - $ gcc -dM -E -xc /dev/null >gcc.txt - $ gcc -mno-cygwin -dM -E -xc /dev/null >gcc-mno-cygwin.txt - $ gcc -mwin32 -dM -E -xc /dev/null >gcc-mwin32.txt -</screen> -<para>Then use the diff and grep utilities to check -what the difference is. -</para> -</answer></qandaentry> - -<qandaentry id="faq.programming.unix-gui"> -<question><para>How should I port my Unix GUI to Windows?</para></question> -<answer> - -<para>There are two basic strategies for porting Unix GUIs to Windows. -</para> -<para>The first is to use a portable graphics library such as tcl/tk, X11, or -V (and others?). Typically, you will end up with a GUI on Windows that -requires some runtime support. With tcl/tk, you'll want to include the -necessary library files and the tcl/tk DLLs. In the case of X11, you'll -need everyone using your program to have an X11 server installed. -</para> -<para>The second method is to rewrite your GUI using Win32 API calls (or MFC -with VC++). If your program is written in a fairly modular fashion, you -may still want to use Cygwin if your program contains a lot of shared -(non-GUI-related) code. That way you still gain some of the portability -advantages inherent in using Cygwin. -</para> -</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> - diff --git a/winsup/doc/faq-resources.xml b/winsup/doc/faq-resources.xml deleted file mode 100644 index 9bf42f722..000000000 --- a/winsup/doc/faq-resources.xml +++ /dev/null @@ -1,51 +0,0 @@ -<!-- faq-resources.xml --> -<qandaentry id="faq.resources.documentation"> -<question><para>Where's the documentation?</para></question> -<answer> - -<para>If you have installed Cygwin, you can find lots of documentation in -<literal>/usr/share/doc/</literal>. Some packages have Cygwin specific -instructions in a file -<literal>/usr/share/doc/Cygwin/<replaceable>package_name</replaceable>.README</literal>. -In addition, many packages ship with standard documentation, which you can -find in -<literal>/usr/share/doc/<replaceable>package_name</replaceable></literal> or -by using the <literal>man</literal> or <literal>info</literal> tools. (Hint: -use <literal>cygcheck -l <replaceable>package_name</replaceable></literal> to -list what man pages the package includes.) Some older packages still keep -their documentation in <literal>/usr/doc/</literal> -instead of <literal>/usr/share/doc/</literal>. -</para> -<para>There are links to quite a lot of documentation on the main Cygwin -project web page, <ulink url="http://cygwin.com/">http://cygwin.com/</ulink>, -including this FAQ. Be sure to at least read any 'Release Notes' or 'Readme' -or 'read this' links on the main web page, if there are any. -</para> -<para>There is a comprehensive Cygwin User's Guide at <ulink -url="http://cygwin.com/cygwin-ug-net/cygwin-ug-net.html">http://cygwin.com/cygwin-ug-net/cygwin-ug-net.html</ulink> -and an API Reference at <ulink -url="http://cygwin.com/cygwin-api/cygwin-api.html">http://cygwin.com/cygwin-api/cygwin-api.html</ulink>. -</para> -<para>You can find documentation for the individual GNU tools at <ulink -url="http://www.fsf.org/manual/">http://www.fsf.org/manual/</ulink>. (You -should read GNU manuals from a local mirror, check <ulink -url="http://www.fsf.org/server/list-mirrors.html">http://www.fsf.org/server/list-mirrors.html</ulink> -for a list of them.) -</para> -</answer></qandaentry> - -<qandaentry id="faq.resources.mailing-lists"> -<question><para>What Cygwin mailing lists can I join?</para></question> -<answer> -<para>Comprehensive information about the Cygwin mailing lists can be found at -<ulink url="http://cygwin.com/lists.html" />. -</para> -</answer></qandaentry> - -<qandaentry id="faq.resources.problems"> -<question><para>What if I have a problem? (Or: Why won't you/the mailing list answer my questions?)</para></question> -<answer> -<para>Comprehensive information about reporting problems with Cygwin can be found at <ulink url="http://cygwin.com/problems.html" />. -</para> -</answer></qandaentry> - diff --git a/winsup/doc/faq-sections.xml b/winsup/doc/faq-sections.xml deleted file mode 100644 index 4c88d68d5..000000000 --- a/winsup/doc/faq-sections.xml +++ /dev/null @@ -1,82 +0,0 @@ -<?xml version='1.0'?> -<!DOCTYPE article PUBLIC '-//OASIS//DTD DocBook XML V4.2//EN' - "http://www.oasis-open.org/docbook/xml/4.2/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"> - <!ENTITY FAQ-PROBLEMS SYSTEM "faq-problems.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.known-problems"> -<title>Known Problems in the Latest Net Release</title> -<qandaset><?dbhtml toc="1"?> -&FAQ-PROBLEMS; -</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 deleted file mode 100644 index 00d4719bd..000000000 --- a/winsup/doc/faq-setup.xml +++ /dev/null @@ -1,504 +0,0 @@ -<!-- faq-setup.xml --> -<qandaentry id="faq.setup.setup"> -<question><para>What is the recommended installation procedure?</para></question> -<answer> - -<para>There is only one recommended way to install Cygwin, which is to use the GUI -installer ``Cygwin Setup''. It is flexible and easy to use. -You can pick and choose the packages you wish to install, and update -them individually. Full source code is available for all packages and -tools. More information on using Cygwin Setup may be found at -<ulink url="http://cygwin.com/cygwin-ug-net/setup-net.html" />. -</para> -<para>If you do it any other way, you're on your own! That said, keep in mind -that the GUI installer is a "work in progress", so there might be a few -difficulties, especially if you are behind a firewall or have other -specific requirements. If something doesn't work right for you, and -it's not covered here or in the latest development snapshot at -<ulink url="http://cygwin.com/snapshots/">http://cygwin.com/snapshots/</ulink>, then by all means report it to the -mailing list. -</para> -<para>For a searchable list of packages that can be installed with Cygwin, -see <ulink url="http://cygwin.com/packages/">http://cygwin.com/packages/</ulink>. -</para> -</answer></qandaentry> - -<qandaentry id="faq.setup.c"> -<question><para>Why not install in C:\?</para></question> -<answer> - -<para>The Cygwin Setup program will prompt you for a "root" directory. -The default is <literal>C:\cygwin</literal>, but you can change it. You are urged not to -choose something like <literal>C:\</literal> (the root directory on the system drive) for -your Cygwin root. If you do, then critical Cygwin system directories -like <literal>etc</literal>, <literal>lib</literal> and <literal>bin</literal> could easily be corrupted by -other (non-Cygwin) applications or packages that use <literal>\etc</literal>, -<literal>\lib</literal> or <literal>\bin</literal>. Perhaps there is no conflict now, but who -knows what you might install in the future? It's also just good common -sense to segregate your Cygwin "filesystems" from the rest of your -Windows system disk. -</para> -<para>(In the past, there had been genuine bugs that would cause problems -for people who installed in <literal>C:\</literal>, but we believe those are gone -now.) -</para> -</answer></qandaentry> - -<qandaentry id="faq.setup.old-versions"> -<question><para>Can I use Cygwin Setup to get old versions of packages (like gcc-2.95)?</para></question> -<answer> - -<para>Cygwin Setup can be used to install any packages that are on a -Cygwin mirror, which usually includes one version previous to the -current one. The complete list may be searched at -<ulink url="http://cygwin.com/packages/">http://cygwin.com/packages/</ulink>. There is no complete archive of -older packages. If you have a problem with the current version of -a Cygwin package, please report it to the mailing list using the -guidelines at <ulink url="http://cygwin.com/problems.html">http://cygwin.com/problems.html</ulink>. -</para> -<para>That said, if you really need an older package, you may be able to find -an outdated or archival mirror by searching the web for an old package -version (for example, <literal>gcc2-2.95.3-10-src.tar.bz2</literal>), but keep in -mind that this older version will not be supported by the mailing list -and that installing the older version will not help improve Cygwin. -</para> -</answer></qandaentry> - -<qandaentry id="faq.setup.virus"> -<question><para>Is Cygwin Setup, or one of the packages, infected with a virus?</para></question> -<answer> - -<para>Unlikely. Unless you can confirm it, please don't report it to the -mailing list. Anti-virus products have been known to detect false -positives when extracting compressed tar archives. If this causes -problems for you, consider disabling your anti-virus software when -running <literal>setup</literal>. Read the next entry for a fairly safe way to do -this. -</para> -</answer></qandaentry> - -<qandaentry id="faq.setup.hang"> -<question><para>My computer hangs when I run Cygwin Setup!</para></question> -<answer> - -<para>Both Network Associates (formerly McAfee) and Norton anti-virus -products have been reported to "hang" when extracting Cygwin tar -archives. If this happens to you, consider disabling your anti-virus -software when running Cygwin Setup. The following procedure should be -a fairly safe way to do that: -</para> -<orderedlist><listitem><para>Download <literal>setup.exe</literal> and scan it explicitly. -</para> -</listitem> -<listitem><para>Turn off the anti-virus software. -</para> -</listitem> -<listitem><para>Run setup to download and extract all the tar files. -</para> -</listitem> -<listitem><para>Re-activate your anti-virus software and scan everything -in C:\cygwin (or wherever you chose to install), or your entire hard -disk if you are paranoid. -</para> -</listitem> -</orderedlist> - -<para>This should be safe, but only if Cygwin Setup is not substituted by -something malicious, and no mirror has been compromised. -</para> -</answer></qandaentry> - -<qandaentry id="faq.setup.what-packages"> -<question><para>What packages should I download? Where are 'make', 'gcc', 'vi', etc? </para></question> -<answer> -<para>When using Cygwin Setup for the first time, the default is to install -a minimal subset of all available packages. If you want anything beyond that, -you will have to select it explicitly. See -<ulink url="http://cygwin.com/packages/" /> for a searchable list of available -packages, or use <literal>cygcheck -p </literal> as described in the Cygwin -User's Guide at -<ulink url="http://cygwin.com/cygwin-ug-net/using-utils.html#cygcheck" />. -</para> -<para>If you want to build programs, of course you'll need <literal>gcc</literal>, -<literal>binutils</literal>, <literal>make</literal> and probably other packages from the -``Devel'' category. Text editors can be found under ``Editors''. -</para> -</answer></qandaentry> - -<qandaentry id="faq.setup.everything"> -<question><para>How do I just get everything?</para></question> -<answer> - -<para>Long ago, the default was to install everything, much to the -irritation of most users. Now the default is to install only a basic -core of packages. Cygwin Setup is designed to make it easy to browse -categories and select what you want to install or omit from those -categories. It's also easy to install everything: -</para> -<orderedlist> -<listitem><para>At the ``Select Packages'' screen, in ``Categories'' view, at the line -marked ``All'', click on the word ``default'' so that it changes to -``install''. (Be patient, there is some computing to do at this step. -It may take a second or two to register the change.) This tells Setup -to install <emphasis>everything</emphasis>, not just what it thinks you should have -by default. -</para> -</listitem> -<listitem><para>Now click on the ``View'' button (twice) until you get the -``Partial'' view. This shows exactly which packages are about to be -downloaded and installed. -</para> -</listitem> -</orderedlist> - -<para>This procedure only works for packages that are currently available. -There is no way to tell Cygwin Setup to install all packages by -default from now on. As new packages become available that would not -be installed by default, you have to repeat the above procedure to get -them. -</para> -<para>In general, a better method (in my opinion), is to: -</para> -<orderedlist> -<listitem><para>First download & install all packages that would normally be -installed by default. This includes fundamental packages and any -updates to what you have already installed. Then... -</para> -</listitem> -<listitem><para>Run Cygwin Setup again, and apply the above technique to get all -new packages that would not be installed by default. You can check -the list in the Partial View before proceeding, in case there's -something you really <emphasis>don't</emphasis> want. -</para> -</listitem> -<listitem><para>In the latest version of Cygwin Setup, if you click the ``View'' -button (twice) more, it shows packages not currently installed. You -ought to check whether you <emphasis>really</emphasis> want to install everything! -</para> -</listitem> -</orderedlist> - -</answer></qandaentry> - -<qandaentry id="faq.setup.disk-space"> -<question><para>How much disk space does Cygwin require?</para></question> -<answer> - -<para>That depends, obviously, on what you've chosen to download and -install. A full installation today is probably larger than 800MB -installed, not including the package archives themselves nor the source -code. -</para> -<para>After installation, the package archives remain in your ``Local -Package Directory'', by default the location of <literal>setup.exe</literal>. You -may conserve disk space by deleting the subdirectories there. These -directories will have very weird looking names, being encoded with -their URLs (named <literal>ftp%3a%2f...</literal>). -</para> -<para>Of course, you can keep them around in case you want to reinstall a -package. If you want to clean out only the outdated packages, Michael Chase -has written a script called <literal>clean_setup.pl</literal>, available -at <ulink url="http://home.ix.netcom.com/~mchase/zip/" />. -</para> -</answer></qandaentry> - -<qandaentry id="faq.setup.what-upgraded"> -<question><para>How do I know which version I upgraded from?</para></question> -<answer> - -<para>Detailed logs of the most recent Cygwin Setup session can be found in -<literal>/var/log/setup.log.full</literal> and less verbose information about -prior actions is in <literal>/var/log/setup.log</literal>. -</para> - -</answer></qandaentry> - -<qandaentry id="faq.setup.setup-fails"> -<question><para>What if setup fails?</para></question> -<answer> - -<para>First, make sure that you are using the latest version of Cygwin Setup. -The latest version is always available from the 'Install Cygwin now' link on -the Cygwin Home Page at <ulink -url="http://cygwin.com/">http://cygwin.com/</ulink>. </para> -<para>If you are downloading from the Internet, setup will fail if it cannot -download the list of mirrors at <ulink -url="http://cygwin.com/mirrors.html">http://cygwin.com/mirrors.html</ulink>. -It could be that the network is too busy. Something similar could be the -cause of a download site not working. Try another mirror, or try again -later. -</para> -<para>If setup refuses to download a package that you know needs to be -upgraded, try deleting that package's entry from /etc/setup. If you are -reacting quickly to an announcement on the mailing list, it could be -that the mirror you are using doesn't have the latest copy yet. Try -another mirror, or try again tomorrow. -</para> -<para>If setup has otherwise behaved strangely, check the files -<literal>setup.log</literal> and <literal>setup.log.full</literal> in -<literal>/var/log</literal> (<literal>C:\cygwin\var\log</literal> by -default). It may provide some clues as to what went wrong and why. -</para> -<para>If you're still baffled, search the Cygwin mailing list for clues. -Others may have the same problem, and a solution may be posted there. -If that search proves fruitless, send a query to the Cygwin mailing -list. You must provide complete details in your query: version of -setup, options you selected, contents of setup.log and setup.log.full, -what happened that wasn't supposed to happen, etc. -</para> -</answer></qandaentry> - -<qandaentry id="faq.setup.name-with-space"> -<question><para>My Windows logon name has a space in it, will this cause problems?</para></question> -<answer> - -<para>Most definitely yes! UNIX shells (and thus Cygwin) use the space -character as a word delimiter. Under certain circumstances, it is -possible to get around this with various shell quoting mechanisms, but -you are much better off if you can avoid the problem entirely. -</para> -<para>On Windows NT/2000/XP you have two choices: -</para><orderedlist> -<listitem><para>You can rename the user in the Windows User Manager GUI and then -run mkpasswd. -</para> -</listitem> -<listitem><para>You can simply edit the /etc/passwd file and change the Cygwin user name -(first field). It's also a good idea to avoid spaces in the home directory. -</para> -</listitem> -</orderedlist> - -<para>On Windows 95/98/ME you can create a new user and run mkpasswd, -or you can delete the offending entry from /etc/passwd. -Cygwin will then use the name in the default entry with uid 500. -</para> -</answer></qandaentry> - -<qandaentry id="faq.setup.home"> -<question><para>My <literal>HOME</literal> environment variable is not what I want.</para></question> -<answer> - -<para>When starting Cygwin from Windows, <literal>HOME</literal> is determined as follows -in order of decreasing priority: -</para> -<orderedlist> -<listitem><para><literal>HOME</literal> from the Windows environment, translated to POSIX form. -</para> -</listitem> -<listitem><para>The entry in /etc/passwd -</para> -</listitem> -<listitem><para><literal>HOMEDRIVE</literal> and <literal>HOMEPATH</literal> from the Windows environment -</para> -</listitem> -<listitem><para>/ -</para> -</listitem> -</orderedlist> - -<para>When using Cygwin from the network (telnet, ssh,...), <literal>HOME</literal> is set -from /etc/passwd. -</para> -<para>If your <literal>HOME</literal> is set to a value such as /cygdrive/c, it is likely -that it was set in Windows. Start a DOS Command Window and type -"set HOME" to verify if this is the case. -</para> -<para>Access to shared drives is often restricted when starting from the network, -thus Domain users may wish to have a different <literal>HOME</literal> in the -Windows environment (on shared drive) than in /etc/passwd (on local drive). -Note that ssh only considers /etc/passwd, disregarding <literal>HOME</literal>. -</para> -</answer></qandaentry> - -<qandaentry id="faq.setup.uninstall-packages"> -<question><para>How do I uninstall individual packages?</para></question> -<answer> - -<para>Run Cygwin Setup as you would to install packages. In the list of -packages to install, browse the relevant category or click on the -``View'' button to get a full listing. Click on the cycle glyph until -the action reads ``Uninstall''. Proceed by clicking ``Next''. -</para> -</answer></qandaentry> - -<qandaentry id="faq.setup.uninstall-service"> -<question><para>How do I uninstall a Cygwin service?</para></question> -<answer> -<para>If you don't know the name of the service, you can list all -services you have installed with <literal>cygrunsrv -L</literal>. Before -removing the service, you should stop it with -<literal>cygrunsrv --stop <replaceable>service_name</replaceable></literal>. -If you have <literal>inetd</literal> configured to run as a standalone -service, it will not show up in the list, but <literal>cygrunsrv --stop inetd</literal> -will work to stop it as well. Lastly, remove the service with -<literal>cygrunsrv --remove <replaceable>service_name</replaceable></literal>. -</para> -</answer></qandaentry> - -<qandaentry id="faq.setup.uninstall-all"> -<question><para>How do I uninstall <emphasis role='bold'>all</emphasis> of Cygwin?</para></question> -<answer> - -<para>Setup has no automatic uninstall facility. The recommended method to remove all -of Cygwin is as follows: -</para> -<orderedlist> -<listitem><para>First remove all Cygwin services by repeating the instructions -in <ulink -url="http://cygwin.com/faq/faq.setup.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>, -<literal>postgresql</literal>, and so on. -</para> -</listitem> -<listitem><para>Stop the X11 server if it is running, and terminate any Cygwin programs -that might be running in the background. Remove all mount information by typing -<literal>umount -A</literal> and then exit the command prompt and ensure that no Cygwin -processes remain. Note: If you want to save your mount points for a later -reinstall, first save the output of <literal>mount -m</literal> as described at -<ulink url="http://cygwin.com/cygwin-ug-net/using-utils.html#mount" />. -</para> -</listitem> -<listitem><para>Delete the Cygwin root folder and all subfolders. If you get an error -that an object is in use, then ensure that you've stopped all services and -closed all Cygwin programs. If you get a 'Permission Denied' error then you -will need to modify the permissions and/or ownership of the files or folders -that are causing the error. For example, sometimes files used by system -services end up owned by the SYSTEM account and not writable by regular users. -</para> -<para>The quickest way to delete the entire tree if you run into this problem is to -change the ownership of all files and folders to your account. To do this in -Windows Explorer, right click on the root Cygwin folder, choose Properties, then -the Security tab. Select Advanced, then go to the Owner tab and make sure your -account is listed as the owner. Select the 'Replace owner on subcontainers and -objects' checkbox and press Ok. After Explorer applies the changes you should -be able to delete the entire tree in one operation. Note that you can also -achieve this in Cygwin by typing <literal>chown -R user /</literal> or by using other tools -such as CACLS.EXE. -</para> -</listitem> -<listitem><para>Delete the Cygwin shortcuts on the Desktop and Start Menu, and anything -left by setup.exe in the download directory. However, if you plan to reinstall -Cygwin it's a good idea to keep your setup.exe download directory since you can -reinstall the packages left in its cache without redownloading them. -</para> -</listitem> -<listitem><para>If you added Cygwin to your system path, you should remove it unless you -plan to reinstall Cygwin to the same location. Similarly, if you set your -CYGWIN environment variable system-wide and don't plan to reinstall, you should -remove it. -</para> -</listitem> -<listitem><para>Finally, if you want to be thorough you can delete the registry tree -<literal>Software\Cygnus Solutions</literal> under <literal>HKEY_LOCAL_MACHINE</literal> and/or -<literal>HKEY_CURRENT_USER</literal>. However, if you followed the directions above you -will have already removed all the mount information which is typically the only -thing stored in the registry. -</para> -</listitem> -</orderedlist> - -</answer></qandaentry> - -<qandaentry id="faq.setup.snapshots"> -<question><para>How do I install snapshots?</para></question> -<answer> - -<para>First, are you sure you want to do this? Snapshots are risky. They -have not been tested. Use them <emphasis role='bold'>only</emphasis> if there is a feature or -bugfix that you need to try, and you are willing to deal with any -problems, or at the request of a Cygwin developer. -</para> -<para>You should generally install the full -<literal>cygwin-inst-YYYYMMDD.tar.bz2</literal> update, rather than just the DLL, -otherwise some components may be out of sync. -</para> -<para>You cannot use Cygwin Setup to install a snapshot. -</para> -<para>First, you will need to download the snapshot from the snapshots -page at <ulink url="http://cygwin.com/snapshots/">http://cygwin.com/snapshots/</ulink>. Note the directory where -you saved the snapshot tarball. -</para> -<para>Before installing a snapshot, you must first Close <emphasis role='bold'>all</emphasis> Cygwin -applications, including shells and services (e.g., <literal>inetd</literal>, <literal>sshd</literal>). -You will not be able to replace <literal>cygwin1.dll</literal> if any Cygwin process is -running. You may have to restart Windows to clear the DLL from memory -(beware of automatic service startup). -</para> -<para>Most of the downloaded snapshot can be installed using <literal>tar</literal>. Cygwin -<literal>tar</literal> won't be able to update <literal>/usr/bin/cygwin1.dll</literal> (because it's -used by <literal>tar</literal> itself), but it should succeed with everything else. If -you are only installing the DLL snapshot, skip the first tar command. Open -a <literal>bash</literal> shell (it should be the only running Cygwin process) and issue -the following commands: -<screen> - /bin/tar -C/ -jxvf /posix/path/to/cygwin-inst-YYYYMMDD.tar.bz2 --exclude=usr/bin/cygwin1.dll - /bin/tar -C/tmp -jxvf /posix/path/to/cygwin-inst-YYYYMMDD.tar.bz2 usr/bin/cygwin1.dll -</screen> -</para> -<para>Exit the bash shell, and use Explorer or the Windows command shell to -first rename <literal>C:\cygwin\bin\cygwin1.dll</literal> to -<literal>C:\cygwin\bin\cygwin1-prev.dll</literal> and then move -<literal>C:\cygwin\tmp\usr\bin\cygwin1.dll</literal> -to <literal>C:\cygwin\bin\cygwin1.dll</literal> (assuming you installed Cygwin in -<literal>C:\cygwin</literal>). -</para> -<para>The operative word in trying the snapshots is "<emphasis>trying</emphasis>". If you -notice a problem with the snapshot that was not present in the release -DLL (what we call a "regression"), please report it to the Cygwin -mailing list (see <ulink url="http://cygwin.com/problems.html">http://cygwin.com/problems.html</ulink> for problem -reporting guidelines). If you wish to go back to the older version of the -DLL, again, close all Cygwin processes, delete -<literal>C:\cygwin\bin\cygwin1.dll</literal>, and -rename <literal>C:\cygwin\bin\cygwin1-prev.dll</literal> back to -<literal>C:\cygwin\bin\cygwin1.dll</literal> (again assuming that your "<literal>/</literal>" is -<literal>C:\cygwin</literal>). To restore the rest of the snapshot -files, reinstall the "<literal>cygwin</literal>" package using Setup. -</para> - -</answer></qandaentry> - -<qandaentry id="faq.setup.mirror"> -<question><para>Can Cygwin Setup maintain a ``mirror''?</para></question> -<answer> - -<para>NO. Cygwin Setup cannot do this for you. Use a tool designed for -this purpose. See <ulink url="http://rsync.samba.org/">http://rsync.samba.org/</ulink>, -<ulink url="http://wget.sunsite.dk/">http://wget.sunsite.dk/</ulink> for utilities that can do this for you. -For more information on setting up a custom Cygwin package server, see -the Cygwin Setup homepage at -<ulink url="http://sources.redhat.com/cygwin-apps/setup.html">http://sources.redhat.com/cygwin-apps/setup.html</ulink>. -</para> -</answer></qandaentry> - -<qandaentry id="faq.setup.cd"> -<question><para>How can I make my own portable Cygwin on CD?</para></question> -<answer> - -<para>While some users have successfully done this, for example Indiana -University's XLiveCD <ulink url="http://xlivecd.indiana.edu/">http://xlivecd.indiana.edu/</ulink>, there is no -easy way to do it. Full instructions for constructing a porttable Cygwin -on CD by hand can be found on the mailing list at -<ulink url="http://www.cygwin.com/ml/cygwin/2003-07/msg01117.html">http://www.cygwin.com/ml/cygwin/2003-07/msg01117.html</ulink>. (Thanks -to fergus at bonhard dot uklinux dot net for these instructions.) -</para> -</answer></qandaentry> - -<qandaentry id="faq.setup.registry"> -<question><para>How do I save, restore, delete, or modify the Cygwin information stored in the registry?</para></question> -<answer> - -<para>Currently Cygwin stores its mount table information in the registry. It -is recommended that you use the <literal>mount</literal> and <literal>umount</literal> commands -to manipulate the mount information instead of directly modifying the -registry. -</para> -<para>To save the mount information to a file for later restoration, use -<literal>mount -m > mounts.bat</literal> To remove all mount information use -<literal>umount -A</literal>. To reincorporate saved mount information just run the -batch file. For more information on using <literal>mount</literal>, see -<ulink url="http://cygwin.com/cygwin-ug-net/using-utils.html#mount">http://cygwin.com/cygwin-ug-net/using-utils.html#mount</ulink>. -</para></answer></qandaentry> - diff --git a/winsup/doc/faq-using.xml b/winsup/doc/faq-using.xml deleted file mode 100644 index 39a1ac1c3..000000000 --- a/winsup/doc/faq-using.xml +++ /dev/null @@ -1,959 +0,0 @@ -<!-- faq-problems.xml --> -<qandaentry id="faq.using.missing-dlls"> -<question><para>Why can't my application locate cygncurses5.dll? or cygintl.dll? or cygreadline5.dll? or ...?</para></question> -<answer> - -<para>If you upgraded recently, and suddenly vim (or some other Cygwin -application) cannot find <literal>cygncurses5.dll</literal>, it probably means that you did -not follow these instructions properly: -<ulink url="http://cygwin.com/ml/cygwin-announce/2001/msg00124.html">http://cygwin.com/ml/cygwin-announce/2001/msg00124.html</ulink>. To -repair the damage, you must run Cygwin Setup again, and re-install the -<literal>libncurses5</literal> package. -</para> -<para>Note that Cygwin Setup won't show this option by default. In the -``Select packages to install'' dialog, click on the <literal>Full/Part</literal> -button. This lists all packages, even those that are already -installed. Scroll down to locate the <literal>libncurses5</literal> package. -Click on the ``cycle'' glyph until it says ``Reinstall''. Continue -with the installation. -</para> -<para>Similarly, if something cannot find <literal>cygintl.dll</literal>, then run -Cygwin Setup and re-install the <literal>libintl</literal> and <literal>libintl1</literal> -packages. -</para> -<para>For a detailed explanation of the general problem, and how to extend -it to other missing DLLs (like cygreadline5.dll) and identify their -containing packages, see -<ulink url="http://cygwin.com/ml/cygwin/2002-01/msg01619.html">http://cygwin.com/ml/cygwin/2002-01/msg01619.html</ulink>. -</para> -</answer></qandaentry> - -<qandaentry id="faq.using.slow"> -<question><para>Why is Cygwin suddenly <emphasis>so</emphasis> slow?</para></question> -<answer> - -<para>If you recently upgraded and suddenly <emphasis>every</emphasis> command takes a -<emphasis>very</emphasis> long time, then something is probably attempting to -access a network share. You may have the obsolete <literal>//c</literal> -notation in your PATH or startup files. This now means the -<emphasis>network share</emphasis> <literal>c</literal>, which will slow things down -tremendously if it does not exist. -</para> -<para>Using //c (for C:) doesn't work anymore. (Similarly for any drive -letter, e.g. <literal>//z</literal> for <literal>Z:</literal>) This ``feature'' has long been -deprecated, and no longer works at all in the latest release. As of -release 1.3.3, <literal>//c</literal> now means the <emphasis>network share</emphasis> <literal>c</literal>. -For a detailed discussion of why this change was made, and how deal -with it now, refer to -<ulink url="http://sources.redhat.com/ml/cygwin/2001-09/msg00014.html">http://sources.redhat.com/ml/cygwin/2001-09/msg00014.html</ulink>. -</para> -</answer></qandaentry> - -<qandaentry id="faq.using.services"> -<question><para>Why don't my services work?</para></question> -<answer> - -<para>Most Windows services run as a special user called <literal>SYSTEM</literal>. If you -installed Cygwin for "Just Me", the <literal>SYSTEM</literal> user won't see your -Cygwin mount table. You need to re-mount all of your mounts as -"system" for services to work. You can re-run <literal>setup.exe</literal> and -select "Install for All Users", or this script will do the trick: -</para> -<screen> -eval "`mount -m | sed -e 's/ -u / -s /g' -e 's/$/;/'`" -</screen> -</answer></qandaentry> - -<qandaentry id="faq.using.shares"> -<question><para>Why can't my services access network shares?</para></question> -<answer> - -<para>When a service switches to a certain user, it is running as -<literal>SYSTEM</literal> impersonating the user account. During -impersonation, the user's password is not available and so non-public -network shares are not available. For more information, see -<ulink url="http://cygwin.com/cygwin-ug-net/ntsec.html" />. -</para> -<para>Workarounds include using public network share that does not require -authentication (for non-critical files), providing your password to a -<command>net use</command> command, or running the service as your own -user with <literal>cygrunsrv -u</literal> (see -<literal>/usr/share/doc/Cygwin/cygrunsrv.README</literal> for more -information). -</para> -</answer></qandaentry> - -<qandaentry id="faq.using.path"> -<question><para>How should I set my PATH?</para></question> -<answer> - -<para>This is done for you in the file /etc/profile, which is sourced by bash -when you start it from the Desktop or Start Menu shortcut, created by -<literal>setup.exe</literal>. The line is -</para> -<screen> - PATH="/usr/local/bin:/usr/bin:/bin:$PATH" -</screen> - -<para>Effectively, this <emphasis role='bold'>prepends</emphasis> /usr/local/bin and /usr/bin to your -Windows system path. If you choose to reset your PATH, say in -$HOME/.bashrc, or by editing etc/profile directly, then you should -follow this rule. You <emphasis role='bold'>must</emphasis> have <literal>/usr/bin</literal> in your PATH -<emphasis role='bold'>before</emphasis> any Windows system directories. (And you must not omit -the Windows system directories!) Otherwise you will likely encounter -all sorts of problems running Cygwin applications. -</para> -</answer></qandaentry> - -<qandaentry id="faq.using.not-found"> -<question><para>Bash says "command not found", but it's right there!</para></question> -<answer> - -<para>If you compile a program, you might find that you can't run it: -</para> -<screen> - bash$ gcc -o hello hello.c - bash$ hello - bash: hello: command not found -</screen> - -<para>Unlike Windows, bash does not look for programs in <literal>.</literal> (the current -directory) by default. You can add <literal>.</literal> to your PATH (see above), -but this is not recommended (at least on UNIX) for security reasons. -Just tell bash where to find it, when you type it on the command line: -</para> -<screen> - bash$ gcc -o hello hello.c - bash$ ./hello - Hello World! -</screen> - -</answer></qandaentry> - -<qandaentry id="faq.using.converting-paths"> -<question><para>How do I convert between Windows and UNIX paths?</para></question> -<answer> - -<para>Use the 'cygpath' utility. Type '<literal>cygpath --help</literal>' for -information. For example (on my installation): -<screen> - bash$ cygpath --windows ~/.bashrc - D:\starksb\.bashrc - bash$ cygpath --unix C:/cygwin/bin/cygwin.bat - /usr/bin/cygwin.bat - bash$ cygpath --unix C:\\cygwin\\bin\\cygwin.bat - /usr/bin/cygwin.bat -</screen> -Note that bash interprets the backslash '\' as an escape character, so -you must type it twice in the bash shell if you want it to be recognized -as such. -</para> -</answer></qandaentry> - -<qandaentry id="faq.using.bashrc"> -<question><para>Why doesn't bash read my .bashrc file on startup?</para></question> -<answer> - -<para>Your .bashrc is read from your home directory specified by the HOME -environment variable. It uses /.bashrc if HOME is not set. So you need -to set HOME correctly, or move your .bashrc to the top of the drive -mounted as / in Cygwin. -</para> -</answer></qandaentry> - -<qandaentry id="faq.using.bash-insensitive"> -<question><para>How can I get bash filename completion to be case insensitive?</para></question> -<answer> - -<para>Add the following to your <literal>~/.bashrc</literal> file: -</para> -<screen> - shopt -s nocaseglob -</screen> - -<para>and add the following to your <literal>~/.inputrc</literal> file: -</para> -<screen> - set completion-ignore-case on -</screen> - -</answer></qandaentry> - -<qandaentry id="faq.using.filename-spaces"> -<question><para>Can I use paths/filenames containing spaces in them?</para></question> -<answer> - -<para>Cygwin does support spaces in filenames and paths. That said, some -utilities that use the library may not, since files don't typically -contain spaces in Unix. If you stumble into problems with this, you -will need to either fix the utilities or stop using spaces in filenames -used by Cygwin tools. -</para> -<para>In particular, bash interprets space as a word separator. You would have -to quote a filename containing spaces, or escape the space character. -For example: -<screen> - bash-2.03$ cd '/cygdrive/c/Program Files' -</screen> -or -<screen> - bash-2.03$ cd /cygdrive/c/Program\ Files -</screen> -</para> -</answer></qandaentry> - -<qandaentry id="faq.using.shortcuts"> -<question><para>Why can't I cd into a shortcut to a directory?</para></question> -<answer> - -<para>Cygwin versions < 1.3.0 do not follow MS Windows Explorer Shortcuts -(*.lnk files). It sees a shortcut as a regular file and this you -cannot "cd" into it. -</para> -<para>Since version 1.3.0, Cygwin uses shortcuts as symlinks by default. -</para> -<para>Cygwin shortcuts are different from shortcuts created by native Windows -applications. Windows applications can usually make use of Cygwin -shortcuts but not vice versa. This is by choice. The reason is that -Windows shortcuts may contain a bunch of extra information which would -get lost, if, for example, Cygwin tar archives and extracts them as -symlinks. -</para> -<para>Changing a Cygwin shortcut in Windows Explorer usually changes a Cygwin -shortcut into a Windows native shortcut. Afterwards, Cygwin will not -recognize it as symlink anymore. -</para> -</answer></qandaentry> - -<qandaentry id="faq.using.find"> -<question><para>I'm having basic problems with find. Why?</para></question> -<answer> - -<para>Make sure you are using the find that came with Cygwin and that you -aren't picking up the Win32 find command instead. You can verify that -you are getting the right one by doing a "type find" in bash. -</para> -<para>If the path argument to find, including current directory (default), is -itself a symbolic link, then find will not traverse it unless you -specify the <literal>-follow</literal> option. This behavior is different than most -other UNIX implementations, but is not likely to change. -</para> -<para>If find does not seem to be producing enough results, or seems to be -missing out some directories, you may be experiencing a problem with one -of find's optimisations. The absence of <literal>.</literal> and <literal>..</literal> -directories on some filesystems, such as DVD-R UDF, can confuse find. -See the documentation for the option <literal>-noleaf</literal> in the man page. -</para> -</answer></qandaentry> - -<qandaentry id="faq.using.su"> -<question><para>Why doesn't <literal>su</literal> work?</para></question> -<answer> - -<para>The <literal>su</literal> command has been in and out of Cygwin distributions, but -it has not been ported to Cygwin and has never worked. It is -currently installed as part of the sh-utils, but again, it does not work. -</para> -<para>You may be able to use <literal>login</literal> instead, but you should read -<ulink url="http://www.cygwin.com/ml/cygwin/2001-03/msg00337.html">http://www.cygwin.com/ml/cygwin/2001-03/msg00337.html</ulink> first. -</para> -<para>For some technical background into why <literal>su</literal> doesn't work, read -<ulink url="http://www.cygwin.com/ml/cygwin/2003-06/msg00897.html">http://www.cygwin.com/ml/cygwin/2003-06/msg00897.html</ulink> and -related messages. -</para> -</answer></qandaentry> - -<qandaentry id="faq.using.man"> -<question><para>Why doesn't man (or apropos) work?</para></question> -<answer> - -<para>Before you can use <literal>man -k</literal> or <literal>apropos</literal>, you -must create the whatis database. Just run the command -</para> -<screen> - /usr/sbin/makewhatis -</screen> - -<para>(it may take a minute to complete). -</para> -</answer></qandaentry> - -<qandaentry id="faq.using.chmod"> -<question><para>Why doesn't chmod work?</para></question> -<answer> - -<para><literal>ntsec</literal> will allow UNIX permissions in Windows NT on NTFS file -systems. This is on by default (a recent change). -</para> -<para><literal>ntea</literal> works on NTFS <emphasis>and</emphasis> FAT but it creates a huge, -<emphasis role='bold'>undeletable</emphasis> file on FAT filesystems. -</para> -<para>(The <literal>ntsec</literal> and <literal>ntea</literal> settings are values for the -<literal>CYGWIN</literal> environment variable. See the Cygwin User's Guide at -<ulink url="http://cygwin.com/cygwin-ug-net/cygwin-ug-net.html">http://cygwin.com/cygwin-ug-net/cygwin-ug-net.html</ulink> for more -information on this variable and its settings.) -</para> -<para>There is no solution at all for Windows 9x. -</para> -<para>If you have an application that requires a certain permission mode on a -file, you may be able to work around this requirement by modifying the -application's source code. For a hint, based on work done by Corinna -Vinschen for OpenSSH, see this message from the cygwin mailing list: -<ulink url="http://cygwin.com/ml/cygwin/2000-11/msg01176.html">http://cygwin.com/ml/cygwin/2000-11/msg01176.html</ulink>. -</para> -</answer></qandaentry> - -<qandaentry id="faq.using.mkdir-network"> -<question><para>Why doesn't <literal>mkdir -p</literal> work on a network share?</para></question> -<answer> - -<para>Starting with <literal>coreutils-5.3.0-6</literal> and <literal>cygwin-1.5.17</literal>, you can -do something like this: -</para> -<screen> -bash$ mkdir -p //MACHINE/Share/path/to/new/dir -</screen> - -<para>However, coreutils expects Unix path names, so something like -<literal>mkdir -p \\\\machine\\share\\path</literal> will fail. -</para> -</answer></qandaentry> - -<qandaentry id="faq.using.shell-scripts"> -<question><para>Why doesn't my shell script work?</para></question> -<answer> - -<para>There are two basic problems you might run into. One is the fact that -<command>/bin/sh</command> is really <command>bash</command> (prior to -<command>bash-3.0-6</command>, <command>/bin/sh</command> was ash). and is -missing some features you might expect in <command>/bin/sh</command>, -particularly if you are used to <command>/bin/sh</command> actually being -<command>zsh</command> (MacOS X "Panther") or <command>ksh</command> (Tru64). -</para> - -<para>Or, it could be a permission problem, and Cygwin doesn't understand that your script is executable. Because <literal>chmod</literal> may not work (see FAQ entry above), Cygwin must read the contents of files to determine if -they are executable. If your script does not start with -</para> -<screen> - #! /bin/sh -</screen> - -<para>(or any path to a script interpreter, it does not have to be /bin/sh) -then Cygwin will not know it is an executable script. The Bourne shell -idiom -</para> -<screen> - : - # This is the 2nd line, assume processing by /bin/sh -</screen> - -<para>also works. -</para> -<para>Note that you can use <literal>mount -x</literal> to force Cygwin to treat all files -under the mount point as executable. This can be used for individual -files as well as directories. Then Cygwin will not bother to read files -to determine whether they are executable. -</para> -</answer></qandaentry> - -<qandaentry id="faq.using.printing"> -<question><para>How do I print under Cygwin?</para></question> -<answer> - -<para>There is no working lp or lpr system as you would find on UNIX. -</para> -<para>Jason Tishler has written a couple of messages that explain how to use -a2ps (for nicely formatted text in PostScript) and ghostscript (to print -PostScript files on non-PostScript Windows printers). Start at -<ulink url="http://cygwin.com/ml/cygwin/2001-04/msg00657.html">http://cygwin.com/ml/cygwin/2001-04/msg00657.html</ulink>. Note that the -<literal>file</literal> command is now available as part of Cygwin setup. -</para> -<para>Alternatively, on NT, you can use the Windows <literal>print</literal> command. (It -does not seem to be available on Win9x.) Type -</para> -<screen> - bash$ print /\? -</screen> - -<para>for usage instructions (note the <literal>?</literal> must be escaped from the -shell). -</para> -<para>Finally, you can simply <literal>cat</literal> the file to the printer's share name: -</para> -<screen> - bash$ cat myfile > //host/printer -</screen> - -<para>You may need to press the formfeed button on your printer or append the -formfeed character to your file. -</para> -</answer></qandaentry> - -<qandaentry id="faq.using.unicode"> -<question><para>Why don't international (Unicode) characters work?</para></question> -<answer> - -<para>Internationalization is a complex issue. The short answer is that -Cygwin is not Unicode-aware, so things that might work in Linux will -not necessarily work on Cygwin. However, some things do work. To type -international characters (£äö) in <literal>bash</literal>, add the following -lines to your <literal>~/.inputrc</literal> file and restart <literal>bash</literal>: -</para> -<screen> - set meta-flag on - set convert-meta off - set output-meta on - set input-meta on - set kanji-code sjis - set meta-flag on -</screen> - -<para>These are options to the <literal>readline</literal> library, which you can read -about in the <literal>bash(1)</literal> and <literal>readline(3)</literal> man pages. Other -tools that do not use <literal>readline</literal> for display, such as <literal>less</literal> -and <literal>ls</literal>, require additional settings, which could be put in your -<literal>~/.bashrc</literal>: -<screen> -alias less='/bin/less -r' -alias ls='/bin/ls -F --color=tty --show-control-chars' -export LANG="ja_JP.SJIS" -export OUTPUT_CHARSET="sjis" -</screen> -These examples use the Japanese Shift-JIS character set, obviously -you will want to change them for your own locale. -</para> - -</answer></qandaentry> - -<qandaentry id="faq.using.cursor"> -<question><para>Why don't cursor keys work under Win95/Win98?</para></question> -<answer> - -<para><emphasis role='bold'>(Please note: This section has not yet been updated for the latest net release.)</emphasis> -</para> -<para>Careful examination shows that they not just non-functional, but -rather behave strangely, for example, with NumLock off, keys on numeric -keyboard work, until you press usual cursor keys, when even numeric -stop working, but they start working again after hitting alphanumeric -key, etc. This reported to happen on localized versions of Win98 and -Win95, and not specific to Cygwin; there are known cases of Alt+Enter -(fullscreen/windowed toggle) not working and shifts sticking with -other programs. The cause of this problem is Microsoft keyboard -localizer which by default installed in 'autoexec.bat'. Corresponding -line looks like: -</para> -<screen> -keyb ru,,C:\WINDOWS\COMMAND\keybrd3.sys -</screen> - -<para>(That's for russian locale.) You should comment that line if you want -your keys working properly. Of course, this will deprive you of your -local alphabet keyboard support, so you should think about -another localizer. ex-USSR users are of course knowledgeable of Keyrus -localizer, and it might work for other locales too, since it has keyboard -layout editor. But it has russian messages and documentation ;-( -Reference URL is http://www.hnet.ru/software/contrib/Utils/KeyRus/ -(note the you may need to turn off Windows logo for Keyrus to operate -properly). -</para> -</answer></qandaentry> - -<qandaentry id="faq.using.multiple-copies"> -<question><para>Is it OK to have multiple copies of the DLL?</para></question> -<answer> - -<para>You should only have one copy of the Cygwin DLL on your system. If you -have multiple versions, they will conflict and cause problems. -</para> -<para>If you get the error "shared region is corrupted" or "shared region -version mismatch" it means you have multiple versions of cygwin1.dll -running at the same time. This could happen, for example, if you update -cygwin1.dll without exiting <emphasis>all</emphasis> Cygwin apps (including inetd) -beforehand. -</para> -<para>The only DLL that is sanctioned by the Cygwin project is the one that -you get by running <ulink url="http://cygwin.com/setup.exe">http://cygwin.com/setup.exe</ulink>, installed in the -directory controlled by this program. If you have other versions on -your system and desire help from the cygwin project, you should delete -or rename all DLLs that are not installed by <filename>setup.exe</filename>. -</para> -<para>If you're trying to find multiple versions of the DLL that are causing -this problem, reboot first, in case DLLs still loaded in memory are the -cause. Then use the Windows System find utility to search your whole -machine, not just components in your PATH (as 'type' would do) or -cygwin-mounted filesystems (as Cygwin 'find' would do). -</para> -</answer></qandaentry> - -<qandaentry id="faq.using.missing-packages"> -<question><para>Why isn't package XYZ available in Cygwin?</para></question> -<answer> - -<para>Probably because there is nobody willing or able to maintain it. It -takes time, and the priority for the Cygwin Team is the Cygwin package. -The rest is a volunteer effort. Want to contribute? See -<ulink url="http://cygwin.com/setup.html">http://cygwin.com/setup.html</ulink>. -</para> -</answer></qandaentry> - -<qandaentry id="faq.using.old-packages"> -<question><para>Why is the Cygwin package of XYZ so out of date?</para></question> -<answer> - -<para>(Also: Why is the version of package XYZ older than the version that I -can download from the XYZ web site? Why is the version of package XYZ -older than the version that I installed on my linux system? Is there -something special about Cygwin which requires that only an older version -of package XYZ will work on it?) -</para> -<para>Every package in the Cygwin distribution has a maintainer who is -responsible for sending out updates of the package. This person is a -volunteer who is rarely the same person as the official developer of the -package. If you notice that a version of a package seems to be out of -date, the reason is usually pretty simple -- the person who is -maintaining the package hasn't gotten around to updating it yet. Rarely, -the newer package actually requires complex changes that the maintainer -is working out. -</para> -<para>If you urgently need an update, sending a polite message to the cygwin -mailing list pinging the maintainer is perfectly acceptable. There are -no guarantees that the maintainer will have time to update the package -or that you'll receive a response to your request, however. -</para> -<para>Remeber that the operative term here is "volunteer". -</para> -</answer></qandaentry> - -<qandaentry id="faq.using.accessing-drives"> -<question><para>How can I access other drives?</para></question> -<answer> - -<para>You have some flexibility here. -</para> -<para>Cygwin has a builtin "cygdrive prefix" for drives that are not mounted. -You can access any drive, say Z:, as '/cygdrive/z/'. -</para> -<para>In some applications (notably bash), you can use the familiar windows -<drive>:/path/, using posix forward-slashes ('/') instead of Windows -backward-slashes ('\'). (But see the warning below!) This maps in the -obvious way to the Windows path, but will be converted internally to use -the Cygwin path, following mounts (default or explicit). For example: -<screen> - bash$ cd C:/Windows - bash$ pwd - /cygdrive/c/Windows -</screen> -and -<screen> - bash$ cd C:/cygwin - bash$ pwd - / -</screen> -for a default setup. You could also use backward-slashes in the -Windows path, but these would have to be escaped from the shell. -</para> -<para><emphasis role='bold'>Warning:</emphasis> There is some ambiguity in going from a Windows path -to the posix path, because different posix paths, through different -mount points, could map to the same Windows directory. This matters -because different mount points may be binmode or textmode, so the -behavior of Cygwin apps will vary depending on the posix path used to -get there. -</para> -<para>You can avoid the ambiguity of Windows paths, and avoid typing -"/cygdrive", by explicitly mounting drives to posix paths. For example: -<screen> - bash$ mkdir /c - bash$ mount c:/ /c - bash$ ls /c -</screen> -Then <literal>/cygdrive/c/Windows</literal> becomes <literal>/c/Windows</literal> which is a -little less typing. -</para> -<para>Note that you only need to mount drives once. The mapping is kept -in the registry so mounts stay valid pretty much indefinitely. -You can only get rid of them with umount, or the registry editor. -</para> -<para>The '-b' option to mount mounts the mountpoint in binary mode -("binmode") where text and binary files are treated equivalently. This -should only be necessary for badly ported Unix programs where binary -flags are missing from open calls. It is also the setting for /, -/usr/bin and /usr/lib in a default Cygwin installation. The default for -new mounts is text mode ("textmode"), which is also the mode for all -"cygdrive" mounts. -</para> -<para>You can change the default <literal>cygdrive</literal> prefix and whether it is -binmode or textmode using the <literal>mount</literal> command. For example, -<screen> - bash$ mount -b --change-cygdrive-prefix cygdrive -</screen> -will change all <literal>/cygdrive/...</literal> mounts to binmode. -</para> -</answer></qandaentry> - -<qandaentry id="faq.using.copy-and-paste"> -<question><para>How can I copy and paste into Cygwin console windows?</para></question> -<answer> - -<para>First, consider using rxvt instead of the standard console window. In -rxvt, selecting with the left-mouse also copies, and middle-mouse -pastes. It couldn't be easier! -</para> -<para>Under Windows NT, open the properties dialog of the console window. -The options contain a toggle button, named "Quick edit mode". It must -be ON. Save the properties. -</para> -<para>Under Windows 9x, open the properties dialog of the console window. -Select the Misc tab. Uncheck Fast Pasting. Check QuickEdit. -</para> -<para>You can also bind the insert key to paste from the clipboard by adding -the following line to your .inputrc file: -<screen> - "\e[2~": paste-from-clipboard -</screen> -</para> -</answer></qandaentry> - -<qandaentry id="faq.using.firewall"> -<question><para>What firewall should I use with Cygwin? </para></question> -<answer> - -<para>We have had good reports about Kerio Personal Firewall, ZoneLabs -Integrity Desktop, and the built-in firewall in Windows XP. Other -well-known products including ZoneAlarm and Norton Internet Security have -caused problems for some users but work fine for others. At last report, -Agnitum Outpost did not work with Cygwin. If you are having strange -connection-related problems, disabling the firewall is a good -troubleshooting step (as is closing or disabling all other running -applications, especially resource-intensive processes such as indexed -search). -</para> -<para>On the whole, Cygwin doesn't care which firewall is used. The few rare -exceptions have to do with socket code. -Cygwin uses sockets to implement many of its functions, such as IPC. -Some overzealous firewalls install themselves deeply into the winsock -stack (with the 'layered service provider' API) and install hooks -throughout. Sadly the mailing list archives are littered with examples -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> -</answer></qandaentry> - -<qandaentry id="faq.using.sharing-files"> -<question><para>How can I share files between Unix and Windows?</para></question> -<answer> - -<para>During development, we have both Linux boxes running Samba and Windows -machines. We often build with cross-compilers under Linux and copy -binaries and source to the Windows system or just toy with them -directly off the Samba-mounted partition. On dual-boot NT/Windows 9x -machines, we usually use the FAT filesystem so we can also access the -files under Windows 9x. -</para> -</answer></qandaentry> - -<qandaentry id="faq.using.case-sensitive"> -<question><para>Is Cygwin case-sensitive? What are managed mounts?</para></question> -<answer> - -<para>Several Unix programs expect to be able to use to filenames -spelled the same way, but with different case. A prime example -of this is perl's configuration script, which wants <literal>Makefile</literal> and -<literal>makefile</literal>. WIN32 can't tell the difference between files with -just different case, so the configuration fails. -</para> -<para>To help with this problem, starting in <literal>cygwin-1.5.0</literal> it is -possible to have a case sensitive Cygwin managed mount. This is an -experimental feature and should be used with caution. You should only -use it for directories that are initially unpopulated and are due to -be completely managed by cygwin (hence the name). So, the best use -would be to create an empty directory, mount it, and then add files to -it: -</para> -<screen> -mkdir /managed-dir -mount -o managed c:/cygwin/managed-dir /managed-dir -cd /managed-dir/ -touch makefile -touch Makefile -</screen> - -</answer></qandaentry> - -<qandaentry id="faq.using.dos-filenames"> -<question><para>What about DOS special filenames?</para></question> -<answer> - -<para>Files cannot be named com1, lpt1, or aux (to name a few); either as -the root filename or as the extension part. If you do, you'll have -trouble. Unix programs don't avoid these names which can make things -interesting. E.g., the perl distribution has a file called -<literal>aux.sh</literal>. The perl configuration tries to make sure that -<literal>aux.sh</literal> is there, but an operation on a file with the magic -letters 'aux' in it will hang. -</para> -</answer></qandaentry> - -<qandaentry id="faq.using.hangs"> -<question><para>When it hangs, how do I get it back?</para></question> -<answer> - -<para>If something goes wrong and the tools hang on you for some reason (easy -to do if you try and read a file called aux.sh), first try hitting ^C to -return to bash or the cmd prompt. -</para> -<para>If you start up another shell, and applications don't run, it's a good -bet that the hung process is still running somewhere. Use the Task -Manager, pview, or a similar utility to kill the process. -</para> -<para>And, if all else fails, there's always the reset button/power switch. -This should never be necessary under Windows NT. -</para> -</answer></qandaentry> - -<qandaentry id="faq.using.directory-structure"> -<question><para>Why the weird directory structure?</para></question> -<answer> - -<para>Why do /lib and /usr/lib (and /bin, /usr/bin) point to the same thing? -</para> -<para>Why use mounts instead of symbolic links? -</para> -<para>Can I use a disk root (e.g., C:\) as Cygwin root? Why is this discouraged? -</para> -<para>After a new installation in the default location, your mount points will -look something like this: -</para> -<screen> - bash$ mount - C:\cygwin\bin on /usr/bin type system (binmode) - C:\cygwin\lib on /usr/lib type system (binmode) - C:\cygwin on / type system (binmode) -</screen> - -<para>(Exactly what you see depends on what options you gave to <literal>setup.exe</literal>.) -</para> -<para>Note that /bin and /usr/bin point to the same location, as do /lib and -/usr/lib. This is intentional, and you should not undo these mounts -unless you <emphasis>really</emphasis> know what you are doing. -</para> -<para>Various applications and packages may expect to be installed in /lib or -/usr/lib (similarly /bin or /usr/bin). Rather than distinguish between -them and try to keep track of them (possibly requiring the occasional -duplication or symbolic link), it was decided to maintain only one -actual directory, with equivalent ways to access it. -</para> -<para>Symbolic links had been considered for this purpose, but were dismissed -because they do not always work on Samba drives. Also, mounts are -faster to process because no disk access is required to resolve them. -</para> -<para>Note that non-cygwin applications will not observe Cygwin mounts (or -symlinks for that matter). For example, if you use WinZip to unpack the -tar distribution of a Cygwin package, it may not get installed to the -correct Cygwin path. <emphasis>So don't do this!</emphasis> -</para> -<para>It is strongly recommended not to make the Cygwin root directory the -same as your drive's root directory, unless you know what you are doing -and are prepared to deal with the consequences. It is generally easier -to maintain the Cygwin hierarchy if it is isolated from, say, C:\. For -one thing, you avoid possible collisions with other (non-cygwin) -applications that may create (for example) \bin and \lib directories. -(Maybe you have nothing like that installed now, but who knows about -things you might add in the future?) -</para> -</answer></qandaentry> - -<qandaentry id="faq.using.anti-virus"> -<question><para>How do anti-virus programs like Cygwin?</para></question> -<answer> - -<para>Users have reported that NAI (formerly McAfee) VirusScan for NT (and -others?) is incompatible with Cygwin. This is because it tries to scan -the newly loaded shared memory in cygwin1.dll, which can cause fork() to -fail, wreaking havoc on many of the tools. (It is not confirmed that -this is still a problem, however.) -</para> -<para>There have been several reports of NAI VirusScan causing the system to -hang when unpacking tar.gz archives. This is surely a bug in VirusScan, -and should be reported to NAI. The only workaround is to disable -VirusScan when accessing these files. This can be an issue during -setup, and is discussed in that FAQ entry. -</para> -<para>Some users report a significant performance hit using Cygwin when their -anti-virus software is enabled. Rather than disable the anti-virus -software completely, it may be possible to specify directories whose -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> -</answer></qandaentry> - -<qandaentry id="faq.using.emacs"> -<question><para>Is there a Cygwin port of GNU Emacs?</para></question> -<answer> - -<para>Yes! It uses the X11 (<ulink url="http://cygwin.com/xfree/">http://cygwin.com/xfree/</ulink>) Windows -interface. From a remote login shell, this ``emacs -nw'' works fine. -There is also a non-X11 version which just provides the text-only -terminal interface. Use Cygwin Setup to install either one (or both). -</para> -</answer></qandaentry> - -<qandaentry id="faq.using.ntemacs"> -<question><para>What about NT Emacs?</para></question> -<answer> - -<para>If you want GNU Emacs with a native Microsoft Windows interface, but -without X, then you must use the native Windows port, commonly known -as ``NT Emacs''. You get NT Emacs from any GNU mirror. It is not -available from Cygwin Setup. -</para> -<para>NT Emacs uses the Windows command shell by default. Since it is not a -Cygwin application, it has no knowledge of Cygwin mounts. With those -points in mind, you need to add the following code to your ~/.emacs -(or ~/_emacs) file in order to use Cygwin bash. This is particularly useful -for the JDEE package (<ulink url="http://jdee.sunsite.dk/">http://jdee.sunsite.dk/</ulink>). The following -settings are for Emacs 21.1: -</para> -<screen> - ;; This assumes that Cygwin is installed in C:\cygwin (the - ;; default) and that C:\cygwin\bin is not already in your - ;; Windows Path (it generally should not be). - ;; - (setq exec-path (cons "C:/cygwin/bin" exec-path)) - (setenv "PATH" (concat "C:\\cygwin\\bin;" (getenv "PATH"))) - ;; - ;; NT-emacs assumes a Windows command shell, which you change - ;; here. - ;; - (setq shell-file-name "bash") - (setenv "SHELL" shell-file-name) - (setq explicit-shell-file-name shell-file-name) - ;; - ;; This removes unsightly ^M characters that would otherwise - ;; appear in the output of java applications. - ;; - (add-hook 'comint-output-filter-functions - 'comint-strip-ctrl-m) -</screen> - -<para>If you want NT Emacs to understand Cygwin paths, get -cygwin-mount.el from <ulink url="http://www.emacswiki.org/elisp/index.html">http://www.emacswiki.org/elisp/index.html</ulink>. -</para> -<para>Note that all of this ``just works'' if you use the Cygwin port of -Emacs from Cygwin Setup. -</para> -</answer></qandaentry> - -<qandaentry id="faq.using.xemacs"> -<question><para>What about XEmacs?</para></question> -<answer> - -<para>For a concise description of the current situation with XEmacs, see -this message from the Cygwin mailing list: -<ulink url="http://cygwin.com/ml/cygwin/2002-11/msg00609.html">http://cygwin.com/ml/cygwin/2002-11/msg00609.html</ulink>. -</para> -</answer></qandaentry> - -<qandaentry id="faq.using.console-window"> -<question><para>Is there a better alternative to the standard console window?</para></question> -<answer> - -<para>Yes! Use rxvt instead. It's an optional package in Cygwin Setup. -You can use it with or without X11. You can resize it easily by -dragging an edge or corner. Copy and paste is easy with the left and -middle mouse buttons, respectively. It will honor settings in your -~/.Xdefaults file, even without X. -</para> -<para>Don't invoke as simply ``rxvt'' because that will run /bin/sh (really -ash) which is not a good interactive shell. For details see -<literal>/usr/doc/Cygwin/rxvt-<ver>.README</literal>. -</para> -</answer></qandaentry> - -<qandaentry id="faq.using.info-error"> -<question><para>info error "dir: No such file or directory"</para></question> -<answer> - -<para>Cygwin packages install their info documentation in the -<literal>/usr/share/info</literal> directory. But you need to create a <literal>dir</literal> -file there before the standalone info program (probably -<literal>/usr/bin/info</literal>) can be used to read those info files. This is how -you do it: -<screen> - bash$ cd /usr/share/info - bash$ for f in *.info ; do install-info $f dir ; done -</screen> -This may generate warnings: -<screen> - install-info: warning: no info dir entry in `gzip.info' - install-info: warning: no info dir entry in `time.info' -</screen> -The <literal>install-info</literal> command cannot parse these files, so you will -have to add their entries to <literal>/usr/share/info/dir</literal> by hand. -</para> -<para>Even if the dir file already exists, you may have to update it when -you install new Cygwin packages. Some packages update the dir file -for you, but many don't. -</para> -</answer></qandaentry> - -<qandaentry id="faq.using.out-of-queue"> -<question><para>Why do I get a message saying Out of Queue slots?</para></question> -<answer> - -<para>"Out of queue slots!" generally occurs when you're trying to remove -many files that you do not have permission to remove (either because -you don't have permission, they are opened exclusively, etc). What -happens is Cygwin queues up these files with the supposition that it -will be possible to delete these files in the future. Assuming that -the permission of an affected file does change later on, the file will -be deleted as requested. However, if too many requests come in to -delete inaccessible files, the queue overflows and you get the message -you're asking about. Usually you can remedy this with a quick chmod, -close of a file, or other such thing. (Thanks to Larry Hall for -this explanation). -</para> -</answer></qandaentry> - -<qandaentry id="faq.using.symlinks-samba"> -<question><para>Why don't symlinks work on samba-mounted filesystems?</para></question> -<answer> - -<para>Symlinks are marked with "system" file attribute. Samba does not -enable this attribute by default. To enable it, consult your Samba -documentation and then add these lines to your samba configuration -file: -</para> -<screen> - map system = yes - create mask = 0775 -</screen> - -<para>Note that the 0775 can be anything as long as the 0010 bit is set. -</para> -</answer></qandaentry> - -<qandaentry id="faq.using.df-incorrect"> -<question><para>Why does df report sizes incorrectly.</para></question> -<answer> - -<para>There is a bug in the Win32 API function GetFreeDiskSpace that -makes it return incorrect values for disks larger than 2 GB in size. -Perhaps that may be your problem? -</para> -</answer></qandaentry> - -<qandaentry id="faq.using.tcl-tk"> -<question><para>Why doesn't Cygwin tcl/tk understand Cygwin paths?</para></question> -<answer> - -<para>The versions of Tcl/Tk distributed with Cygwin (e.g. cygtclsh80.exe, -cygwish80.exe) are not actually "Cygwin versions" of those tools. -They are built with the <literal>-mno-cygwin</literal> option to <literal>gcc</literal>, which -means they do not understand Cygwin mounts or symbolic links. -</para> -<para>See the entry "How do I convert between Windows and UNIX paths?" -elsewhere in this FAQ. -</para></answer></qandaentry> - diff --git a/winsup/doc/faq-what.xml b/winsup/doc/faq-what.xml deleted file mode 100644 index 3260abf8e..000000000 --- a/winsup/doc/faq-what.xml +++ /dev/null @@ -1,206 +0,0 @@ -<!-- faq-what.xml --> -<qandaentry id="faq.what"> -<question><para>What is it?</para></question> -<answer> - -<para>The Cygwin tools are ports of the popular GNU development tools for -Microsoft Windows. They run thanks to the Cygwin library which -provides the UNIX system calls and environment these programs expect. -</para> -<para>With these tools installed, it is possible to write Win32 console or -GUI applications that make use of the standard Microsoft Win32 API -and/or the Cygwin API. As a result, it is possible to easily -port many significant Unix programs without the need -for extensive changes to the source code. This includes configuring -and building most of the available GNU software (including the packages -included with the Cygwin development tools themselves). Even if -the development tools are of little to no use to you, you may have -interest in the many standard Unix utilities provided with the package. -They can be used both from the bash shell (provided) or from the -standard Windows command shell. -</para> -</answer></qandaentry> - -<qandaentry id="faq.what.supported"> -<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, except Windows CE. This includes Windows 95/98/ME/NT/2000/XP/2003 -and the WOW64 32 bit environment on released 64 bit versions of Windows. -As far as we know no one is working on a native 64 bit version of Cygwin. -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" />. -</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 -exhibit different limitations, on the various versions of Windows. -</para> -</answer></qandaentry> - -<qandaentry id="faq.what.where"> -<question><para>Where can I get it?</para></question> -<answer> - -<para>The home page for the Cygwin project is <ulink url="http://cygwin.com/">http://cygwin.com/</ulink>. -There you should find everything you need for Cygwin, including links -for download and setup, a current list of mirror sites, a User's -Guide, an API Reference, mailing lists and archives, and additional -ported software. -</para> -<para>You can find documentation for the individual GNU tools at -<ulink url="http://www.gnu.org/manual/" />. (You should read GNU manuals from a -local mirror. Check <ulink url="http://www.gnu.org/server/list-mirrors.html" /> -for a list of them.) -</para> -</answer></qandaentry> - -<qandaentry id="faq.what.free"> -<question><para>Is it free software?</para></question> -<answer> - -<para>Yes. Parts are GNU software (gcc, gas, ld, etc...), parts are covered -by the standard X11 license, some of it is public domain, some of -it was written by Cygnus and placed under the GPL. None of it is -shareware. You don't have to pay anyone to use it but you should be -sure to read the copyright section of the FAQ for more information on -how the GNU General Public License may affect your use of these tools. -</para> -<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; please visit -<ulink url="http://cygwin.com/license.html" /> for more information. -All other questions should be sent to the project -mailing list cygwin@cygwin.com. -</para> -<para>Note that when we say "free" we mean freedom, not price. The goal of -such freedom is that the people who use a given piece of software -should be able to change it to fit their needs, learn from it, share -it with their friends, etc. The Cygwin license allows you those -freedoms, so it is free software. -</para> -</answer></qandaentry> - -<qandaentry id="faq.what.version"> -<question><para>What version of Cygwin <emphasis>is</emphasis> this, anyway?</para></question> -<answer> - -<para>To find the version of the Cygwin DLL installed, you can use -<filename>uname</filename> as on Linux or <filename>cygcheck</filename>. Refer to each command's -<literal>--help</literal> output and the <ulink url='http://cygwin.com/cygwin-ug-net/'>Cygwin User's Guide</ulink> for more information. -</para> -<para>If you are looking for the version number for the whole Cygwin -release, there is none. Each package in the Cygwin release has its own -version. The packages in Cygwin are continually improving, thanks to -the efforts of net volunteers who maintain the Cygwin binary ports. -Each package has its own version numbers and its own release process. -</para> -<para>So, how do you get the most up-to-date version of Cygwin? Easy. Just -download the Cygwin Setup program from -<ulink url='http://cygwin.com/setup.exe'>http://cygwin.com/setup.exe</ulink>. This program will handle the task -of updating the packages on your system to the latest version. For -more information about using Cygwin's <filename>setup.exe</filename>, see -<ulink url='http://cygwin.com/cygwin-ug-net/setup-net.html'>Setting Up Cygwin</ulink> -in the Cygwin User's Guide. -</para></answer></qandaentry> - -<qandaentry id="faq.what.history"> -<question><para>History</para></question> -<answer> -<para>See <ulink url="http://cygwin.com/history.html">http://cygwin.com/history.html</ulink>. -</para> -</answer></qandaentry> - -<qandaentry id="faq.what.who"> -<question><para>Who's behind the project?</para></question> -<answer> - -<para><emphasis role='bold'>(Please note that if you have cygwin-specific questions, all of these people will appreciate it if you use the cygwin mailing lists rather than sending personal email.)</emphasis> -</para> -<para>Chris Faylor is behind many of the recent changes in Cygwin. Prior to -joining Cygnus, he contributed significant fixes to the process control -and environ code, reworked the strace mechanism, and rewrote the -signal-related code from scratch as a Net contributor. In addition to -continuing to make technical contributions, Chris is also currently the -group's manager. -</para> -<para>Corinna Vinschen has contributed several useful fixes to the path -handling code, console support, improved security handling, and raw -device support. Corinna is currently employed by Red Hat as a -GDB/Cygwin engineer. -</para> -<para>DJ Delorie has done important work in profiling Cygwin, -worked on the Dejagnu automated testing framework, merged the dlltool -functionality into ld, wrote a good deal of the Cygwin Users' Guide, -authored the cygcheck utility, and made automated snapshots available -from our project WWW page. DJ is currently employed by Red Hat as -a GCC engineer. -</para> -<para>Egor Duda has contributed many useful fixes. He is responsible for -Cygwin's ability to start a debugger on detection of a fatal error -as well as produce core dumps. -</para> -<para>Robert Collins has contributed many improvements to thread handling -as well as generic fixes to cygwin itself. -</para> -<para>Kazuhiro Fujieda has contributed many bug fixes and bug reports. -</para> -<para>Earnie Boyd has contributed many bug fixes and is the mingw and w32api -maintainer. -</para> -<para>David Starks-Browning is our dedicated FAQ maintainer. -</para> -<para>Geoffrey Noer took over the Cygwin project from its initial author Steve -Chamberlain in mid-1996. As maintainer, he produced Net releases beta -16 through 20; made the development snapshots; worked with Net -contributors to fix bugs; made many various code improvements himself; -wrote a paper on Cygwin for the 1998 Usenix NT Symposium; authored the -project WWW pages, FAQ, README; etc. Geoffrey is not currently employed -by Red Hat. -</para> -<para>Steve Chamberlain designed and implemented -Cygwin in 1995-1996 while working for Cygnus. He worked with the Net -to improve the technology, ported/integrated many of the user tools -for the first time to Cygwin, and produced all of the releases up to -beta 14. Steve is not currently employed by Red Hat. -</para> -<para>Marco Fuykschot and Peter Boncz of Data Distilleries contributed nearly -all of the changes required to make Cygwin thread-safe. They also -provided the pthreads interface. -</para> -<para>Sergey Okhapkin has been an invaluable Net contributor. He implemented -the tty/pty support, has played a significant role in revamping signal -and exception handling, and has made countless contributions throughout -the library. He also provided binaries of the development snapshots to -the Net after the beta 19 release. -</para> -<para>Mumit Khan has been most helpful on the EGCS end of things, providing -quite a large number of stabilizing patches to the compiler tools for -the B20 release. -</para> -<para>Philippe Giacinti contributed the implementation of dlopen, dlclose, -dlsym, dlfork, and dlerror in Cygwin. -</para> -<para>Ian Lance Taylor did a much-needed rework of the path handling code for -beta 18, and has made many assorted fixes throughout the code. Jeremy -Allison made significant contributions in the area of file handling and -process control, and rewrote select from scratch. Doug Evans rewrote -the path-handling code in beta 16, among other things. Kim Knuttila and -Michael Meissner put in many long hours working on the now-defunct -PowerPC port. Jason Molenda and Mark Eichin have also made important -contributions. -</para> -<para>Please note that all of us working on Cygwin try to -be as responsive as possible and deal with patches and questions as we -get them, but realistically we don't have time to answer all of the -email that is sent to the main mailing list. Making Net releases of the -Win32 tools and helping people on the Net out is not our primary job -function, so some email will have to go unanswered. -</para> -<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> - diff --git a/winsup/doc/faq.xml b/winsup/doc/faq.xml deleted file mode 100644 index 64491219c..000000000 --- a/winsup/doc/faq.xml +++ /dev/null @@ -1,78 +0,0 @@ -<?xml version='1.0'?> -<!DOCTYPE article PUBLIC '-//OASIS//DTD DocBook XML V4.2//EN' - "http://www.oasis-open.org/docbook/xml/4.2/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"> - <!ENTITY FAQ-PROBLEMS SYSTEM "faq-problems.xml"> -]> - -<article id="faq-nochunks" lang="en"> - <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.known-problems"> -<title>Known Problems in the Latest Net Release</title> -&FAQ-PROBLEMS; -</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> - -</article> diff --git a/winsup/doc/fhandler-tut.txt b/winsup/doc/fhandler-tut.txt deleted file mode 100644 index 00a3b4b94..000000000 --- a/winsup/doc/fhandler-tut.txt +++ /dev/null @@ -1,94 +0,0 @@ -fhandler tutorial - -This document will show how to add a new "fhandler" to cygwin, by -showing an example of /dev/zero. - -Files to note: - -fhandler.h - must define a new derived class here and FH_* -devices.in - to notice "/dev/zero" and mark it -fhandler_zero.cc - new -dtable.cc - to create the fhandler instance - -OK, first we have to define what this new fhandler will do. In our -example case, we're going to implement the unix "/dev/zero" device, -which has the following characteristics: - -* writes to /dev/zero are silently discarded -* reads from /dev/zero return all zero bytes -* mmap()ing /dev/zero maps a chunk of zero'd out memory. - -Since windows doesn't have a device that acts like this, we'll be -simulating everything. Thus: - -* writes simply return a success status -* reads memset() the buffer and return success -* we take advantage of the fact that CreateFileMapping can take a - handle of -1, which (1) maps swap memory, and (2) zeros it out for - us (at least, on NT). - -OK, let's start with devices.h. - -We have to create a new entry in the enum fh_devices. The new -devices must get a major and a minor ID. As a rule of thumb, just -copy the ones that are used on a linux system. - -Now, let's continue with fhandler.h. - -First, update the fhandler_union near the end of the file with a -line for the new device. Use existing members, in this case __dev_null -as a template. This union is sorted alphabetically. - -Earlier in that file, we'll copy fhandler_dev_null and edit it to be -fhandler_dev_zero. I chose that one because it's small, but we'll add -more members as we go (since we're simulating the whole thing). In -fact, let's copy the I/O methods from fhandler_windows since we'll -need all those anyway, even though we'll go through the full list -later. - -OK, next we need to edit devices.in. There is a section where each device -is listed with its cygwin path, its structure and its windows path. -"/dev/zero", FH_ZERO, "\\dev\\zero" -This is needed to recognize when the user is trying to open "/dev/zero". -You have to build devices.cc from devices.in now. -There is a script 'gendevices' in the winsup/cygwin directory which may -be called at some time in the future if you use 'make' to build the DLL. -This should rebuild the devices.cc file. You have to have shilka -available to do that; this is part of the cygwin cocom package. - -To go along with that change, we'll need to change dtable.cc. Look for -FH_NULL and add a case for FH_ZERO as well. - -Now we get to fhandler_zero.cc itself. Create the empty file and copy -the "usual" header/copyright/includes from some other fhandler_*.cc -source file. Also, edit Makefile.in to build this new file. Add one -new entry to DLL_OFILES, and a new line for the winsup.h dependencies. - -Since we changed fhandler.h, when you type "make" it will rebuild -everything. Go ahead and do that when you get a chance to let it run, -since we're not changing the headers any more. Note that you won't be -able to link the new dll, as we haven't added all the methods for the -new fhandler class yet, but at least you'll get a lot of compilation -out of the way. - -Next we start adding in the fhandler methods themselves. - -Constructor: This takes a name, and all we do is pass that name back -to the base class, along with the FH_ZERO value. We call set_cb -because all fhandlers call this (it's for exec to copy the fd). - -open: we override the one that takes a name because there are no real -windows devices like /dev/zero, but we ignore the name. We call -set_flags to save the flags. - -write: writes are discarded; we return success. - -read: reads read NUL bytes, so fill the buffer with NULs and return -success. - -lseek/close: just return success. - -dump: this is just for debugging, so we just print something. - -select_*: we don't support this yet, see the myriad examples in -select.cc for examples. The base fhandler's methods will do for now. diff --git a/winsup/doc/filemodes.sgml b/winsup/doc/filemodes.sgml deleted file mode 100644 index 5f34aac84..000000000 --- a/winsup/doc/filemodes.sgml +++ /dev/null @@ -1,34 +0,0 @@ -<sect1 id="using-filemodes"><title>File permissions</title> - -<para>On Windows 9x systems, files are always readable, and Cygwin uses the -native read-only mode to determine if they are writable. Files are -considered to be executable if the filename ends with .bat, .com or .exe, or -if its content starts with #!. Consequently <command>chmod</command> can -only affect the "w" mode, it silently ignores actions involving the other -modes. This means that <command>ls -l</command> -needs to open and read files. It can thus be relatively slow.</para> - -<para>Under NT, file permissions default to the same behavior as Windows -9x but there is optional functionality in Cygwin that can make file -systems behave more like on UNIX systems. This is turned on by adding -the "ntea" option to the <envar>CYGWIN</envar> environment variable.</para> - -<para>When the "ntea" feature is activated, Cygwin will start with basic -permissions as determined above, but can store POSIX file permissions in NT -Extended Attributes. This feature works quite well on NTFS partitions -because the attributes can be stored sensibly inside the normal NTFS -filesystem structure. However, on a FAT partition, NT stores extended -attributes in a flat file at the root of the partition called <filename>EA -DATA. SF</filename>. This file can grow to extremely large sizes if you -have a large number of files on the partition in question, slowing the -system to a crawl. In addition, the <filename>EA DATA. SF</filename> file -can only be deleted outside of Windows because of its "in use" status. For -these reasons, the use of NT Extended Attributes is off by default in -Cygwin. Finally, note that specifying "ntea" in <envar>CYGWIN</envar> has no -effect under Windows 9x. </para> - -<para>Under NT, the test "[ -w filename]" is only true if filename is -writable across the board, e.g. <command>chmod +w filename</command>. </para> - -</sect1> - diff --git a/winsup/doc/gcc.sgml b/winsup/doc/gcc.sgml deleted file mode 100644 index f1d5431b7..000000000 --- a/winsup/doc/gcc.sgml +++ /dev/null @@ -1,156 +0,0 @@ -<sect1 id="gcc"><title>Using GCC with Cygwin</title> - -<sect2 id="gcc-cons"><title>Console Mode Applications</title> - -<para>Use gcc to compile, just like under UNIX. -Refer to the GCC User's Guide for information on standard usage and -options. Here's a simple example:</para> - -<example> -<title>Building Hello World with GCC</title> -<screen> -<prompt>C:\></prompt> <userinput>gcc hello.c -o hello.exe</userinput> -<prompt>C:\></prompt> <userinput>hello.exe</userinput> -Hello, World - -<prompt>C:\></prompt> -</screen> -</example> - -</sect2> - -<sect2 id="gcc-gui"><title>GUI Mode Applications</title> - -<para>Cygwin allows you to build programs with full access to the -standard Windows 32-bit API, including the GUI functions as defined in -any Microsoft or off-the-shelf publication. However, the process of -building those applications is slightly different, as you'll be using -the GNU tools instead of the Microsoft tools.</para> - -<para>For the most part, your sources won't need to change at all. -However, you should remove all __export attributes from functions -and replace them like this:</para> - -<screen> -int foo (int) __attribute__ ((__dllexport__)); - -int -foo (int i) -</screen> - -<para>The Makefile is similar to any other UNIX-like Makefile, -and like any other Cygwin makefile. The only difference is that you use -<command>gcc -mwindows</command> to link your program into a GUI -application instead of a command-line application. Here's an example:</para> - -<screen> -<![CDATA[ -myapp.exe : myapp.o myapp.res - gcc -mwindows myapp.o myapp.res -o $@ - -myapp.res : myapp.rc resource.h - windres $< -O coff -o $@ -]]> -</screen> - -<para>Note the use of <filename>windres</filename> to compile the -Windows resources into a COFF-format <filename>.res</filename> file. -That will include all the bitmaps, icons, and other resources you -need, into one handy object file. Normally, if you omitted the "-O -coff" it would create a Windows <filename>.res</filename> format file, -but we can only link COFF objects. So, we tell -<filename>windres</filename> to produce a COFF object, but for -compatibility with the many examples that assume your linker can -handle Windows resource files directly, we maintain the -<filename>.res</filename> naming convention. For more information on -<filename>windres</filename>, consult the Binutils manual. </para> - -<para> -The following is a simple GUI-mode "Hello, World!" program to help -get you started: -<screen> -/*-------------------------------------------------*/ -/* hellogui.c - gui hello world */ -/* build: gcc -mwindows hellogui.c -o hellogui.exe */ -/*-------------------------------------------------*/ -#include <windows.h> - -char glpszText[1024]; - -LRESULT CALLBACK WndProc(HWND, UINT, WPARAM, LPARAM); - -int APIENTRY WinMain(HINSTANCE hInstance, - HINSTANCE hPrevInstance, - LPSTR lpCmdLine, - int nCmdShow) -{ - sprintf(glpszText, - "Hello World\nGetCommandLine(): [%s]\n" - "WinMain lpCmdLine: [%s]\n", - lpCmdLine, GetCommandLine() ); - - WNDCLASSEX wcex; - - wcex.cbSize = sizeof(wcex); - wcex.style = CS_HREDRAW | CS_VREDRAW; - wcex.lpfnWndProc = WndProc; - wcex.cbClsExtra = 0; - wcex.cbWndExtra = 0; - wcex.hInstance = hInstance; - wcex.hIcon = LoadIcon(NULL, IDI_APPLICATION); - wcex.hCursor = LoadCursor(NULL, IDC_ARROW); - wcex.hbrBackground = (HBRUSH)(COLOR_WINDOW+1); - wcex.lpszMenuName = NULL; - wcex.lpszClassName = "HELLO"; - wcex.hIconSm = NULL; - - if (!RegisterClassEx(&wcex)) - return FALSE; - - HWND hWnd; - hWnd = CreateWindow("HELLO", "Hello", WS_OVERLAPPEDWINDOW, - CW_USEDEFAULT, CW_USEDEFAULT, CW_USEDEFAULT, CW_USEDEFAULT, NULL, NULL, hInstance, NULL); - - if (!hWnd) - return FALSE; - - ShowWindow(hWnd, nCmdShow); - UpdateWindow(hWnd); - - MSG msg; - while (GetMessage(&msg, NULL, 0, 0)) - { - TranslateMessage(&msg); - DispatchMessage(&msg); - } - - return msg.wParam; -} - -LRESULT CALLBACK WndProc(HWND hWnd, UINT message, WPARAM wParam, LPARAM lParam) -{ - PAINTSTRUCT ps; - HDC hdc; - - switch (message) - { - case WM_PAINT: - hdc = BeginPaint(hWnd, &ps); - RECT rt; - GetClientRect(hWnd, &rt); - DrawText(hdc, glpszText, strlen(glpszText), &rt, DT_TOP | DT_LEFT); - EndPaint(hWnd, &ps); - break; - case WM_DESTROY: - PostQuitMessage(0); - break; - default: - return DefWindowProc(hWnd, message, wParam, lParam); - } - return 0; -} -</screen> -</para> - -</sect2> -</sect1> diff --git a/winsup/doc/gdb.sgml b/winsup/doc/gdb.sgml deleted file mode 100644 index 732004f49..000000000 --- a/winsup/doc/gdb.sgml +++ /dev/null @@ -1,88 +0,0 @@ - -<sect1 id="gdb"><title>Debugging Cygwin Programs</title> - -<para>When your program doesn't work right, it usually has a "bug" in -it, meaning there's something wrong with the program itself that is -causing unexpected results or crashes. Diagnosing these bugs and -fixing them is made easy by special tools called -<emphasis>debuggers</emphasis>. In the case of Cygwin, the debugger -is GDB, which stands for "GNU DeBugger". This tool lets you run your -program in a controlled environment where you can investigate the -state of your program while it is running or after it crashes. -Crashing programs sometimes create "core" files. In Cygwin these are -regular text files that cannot be used directly by GDB. -</para> - -<para>Before you can debug your program, you need to prepare your -program for debugging. What you need to do is add -<literal>-g</literal> to all the other flags you use when compiling -your sources to objects.</para> - -<example><title>Compiling with -g</title> -<screen> -<prompt>$</prompt> gcc -g -O2 -c myapp.c -<prompt>$</prompt> gcc -g myapp.c -o myapp -</screen> -</example> - -<para>What this does is add extra information to the objects (they get -much bigger too) that tell the debugger about line numbers, variable -names, and other useful things. These extra symbols and debugging -information give your program enough information about the original -sources so that the debugger can make debugging much easier for -you.</para> - -<para>In Windows versions of GNUPro, GDB comes with a full-featured -graphical interface. In Cygwin Net distributions, GDB is only -available as a command-line tool. To invoke GDB, simply type -<command>gdb myapp.exe</command> at the command prompt. It will -display some text telling you about itself, then -<literal>(gdb)</literal> will appear to prompt you to enter commands. -Whenever you see this prompt, it means that gdb is waiting for you to -type in a command, like <command>run</command> or -<command>help</command>. Oh <literal>:-)</literal> type -<command>help</command> to get help on the commands you can type in, -or read the <citation>GDB User's Manual</citation> for a complete -description of GDB and how to use it.</para> - -<para>If your program crashes and you're trying to figure out why it -crashed, the best thing to do is type <command>run</command> and let -your program run. After it crashes, you can type -<command>where</command> to find out where it crashed, or -<command>info locals</command> to see the values of all the local -variables. There's also a <command>print</command> that lets you look -at individual variables or what pointers point to.</para> - -<para>If your program is doing something unexpected, you can use the -<command>break</command> command to tell gdb to stop your program when it -gets to a specific function or line number:</para> - -<example><title>"break" in gdb</title> -<screen> -<prompt>(gdb)</prompt> break my_function -<prompt>(gdb)</prompt> break 47 -</screen> -</example> - -<para>Now, when you type <command>run</command> your program will stop -at that "breakpoint" and you can use the other gdb commands to look at -the state of your program at that point, modify variables, and -<command>step</command> through your program's statements one at a -time.</para> - -<para>Note that you may specify additional arguments to the -<command>run</command> command to provide command-line arguments to -your program. These two cases are the same as far as your program is -concerned:</para> - -<example><title>Debugging with command line arguments</title> -<screen> -<prompt>$</prompt> myprog -t foo --queue 47 - -<prompt>$</prompt> gdb myprog -<prompt>(gdb)</prompt> run -t foo --queue 47 -</screen> -</example> - - -</sect1> diff --git a/winsup/doc/legal.sgml b/winsup/doc/legal.sgml deleted file mode 100644 index 71ff3f96d..000000000 --- a/winsup/doc/legal.sgml +++ /dev/null @@ -1,30 +0,0 @@ -<legalnotice id="legal"> - -<para>Copyright © 1998, 1999, 2000, 2001, 2002, 2003 Red Hat, Inc.</para> - -<!-- - -<para>GNUPro™, the GNUPro™ logo, and the Red Hat -logo are trademarks of Red Hat, Inc. All other brand and product -names are trademarks of their respective owners.</para> - -<para>Permission is granted to make and distribute verbatim copies of -this documentation provided the copyright notice and this permission -notice are preserved on all copies.</para> - -<para>Permission is granted to copy and distribute modified versions -of this documentation under the conditions for verbatim copying, -provided that the entire resulting derived work is distributed under -the terms of a permission notice identical to this one.</para> - -<para>Permission is granted to copy and distribute translations of -this documentation into another language, under the above conditions -for modified versions, except that this permission notice may be -stated in a translation approved by the Free Software -Foundation.</para> - -<para>This documentation has been prepared by Red Hat, Inc. -Technical Publications.</para> ---> - -</legalnotice> diff --git a/winsup/doc/ntsec.sgml b/winsup/doc/ntsec.sgml deleted file mode 100644 index 4859feb48..000000000 --- a/winsup/doc/ntsec.sgml +++ /dev/null @@ -1,834 +0,0 @@ -<sect1 id="ntsec"><title>NT security and usage of <literal>ntsec</literal></title> - -<para>The setting of UNIX like object permissions is controlled by the -<link linkend="using-cygwinenv"><envar>CYGWIN</envar> environment -variable</link> setting <literal>(no)ntsec</literal> which is set to -<literal>ntsec</literal> by default.</para> - -<para>The design goal of <literal>ntsec</literal> is to get a more UNIX-like -permission structure based upon the security features of Windows NT. -To describe the changes, I will first give a short overview in -<xref linkend="ntsec-common"></xref>. -</para> -<para><link linkend="ntsec-processes" endterm="ntsec-processes.title"></link> -discusses the changes in ntsec related to privileges on processes.</para> - -<para><link linkend="ntsec-files" endterm="ntsec-files.title"></link> shows -the basics of UNIX-like setting of file permissions.</para> - -<para><link linkend="ntsec-sids" endterm="ntsec-sids.title"></link> -talks about using SIDs in <filename>/etc/passwd</filename> and -<filename>/etc/group</filename>.</para> - -<para><link linkend="ntsec-mapping" endterm="ntsec-mapping.title"></link> -illustrates the permission mapping leak of Windows NT.</para> - -<para><link linkend="ntsec-aclfuncs" endterm="ntsec-aclfuncs.title"></link> -describes in short the ACL API since release 1.1.</para> - -<para><link linkend="ntsec-setuid" endterm="ntsec-setuid.title"></link> -describes the new support of a setuid concept introduced with release -1.1.3.</para> - -<para><link linkend="ntsec-switch" endterm="ntsec-switch.title"></link> -gives the basics of using the SYSTEM user to switch user context. -</para> - -<para><link linkend="ntsec-ids" endterm="ntsec-ids.title"></link> -explains the way Cygwin shows users and groups that are not in -<filename>/etc/passwd</filename> or <filename>/etc/group</filename>. -</para> - -<sect2 id="ntsec-common"><title>NT security</title> - -<para>The NT security allows a process to allow or deny access of -different kind to `objects'. `Objects' are files, processes, -threads, semaphores, etc.</para> - -<para>The main data structure of NT security is the `security descriptor' -(SD) structure. It explains the permissions, that are granted (or denied) -to an object and contains information, that is related to so called -`security identifiers' (SID).</para> - -<para>A SID is a unique identifier for users, groups and domains. -SIDs are comparable to UNIX UIDs and GIDs, but are more complicated -because they are unique across networks. Example:</para> - -<para>SID of a system `foo':</para> - -<screen> - S-1-5-21-165875785-1005667432-441284377 -</screen> - -<para>SID of a user `johndoe' of the system `foo':</para> - -<screen> - S-1-5-21-165875785-1005667432-441284377-1023 -</screen> - -<para>The above example shows the convention for printing SIDs. The leading -`S' should show that it is a SID. The next number is a version number which -is always 1. The next number is the so called `top-level authority' that -identifies the source that issued the SID.</para> - -<para>While each system in a NT network has it's own SID, the situation -is modified in NT domains: The SID of the domain controller is the -base SID for each domain user. If an NT user has one account as domain -user and another account on his local machine, these accounts are under -any circumstances DIFFERENT, regardless of the usage of the same user -name and password!</para> - -<para>SID of a domain `bar':</para> - -<screen> - S-1-5-21-186985262-1144665072-740312968 -</screen> - -<para>SID of a user `johndoe' in the domain `bar':</para> - -<screen> - S-1-5-21-186985262-1144665072-740312968-1207 -</screen> - -<para>The last part of the SID, the so called `relative identifier' (RID), -is by default used as UID and/or GID under Cygwin. As the name and the -above example implies, this id is unique only relative to one system or -domain.</para> - -<para>Note, that it's possible that a user has the same RID on two -different systems. The resulting SIDs are nevertheless different, so -the SIDs are representing different users in an NT network.</para> - -<para>There is a big difference between UNIX IDs and NT SIDs: the existence of -the so called `well known groups'. For example UNIX has no GID for the -group of `all users'. NT has an SID for them, called `Everyone' in the -English versions. The SIDs of well-known groups are not unique across -an NT network but their meanings are unmistakable. -Examples of well-known groups:</para> - -<screen> -everyone S-1-1-0 -creator/owner S-1-3-0 -batch process (via `at') S-1-5-3 -authenticated users S-1-5-11 -system S-1-5-18 -</screen> - -<para>The last important group of SIDs are the `predefined groups'. This -groups are used mainly on systems outside of domains to simplify the -administration of user permissions. The corresponding SIDs are not unique -across the network so they are interpreted only locally:</para> - -<screen> -administrators S-1-5-32-544 -users S-1-5-32-545 -guests S-1-5-32-546 -... -</screen> - -<para>Now, how are permissions given to objects? A process may assign an SD -to the object. The SD of an object consists of three parts:</para> - -<itemizedlist spacing="compact"> -<listitem><para>the SID of the owner </para></listitem> -<listitem><para>the SID of the group </para></listitem> -<listitem><para>a list of SIDs with their permissions, called -`access control list' (ACL) </para></listitem> -</itemizedlist> - -<para>UNIX is able to create three different permissions, the permissions -for the owner, for the group and for the world. In contrast the ACL -has a potentially infinite number of members. Every member is a so called -`access control element' (ACE). An ACE contains three parts:</para> - -<itemizedlist spacing="compact"> -<listitem><para>the type of the ACE </para></listitem> -<listitem><para>permissions, described with a DWORD </para></listitem> -<listitem><para>the SID, for which the above mentioned permissions are -set </para></listitem> -</itemizedlist> - -<!-- Is the historical note really important here? we're at version 1.5.9, after all.. --> -<para>The two important types of ACEs are the `access allowed ACE' and the -`access denied ACE'. The ntsec functionality only used `access allowed ACEs' up -to Cygwin version 1.1.0. Later versions also use `access denied ACEs' -to reflect the UNIX permissions as well as possible.</para> - -<para>The possible permissions on objects are more detailed than in -UNIX. For example, the permission to delete an object is different -from the write permission.</para> - -<para>With the aforementioned method NT is able to grant or revoke permissions -to objects in a far more specific way. But what about cygwin? In a POSIX -environment it would be fine to have the security behavior of a POSIX -system. The NT security model is MOSTLY able to reproduce the POSIX model. -The ntsec method tries to do this in cygwin.</para> - -<para>You ask "Mostly? Why mostly???" Because there's a leak in the NT model. -I will describe that in detail in chapter 5.</para> - -<para>Creating explicit object security is not that easy so you will often -see only two simple variations in use:</para> - -<itemizedlist spacing="compact"> -<listitem><para>default permissions, computed by the operating system </para></listitem> -<listitem><para>each permission to everyone </para></listitem> -</itemizedlist> - -<para>For parameters to functions that create or open securable objects another -data structure is used, the `security attributes' (SA). This structure -contains an SD and a flag that specifies whether the returned handle -to the object is inherited to child processes or not. -This property is not important for ntsec so in -this document the difference between SDs and SAs is ignored.</para> - -</sect2> - -<sect2 id="ntsec-processes"><title id="ntsec-processes.title">Process privileges</title> - -<para>Any process started under control of Cygwin has a semaphore attached -to it, that is used for signaling purposes. The creation of this semaphore -can be found in sigproc.cc, function `getsem'. The first parameter to the -function call `CreateSemaphore' is an SA. Without ntsec this SA -assigns default security to the semaphore. There is a simple disadvantage: -Only the owner of the process may send signals to it. Or, in other words, -if the owner of the process is not a member of the administrators' group, -no administrator may kill the process! This is especially annoying, if -processes are started via service manager.</para> - -<para>Ntsec now assigns an SA to the process control semaphore, that -has each permission set for the user of the process, for the -administrators' group and for `system', which is a synonym for the -operating system itself. The creation of this SA is done by the function -`sec_user', that can be found in `shared.cc'. Each member of the -administrators' group is now allowed to send signals to any process -created in Cygwin, regardless of the process owner.</para> - -<para>Moreover, each process now has the appropriate security settings, when -it is started via `CreateProcess'. You will find this in function -`spawn_guts' in module `spawn.cc'. The security settings for starting a -process in another user context have to add the SID of the new user, too. -In the case of the `CreateProcessAsUser' call, sec_user creates an SA with -an additional entry for the sid of the new user.</para> - -</sect2> - -<sect2 id="ntsec-files"><title id="ntsec-files.title">File permissions</title> - -<para>If ntsec is turned on, file permissions are set as in UNIX. An SD is -assigned to the file containing the owner and group and ACEs for the -owner, the group and `Everyone'.</para> - -<para>The complete settings of UNIX like permissions can be found in the file -`security.cc'. The two functions `get_nt_attribute' and `set_nt_attribute' -are the main code. The reading and writing of the SDs is done by the -functions `read_sd' and `write_sd'. `write_sd' uses the function `BackupRead' -instead of the simpler function `SetFileSecurity' because the latter is -unable to set owners different from the caller.</para> - -<para>If you are creating a file `foo' outside of Cygwin, you will see something -like the following on <command>ls -ln</command>:</para> - -<para>If your login is member of the administrators' group:</para> -<screen> - rwxrwxrwx 1 544 513 ... foo -</screen> -<para>if not:</para> -<screen> - rwxrwxrwx 1 1000 513 ... foo -</screen> - -<para>Note the user and group IDs. 544 is the UID of the administrators' group. -This is a `feature' <literal>:-P</literal> of WinNT. If you are a member of -the administrators' group, every file that you create is owned by the -administrators' group, instead of by you.</para> - -<para>The second example shows the UID of the first user, that has been -created with NT's the user administration tool. The users and groups are -sequentially numbered, starting with 1000. Users and groups are using the -same numbering scheme, so a user and a group don't share the same ID.</para> - -<para>In both examples the GID 513 is of special interest. This GID is a -well known group with different naming in local systems and domains. -Outside of domains the group is named 'None' (`Kein' in German, `Aucun' -in French, etc.), in domains it is named 'Domain Users'. Unfortunately, -the group `None' is never shown in the user admin tool outside of domains! -This is very confusing but this seems to have no negative consequences.</para> - -<para>To work correctly, ntsec depends on the files -<filename>/etc/passwd</filename> and <filename>/etc/group</filename>. -In Cygwin release 1.0 the names and the IDs must correspond to the -appropriate NT IDs! The IDs used in Cygwin are the RID of the NT SID, as -mentioned earlier. -A SID of e.g. the user `corinna' on my NT workstation:</para> - -<screen> - S-1-5-21-165875785-1005667432-441284377-1000 -</screen> - -<para>Note the last number: It's the RID 1000, Cygwin's UID.</para> - -<para>Unfortunately, workstations and servers outside of domains are not -able to set primary groups! In these cases, where there is no correlation -of users to primary groups, NT returns 513 (None) as primary group, -regardless of the membership to existing local groups.</para> - -<para>When using <command>mkpasswd -l -g</command> on such systems, you -have to change the primary group by hand if `None' as primary group is -not what you want (and I'm sure, it's not what you want!)</para> - -<para>Look at the following examples, which were parts of my files before -storing SIDs in /etc/passwd and /etc/group had been introduced (See next -chapter for details). With the exception of my personal user entry, all -entries are well known entries.</para> - -<example> -<title>/etc/passwd</title> -<screen> -everyone:*:0:0::: -system:*:18:18::: -administrator::500:544::/home/root:/bin/bash -guest:*:501:546::: -administrators:*:544:544::/home/root: -corinna::1000:547:Corinna Vinschen:/home/corinna:/bin/tcsh -</screen> -</example> - -<example> -<title>/etc/group</title> -<screen> -everyone::0: -system::18: -none::513: -administrators::544: -users::545: -guests::546: -powerusers::547: -</screen> -</example> - -<para>As you can see, I changed my primary group membership from 513 (None) -to 547 (powerusers). So all files I created inside of Cygwin were now owned -by the powerusers group instead of None. This is the way I liked it.</para> - -<para>Groups may be mentioned in the passwd file, too. This has two -advantages:</para> - -<itemizedlist spacing="compact"> -<listitem><para>Because NT assigns them to files as owners, a -<command>ls -l</command> is often more readable.</para></listitem> -<listitem><para>Moreover it's possible to assigned them to files as -owners with Cygwin's <command>chown</command>.</para></listitem> -</itemizedlist> - -<para>The group `system' is the aforementioned synonym for the operating system -itself and is normally the owner of processes that are started through -service manager. The same is true for files that are created by -processes, which are started through service manager.</para> - -</sect2> - -<sect2 id="ntsec-sids"><title id="ntsec-sids.title">NT SIDs in Cygwin</title> - -<para>In Cygwin release 1.1 a new technique of using the -<filename>/etc/passwd</filename> and <filename>/etc/group</filename> - was introduced.</para> - -<para>Both files may now contain SIDs of users and groups. They -are saved in the last field of pw_gecos in <filename>/etc/passwd</filename> -and in the gr_passwd field in <filename>/etc/group</filename>.</para> - -<para>This has the following advantages:</para> -<itemizedlist spacing="compact"> -<listitem><para>ntsec works better in domain environments.</para></listitem> -<listitem><para>Accounts (users and groups) may get another name in -Cygwin than their NT account name. The name in <filename>/etc/passwd</filename> -or <filename>/etc/group</filename> is transparently used by Cygwin -applications (e.g. <command>chown</command>, <command>chmod</command>, -<command>ls</command>):</para> - -<screen> -root::500:513::/home/root:/bin/sh -</screen> - -<para>instead of</para> - -<screen> -adminstrator::500:513::/home/root:/bin/sh -</screen> - -<para>Caution: If you like to use the account as login account via -<command>telnet</command> etc. you have to remain the name unchanged or -you have to use the special version of <command>login</command> which is -part of the standard Cygwin distribution since 1.1.</para></listitem> -<listitem><para>Cygwin UIDs and GIDs are now not necessarily the RID -part of the NT SID:</para> - -<screen> -root::0:513:S-1-5-21-54355234-56236534-345635656-500:/home/root:/bin/sh -</screen> - -<para>instead of</para> - -<screen> -root::500:513::/home/root:/bin/sh -</screen> - -</listitem> -<listitem><para>As in U*X systems UIDs and GIDs numbering scheme now -don't influence each other. So it's possible to have same Id's for a -user and a group:</para> -<example> -<title>/etc/passwd:</title> -<screen> -root::0:0:S-1-5-21-54355234-56236534-345635656-500:/home/root:/bin/sh -</screen> -</example> - -<example> -<title>/etc/group:</title> -<screen> -root:S-1-5-32-544:0: -</screen> -</example> -</listitem> -</itemizedlist> - -<para>The tools <command>mkpasswd</command> and <command>mkgroup</command> -create the needed entries by default. If you don't want that you can use -the options <literal>-s</literal> or <literal>--no-sids</literal>. I suggest -not to do this since ntsec works better when having the SIDs available.</para> - -<para>Please note that the pw_gecos field in <filename>/etc/passwd</filename> -is defined as a comma separated list. The SID has to be the last field!</para> - -<para>As aforementioned you are able to use Cygwin account names different -from the NT account names. If you want to login through `telnet' or something -else you have to use the special <command>login</command>. You may then -add another field to pw_gecos which contains the NT user name including -it's domain. So you are able to login as each domain user. The syntax -is easy: Just add an entry of the form U-ntdomain\ntusername to the pw_gecos -field. Note that the SID must still remain the last field in pw_gecos!</para> - -<screen> -the_king::1:1:Elvis Presley,U-STILLHERE\elvis,S-1-5-21-1234-5678-9012-1000:/bin/sh -</screen> - -<para>For a local user just drop the domain:</para> - -<screen> -the_king::1:1:Elvis Presley,U-elvis,S-1-5-21-1234-5678-9012-1000:/bin/sh -</screen> - -<para>In either case the password of the user is taken from the NT user -database, NOT from the passwd file!</para> - -<para>As in the previous chapter I give my personal -<filename>/etc/passwd</filename> and <filename>/etc/group</filename> as -examples. Please note that I've changed these files heavily! There's no -need to change them that way, it's just for testing purposes and... -for fun.</para> - -<example> -<title>/etc/passwd</title> -<screen> -root:*:0:0:Administrators group,S-1-5-32-544:: -SYSTEM:*:18:18:,S-1-5-18:/home/system:/bin/bash -admin:*:500:513:,S-1-5-21-1844237615-436374069-1060284298-500:/home/Administrator:/bin/bash -corinna:*:100:0:Corinna Vinschen,S-1-5-21-1844237615-436374069-1060284298-1003:/home/corinna:/bin/tcsh -Guest:*:501:546:,S-1-5-21-1844237615-436374069-1060284298-501:/home/Guest:/bin/bash -</screen> -</example> - -<example> -<title>/etc/group</title> -<screen> -root:S-1-5-32-544:0: -local:S-1-2-0:2: -network:S-1-5-2:3: -interactive:S-1-5-4:4: -authenticatedusers:S-1-5-11:5: -SYSTEM:S-1-5-18:18: -local_svc:S-1-5-19:19: -netwrk_svc:S-1-5-20:20: -none:S-1-5-21-1844237615-436374069-1060284298-513:513: -bckup_op:S-1-5-32-551:551: -guests:S-1-5-32-546:546: -pwrusers:S-1-5-32-547:547: -replicator:S-1-5-32-552:552: -users:S-1-5-32-545:545: -</screen> -</example> - -<para>If you want to do similar changes to your files, please do that only -if you're feeling comfortably with the concepts. Otherwise don't be surprised -if some stuff doesn't work anymore. If you screwed up things, revert to files -created by mkpasswd and mkgroup. Especially don't change the UID or the name -of user SYSTEM. Even if that works mostly, some Cygwin applications running -as local service under that account could suddenly start behaving strangely. -</para> - -</sect2> - -<sect2 id="ntsec-mapping"><title id="ntsec-mapping.title">The mapping leak</title> - -<para>Now its time to point out the leak in the NT permissions. -The official documentation explains in short the following:</para> -<itemizedlist spacing="compact"> -<listitem><para>access allow ACEs are accumulated regarding to the -group membership of the caller.</para></listitem> -<listitem><para>The order of ACEs is important. The system reads them -in sequence until either any needed right is denied or all needed rights -are granted. Later ACEs are then not taken into account.</para></listitem> -<listitem><para>All access denied ACEs _should_ precede any -access allowed ACE.</para></listitem> -</itemizedlist> - -<para>Note that the last rule is a preference, not a law. NT will correctly -deal with the ACL regardless of the sequence order. The second rule is -not modified to get the ACEs in the preferred order.</para> - -<para>Unfortunately the security tab of the NT4 explorer is completely -unable to deal with access denied ACEs while the explorer of W2K rearranges -the order of the ACEs before you can read them. Thank God, the sort order -remains unchanged if one presses the Cancel button.</para> - -<para>You still ask "Where is the leak?" NT ACLs are unable to reflect each -possible combination of POSIX permissions. Example:</para> - -<screen> -rw-r-xrw- -</screen> - -<para>1st try:</para> - -<screen> -UserAllow: 110 -GroupAllow: 101 -OthersAllow: 110 -</screen> - -<para>Hmm, because of the accumulation of allow rights the user may -execute because the group may execute.</para> - -<para>2st try:</para> - -<screen> -UserDeny: 001 -GroupAllow: 101 -OthersAllow: 110 -</screen> - -<para>Now the user may read and write but not execute. Better? No! -Unfortunately the group may write now because others may write.</para> - -<para>3rd try:</para> - -<screen> -UserDeny: 001 -GroupDeny: 010 -GroupAllow: 001 -OthersAllow: 110 -</screen> - -<para>Now the group may not write as intended but unfortunately the user may -not write anymore, either. How should this problem be solved? According to -the official rules a UserAllow has to follow the GroupDeny but it's -easy to see that this can never be solved that way.</para> - -<para>The only chance:</para> - -<screen> -UserDeny: 001 -UserAllow: 010 -GroupDeny: 010 -GroupAllow: 001 -OthersAllow: 110 -</screen> - -<para>Again: This works for both, NT4 and W2K. Only the GUIs aren't -able to deal with that order.</para> - -</sect2> - -<sect2 id="ntsec-aclfuncs"><title id="ntsec-aclfuncs.title">The ACL API</title> - -<para>For dealing with ACLs Cygwin now has the ACL API as it's -implemented in newer versions of Solaris. The new data structure -for a single ACL entry (ACE in NT terminology) is defined in -<filename>sys/acl.h</filename> as:</para> - -<screen> -typedef struct acl { - int a_type; /* entry type */ - uid_t a_id; /* UID | GID */ - mode_t a_perm; /* permissions */ -} aclent_t; -</screen> - -<para>The a_perm member of the aclent_t type contains only the bits -for read, write and execute as in the file mode. If e.g. read permission -is granted, all read bits (S_IRUSR, S_IRGRP, S_IROTH) are set. -CLASS_OBJ or MASK ACL entries are not fully implemented yet.</para> - -<para>The new API calls are</para> - -<screen> -acl(2), facl(2) -aclcheck(3), -aclsort(3), -acltomode(3), aclfrommode(3), -acltopbits(3), aclfrompbits(3), -acltotext(3), aclfromtext(3) -</screen> - -<para>Like in Solaris, Cygwin has two new commands for working with -ACLs on the command line: <command>getfacl</command> and -<command>setfacl</command>.</para> - -<para>Online man pages for the aforementioned commands and API calls can be -found on <ulink url="http://docs.sun.com">http://docs.sun.com</ulink> </para> - -</sect2> - -<sect2 id="ntsec-setuid"><title id="ntsec-setuid.title">New setuid concept</title> - -<para>UNIX applications which have to switch the user context are using -the <command>setuid</command> and <command>seteuid</command> calls which -are not part of the Windows API. -Nevertheless these calls are supported under Windows NT/W2K since Cygwin -release 1.1.3. Because of the nature of NT security an application which -needs the ability has to be patched, though.</para> - -<para>NT uses so-called `access tokens' to identify a user and it's -permissions. To switch the user context the application has to request -such an `access token'. This is typically done by calling the NT API -function <command>LogonUser</command>. The access token is returned and -either used in <command>ImpersonateLoggedOnUser</command> to change user -context of the current process or in <command>CreateProcessAsUser</command> -to change user context of a spawned child process. An important restriction -is that the application using <command>LogonUser</command> must have special -permissions:</para> - -<screen> -"Act as part of the operating system" -"Replace process level token" -"Increase quotas" -</screen> - -<para>Note that administrators do not have all these user rights set -by default.</para> - -<para>Two new Cygwin calls are introduced to support porting -<command>setuid</command> applications with a minimum of effort. You only -give Cygwin the right access token and then you can call -<command>seteuid</command> or <command>setuid</command> as usual in POSIX -applications. The call to <command>sexec</command> is not needed -anymore. Porting a <command>setuid</command> application is illustrated by -a short example:</para> - -<screen> -<![CDATA[ -/* First include all needed cygwin stuff. */ -#ifdef __CYGWIN__ -#include <windows.h> -#include <sys/cygwin.h> -/* Use the following define to determine the Windows version */ -#define is_winnt (GetVersion() < 0x80000000) -#endif - -[...] - - struct passwd *user_pwd_entry = getpwnam (username); - char *cleartext_password = getpass ("Password:"); - -[...] - -#ifdef __CYGWIN__ - /* Patch the typical password test. */ - if (is_winnt) - { - HANDLE token; - - /* Try to get the access token from NT. */ - token = cygwin_logon_user (user_pwd_entry, cleartext_password); - if (token == INVALID_HANDLE_VALUE) - error_exit; - /* Inform Cygwin about the new impersonation token. - Cygwin is able now, to switch to that user context by - setuid or seteuid calls. */ - cygwin_set_impersonation_token (token); - } - else -#endif /* CYGWIN */ - /* Use standard method for W9X as well. */ - hashed_password = crypt (cleartext_password, salt); - if (!user_pwd_entry || - strcmp (hashed_password, user_pwd_entry->pw_password)) - error_exit; - -[...] - - /* Everything else remains the same! */ - - setegid (user_pwd_entry->pw_gid); - seteuid (user_pwd_entry->pw_uid); - execl ("/bin/sh", ...); -]]> - -</screen> - -<para>The new Cygwin call to retrieve an access token is defined as follows:</para> - -<screen> -#include <windows.h> -#include <sys/cygwin.h> - -HANDLE -cygwin_logon_user (struct passwd *pw, const char *cleartext_password) -</screen> - -<para>You can call that function as often as you want for different user -logons and remember the access tokens for further calls to the second function.</para> - -<screen> -#include <windows.h> -#include <sys/cygwin.h> - -void -cygwin_set_impersonation_token (HANDLE hToken); -</screen> - -<para> is the call to inform Cygwin about the user context to which further -calls to <command>setuid</command>/<command>seteuid</command> should switch to. -While you always need the correct access token to do a -<command>setuid</command>/<command>seteuid</command> to another user's context, -you are always able to use <command>setuid</command>/<command>seteuid</command> -to return to your own user context by giving your own uid as parameter.</para> - -<para>If you have remembered several access tokens from calls to -<command>cygwin_logon_user</command> you can switch to different user -contexts by observing the following order:</para> - -<screen> - - cygwin_set_impersonation_token (user1_token); - seteuid (user1_uid); - -[...] - - seteuid (own_uid); - cygwin_set_impersonation_token (user2_token); - seteuid (user2_uid); - -[...] - - seteuid (own_uid); - cygwin_set_impersonation_token (user1_token); - seteuid (user1_uid); - -etc. - -</screen> - -</sect2> - -<sect2 id="ntsec-switch"><title id="ntsec-switch.title">Switching User -Context</title> - -<para> -Since Cygwin release 1.3.3, applications that are members of the -Administrators group and have the <command>Create a token -object</command>, <command>Replace a process level token</command> and -<command>Increase Quota</command> user rights can switch user -context without giving a password by just calling the usual -<command>setuid</command>, <command>seteuid</command>, -<command>setgid</command> and <command>setegid</command> functions. -</para> -<para> -On NT and Windows 2000 the <systemitem -class="username">SYSTEM</systemitem> user has these privileges and can -run services such as <command>sshd</command>. However, on Windows 2003 -<systemitem class="username">SYSTEM</systemitem> lacks the -<command>Create a token object</command> right, so it is necessary to -create a special user with all the necessary rights, as -well as <command>Logon as a service</command>, to run such services. -For security reasons this user should be denied the rights to logon -interactively or over the network. All this is done by configuration -scripts such as <command>ssh-host-config</command>. -</para> -<para> -An important restriction of this method is that a process started -without a password cannot access network shares which require -authentication. This also applies to subprocesses which switched user -context without a password. Therefore, when using -<command>ssh</command> or <command>rsh</command> without a password, it -is typically not possible to access network drives. -</para> - -</sect2> - -<sect2 id="ntsec-ids"><title id="ntsec-ids.title">Special values of user and group -ids</title> - -<para> -If the current user is not present in <filename>/etc/passwd</filename>, -that user's user id is set to a special value of 400. The user name for -the current user will always be shown correctly. If another user -(or a Windows group, treated as a user) is not present in -<filename>/etc/passwd</filename>, the user id of that user will have a -special value of -1 (which would be shown by <command>ls</command> as -65535). The user name shown in this case will be '????????'. -</para> - -<para> -If the current user is not present in <filename>/etc/passwd</filename>, -that user's login group id is set to a special value of 401. If another -user is not present in <filename>/etc/passwd</filename>, that user's login -group id is set to a special value of -1. If the user is present in -<filename>/etc/passwd</filename>, but that user's group is not in -<filename>/etc/group</filename> and is not the login group of that user, -the group id is set to a special value of -1. The name of this group -(id -1) will be shown as '????????'. -In releases of Cygwin before 1.3.20, the group id 401 had a group name -'None'. Since Cygwin release 1.3.20, the group id 401 is shown as -'mkpasswd', indicating the command that should be run to alleviate the -situation. -</para> - -<para> -Also, since Cygwin release 1.3.20, if the current user is present in -<filename>/etc/passwd</filename>, but that user's login group is not -present in <filename>/etc/group</filename>, the group name will be shown -as 'mkgroup', again indicating the appropriate command. -</para> - -<para>To summarize:</para> -<itemizedlist spacing="compact"> - -<listitem><para>If the current user doesn't show up in -<filename>/etc/passwd</filename>, it's <emphasis>group</emphasis> will -be named 'mkpasswd'.</para></listitem> - -<listitem><para>Otherwise, if the login group of the current user isn't -in <filename>/etc/group</filename>, it will be named 'mkgroup'.</para> -</listitem> - -<listitem><para>Otherwise a group not in <filename>/etc/group</filename> -will be shown as '????????' and a user not in -<filename>/etc/passwd</filename> will be shown as "????????".</para> -</listitem> - -</itemizedlist> - -<para> -Note that, since the special user and group names are just indicators, -nothing prevents you from actually having a user named `mkpasswd' in -<filename>/etc/passwd</filename> (or a group named `mkgroup' in -<filename>/etc/group</filename>). If you do that, however, be aware of -the possible confusion. -</para> - -</sect2> - -</sect1> diff --git a/winsup/doc/overview.sgml b/winsup/doc/overview.sgml deleted file mode 100644 index 6e38832e8..000000000 --- a/winsup/doc/overview.sgml +++ /dev/null @@ -1,115 +0,0 @@ -<chapter id="overview"><title>Cygwin Overview</title> - -<sect1 id="what-is-it"><title>What is it?</title> - -<para> -Cygwin is a Linux-like environment for Windows. It consists of a DLL -(<filename>cygwin1.dll</filename>), which acts as an emulation layer -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 -versions of Windows since Windows 95. 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. -Two other major differences between Cygwin and Linux are the C library -(<literal>newlib</literal> instead of <literal>glibc</literal>) and -default <command>/bin/sh</command>, which is <command>ash</command> on -Cygwin but <command>bash</command> on most Linux distributions. -</para> -<para> -With Cygwin installed, users have access to many standard UNIX -utilities. They can be used from one of the provided shells such -as <command>bash</command> or from the Windows Command Prompt. -Additionally, programmers may write Win32 console or GUI applications -that make use of the standard Microsoft Win32 API and/or the Cygwin API. -As a result, it is possible to easily port many significant UNIX -programs without the need for extensive changes to the source code. -This includes configuring and building most of the available GNU -software (including the development tools included with the Cygwin -distribution). -</para> -</sect1> - -DOCTOOL-INSERT-ov-ex-win -DOCTOOL-INSERT-ov-ex-unix - -<sect1 id="are-free"><title>Are the Cygwin tools free software?</title> - -<para>Yes. Parts are <ulink url="http://www.gnu.org/">GNU</ulink> software -(<command>gcc</command>, <command>gas</command>, <command>ld</command>, etc.), -parts are covered by the standard -<ulink url="http://www.x.org/Downloads_terms.html">X11 license</ulink>, -some of it is public domain, some of it was written by Red Hat and placed under -the <ulink url="http://www.gnu.org/licenses/gpl.html">GNU General Public -License</ulink> (GPL). None of it is shareware. You don't have to pay anyone to -use it but you should be sure to read the copyright section of the FAQ for more -information on how the GNU GPL may affect your use of these -tools. If you intend to port a proprietary application using the Cygwin -library, you may want the Cygwin proprietary-use license. -For more information about the proprietary-use license, please go to -<ulink url="http://www.redhat.com/software/tools/cygwin/">http://www.redhat.com/software/tools/cygwin/ -</ulink>. Customers of the native Win32 GNUPro should feel free to submit bug -reports and ask questions through the normal channels. All other -questions should be sent to the project mailing list -<email>cygwin@cygwin.com</email>.</para> - -</sect1> - -<sect1 id="brief-history"><title>A brief history of the Cygwin project</title> - -<note> -<para> -A more complete historical look Cygwin is Geoffrey J. Noer's 1998 paper, -"Cygwin32: A Free Win32 Porting Layer for UNIX® Applications" which can be -found at the <ulink -url="http://www.usenix.org/publications/library/proceedings/usenix-nt98/technical.html"> -2nd USENIX Windows NT Symposium Online Proceedings</ulink>. -</para> -</note> -<para> -Cygwin began development in 1995 at Cygnus Solutions (now part of Red Hat -Software). The first thing done was to enhance the development tools -(<command>gcc</command>, <command>gdb</command>, <command>gas</command>, -etc.) so that they could generate and interpret Win32 native -object files. -The next task was to port the tools to Win NT/9x. We could have -done this by rewriting large portions of the source to work within the -context of the Win32 API. But this would have meant spending a huge -amount of time on each and every tool. Instead, we took a -substantially different approach by writing a shared library -(the Cygwin DLL) that adds the necessary UNIX-like functionality -missing from the Win32 API (<function>fork</function>, -<function>spawn</function>, <function>signals</function>, -<function>select</function>, <function>sockets</function>, etc.). We call this -new interface the Cygwin API. Once written, it was possible to build working -Win32 tools using UNIX-hosted cross-compilers, linking against this -library.</para> - -<para>From this point, we pursued the goal of producing native tools -capable of rebuilding themselves under Windows 9x and NT (this is -often called self-hosting). Since neither OS ships with standard UNIX -user tools (fileutils, textutils, bash, etc...), we had to get the GNU -equivalents working with the Cygwin API. Most of these tools were -previously only built natively so we had to modify their configure -scripts to be compatible with cross-compilation. Other than the -configuration changes, very few source-level changes had to be -made. Running bash with the development tools and user tools in place, -Windows 9x and NT look like a flavor of UNIX from the perspective of -the GNU configure mechanism. Self hosting was achieved as of the beta -17.1 release in October 1996.</para> - -<para> -The entire Cygwin toolset was available as a monolithic install. In -April 2000, the project announced a -<ulink url="http://www.cygwin.com/ml/cygwin/2000-04/msg00269.html"> -New Cygwin Net Release</ulink> which provided the native Win32 program -<command>setup.exe</command> to install and upgrade each package -separately. Since then, the Cygwin DLL and <command>setup.exe</command> -have seen continuous development. -</para> -</sect1> - -DOCTOOL-INSERT-highlights - -</chapter> diff --git a/winsup/doc/overview2.sgml b/winsup/doc/overview2.sgml deleted file mode 100644 index f0aa47f0b..000000000 --- a/winsup/doc/overview2.sgml +++ /dev/null @@ -1,383 +0,0 @@ -<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 find a set of tools capable of -writing console or GUI executables that rely on the Microsoft Win32 API. The -<command>dlltool</command> utility may be used to write Windows Dynamically -Linked Libraries (DLLs). The resource compiler <command>windres</command> is -also provided. All tools may be used from the Microsoft command prompt, -with full support for normal Windows pathnames. -</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. 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> -Any time you want to update or install a Cygwin package, use the -graphical <command>setup.exe</command> program. By default, -<command>setup.exe</command> only installs a minimal set of packages, -so look around and choose your favorite utilities on the package -selection screen. You may also search for specfic tools on the Cygwin -website's <ulink url="http://cygwin.com/packages/">Setup Package -Search</ulink> For more information about what each option in -<command>setup.exe</command> means, see <xref linkend="internet-setup"></xref>. -</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 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 or 9x will find that the Cygwin library provides -an easy way to port many UNIX packages, with only minimal source code -changes. -</para> - -</sect1> - -<sect1 id="highlights"><title>Highlights of Cygwin Functionality</title> - -<sect2 id="ov-hi-intro"><title>Introduction</title> <para>When a binary linked -against the library is executed, the Cygwin DLL is loaded into the -application's text segment. Because we are trying to emulate a UNIX kernel -which needs access to all processes running under it, the first Cygwin DLL to -run creates shared memory areas that other processes using separate instances -of the DLL can access. This is used to keep track of open file descriptors and -assist fork and exec, among other purposes. In addition to the shared memory -regions, every process also has a per_process structure that contains -information such as process id, user id, signal masks, and other similar -process-specific information.</para> - -<para>The DLL is implemented using the Win32 API, which allows it to run on all -Win32 hosts. Because processes run under the standard Win32 subsystem, they -can access both the UNIX compatibility calls provided by Cygwin as well as -any of the Win32 API calls. This gives the programmer complete flexibility in -designing the structure of their program in terms of the APIs used. For -example, they could write a Win32-specific GUI using Win32 API calls on top of -a UNIX back-end that uses Cygwin.</para> - -<para>Early on in the development process, we made the important design -decision that it would not be necessary to strictly adhere to existing UNIX -standards like POSIX.1 if it was not possible or if it would significantly -diminish the usability of the tools on the Win32 platform. In many cases, an -environment variable can be set to override the default behavior and force -standards compliance.</para> -</sect2> - -<sect2 id="ov-hi-win9xnt"><title>Supporting both Windows NT and 9x</title> -<para>While Windows 95 and Windows 98 are similar enough to each other that we -can safely ignore the distinction when implementing Cygwin, Windows NT is an -extremely different operating system. For this reason, whenever the DLL is -loaded, the library checks which operating system is active so that it can act -accordingly.</para> - -<para>In some cases, the Win32 API is only different for -historical reasons. In this situation, the same basic functionality is -available under Windows 9x and NT but the method used to gain this -functionality differs. A trivial example: in our implementation of -uname, the library examines the sysinfo.dwProcessorType structure -member to figure out the processor type under Windows 9x. This field -is not supported in NT, which has its own operating system-specific -structure member called sysinfo.wProcessorLevel.</para> - -<para>Other differences between NT and 9x are much more fundamental in -nature. The best example is that only NT provides a security model.</para> -</sect2> - -<sect2 id="ov-hi-perm"><title>Permissions and Security</title> -<para>Windows NT includes a sophisticated security model based on Access -Control Lists (ACLs). Cygwin maps Win32 file ownership and permissions to the -more standard, older UNIX model by default. Cygwin version 1.1 introduces -support for ACLs according to the system calls used on newer versions of -Solaris. This ability is used when the `ntsec' feature is switched on which -is described in <xref linkend="ntsec"></xref>. -The chmod call maps UNIX-style permissions -back to the Win32 equivalents. Because many programs expect to be able to find -the /etc/passwd and /etc/group files, we provide <ulink -url="http://cygwin.com/cygwin-ug-net/using-utils.html#mount">utilities</ulink> -that can be used to construct them from the user and group information -provided by the operating system.</para> - -<para>Under Windows NT, users with Administrator rights are permitted to -chown files. With version 1.1.3 Cygwin introduced a mechanism for setting real -and effective UIDs under Windows NT/W2K. This is described in -<xref linkend="ntsec"></xref>. As of version 1.5.13, the Cygwin developers -are not aware of any feature in the Cygwin DLL that would allow users to gain -privileges or to access objects to which they have no rights under Windows. -However there is no guarantee that Cygwin is as secure as the Windows it runs -on. Cygwin processes share some variables and are thus easier targets of -denial of service type of attacks. -</para> - -<para>Under Windows 9x, the situation is considerably different. Since a -security model is not provided, Cygwin fakes file ownership by making all -files look like they are owned by a default user and group id. As under NT, -file permissions can still be determined by examining their read/write/execute -status. Rather than return an unimplemented error, under Windows 9x, the -chown call succeeds immediately without actually performing any action -whatsoever. This is appropriate since essentially all users jointly own the -files when no concept of file ownership exists.</para> - -</sect2> - -<sect2 id="ov-hi-files"><title>File Access</title> <para>Cygwin supports -both Win32- and POSIX-style paths, using either forward or back slashes as the -directory delimiter. Paths coming into the DLL are translated from Win32 to -POSIX as needed. As a result, the library believes that the file system is a -POSIX-compliant one, translating paths back to Win32 paths whenever it calls a -Win32 API function. UNC pathnames (starting with two slashes) are -supported.</para> - -<para>The layout of this POSIX view of the Windows file system space is stored -in the Windows registry. While the slash ('/') directory points to the system -partition by default, this is easy to change with the Cygwin mount utility. -In addition to selecting the slash partition, it allows mounting arbitrary -Win32 paths into the POSIX file system space. Many people use the utility to -mount each drive letter under the slash partition (e.g. C:\ to /c, D:\ to /d, -etc...).</para> - -<para>The library exports several Cygwin-specific functions that can be used -by external programs to convert a path or path list from Win32 to POSIX or vice -versa. Shell scripts and Makefiles cannot call these functions directly. -Instead, they can do the same path translations by executing the cygpath -utility program that we provide with Cygwin.</para> - -<para>Win32 file systems are case preserving but case insensitive. Cygwin -does not currently support case distinction because, in practice, few UNIX -programs actually rely on it. While we could mangle file names to support case -distinction, this would add unnecessary overhead to the library and make it -more difficult for non-Cygwin applications to access those files.</para> - -<para>Symbolic links are emulated by files containing a magic cookie followed -by the path to which the link points. They are marked with the System -attribute so that only files with that attribute have to be read to determine -whether or not the file is a symbolic link. Hard links are fully supported -under Windows NT on NTFS file systems. On a FAT file system, the call falls -back to simply copying the file, a strategy that works in many cases.</para> - -<para>The inode number for a file is calculated by hashing its full Win32 path. -The inode number generated by the stat call always matches the one returned in -d_ino of the dirent structure. It is worth noting that the number produced by -this method is not guaranteed to be unique. However, we have not found this to -be a significant problem because of the low probability of generating a -duplicate inode number.</para> - -<para>Chroot is supported since release 1.1.3. Note that chroot isn't -supported native by Windows. This implies some restrictions. First of all, -the chroot call isn't a privileged call. Each user may call it. Second, the -chroot environment isn't safe against native windows processes. If you -want to support a chroot environment as, for example, by allowing an -anonymous ftp with restricted access, you'll have to care that only -native Cygwin applications are accessible inside of the chroot environment. -Since that applications are only using the Cygwin POSIX API to access the -file system their access can be restricted as it is intended. This includes -not only POSIX paths but Win32 paths (containing drive letter and/or -backslashes) and CIFS paths (//server/share or \\server\share) as well.</para> -</sect2> - -<sect2 id="ov-hi-textvsbinary"><title>Text Mode vs. Binary Mode</title> -<para>Interoperability with other Win32 programs such as text editors was -critical to the success of the port of the development tools. Most Red Hat -customers upgrading from the older DOS-hosted toolchains expected the new -Win32-hosted ones to continue to work with their old development -sources.</para> - -<para>Unfortunately, UNIX and Win32 use different end-of-line terminators in -text files. Consequently, carriage-return newlines have to be translated on -the fly by Cygwin into a single newline when reading in text mode.</para> - -<para>This solution addresses the compatibility requirement at the expense of -violating the POSIX standard that states that text and binary mode will be -identical. Consequently, processes that attempt to lseek through text files can -no longer rely on the number of bytes read as an accurate indicator of position -in the file. For this reason, the CYGWIN environment variable can be -set to override this behavior.</para> -</sect2> - -<sect2 id="ov-hi-ansiclib"><title>ANSI C Library</title> -<para>We chose to include Red Hat's own existing ANSI C library -"newlib" as part of the library, rather than write all of the lib C -and math calls from scratch. Newlib is a BSD-derived ANSI C library, -previously only used by cross-compilers for embedded systems -development.</para> - -<para>The reuse of existing free implementations of such things -as the glob, regexp, and getopt libraries saved us considerable -effort. In addition, Cygwin uses Doug Lea's free malloc -implementation that successfully balances speed and compactness. The -library accesses the malloc calls via an exported function pointer. -This makes it possible for a Cygwin process to provide its own -malloc if it so desires.</para> -</sect2> - -<sect2 id="ov-hi-process"><title>Process Creation</title> -<para>The fork call in Cygwin is particularly interesting because it -does not map well on top of the Win32 API. This makes it very -difficult to implement correctly. Currently, the Cygwin fork is a -non-copy-on-write implementation similar to what was present in early -flavors of UNIX.</para> - -<para>The first thing that happens when a parent process -forks a child process is that the parent initializes a space in the -Cygwin process table for the child. It then creates a suspended -child process using the Win32 CreateProcess call. Next, the parent -process calls setjmp to save its own context and sets a pointer to -this in a Cygwin shared memory area (shared among all Cygwin -tasks). It then fills in the child's .data and .bss sections by -copying from its own address space into the suspended child's address -space. After the child's address space is initialized, the child is -run while the parent waits on a mutex. The child discovers it has -been forked and longjumps using the saved jump buffer. The child then -sets the mutex the parent is waiting on and blocks on another mutex. -This is the signal for the parent to copy its stack and heap into the -child, after which it releases the mutex the child is waiting on and -returns from the fork call. Finally, the child wakes from blocking on -the last mutex, recreates any memory-mapped areas passed to it via the -shared area, and returns from fork itself.</para> - -<para>While we have some -ideas as to how to speed up our fork implementation by reducing the -number of context switches between the parent and child process, fork -will almost certainly always be inefficient under Win32. Fortunately, -in most circumstances the spawn family of calls provided by Cygwin -can be substituted for a fork/exec pair with only a little effort. -These calls map cleanly on top of the Win32 API. As a result, they -are much more efficient. Changing the compiler's driver program to -call spawn instead of fork was a trivial change and increased -compilation speeds by twenty to thirty percent in our -tests.</para> - -<para>However, spawn and exec present their own set of -difficulties. Because there is no way to do an actual exec under -Win32, Cygwin has to invent its own Process IDs (PIDs). As a -result, when a process performs multiple exec calls, there will be -multiple Windows PIDs associated with a single Cygwin PID. In some -cases, stubs of each of these Win32 processes may linger, waiting for -their exec'd Cygwin process to exit.</para> -</sect2> - -<sect2 id="ov-hi-signals"><title>Signals</title> -<para>When -a Cygwin process starts, the library starts a secondary thread for -use in signal handling. This thread waits for Windows events used to -pass signals to the process. When a process notices it has a signal, -it scans its signal bitmask and handles the signal in the appropriate -fashion.</para> - -<para>Several complications in the implementation arise from the -fact that the signal handler operates in the same address space as the -executing program. The immediate consequence is that Cygwin system -functions are interruptible unless special care is taken to avoid -this. We go to some lengths to prevent the sig_send function that -sends signals from being interrupted. In the case of a process -sending a signal to another process, we place a mutex around sig_send -such that sig_send will not be interrupted until it has completely -finished sending the signal.</para> - -<para>In the case of a process sending -itself a signal, we use a separate semaphore/event pair instead of the -mutex. sig_send starts by resetting the event and incrementing the -semaphore that flags the signal handler to process the signal. After -the signal is processed, the signal handler signals the event that it -is done. This process keeps intraprocess signals synchronous, as -required by POSIX.</para> - -<para>Most standard UNIX signals are provided. Job -control works as expected in shells that support -it.</para> -</sect2> - -<sect2 id="ov-hi-sockets"><title>Sockets</title> -<para>Socket-related calls in Cygwin simply -call the functions by the same name in Winsock, Microsoft's -implementation of Berkeley sockets. Only a few changes were needed to -match the expected UNIX semantics - one of the most troublesome -differences was that Winsock must be initialized before the first -socket function is called. As a result, Cygwin has to perform this -initialization when appropriate. In order to support sockets across -fork calls, child processes initialize Winsock if any inherited file -descriptor is a socket.</para> - -<para>Unfortunately, implicitly loading DLLs -at process startup is usually a slow affair. Because many processes -do not use sockets, Cygwin explicitly loads the Winsock DLL the -first time it calls the Winsock initialization routine. This single -change sped up GNU configure times by thirty -percent.</para> -</sect2> - -<sect2 id="ov-hi-select"><title>Select</title> -<para>The UNIX select function is another -call that does not map cleanly on top of the Win32 API. Much to our -dismay, we discovered that the Win32 select in Winsock only worked on -socket handles. Our implementation allows select to function normally -when given different types of file descriptors (sockets, pipes, -handles, and a custom /dev/windows Windows messages -pseudo-device).</para> - -<para>Upon entry into the select function, the first -operation is to sort the file descriptors into the different types. -There are then two cases to consider. The simple case is when at -least one file descriptor is a type that is always known to be ready -(such as a disk file). In that case, select returns immediately as -soon as it has polled each of the other types to see if they are -ready. The more complex case involves waiting for socket or pipe file -descriptors to be ready. This is accomplished by the main thread -suspending itself, after starting one thread for each type of file -descriptor present. Each thread polls the file descriptors of its -respective type with the appropriate Win32 API call. As soon as a -thread identifies a ready descriptor, that thread signals the main -thread to wake up. This case is now the same as the first one since -we know at least one descriptor is ready. So select returns, after -polling all of the file descriptors one last time.</para> -</sect2> -</sect1> - diff --git a/winsup/doc/pathnames.sgml b/winsup/doc/pathnames.sgml deleted file mode 100644 index 608f7f31d..000000000 --- a/winsup/doc/pathnames.sgml +++ /dev/null @@ -1,377 +0,0 @@ -<sect1 id="using-pathnames"><title>Mapping path names</title> - -<sect2><title>Introduction</title> - -<para>Cygwin supports both Win32- and POSIX-style paths, where -directory delimiters may be either forward or back slashes. UNC -pathnames (starting with two slashes and a network name) are also -supported.</para> - -<para>POSIX operating systems (such as Linux) do not have the concept -of drive letters. Instead, all absolute paths begin with a -slash (instead of a drive letter such as "c:") and all file systems -appear as subdirectories (for example, you might buy a new disk and -make it be the <filename>/disk2</filename> directory).</para> - -<para>Because many programs written to run on UNIX systems assume -the existance of a single unified POSIX file system structure, Cygwin -maintains a special internal POSIX view of the Win32 file system -that allows these programs to successfully run under Windows. Cygwin -uses this mapping to translate from POSIX to Win32 paths as -necessary.</para> - -</sect2> - -<sect2 id="mount-table"><title>The Cygwin Mount Table</title> - -<para>The <command>mount</command> utility program is used to -to map Win32 drives and network shares into Cygwin's internal POSIX -directory tree. This is a similar concept to the typical UNIX mount -program. For those people coming from a Windows background, the -<command>mount</command> utility is very similar to the old DOS -<command>join</command>, in that it makes your drive letters appear as -subdirectories somewhere else.</para> - -<para>The mapping is stored in the current user's Cygwin -<firstterm>mount table</firstterm> in the Windows registry so that the -information will be retrieved next time the user logs in. Because it -is sometimes desirable to have system-wide as well as user-specific -mounts, there is also a system-wide mount table that all Cygwin users -inherit. The system-wide table may only be modified by a user with -the appropriate privileges (Administrator privileges in Windows -NT).</para> - -<para>The current user's table is located under -"HKEY_CURRENT_USER/Software/Cygnus Solutions/Cygwin/mounts -v<version>" -where <version> is the latest registry version associated with -the Cygwin library (this version is not the same as the release -number). The system-wide table is located under the same subkeys -under HKEY_LOCAL_SYSTEM. The user mount table takes precedence over -the system-wide table if a path is mounted in both. This includes the -setting of the cygdrive prefix.</para> - -<para>The <command>mount</command> command can set the POSIX root -<filename>/</filename> to any directory in the Windows file system. -In absence of such a mount, Cygwin maps <filename>/</filename> to the -root of the current Windows working directory (for example, -<filename>H:\</filename> or <filename>\\computer\share</filename>). -Normally Cygwin's <command>setup.exe</command> creates the initial -mount point for the POSIX root. -</para> - -<para>Whenever Cygwin generates a Win32 path from a POSIX one, it uses -the longest matching prefix in the mount table. Thus, if -<filename>C:</filename> is mounted as <filename>/c</filename> and also -as <filename>/</filename>, then Cygwin would translate -<filename>C:/foo/bar</filename> to <filename>/c/foo/bar</filename>. -This translation is normally only used when trying to derive the -POSIX equivalent current directory. Otherwise, the handling of MS-DOS -filenames bypasses the mount table. -</para> - -<para>Invoking <command>mount</command> without any arguments displays -Cygwin's current set of mount points. -In the following example, the C -drive is the POSIX root and D drive is mapped to -<filename>/d</filename>. Note that in this case, the root mount is a -system-wide mount point that is visible to all users running Cygwin -programs, whereas the <filename>/d</filename> mount is only visible -to the current user.</para> - -<example> -<title>Displaying the current set of mount points</title> -<screen> -<prompt>c:\></prompt> <userinput>mount</userinput> -f:\cygwin\bin on /usr/bin type system (binmode) -f:\cygwin\lib on /usr/lib type system (binmode) -f:\cygwin on / type system (binmode) -e:\src on /usr/src type system (binmode) -c: on /cygdrive/c type user (binmode,noumount) -e: on /cygdrive/e type user (binmode,noumount) -</screen> -</example> - -<para>You can also use the <command>mount</command> command to add -new mount points, and the <command>umount</command> to delete -them. See <xref linkend="mount"></xref> and <xref linkend="umount"></xref> for more -information on how to use these utilities to set up your Cygwin POSIX -file system.</para> - -<para>Whenever Cygwin cannot use any of the existing mounts to convert -from a particular Win32 path to a POSIX one, Cygwin will -automatically default to an imaginary mount point under the default POSIX -path <filename>/cygdrive</filename>. For example, if Cygwin accesses -<filename>Z:\foo</filename> and the Z drive is not currently in the -mount table, then <filename>Z:\</filename> would be automatically -converted to <filename>/cygdrive/Z</filename>. The default -prefix of <filename>/cygdrive</filename> may be changed (see the -<xref linkend="mount"></xref> for more information).</para> - -<para>It is possible to assign some special attributes to each mount -point. Automatically mounted partitions are displayed as "auto" -mounts. Mounts can also be marked as either "textmode" or "binmode" --- whether text files are read in the same manner as binary files by -default or not (see <xref linkend="using-textbinary"></xref> for more -information on text and binary modes.</para> - -</sect2> - -<sect2><title>Additional Path-related Information</title> - -<para>The <command>cygpath</command> program provides the ability to -translate between Win32 and POSIX pathnames in shell scripts. See -<xref linkend="cygpath"></xref> for the details.</para> - -<para>The <envar>HOME</envar>, <envar>PATH</envar>, and -<envar>LD_LIBRARY_PATH</envar> environment variables are automatically -converted from Win32 format to POSIX format (e.g. from -<filename>c:\cygwin\bin</filename> to <filename>/bin</filename>, if -there was a mount from that Win32 path to that POSIX path) when a Cygwin -process first starts.</para> - -<para>Symbolic links can also be used to map Win32 pathnames to POSIX. -For example, the command -<command>ln -s //pollux/home/joe/data /data</command> would have about -the same effect as creating a mount point from -<filename>//pollux/home/joe/data</filename> to <filename>/data</filename> -using <command>mount</command>, except that symbolic links cannot set -the default file access mode. Other differences are that the mapping is -distributed throughout the file system and proceeds by iteratively -walking the directory tree instead of matching the longest prefix in a -kernel table. Note that symbolic links will only work on network -drives that are properly configured to support the "system" file -attribute. Many do not do so by default (the Unix Samba server does -not by default, for example).</para> - -</sect2> - -</sect1> - -<sect1 id="using-specialnames"><title>Special filenames</title> - -<sect2> <title>DOS devices</title> - -<para>Windows filenames invalid under Windows are also invalid under -Cygwin. This means that base filenames such as -<filename>AUX</filename>, <filename>COM1</filename>, -<filename>LPT1</filename> or <filename>PRN</filename> (to name a few) -cannot be used in a regular Cygwin Windows or POSIX path, even with an -extension (<filename>prn.txt</filename>). However the special names can be -used as filename extensions (<filename>file.aux</filename>). You can use -the special names as you would under DOS, for example you can print on your -default printer with the command <command>cat filename > PRN</command> -(make sure to end with a Form Feed). -</para> - -</sect2> - -<sect2> <title>POSIX devices</title> -<para>There is no need to create a POSIX <filename>/dev</filename> -directory as Cygwin automatically simulates it internally. -These devices cannot be seen with the command <command>ls /dev/</command> -although commands such as <command>ls /dev/tty</command> work fine. -If you want to be able to see all devices in -<filename>/dev/</filename>, you can use Igor Pechtchanski's -<ulink -url="http://cygwin.com/ml/cygwin/2004-03/txt00028.txt">create_devices.sh</ulink> -script. -</para> -<para> -Cygwin supports the following devices commonly found on POSIX systems: -<filename>/dev/dsp</filename>, <filename>/dev/null</filename>, -<filename>/dev/zero</filename>, <filename>/dev/console</filename>, -<filename>/dev/tty</filename>, <filename>/dev/ttym</filename>, -<filename>/dev/ttyX</filename>, <filename>/dev/ttySX</filename>, -<filename>/dev/pipe</filename>, <filename>/dev/port</filename>, -<filename>/dev/ptmx</filename>, <filename>/dev/mem</filename>, -<filename>/dev/random</filename>, and <filename>/dev/urandom</filename>. -Some other POSIX devices, such as -<filename>/dev/kmem</filename>, are planned for development. -Cygwin also has several Windows-specific devices: -<filename>/dev/comX</filename> (the serial ports, starting with -<filename>COM1</filename> which is the same as <filename>ttyS0</filename>), -<filename>/dev/conin</filename> (Windows <filename>CONIN$</filename>), -<filename>/dev/conout</filename> (Windows <filename>CONOUT$</filename>), -<filename>/dev/clipboard</filename> (the Windows clipboard, currently -text only), and <filename>/dev/windows</filename> (the Windows message -queue). -</para> - -<para>Windows NT/W2K/XP additionally support raw devices like floppies, -disks, partitions and tapes. These are accessed from Cygwin applications -using POSIX device names which are supported in two different ways. -</para> - -<para>Up to Cygwin 1.3.3 the only way to access those devices was -to mount the Win32 device names to a POSIX device name but this usage -is discouraged since Cygwin 1.3.4 and only kept for backward compatibility. -</para> - -<para> -Beginning with Cygwin 1.3.4, raw devices are accessible by Cygwin processes -using fixed POSIX device names. These fixed 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 new fixed POSIX names are mapped to NT internal devices as -follows:</para> - -<screen> -/dev/st0 \device\tape0, rewind -/dev/nst0 \device\tape0, no-rewind -/dev/st1 \device\tape1 -... - -/dev/fd0 \device\floppy0 -/dev/fd1 \device\floppy1 -... - -/dev/scd0 \device\cdrom0 -/dev/scd1 \device\cdrom1 -... - -/dev/sr0 \device\cdrom0 -/dev/sr1 \device\cdrom1 -... - -/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/sdl \device\harddisk11\partition0 -/dev/sdl1 \device\harddisk11\partition1 -... -/dev/sdl15 \device\harddisk11\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/scd0 /dev/cdrom -ln -s /dev/nst0 /dev/tape -... -</screen> - -<warning> -<para> -Note that you can't use the mount table to map from fixed device name -to your own device name or to map from internal NT device name to -your own device name. Also using symbolic links to map from the internal -NT device name to your own device name will not do what you want. -The following three examples will not work as expected: -</para> - -<screen> -mount -f -b /dev/nst0 /dev/tape # DOES NOT WORK -mount -f -b /device/tape0 /dev/tape # DOES NOT WORK -ln -s /device/tape0 /dev/tape # DOES NOT WORK -</screen> -</warning> - -</sect2> - -<sect2><title>The .exe extension</title> - -<para> Executable program 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>C:\></prompt> <userinput>ls * </userinput> -a a.exe b.exe -<prompt>C:\></prompt> <userinput>ls -i a a.exe</userinput> -445885548 a 435996602 a.exe -<prompt>C:\></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 program -has precedence and is selected for execution of -<command>myprog</command>.</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> - -<para>Unfortunately, the <command>install</command> and -<command>strip</command> commands do distinguish between -<filename>filename</filename> and <filename>filename.exe</filename>. They -fail when working on a non-existing <filename>filename</filename> even if -<filename>filename.exe</filename> exists, thus breaking some makefiles. -This problem can be solved by writing <command>install</command> and -<command>strip</command> shell scripts to provide the extension ".exe" -when needed. -</para> -</sect2> - -<sect2><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>, which displays the Windows -registry with 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. -</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><title>The @pathnames</title> -<para>To circumvent the limitations on shell line length in the native -Windows command shells, Cygwin programs 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. -Embedded double quotes must be repeated. -In the following example compare the behaviors of the bash built-in -<command>echo</command> and of the program <command>/bin/echo</command>.</para> - -<example><title> Using @pathname</title> -<screen> -<prompt>bash$</prompt> <userinput>echo 'This is "a long" line' > mylist</userinput> -<prompt>bash$</prompt> <userinput>echo @mylist</userinput> -@mylist -<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/setup-net.sgml b/winsup/doc/setup-net.sgml deleted file mode 100644 index c098c32ea..000000000 --- a/winsup/doc/setup-net.sgml +++ /dev/null @@ -1,259 +0,0 @@ -<chapter id="setup-net"><title>Setting Up Cygwin</title> - -<sect1 id="internet-setup"> -<title>Internet Setup</title> -<para>To install the Cygwin net release, go to <ulink -url="http://cygwin.com/">http://cygwin.com/</ulink> and click on <ulink -url="http://cygwin.com/setup.exe">"Install Cygwin Now!"</ulink>. This will -download a GUI installer called <command>setup.exe</command> which can -be run to download a complete cygwin installation via the internet. -Follow the instructions on each screen to install Cygwin. -</para> - -<para> -The <command>setup.exe</command> installer is designed to be easy -for new users to understand while remaining flexible for the -experienced. The volunteer development team is constantly working -on <command>setup.exe</command>; before requesting a new feature, -check the wishlist in the <ulink url="http://sources.redhat.com/cgi-bin/cvsweb.cgi/setup/README?cvsroot=cygwin-apps&rev=2">CVS <literal>README</literal> -</ulink>. It may already be present in the CVS version! -</para> - -<para> -Since the default value for each option is the logical choice for -most installations, you can get a working minimal Cygwin environment -installed by simply clicking the <literal>Next</literal> button -at each page. The only exception to this is choosing a Cygwin mirror, -which you can choose by experimenting with those listed at -<ulink url="http://cygwin.com/mirrors.html"> -http://cygwin.com/mirrors.html -</ulink>. For more details about each of page of the -<command>setup.exe</command> installation, read on below. -Please note that this guide assumes that you have a basic understanding -of Unix (or a Unix-like OS). If you are new to Unix, you will also want -to make use of <ulink url="http://www.google.com/search?q=new+to+unix"> -other resources</ulink>. -</para> - -<sect2><title>Download Source</title> -<para> -Cygwin uses packages to manage installing various software. When -the default <literal>Install from Internet</literal> option is chosen, -<command>setup.exe</command> creates a local directory to store -the packages before actually installing the contents. -<literal>Download from Internet</literal> performs only the first -part (storing the packages locally), while -<literal>Install from Local Directory</literal> performs only the -second (installing the contents of the packages). -</para> -<para> -The <literal>Download from Internet</literal> option is mainly -for creating a base Cygwin package tree on one computer for -installation on several machines with -<literal>Install from Local Directory</literal>; copy the -entire local package tree to another machine with the directory -tree intact. For example, you might create a <literal>C:\cache\</literal> -directory and place <command>setup.exe</command> in it. Run -<command>setup.exe</command> to <literal>Install from Internet</literal> -or <literal>Download from Internet</literal>, then copy the whole -<literal>C:\cache\</literal> to each machine and instead choose -<literal>Install from Local Directory</literal>. Unfortunately -<command>setup.exe</command> does not yet support unattended installs. -</para> -<para> -Though this provides some basic mirroring functionality, if you -are managing a wide Cygwin installation, to keep up to date we recommend -using a mirroring tool such as <command>wget</command>. A helpful user on -the Cygwin mailing list created a simple demonstration script to accomplish -this; search the list for <command>mkcygwget</command> for ideas. -</para> -</sect2> - -<sect2><title>Selecting an Install Directory</title> -<para> -The <literal>Root Directory</literal> for Cygwin (default -<literal>C:\cygwin</literal>) will become <literal>/</literal> -within your Cygwin installation. You must have write access to -the parent directory, and any ACLs on the parent directory will -determine access to installed files. -</para> -<para> -The <literal>Install For</literal> options of <literal>All Users</literal> -or <literal>Just Me</literal> should always be left on the default -<literal>All Users</literal>, unless you do not have write access to -<literal>HKEY_LOCAL_MACHINE</literal> in the registry or the All Users -Start Menu. This is true even if you are the only user planning to use Cygwin -on the machine. Selecting <literal>Just Me</literal> will cause problems -for programs such as <command>crond</command> and <command>sshd</command>. -If you do not have the necessary permissions, but still want to use these -programs, consult the Cygwin mailing list archives about others' experiences. - -</para> -<para> -The <literal>Default Text File Type</literal> should be left on -<literal>Unix</literal> (that is, <literal>\n</literal>) unless you -have a very good reason to switch it to -<literal>DOS</literal> (that is, <literal>\r\n</literal>). -</para> -</sect2> - -<sect2><title>Local Package Directory</title> -<para> -The <literal>Local Package Directory</literal> is the cache where -<command>setup.exe</command> stores the packages before they are -installed. The cache must not be the same folder as the Cygwin -root. Within the cache, a separate directory is created for each -Cygwin mirror, which allows <command>setup.exe</command> to use -multiple mirrors and custom packages. After installing Cygwin, -the cache is no longer necessary, but you may want to retain the -packages as backups, for installing Cygwin to another system, -or in case you need to reinstall a package. -</para> -</sect2> - -<sect2><title>Connection Method</title> -<para> -The <literal>Direct Connection</literal> method of downloading will -directly download the packages, while the IE5 method will leverage your -IE5 cache for performance. If your organisation uses a proxy server or -auto-configuration scripts, the IE5 method also uses these settings. -If you have a proxy server, you can manually type it into -the <literal>Use Proxy</literal> section. Unfortunately, -<command>setup.exe</command> does not currently support password -authorization for proxy servers. -</para> -</sect2> - -<sect2><title>Choosing Mirrors</title> -<para> -Since there is no way of knowing from where you will be downloading -Cygwin, you need to choose at least one mirror site. Cygwin mirrors -are geographically distributed around the world; check the list at <ulink -url="http://cygwin.com/mirrors.html">http://cygwin.com/mirrors.html</ulink> -to find one near you. You can select multiple mirrors by holding down -<literal>CTRL</literal> and clicking on each one. If you have the URL of -an unlisted mirror (for example, if your organization has an internal Cygwin -mirror) you can add it. -</para> -</sect2> - -<sect2><title>Choosing Packages</title> -<para> -For each selected mirror site, <command>setup.exe</command> downloads a -small text file called <literal>setup.bz2</literal> that contains a list -of packages available from that site along with some basic information about -each package which <command>setup.exe</command> parses and uses to create the -chooser window. For details about the format of this file, see -the <ulink url="http://sources.redhat.com/cygwin-apps/setup.html"> -setup.exe homepage</ulink>. -</para> -<para> -The chooser is the most complex part of <command>setup.exe</command>. -Packages are grouped into categories, and one package may belong to multiple -categories (assigned by the volunteer package maintainer). Each package -can be found under any of those categories in the heirarchial chooser view. -By default <command>setup.exe</command> -will install only the packages in the <literal>Base</literal> category -and their dependencies, resulting in a minimal Cygwin installation. -However, this will not include many commonly used tools such as -<command>gcc</command> (which you will find in the <literal>Devel</literal> -category). Since <command>setup.exe</command> automatically selects -dependencies, be careful not to unselect any required packages. In -particular, everything in the <literal>Base</literal> category is -required. -</para> -<para> -You can change <command>setup.exe</command>'s view style, which is helpful -if you know the name of a package you want to install but not which -category it is in. -Click on the <literal>View</literal> button and it will rotate between -<literal>Category</literal> (the default), <literal>Full</literal> (all -packages), and <literal>Partial</literal> (only packages to be upgraded). -If you are familiar with Unix, you will probably want to at least glance -through the <literal>Full</literal> listing for your favorite tools. -</para> -<para> -Once you have an existing Cygwin installation, the <command>setup.exe</command> -chooser is also used to manage your Cygwin installation. -Information on installed packages is kept in the -<literal>/etc/setup/</literal> directory of your Cygwin installation; if -<command>setup.exe</command> cannot find this directory it will act just like -you had no Cygwin installation. If <command>setup.exe</command> -finds a newer version of an installed package available, it will automatically -mark it to be upgraded. -To <literal>Uninstall</literal>, <literal>Reinstall</literal>, or get the -<literal>Source</literal> for an existing package, click on -<literal>Keep</literal> to toggle it. -Also, to avoid the need to reboot after upgrading, make sure -to close all Cygwin windows and stop all Cygwin processes before -<command>setup.exe</command> begins to install the upgraded package. -</para> -<para> -The final feature of the <command>setup.exe</command> chooser is for -<literal>Previous</literal> and <literal>Experimental</literal> packages. -By default the chooser shows only the current version of each package, -though mirrors have at least one previous version and occasionally there -is a testing or beta version of a package available. To see these package, -click on the <literal>Prev</literal> or <literal>Exp</literal> radio button. -Be warned, however, that the next time you run <command>setup.exe</command> -it will try to replace old or experimental versions with the current -stable version. -</para> -</sect2> - -<sect2><title>Download and Installation Progress</title> -<para> -First, <command>setup.exe</command> will download all selected packages -to the local directory chosen earlier. Before installing, -<command>setup.exe</command> performs a checksum on each package. If the -local directory is a slow medium (such as a network drive) this can take -a long time. During the download and installation, <command>setup.exe</command> -show progress bars for the current task and total remaining disk space. -</para> -</sect2> - -<sect2><title>Icons</title> -<para> -You may choose to install shortcuts on the Desktop and/or Start Menu -to start a <literal>bash</literal> shell. If you prefer to use a different -shell or the native Windows version of <literal>rxvt</literal>, you can -use these shortcuts as a guide to creating your own. -</para> -</sect2> - -<sect2><title>Post-Install Scripts</title> -<para> -Last of all, <command>setup.exe</command> will run any post-install -scripts to finish correctly setting up installed packages. Since each -script is run separately, several windows may pop up. If you are -interested in what is being done, see the Cygwin Package Contributor's -Guide at <ulink -url="http://cygwin.com/setup.html">http://cygwin.com/setup.html</ulink> -When the last post-install script is completed, <command>setup.exe</command> -will display a box announcing the completion. A few packages, such as -the OpenSSH server, require some manual site-specific configuration. -Relevant documentation can be found in the <literal>/usr/doc/Cygwin/</literal> -or <literal>/usr/share/doc/Cygwin/</literal> directory. -</para> -</sect2> -<sect2><title>Troubleshooting</title> -<para> -Unfortunately, the complex setup process means that odd problems can -occur. If you're having trouble downloading packages, it may be network -congestion, so try a different mirror and/or a different protocol (i.e., -HTTP instead of FTP). If you notice something is not working after -running setup, you can check the <command>setup.exe</command> log file -at <literal>/var/log/setup.log.full</literal>. Make a backup of this -file before running <command>setup.exe</command> again, and follow the -steps for <ulink url="http://cygwin.com/problems.html">Reporting -Problems with Cygwin</ulink>. -</para> -</sect2> - -</sect1> - -DOCTOOL-INSERT-setup-env -DOCTOOL-INSERT-setup-maxmem -DOCTOOL-INSERT-ntsec -DOCTOOL-INSERT-setup-files -</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/setup2.sgml b/winsup/doc/setup2.sgml deleted file mode 100644 index bd1e8dec0..000000000 --- a/winsup/doc/setup2.sgml +++ /dev/null @@ -1,206 +0,0 @@ -<sect1 id="setup-env"><title>Environment Variables</title> - -<para> -Before starting bash, you may set some environment variables. A .bat -file is provided where the most important ones are set before bash in -launched. This is the safest way to launch bash initially. The .bat -file is installed in the root directory that you specified during setup -and pointed to in the Start Menu under the "Cygwin" option. You can -edit it this file your liking.</para> - -<para> -The <envar>CYGWIN</envar> variable is used to configure many global -settings for the Cygwin runtime system. Initially you can leave -<envar>CYGWIN</envar> unset or set it to <literal>tty</literal> (e.g. -to support job control with ^Z etc...) using a syntax like this in the -DOS shell, before launching bash. </para> - -<screen> -<prompt>C:\></prompt> <userinput>set CYGWIN=tty notitle glob</userinput> -</screen> - -<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:\WinNT\system32;C:\WinNT</filename>) to UNIX format -(e.g., <filename>/WinNT/system32:/WinNT</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. -</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. Set it to point to your home directory -before launching bash. -</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> - -</sect1> - -<sect1 id="setup-maxmem"><title>Changing Cygwin's Maximum Memory</title> - -<para> -By default no Cygwin program can allocate more than 384 MB of memory -(program+data). You should not need to change this default in most -circumstances. However, if you need to use more real or virtual memory in -your machine you may add an entry in the either the -<literal>HKEY_LOCAL_MACHINE</literal> (to change the limit for all users) or -<literal>HKEY_CURRENT_USER</literal> (for just the current user) section of -the registry. -</para> - -<para> -Add the <literal>DWORD</literal> value <literal>heap_chunk_in_mb</literal> -and set it to the desired memory limit in decimal MB. It is preferred to do -this in Cygwin using the <command>regtool</command> program included in the -Cygwin package. -(For more information about <command>regtool</command> or the other Cygwin -utilities, see <xref linkend="using-utils"></xref> or use each the -<literal>--help</literal> option of each util.) You should always be careful -when using <command>regtool</command> since damaging your system registry can -result in an unusable system. This example sets memory limit to 1024 MB: - -<screen> -regtool -i set /HKLM/Software/Cygnus\ Solutions/Cygwin/heap_chunk_in_mb 1024 -regtool -v list /HKLM/Software/Cygnus\ Solutions/Cygwin -</screen> -</para> - -<para> -Exit all running Cygwin processes and restart them. Memory can be allocated up -to the size of the system swap space minus any the size of any running -processes. The system swap should be at least as large as the physically -installed RAM and can be modified under the System category of the -Control Panel. -</para> - -<para> -Here is a small program written by DJ Delorie that tests the -memory allocation limit on your system: - -<screen> -main() -{ - unsigned int bit=0x40000000, sum=0; - char *x; - - while (bit > 4096) - { - x = malloc(bit); - if (x) - sum += bit; - bit >>= 1; - } - printf("%08x bytes (%.1fMb)\n", sum, sum/1024.0/1024.0); - return 0; -} -</screen> - -You can compile this program using: -<screen> -gcc max_memory.c -o max_memory.exe -</screen> - -Run the program and it will output the maximum amount of allocatable memory. -</para> -</sect1> - -<sect1 id="setup-files"><title>Customizing bash</title> - -<para> -To set bash up so that cut and paste work properly, click on the -"Properties" button of the window, then on the "Misc" tab. Make sure -that "Quick Edit" is checked and "Fast Pasting" isn't. 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. -</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>. These initialization files will only -be read if <envar>HOME</envar> is defined before starting bash. -</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/textbinary.sgml b/winsup/doc/textbinary.sgml deleted file mode 100644 index 1e74c5861..000000000 --- a/winsup/doc/textbinary.sgml +++ /dev/null @@ -1,173 +0,0 @@ -<sect1 id="using-textbinary"><title>Text and Binary modes</title> - -<sect2> <title>The Issue</title> - -<para>On a UNIX system, when an application reads from a file it gets -exactly what's in the file on disk and the converse is true for writing. -The situation is different in the DOS/Windows world where a file can -be opened in one of two modes, binary or text. In the binary mode the -system behaves exactly as in UNIX. However on writing in text mode, a -NL (\n, ^J) is transformed into the sequence CR (\r, ^M) NL. -</para> - -<para>This can wreak havoc with the seek/fseek calls since the number -of bytes actually in the file may differ from that seen by the -application.</para> - -<para>The mode can be specified explicitly as explained in the Programming -section below. In an ideal DOS/Windows world, all programs using lines as -records (such as <command>bash</command>, <command>make</command>, -<command>sed</command> ...) would open files (and change the mode of their -standard input and output) as text. All other programs (such as -<command>cat</command>, <command>cmp</command>, <command>tr</command> ...) -would use binary mode. In practice with Cygwin, programs that deal -explicitly with object files specify binary mode (this is the case of -<command>od</command>, which is helpful to diagnose CR problems). Most -other programs (such as <command>cat</command>, <command>cmp</command>, -<command>tr</command>) use the default mode.</para> - -</sect2> - -<sect2><title>The default Cygwin behavior</title> - -<para>The Cygwin system gives us some flexibility in deciding how files -are to be opened when the mode is not specified explicitly. -The rules are evolving, this section gives the design goals.</para> -<orderedlist numeration="loweralpha"> -<listitem> -<para>If the filename is specified as a POSIX path and it appears to -reside on a file system that is mounted (i.e. if its pathname starts -with a directory displayed by <command>mount</command>), then the -default is specified by the mount flag. If the file is a symbolic link, -the mode of the target file system applies.</para> -</listitem> -<listitem> -<para>If the file is specified via a MS-DOS pathname (i.e., it contains a -backslash or a colon), the default is binary. -</para> -</listitem> -<listitem> -<para>Pipes and non-file devices are opened in binary mode, -except if the <envar>CYGWIN</envar> environment variable contains -<literal>nobinmode</literal>.</para> -<warning><title>Warning!</title><para>In b20.1 of 12/98, a file will be opened -in binary mode if any of the following conditions hold:</para> -<orderedlist numeration="arabic" spacing="compact"> -<listitem><para>binary mode is specified in the open call</para> -</listitem> -<listitem><para>the filename is a MS-DOS filename</para> -</listitem> -<listitem><para>the file resides on a binary mounted partition</para> -</listitem> -<listitem><para><envar>CYGWIN</envar> contains <literal>binmode</literal></para> -</listitem> -<listitem><para>the file is not a disk file</para> -</listitem> -</orderedlist> -</warning> -</listitem> - -<listitem> -<para> When redirecting, the Cygwin shells uses rules (a-e). For -these shells the relevant value of <envar>CYGWIN</envar> is that at the time -the shell was launched and not that at the time the program is executed. -Non-Cygwin shells always pipe and redirect with binary mode. With -non-Cygwin shells the commands <command> cat filename | program </command> -and <command> program < filename </command> are not equivalent when -<filename>filename</filename> is on a text-mounted partition. </para> -</listitem> -</orderedlist> -</sect2> - -<sect2><title>Example</title> -<para>To illustrate the various rules, we provide scripts to delete CRs -from files by using the <command>tr</command> program, which can only write -to standard output. -The script</para> -<screen> -<![CDATA[ -#!/bin/sh -# Remove \r from the file given as argument -tr -d '\r' < "$1" > "$1".nocr -]]> -</screen> -<para> will not work on a text mounted systems because the \r will be -reintroduced on writing. However scripts such as </para> -<screen> -<![CDATA[ -#!/bin/sh -# Remove \r from the file given as argument -tr -d '\r' | gzip | gunzip > "$1".nocr -]]> -</screen> -<para>and the .bat file</para> -<screen> -<![CDATA[ -REM Remove \r from the file given as argument -@echo off -tr -d \r < %1 > %1.nocr -]]> -</screen> -<para> work fine. In the first case (assuming the pipes are binary) -we rely on <command>gunzip</command> to set its output to binary mode, -possibly overriding the mode used by the shell. -In the second case we rely on the DOS shell to redirect in binary mode. -</para> -</sect2> - -<sect2><title>Binary or text?</title> - -<para>UNIX programs that have been written for maximum portability -will know the difference between text and binary files and act -appropriately under Cygwin. For those programs, the text mode default -is a good choice. Programs included in official Cygwin distributions -should work well in the default mode. </para> - -<para>Text mode makes it much easier to mix files between Cygwin and -Windows programs, since Windows programs will usually use the CRLF -format. Unfortunately you may still have some problems with text -mode. First, some of the utilities included with Cygwin do not yet -specify binary mode when they should. -Second, you will introduce CRs in text -files you write, which can cause problems when moving them back to a -UNIX system. </para> - -<para>If you are mounting a remote file system from a UNIX machine, -or moving files back and forth to a UNIX machine, you may want to -access the files in binary mode. The text files found there will normally -be in UNIX NL format, and you would want any files put there by Cygwin -programs to be stored in a format understood by UNIX. -Be sure to remove CRs from all Makefiles and -shell scripts and make sure that you only edit the files with -DOS/Windows editors that can cope with and preserve NL terminated lines. -</para> - -<para>Note that you can decide this on a disk by disk basis (for -example, mounting local disks in text mode and network disks in binary -mode). You can also partition a disk, for example by mounting -<filename>c:</filename> in text mode, and <filename>c:\home</filename> -in binary mode.</para> - -</sect2> - -<sect2><title>Programming</title> - -<para>In the <function>open()</function> function call, binary mode can be -specified with the flag <literal>O_BINARY</literal> and text mode with -<literal>O_TEXT</literal>. These symbols are defined in -<filename>fcntl.h</filename>.</para> - -<para>In the <function>fopen()</function> function call, binary mode can be -specified by adding a <literal>b</literal> to the mode string. Text mode is specified -by adding a <literal>t</literal> to the mode string.</para> - -<para>The mode of a file can be changed by the call -<function>setmode(fd,mode)</function> where <literal>fd</literal> is a file -descriptor (an integer) and <literal>mode</literal> is -<literal>O_BINARY</literal> or <literal>O_TEXT</literal>. The function -returns <literal>O_BINARY</literal> or <literal>O_TEXT</literal> depending -on the mode before the call, and <literal>EOF</literal> on error.</para> - -</sect2> - -</sect1> diff --git a/winsup/doc/using.sgml b/winsup/doc/using.sgml deleted file mode 100644 index 4678cff93..000000000 --- a/winsup/doc/using.sgml +++ /dev/null @@ -1,23 +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-using-cygserver - -DOCTOOL-INSERT-using-utils - -DOCTOOL-INSERT-using-effectively - -</chapter> diff --git a/winsup/doc/windres.sgml b/winsup/doc/windres.sgml deleted file mode 100644 index 82c537dff..000000000 --- a/winsup/doc/windres.sgml +++ /dev/null @@ -1,169 +0,0 @@ - -<sect1 id="windres"><title>Defining Windows Resources</title> - -<para><filename>windres</filename> reads a Windows resource file -(<filename>*.rc</filename>) and converts it to a res or coff file. -The syntax and semantics of the input file are the same as for any -other resource compiler, so please refer to any publication describing -the Windows resource format for details. Also, the -<filename>windres</filename> program itself is fully documented in the -Binutils manual. Here's an example of using it in a project:</para> - -<screen> -<![CDATA[ -myapp.exe : myapp.o myapp.res - gcc -mwindows myapp.o myapp.res -o $@ - -myapp.res : myapp.rc resource.h - windres $< -O coff -o $@ -]]> -</screen> - - -<para>What follows is a quick-reference to the syntax -<filename>windres</filename> supports.</para> - -<screen> - -id ACCELERATORS suboptions -BEG -"^C" 12 -"Q" 12 -65 12 -65 12 , VIRTKEY ASCII NOINVERT SHIFT CONTROL ALT -65 12 , VIRTKEY, ASCII, NOINVERT, SHIFT, CONTROL, ALT -(12 is an acc_id) -END - -SHIFT, CONTROL, ALT require VIRTKEY - - -id BITMAP memflags "filename" -memflags defaults to MOVEABLE - - -id CURSOR memflags "filename" -memflags defaults to MOVEABLE,DISCARDABLE - - -id DIALOG memflags exstyle x,y,width,height styles BEG controls END -id DIALOGEX memflags exstyle x,y,width,height styles BEG controls END -id DIALOGEX memflags exstyle x,y,width,height,helpid styles BEG controls END - -memflags defaults to MOVEABLE -exstyle may be EXSTYLE=number -styles: CAPTION "string" - CLASS id - STYLE FOO | NOT FOO | (12) - EXSTYLE number - FONT number, "name" - FONT number, "name",weight,italic - MENU id - CHARACTERISTICS number - LANGUAGE number,number - VERSIONK number -controls: - AUTO3STATE params - AUTOCHECKBOX params - AUTORADIOBUTTON params - BEDIT params - CHECKBOX params - COMBOBOX params - CONTROL ["name",] id, class, style, x,y,w,h [,exstyle] [data] - CONTROL ["name",] id, class, style, x,y,w,h, exstyle, helpid [data] - CTEXT params - DEFPUSHBUTTON params - EDITTEXT params - GROUPBOX params - HEDIT params - ICON ["name",] id, x,y [data] - ICON ["name",] id, x,y,w,h, style, exstyle [data] - ICON ["name",] id, x,y,w,h, style, exstyle, helpid [data] - IEDIT params - LISTBOX params - LTEXT params - PUSHBOX params - PUSHBUTTON params - RADIOBUTTON params - RTEXT params - SCROLLBAR params - STATE3 params - USERBUTTON "string", id, x,y,w,h, style, exstyle -params: - ["name",] id, x, y, w, h, [data] - ["name",] id, x, y, w, h, style [,exstyle] [data] - ["name",] id, x, y, w, h, style, exstyle, helpid [data] - -[data] is optional BEG (string|number) [,(string|number)] (etc) END - - -id FONT memflags "filename" -memflags defaults to MOVEABLE|DISCARDABLE - -id ICON memflags "filename" -memflags defaults to MOVEABLE|DISCARDABLE - -LANGUAGE num,num - -id MENU options BEG items END -items: - "string", id, flags - SEPARATOR - POPUP "string" flags BEG menuitems END -flags: - CHECKED - GRAYED - HELP - INACTIVE - MENUBARBREAK - MENUBREAK - -id MENUEX suboptions BEG items END -items: - MENUITEM "string" - MENUITEM "string", id - MENUITEM "string", id, type [,state] - POPUP "string" BEG items END - POPUP "string", id BEG items END - POPUP "string", id, type BEG items END - POPUP "string", id, type, state [,helpid] BEG items END - -id MESSAGETABLE memflags "filename" -memflags defaults to MOVEABLE - -id RCDATA suboptions BEG (string|number) [,(string|number)] (etc) END - -STRINGTABLE suboptions BEG strings END -strings: - id "string" - id, "string" - -(User data) -id id suboptions BEG (string|number) [,(string|number)] (etc) END - -id VERSIONINFO stuffs BEG verblocks END -stuffs: FILEVERSION num,num,num,num - PRODUCTVERSION num,num,num,num - FILEFLAGSMASK num - FILEOS num - FILETYPE num - FILESUBTYPE num -verblocks: - BLOCK "StringFileInfo" BEG BLOCK BEG vervals END END - BLOCK "VarFileInfo" BEG BLOCK BEG vertrans END END -vervals: VALUE "foo","bar" -vertrans: VALUE num,num - - - -suboptions: - memflags - CHARACTERISTICS num - LANGUAGE num,num - VERSIONK num - -memflags are MOVEABLE/FIXED PURE/IMPURE PRELOAD/LOADONCALL DISCARDABLE - -</screen> - -</sect1> |