home *** CD-ROM | disk | FTP | other *** search
/ Internet Info 1997 December / Internet_Info_CD-ROM_Walnut_Creek_December_1997.iso / faqs / comp / answers / www / cgi-faq < prev    next >
Encoding:
Internet Message Format  |  1997-10-18  |  57.7 KB

  1. Path: senator-bedfellow.mit.edu!bloom-beacon.mit.edu!news-out.internetmci.com!newsfeed.internetmci.com!193.174.75.126!news-was.dfn.de!news-fra1.dfn.de!news-ge.switch.ch!serra.unipi.it!news.caspur.it!news.flashnet.it!jarl.webthing.com!nobody
  2. From: Nick Kew <nick@webthing.com>
  3. Newsgroups: comp.infosystems.www.authoring.cgi,comp.answers,news.answers
  4. Subject: FAQ: Frequently Asked Questions about CGI Programming
  5. Supersedes: <cgi-faq-875827005@jarl.webthing.com>
  6. Followup-To: comp.infosystems.www.authoring.cgi
  7. Date: Fri, 17 Oct 1997 02:16:57 +0000
  8. Organization: A dangerous illusion
  9. Lines: 1587
  10. Approved: news-answers-request@MIT.EDU
  11. Expires: 6 Nov 1997 02:16:55 GMT
  12. Message-ID: <cgi-faq-877054615@jarl.webthing.com>
  13. NNTP-Posting-Host: ppp-2.microelettra.it
  14. Summary: The Common Gateway Interface - Programming for the WWWeb:
  15.     Basics (what is CGI; when to use CGI vs other
  16.         web programming techniques)
  17.     HTTP and NPH scripts: technical info and references
  18.     Programming tips: "How do I do this..."
  19.     Applications: where to find existing programs and information
  20.     Troubleshooting: How to tackle your problems
  21.     Further Reading: related FAQs and reference material
  22. Keywords: CGI,FAQ,HTTP,WWW
  23. User-Agent: libwww-perl/4.98
  24. Xref: senator-bedfellow.mit.edu comp.infosystems.www.authoring.cgi:58150 comp.answers:28562 news.answers:114703
  25.  
  26. Archive-name: www/cgi-faq
  27. Posting-frequency: Twice monthly
  28.  
  29. Frequently Asked Questions on CGI programming
  30.  
  31. ------------------------------
  32.  
  33. Subject: Table of Contents
  34. ==========================
  35.  
  36. 0.   Preamble
  37. 0.1. Changes
  38. 0.2. Notice and Disclaimer
  39. 0.3. Where to get this document
  40. 0.4. How to contribute to this document?
  41. 0.5. Can I email the author my questions?
  42. 0.6. What's up with posting to comp.infosystems.www.authoring.cgi?
  43. 0.7. Credits
  44.  
  45. 1.   Basic Questions
  46. 1.1. What is CGI?
  47. 1.2. Is it a script or a program?
  48. 1.3. When do I need to use CGI?
  49. 1.4. Should I use CGI or JAVA?
  50. 1.5. Should I use CGI or SSI?
  51. 1.6. Should I use CGI or an API?
  52. 1.7. What do I absolutely need to know?
  53. 1.8. Does CGI create new security risks?
  54. 1.9. Do I need to be on Unix?
  55. 1.10. Do I have to use Perl?
  56. 1.11. Do I have to put it in cgi-bin?
  57. 1.12. Do I have to call it *.cgi?  *.pl?
  58. 1.13. What is CGIWrap, and how does it affect my program?
  59. 1.14. How do I decode the data in my Form?
  60.  
  61. 2.   HTTP Headers and NPH Scripts
  62. 2.1. What is HTTP (HyperText Transfer Protocol)?
  63. 2.2. What HTTP request headers can I use?
  64. 2.3. What Environment variables are available to my application?
  65. 2.4. What HTTP response headers do I need to know about?
  66. 2.5. What is NPH?
  67. 2.6. Must/should/can I write nph scripts?
  68. 2.7. Do I have to call it nph-*
  69. 2.8. What is the difference between GET and POST?
  70.  
  71. 3.   Techniques: "How do I..."
  72. 3.1. Can I get information about who is visiting?
  73. 3.2. Can I get the email of visitors?
  74. 3.3.     "But I saw some.kool.site display my email address..."
  75. 3.4. Can I verify the email addresses people enter in my Form?
  76. 3.5. Subject: How can I get the hostname of the remote user?
  77. 3.6. Can I get browser details and return different pages?
  78. 3.7. Can I trace where a user has come from/is going to?
  79. 3.8. Can I launch a long process and return a page before it's finished?
  80. 3.9. Can I launch a long process which the user interacts with?
  81. 3.10. Can I password-protect my pages?
  82. 3.11. Can I do HTTP authentication using CGI?
  83. 3.12. Can I identify users/sessions without password protection?
  84. 3.13. Can I redirect users to another page?
  85. 3.14. Can I run a CGI script without returning a new page to the browser?
  86. 3.15. Can I write output to a different Netscape frame?
  87. 3.16. Can I write output to several frames at once?
  88. 3.17. Can I use a CGI script to generate both text and inline images?
  89. 3.18. How can I use Caches to make CGI scripts faster and more Net-friendly?
  90. 3.19. How can I avoid users hitting "submit" twice?
  91. 3.20. How can I stop my CGI script reading and writing files as "nobody"?
  92. 3.21. How can I prevent my CGI results being cached by the browser?
  93. 3.22. How can I control the default filename when downloading a file via CGI?
  94.  
  95. 4.   Applications: Is there an existing script to ...
  96. 4.1. Where to look for programs, scripts, and other resources?
  97. 4.2. Where to look for free scripts for my application?
  98. 4.3. Discussion group/bulletin board
  99. 4.4. CSCW/Groupware
  100. 4.5. Database
  101. 4.6. Is than a non-setuid script to allow users to change password?
  102.  
  103. 5.   Troubleshooting a CGI application
  104. 5.1. Are there some interactive debugging tools and services available?
  105. 5.2. I'm having trouble with my headers.   What can I do?
  106. 5.3. Why do I get Error 500 ("the script misbehaved", or "Internal Server Error")
  107. 5.4. I tried to use (Content-Type|Location|whatever), but it appears in my Browser?
  108.  
  109. 6.   Further Reading
  110. 6.1. Other FAQs/collections (including online book)
  111. 6.2. Reference Pages
  112.  
  113. INDEX
  114.  
  115. -------------------------------------------------------------
  116.  
  117. Subject: SECTION 0 -   PREAMBLE
  118.  
  119. NOTE: the numbering in this document is automatically generated by my
  120. posting software, and will change between postings if new questions are
  121. added (as _may_ happen when I see - or someone contributes - a FAQ I've
  122. previously overlooked :-)
  123.  
  124.  
  125. ------------------------------
  126.  
  127. Subject: 0.1 Changes
  128.  
  129.  
  130. Last Modified: October 15th 1997:
  131. * Added new tools to troubleshooting section
  132. * Modified cgi-vs-java question
  133. * Modified answer on defeating cacheing (thanks Alan Flavell for
  134.   pointing out problems with my previous answer)
  135.  
  136.  
  137. ------------------------------
  138.  
  139. Subject: 0.2 Notice and Disclaimer
  140.  
  141.  
  142. Copyright 1996-7 Nick Kew.
  143.  
  144. You are free to copy or distribute this document in whole or in part
  145. for any purpose and on any medium you choose, provided: 
  146.  
  147.       You DON'T do so for profit.
  148.       You DO include this notice and disclaimer in full.
  149.  
  150. Disclaimer: This information is offered in good faith and in the hope
  151. that it may be of use, but is not guaranteed to be correct, up to date
  152. or suitable for any particular purpose.   The author accepts no liability
  153. in respect of this information or its use.
  154.  
  155.  
  156. ------------------------------
  157.  
  158. Subject: 0.3 Where to get this document
  159.  
  160.  
  161. The homes of this document on the Web are now
  162. * the WebThing Virtual Office, at http://www.webthing.com/
  163.     URL  http://www.webthing.com/tutorials/cgifaq.html
  164. * the Web Design Group, at http://www.htmlhelp.com/
  165.     URL  http://www.htmlhelp.com/faq/cgifaq.html
  166.  
  167. NOTE - If you want to mirror the FAQ on your WWW site on a
  168. publicly-visible server, please make sure you keep it up-to-date.
  169.  
  170. Other known sources are:
  171.  
  172. (1) USENET: posted to newsgroups                (TEXT)
  173.     news:comp.infosystems.www.authoring.cgi
  174.     news:comp.answers
  175.     news:news.answers
  176.  
  177. (2) RTFM and mirror sites                    (TEXT)
  178.     ftp://rtfm.mit.edu/pub/usenet/news.answers/www/cgi-faq
  179.  
  180. (3) RTFM WWW mirror sites, including            (Partial HTML)
  181.     Europe - http://www.cs.ruu.nl/cgi-bin/faqwais 
  182.     America - http://www.cis.ohio-state.edu/hypertext/faq/usenet/
  183.  
  184. (4) By EMAIL from my autoresponder             (HTML or TEXT)
  185.     Send blank email to
  186.         mailto:nick+cgi_text@webthing.com
  187.     or
  188.         mailto:nick+cgi_html@webthing.com
  189.     (depending on which version you want)
  190. **** NOTE CHANGE FROM PREVIOUS AUTORESPONDER SETUP! ****
  191.  
  192. (5) By EMAIL from the FAQserver at RTFM             (TEXT)
  193.     Send email to mailto:mail-server@rtfm.mit.edu with
  194.         send usenet/news.answers/www/cgi-faq
  195.     in the body of your message
  196.  
  197.  
  198. ------------------------------
  199.  
  200. Subject: 0.4 How to contribute to this document?
  201.  
  202.  
  203. The WebThing software permits collaborative authoring using your web
  204. browser. When you are reading any entry in this InterFAQ, you can add a
  205. new entry which will then appear as another "more on" subject.
  206. http://www3.pair.com/webthing/
  207. (note: the version at this site is no longer listed in the previous question)
  208.  
  209. In order to maintain the quality of the FAQ, and avoid inappropriate
  210. 'commercial' entries, write permission is limited using an Access Control
  211. List. If you have a contribution to make, send me an email including your
  212. WebThing userid (i.e. what you entered in the registration form) and I'll
  213. add you to the list.
  214.  
  215. InterFAQ readers - If your browser isn't showing a "new entry" button, then
  216. either you aren't logged in or you're not on the access control list.
  217.  
  218. Note that this InterFAQ is limited to questions-and-answers appropriate to
  219. periodic Usenet posting. Other types of contribution can be added
  220. elsewhere in the WebCentre. For example
  221.  
  222.     * If you have a relevant website and want to link to it, enter it the
  223.       appropriate collection (e.g. "scripts" or "misc").    You can then
  224.       also include a description of your site, and have it indexed.
  225.     * If you want to post a question or comment on something in this
  226.       document, you can post it as a followup to the "flat" version of the
  227.       FAQ (library document in the "FAQS" collection). 
  228.  
  229. If you don't want to use the InterFAQ you can always mail me
  230. ( mailto:nick@webthing.com )
  231.  
  232.  
  233. ------------------------------
  234.  
  235. Subject: 0.5 Can I email the author my questions?
  236.  
  237.  
  238. I am not a free advice centre, but in response to persistent questions
  239. I have recently (July '97) opened a commercial help service.
  240. If you're willing to pay, see http://www.webthing.com/support/general.html
  241.  
  242. If you think something already in the FAQ needs clarifying, feel free
  243. to mail me: don't expect a personal reply, but I *might* add
  244. something to the answer in question, so check the next posting (or three).
  245. The newsgroup is the appropriate place for free advice.   But remember:
  246. bad questions usually get bad answers, so think carefully before posting.
  247.  
  248.  
  249. ------------------------------
  250.  
  251. Subject: 0.6 What's up with posting to comp.infosystems.www.authoring.cgi?
  252.  
  253.  
  254. This is now a moderated newsgroup.   The moderator is a bot run by
  255. Thomas Boutell ( mailto:boutell@boutell.com ).   The charter for
  256. moderation is as follows:
  257.  
  258.   This newsgroup is self-moderated.  Your first posting will not appear
  259.   until you have read and responded to an automatic welcome mailing, at
  260.   which point your posting will appear with no further delay.  Provision
  261.   will also be made to automatically approve first postings that contain
  262.   a header requesting this.  Subsequent postings are approved
  263.   automatically.
  264.  
  265. If posting normally doesn't work - as could be the case if your
  266. newsfeed has trouble with moderated groups - you can post articles
  267. by emailing them to:
  268.     mailto:authoring-cgi@boutell.com
  269. Provided the return address in your mail is correct, you will then
  270. receive precise instructions for having your post(s) automatically approved.
  271.  
  272. Alternative means of posting are detailed in the WWW FAQ, posted
  273. regularly by Thomas Boutell.
  274.  
  275.  
  276. ------------------------------
  277.  
  278. Subject: 0.7 Credits
  279.  
  280.  
  281. This FAQ was written by Nick Kew, and has been considerably improved
  282. with the help of comments and criticisms, newsgroup posts and
  283. miscellaneous suggestions from correspondents including
  284. Nathan Neulinger, Maurice L. Marvin, Matthew Healy, Alan J. Flavell,
  285. Don Libes, Alain Deckers, and no doubt others I've forgotten to
  286. credit (please remind me if necessary).
  287.  
  288.  
  289. -------------------------------------------------------------
  290.  
  291. Subject: SECTION 1 -   BASIC QUESTIONS
  292.  
  293. This section aims to deal with basic questions, addressing the role and
  294. nature of CGI, and its place in Web programming. Questions/answers which
  295. just don't appear to 'fit' under any other section may also be included
  296. here.
  297.  
  298.  
  299. ------------------------------
  300.  
  301. Subject: 1.1 What is CGI?
  302.  
  303.  
  304. [ from the CGI reference http://hoohoo.ncsa.uiuc.edu/cgi/overview.html ]
  305.  
  306. The Common Gateway Interface, or CGI, is a standard for external
  307. gateway programs to interface with information servers such as HTTP servers.
  308. A plain HTML document that the Web daemon retrieves is static,
  309. which means it exists in a constant state: a text file that doesn't change.
  310. A CGI program, on the other hand, is executed in real-time, so that it
  311. can output dynamic information.
  312.  
  313.  
  314. ------------------------------
  315.  
  316. Subject: 1.2 Is it a script or a program?
  317.  
  318.  
  319. The distinction is semantic.   Traditionally, compiled executables
  320. (binaries) are called programs, and interpreted programs are usually
  321. called scripts.   In the context of CGI, the distinction has become
  322. even more blurred than before.   The words are often used interchangably
  323. (including in this document).   Current usage favours the word "scripts"
  324. for CGI programs.
  325.  
  326.  
  327. ------------------------------
  328.  
  329. Subject: 1.3 When do I need to use CGI?
  330.  
  331.  
  332. There are innumerable caveats to this answer, but basically any
  333. Webpage containing a form will require a CGI script or program
  334. to process the form inputs.
  335.  
  336.  
  337. ------------------------------
  338.  
  339. Subject: 1.4 Should I use CGI or JAVA?
  340.  
  341.  
  342. [answer to this non-question hopes to try and reduce the noise level of
  343. the recurrent "CGI vs JAVA" threads].
  344.  
  345. CGI and JAVA are fundamentally different, and for most applications
  346. are NOT interchangable.
  347.  
  348. CGI is a protocol for running programs on a WWW server.
  349. Typical applications include accessing a database, submitting
  350. an order, or posting messages to a bulletin board.
  351. JAVA is a programming language, and is an alternative to C, Perl, etc
  352. rather than to CGI.
  353.  
  354. Java was designed for network applications, and its close association
  355. with the Web stems from its ability to run programs safely on the
  356. Client machine, and its adoption in browsers (especially Netscape).
  357.  
  358. In certain instances the two may be combined in a single application:
  359. for example a JAVA applet to define a region of interest from a
  360. geographical map, together with a CGI script to process a query
  361. for the area defined.
  362.  
  363.  
  364. ------------------------------
  365.  
  366. Subject: 1.5 Should I use CGI or SSI?
  367.  
  368.  
  369. CGI and SSI (Server-Side Includes) are often interchangable, and it may
  370. be no more than a matter of personal preference.   Here are a few
  371. guidelines:
  372.   1) CGI is a common standard agreed and supported by all major HTTPDs.
  373.      SSI is NOT a common standard, but an innovation of NCSA's HTTPD
  374.      which has been widely adopted in later servers.   CGI has the
  375.      greatest portability, if this is an issue.
  376.   2) If your requirement is sufficiently simple that it can be done
  377.      by SSI without invoking an exec, then SSI will probably be
  378.      more efficient.   A typical application would be to include
  379.      sitewide 'house styles', such as toolbars, netscapeised <body>
  380.      tags or embedded CSS stylesheets.
  381.   3) For more complex applications - like processing a form -
  382.      where you need to exec (run) a program in any case, CGI
  383.      is usually the best choice.
  384.  
  385.  
  386. ------------------------------
  387.  
  388. Subject: 1.6 Should I use CGI or an API?
  389.  
  390.  
  391. APIs are proprietary programming interfaces supported by particular
  392. platforms.   By using an API, you lose all portability.   If you know
  393. your application will only ever run on one platform (OS and HTTPD),
  394. and it has a suitable API, go ahead and use it.   Otherwise stick to CGI.
  395.  
  396.  
  397. ------------------------------
  398.  
  399. Subject: 1.7 What do I absolutely need to know?
  400.  
  401.  
  402. If you're already a programmer, CGI is extremely straightforward, and just
  403. three resources should get you up to speed in the time it takes to read them:
  404.   1) Installation notes for your HTTPD.   Is it configured to run CGI
  405.      scripts, and if so how does it identify that a URL should be executed?
  406.      (Check your manuals, READMEs, ISP webpages/FAQS, and if you still can't
  407.      find it ask your server administrator).
  408.   2) The CGI specification at NCSA tells you all you need to know
  409.      to get your programs running as CGI applications.
  410.      http://hoohoo.ncsa.uiuc.edu/cgi/interface.html
  411.   3) WWW Security FAQ.   This is not required to 'get it working', but
  412.      is essential reading if you want to KEEP it working!
  413.      http://www-genome.wi.mit.edu/WWW/faqs/www-security-faq.html
  414.  
  415. If you're NOT already a programmer, you'll have to learn.   If you would
  416. find it hard to write, say, a 'grep' or 'cat' utility to run from the
  417. commandline, then you will probably have a hard time with CGI.   Make
  418. sure your programs work from the commandline BEFORE trying them with CGI,
  419. so that at least one possible source of errors has been dealt with.
  420.  
  421.  
  422. ------------------------------
  423.  
  424. Subject: 1.8 Does CGI create new security risks?
  425.  
  426.  
  427. Yes.   Period.
  428. There is a lot you can do to minimise these.   The most important thing
  429. to do is read and understand Lincoln Stein's excellent WWW security
  430. FAQ, at http://www-genome.wi.mit.edu/WWW/faqs/www-security-faq.html .
  431.  
  432.  
  433. ------------------------------
  434.  
  435. Subject: 1.9 Do I need to be on Unix?
  436.  
  437.  
  438. No, but it helps.   The Web, along with the Internet itself, C, Perl,
  439. and almost every other Good Thing in the last 20 years of computing,
  440. originated in Unix.   At the time of writing, this is still the
  441. most mature and best-supported platform for Web applications.
  442.  
  443.  
  444. ------------------------------
  445.  
  446. Subject: 1.10 Do I have to use Perl?
  447.  
  448.  
  449. No - you can use any programming language you please.   Perl is simply
  450. today's most popular choice for CGI applications.   Some other widely-
  451. used languages are C, C++, TCL, BASIC and - for simple tasks -
  452. even shell scripts.
  453.  
  454. Reasons for choosing Perl include its powerful text manipulation
  455. capabilities (in particular the 'regular' expression) and the fantastic
  456. WWW support modules available.
  457.  
  458.  
  459. ------------------------------
  460.  
  461. Subject: 1.11 Do I have to put it in cgi-bin?
  462.  
  463.  
  464. see next question
  465.  
  466.  
  467. ------------------------------
  468.  
  469. Subject: 1.12 Do I have to call it *.cgi?  *.pl?
  470.  
  471.  
  472. Maybe.   It depends on your server installation.
  473.  
  474. These types of filenames are commonly used conventions - no more.
  475. It is up to the server administrator whether or not CGI scripts are
  476. enabled, and (if so) what conventions tell the server to run or
  477. to print them.
  478.  
  479. If you are running your own server, read the manual.
  480. If you're on ISP or other rented webspace, check their webpages for
  481. information or FAQs.   As a last resort, ask the server administrator.
  482.  
  483.  
  484. ------------------------------
  485.  
  486. Subject: 1.13 What is CGIWrap, and how does it affect my program?
  487.  
  488.  
  489. [ quoted from http://www.umr.edu/~cgiwrap/intro.html ]
  490.  
  491. > CGIWrap is a gateway program that allows general users to use CGI scripts
  492. > and HTML forms without compromising the security of the http server.
  493. > Scripts are run with the permissions of the user who owns the script. In
  494. > addition, several security checks are performed on the script, which will not
  495. > be executed if any checks fail. 
  496. > CGIWrap is used via a URL in an HTML document. As distributed, cgiwrap
  497. > is configured to run user scripts which are located in the
  498. > ~/public_html/cgi-bin/ directory. 
  499.  
  500. See http://www.umr.edu/~cgiwrap/
  501.  
  502.  
  503. ------------------------------
  504.  
  505. Subject: 1.14 How do I decode the data in my Form?
  506.  
  507.  
  508. The normal format for data in HTTP requests is URLencoded.   All Form data
  509. is encoded in a string, of the form
  510.     param1=value1¶m2=value2&...paramn=valuen
  511. Many non-alphanumeric characters are "escaped" in the encoding:
  512. the character whose hexadecimal number is "XY" will be represented by
  513. the character string "%XY".
  514.  
  515. Decoding this string is a fundamental function of every CGI library.
  516.  
  517. Another format is "multipart/form-data", also known as "file upload".
  518. You will get this from the HTML markup
  519. <form method="POST" enctype="multipart/form-data">
  520.  
  521. (but note you must accept URLencoded input in any case, since not all
  522. browsers support multipart forms).
  523.  
  524. Most(?) CGI libraries will handle this transparently.
  525.  
  526.  
  527. -------------------------------------------------------------
  528.  
  529. Subject: SECTION 2 -   HTTP HEADERS AND NPH SCRIPTS
  530.  
  531. This is a fairly technical section dealing with HTTP, the protocol of
  532. the Web. It also includes NPH, the mechanism by which CGI programs can
  533. return HTTP header information directly to the Client.
  534.  
  535.  
  536. ------------------------------
  537.  
  538. Subject: 2.1 What is HTTP (HyperText Transfer Protocol)?
  539.  
  540.  
  541. HTTP is the protocol of the Web, by which Servers and Clients (typically
  542. browsers) communicate.  An HTTP transaction comprises a Request sent by
  543. the Client to the Server, and a Response returned from the Server to
  544. the Client.
  545. Every HTTP request and response includes a message header, describing
  546. the message.   These are processed by the HTTPD, and may often be
  547. mostly ignored by CGI applications (but see below).
  548. A message body may also be included:
  549.   1) A HEAD or GET request sends only a header.   Any form data is encoded 
  550.      in an HTTP_QUERY_STRING header field, which is available to the CGI
  551.      program as an environment variable QUERY_STRING.
  552.   2) A POST request sends both header and body.   The body typically
  553.      comprises data entered by a user in a form.
  554.   3) A HEAD request does not expect a body in the response.
  555.   4) A GET or POST request will accept a response with or without a body,
  556.      according to the header.   The body of a response is typically an
  557.      HTML document.
  558.  
  559.  
  560. ------------------------------
  561.  
  562. Subject: 2.2 What HTTP request headers can I use?
  563.  
  564.  
  565. Most HTTP request headers are passed to the CGI script as environment
  566. variables.   Some are guaranteed by the CGI spec.   Others are server,
  567. browser and/or application dependent.
  568.  
  569. To see what _your_ browser and server are telling each other, just use
  570. a trivial little CGI script to print out the environment.   In Unix:
  571.     #!/bin/sh
  572.     echo "Content-type: text/plain"
  573.     echo
  574.     set
  575.  
  576. (Just call it "env.cgi" or something, and put it where your server
  577. will execute it.   Then point your browser at
  578. http://your.server/path/to/env.cgi ).
  579.  
  580. This enables you to see at-a-glance what useful server variables are set.
  581. Note that dumping the environment like this within a more complex
  582. script can be a useful debugging technique.
  583.  
  584. For details, see the CGI Environment Variables specification at
  585. http://hoohoo.ncsa.uiuc.edu/cgi/env.html
  586. (which also includes a version of the above script - somewhat more
  587. nicely formatted - online).
  588.  
  589.  
  590. ------------------------------
  591.  
  592. Subject: 2.3 What Environment variables are available to my application?
  593.  
  594.  
  595. See previous question.   Those you can rely on are documented in NCSA's
  596. pages; those associated with your particular server and browser can
  597. be determined using the above script.
  598.  
  599.  
  600. ------------------------------
  601.  
  602. Subject: 2.4 What HTTP response headers do I need to know about?
  603.  
  604.  
  605. Unless you are using NPH, the HTTPD will insert necessary response
  606. headers on your behalf, always provided it is configured to do so.
  607.  
  608. However, it is conventional for servers to insert the Content-Type header
  609. based on a page's filename, and CGI scripts cannot rely on this.  Hence
  610. the usual advice is to print an explicit Content-Type header.
  611. At least one of "Content-Type", "Status" and "Location" is almost
  612. always required.
  613.  
  614. A few other headers you may wish to use explicitly are:
  615. Status        (to set HTTP return code explicitly.   Caveats:
  616.            (1) Behaviour is undefined if it conflicts with
  617.            another header. (2) This is NOT an HTTP header.)
  618. Location    (to redirect the user to another URI, which may or may
  619.         not be on your own server)
  620. Set-cookie    (Netscape/Nonstandard) Set a cookie
  621. Refresh        (Netscape/Nonstandard) Clientpull
  622.  
  623. You can also use general MIME headers: eg "Keywords" for the benefit of
  624. indexers (although in this instance some major search robots have
  625. regrettably introduced a new protocol to do the same thing).
  626.  
  627. For a detailed reference, see RFC1945 (HTTP/1.0) or RFC2068 (HTTP/1.1).
  628.  
  629.  
  630. ------------------------------
  631.  
  632. Subject: 2.5 What is NPH?
  633.  
  634.  
  635. NPH = No Parsed Headers.   The script undertakes to print the entire
  636. HTTP response including all necessary header fields.   The HTTPD
  637. is thereby instructed not to parse the headers (as it would normally do)
  638. nor add any which are missing.
  639.  
  640.  
  641. ------------------------------
  642.  
  643. Subject: 2.6 Must/should/can I write nph scripts?
  644.  
  645.  
  646. Generally, no.   It is usually better to save yourself hassle by letting
  647. the HTTPD produce the headers for you.
  648.  
  649. If you are going to use NPH, be sure to read and understand the HTTP spec at
  650. http://www.w3.org/pub/WWW/Protocols/
  651.  
  652. Your headers should be complete and accurate, because you're instructing
  653. the HTTPD not to correct them or insert what's missing.
  654.  
  655. Possible circumstances where the use of NPH is appropriate are:
  656.   * When your headers are sufficiently unusal that they might be
  657.     differently parsed by different HTTPDs (eg combining "Location:"
  658.     with a "Status:" other than 302).
  659.   * When returning output over a period of time (eg displaying
  660.     unbuffered results of a slow operation in 'real' time).
  661. See RFC1945 (HTTP/1.0) or RFC2068 (HTTP/1.1) for detail
  662.  
  663.  
  664. ------------------------------
  665.  
  666. Subject: 2.7 Do I have to call it nph-*
  667.  
  668.  
  669. According to NCSA's reference pages, this is the standard for telling
  670. the server that your script is NPH, so this should be a fully portable
  671. convention.
  672.  
  673.  
  674. ------------------------------
  675.  
  676. Subject: 2.8 What is the difference between GET and POST?
  677.  
  678.  
  679. Firstly, the the HTTP protocol specifies differing usages for the two
  680. methods.   GET requests should always be idempotent on the server.
  681. This means that whereas one GET request might (rarely) change some state
  682. on the Server, two or more identical requests will have no further effect.
  683.  
  684. This is a theoretical point which is also good advice in practice.
  685. If a user hits "reload" on his/her browser, an identical request will be
  686. sent to the server, potentially resulting in two identical database or
  687. guestbook entries, counter increments, etc.   Browsers may reload a
  688. GET URL automatically, particularly if cacheing is disabled (as is usually
  689. the case with CGI output), but will typically prompt the user before
  690. re-submitting a POST request.   This means you're far less likely to get
  691. inadvertently-repeated entries from POST.
  692.  
  693. GET is (in theory) the preferred method for idempotent operations, such
  694. as querying a database, though it matters little if you're using a form.
  695. There is a further practical constraint that many systems have builtin
  696. limits to the length of a GET request they can handle: when the total size
  697. of a request (URL+params) approaches or exceeds 1Kb, you are well-advised
  698. to use POST in any case.
  699.  
  700. In terms of mechanics, they differ in how parameters are passed to the
  701. CGI script.   In the case of a POST request, form data is passed on
  702. STDIN, so the script should read from there (the number of bytes to be
  703. read is given by the Content-length header).   In the case of GET, the
  704. data is passed in the environment variable QUERY_STRING.   The content-type
  705. (application/x-www-form-urlencoded) is identical for GET and POST requests.
  706.  
  707.  
  708. -------------------------------------------------------------
  709.  
  710. Subject: SECTION 3 -   TECHNIQUES: "HOW DO I..."
  711.  
  712. This section comprises programming hints and tips for a number of popular
  713. tasks. Also included are a number of common questions to which the answer
  714. is "you can't", with the reasons why.
  715.  
  716.  
  717. ------------------------------
  718.  
  719. Subject: 3.1 Can I get information about who is visiting?
  720.  
  721.  
  722. *sigh*
  723. Many people keep mailing me questions or suggested hacks to get
  724. visitor information, particularly email addresses.   It seems they
  725. won't take "NO" for an answer.
  726.  
  727. The bottom line is that whatever information is available to _you_
  728. is _equally_ available to every spammer on the net.   Therefore when
  729. a browser bug _does_ permit personal data to be collected, it gets
  730. reported and fixed very quickly (one short-lived Netscape release
  731. reportedly had such a bug).
  732.  
  733. You can get some limited information from the environment variables
  734. passed to you by the browser.   Relatively few of these are guaranteed
  735. to be available, and some may be misleading.   For particular types
  736. of information, see below.   For full details, see NCSA's reference pages.
  737.  
  738.  
  739. ------------------------------
  740.  
  741. Subject: 3.2 Can I get the email of visitors?
  742.  
  743.  
  744. Why do you want to do this?
  745.  
  746. The best information available is the REMOTE_ADDR and REMOTE_HOST,
  747. which tell you nothing about the user.   Techniques such as "finger@"
  748. are not reliable, are widely disliked, and generally serve only to
  749. introduce long delays in your CGI.   Better - as well as more polite -
  750. just to ask your users to fill in a form.
  751.  
  752. BTW: the "From:" header line (HTTP_FROM variable) is usually only set
  753. by robots, since human visitors to your webpage will not normally want
  754. their addresses collected without permission, and browsers respect this.
  755.  
  756.  
  757. ------------------------------
  758.  
  759. Subject: 3.3     "But I saw some.kool.site display my email address..."
  760.  
  761.  
  762. Some sites will play party tricks, which can get *some users* email
  763. addresses.   Possible tell-tale signs of this are inordinate delays
  764. loading a page (fingering @REMOTE_HOST - doesn't often work but
  765. probably can't be detected from the webpage), or a submit button that
  766. appears to do nothing at all (a mailto: link - works quite well but
  767. trivially detectable).   As a "snoop" party trick that's fine, but
  768. if you find someone abusing these facilities (eg they send you
  769. junkmail), alert their service provider!
  770.  
  771.  
  772. ------------------------------
  773.  
  774. Subject: 3.4 Can I verify the email addresses people enter in my Form?
  775.  
  776.  
  777. Unfortunately people will sometimes enter an incorrect or invalid
  778. email address in your Form.   Worse, they may enter a valid but
  779. incorrect email address that will deliver to someone who doesn't
  780. want your mail.
  781.  
  782. Proposed regexps to match email addresses are sometimes posted.
  783. Most of these will fail against perfectly valid email addresses,
  784. like "S=N.OTHER/OU1=X12345A/RECIPNUM=1/MTA-BASIC@attmail.com"
  785. (which is what your address looks like if you are connected to
  786. the Internet via X400 - and if you think that example is too easy,
  787. check the ones at the end of Eli the Bearded's Email Addressing FAQ).
  788.  
  789. Probably the most complete parser and checker available for download
  790. is Tom Christiansen's, at
  791. http://www.perl.com/CPAN/authors/Tom_Christiansen/scripts/ckaddr.gz
  792. Of course, this still says nothing about deliverability.
  793.  
  794. A frequently-suggested hack that doesn't work is to use
  795. SMTP EXPN or VRFY commands.   Modern versions of sendmail permit
  796. administrators to disable these commands, and many sites take
  797. advantage of this facility to protect their users' privacy.
  798.  
  799. Probably the best way to verify an email address is to send mail to
  800. it, asking the user to respond.   Include a clause like "if you have
  801. received this mail in error, please accept our apologies..."
  802.  
  803.  
  804. ------------------------------
  805.  
  806. Subject: 3.5 Subject: How can I get the hostname of the remote user?
  807.  
  808.  
  809. You can't. Well, not always.
  810.  
  811. IF it is available, you'll find it in the REMOTE_HOST environment
  812. variable.  However, this will more often than not contain the numerical
  813. IP address rather than the IP name of the remote host. Remember that
  814. not all IP addresses have a hostname associated with them; this is the
  815. case of most IP addresses assigned to dialup users, for example. Your
  816. web server may also not perform a reverse lookup on incoming
  817. connections, in which case REMOTE_HOST will contain the IP address even
  818. if it has a corresponding IP name. In the second case, you can do a
  819. reverse lookup yourself in your script, but this is expensive and
  820. should probably be avoided unless absolutely necessary.
  821.  
  822. Even if you do manage to obtain a hostname, you should be aware that it
  823. may not correspond to the hostname the user is accessing your page
  824. from. It may instead be that of an intervening proxy host.
  825.  
  826. The short answer is therefore that there is no reliable way of finding
  827. out what the remote user's hostname is.
  828.  
  829.  
  830. ------------------------------
  831.  
  832. Subject: 3.6 Can I get browser details and return different pages?
  833.  
  834.  
  835. Why do you want to do this?
  836.  
  837. Well-written HTML will display correctly in any browser, so the correct
  838. answer to this question is to design a template for your output in good
  839. HTML, and make sure your output is correct.
  840.  
  841. If you insist on a different answer, you can use the HTTP_USER_AGENT
  842. environment variable.  This requires care, and can lead to unexpected
  843. results.   For example, checking for "Mozilla" and serving a frameset
  844. to it ensures that you *also* serve the frameset to early (Non-Frame)
  845. Netscapes, me-too browsers (notably MicroSoft) and others who have
  846. chosen to lie to you about their browser.
  847.  
  848. Note also that not every User Agent is a browser.   Your page may be
  849. read by a user agent you've never heard of, and then displayed by
  850. 100 different browsers.   Or retrieved by different browsers from
  851. a cache.   Another reason to write good HTML, and not try to
  852. devise a clever or koool substitute.
  853.  
  854.  
  855. ------------------------------
  856.  
  857. Subject: 3.7 Can I trace where a user has come from/is going to?
  858.  
  859.  
  860. HTTP_REFERER might or might not tell you anything.   By all means
  861. use it to collect partial statistics if you participate in (say)
  862. an advertising banner scheme.   But it is not always set, and may
  863. be meaningless (eg if a user has accessed your page from a bookmark,
  864. and the browser is too dumb to cope with this).
  865.  
  866. You cannot trace outgoing links at all.   If you really must try,
  867. point all the external links to your HTTPD and use its redirection
  868. facility (which gives you generally-reliable logs).   This is much
  869. less inefficient than using a CGI script.
  870.  
  871. BTW: don't even think about asking Javascript to send you information
  872. on some event: it's a violation of privacy which Netscape fixed as
  873. soon as complaints about its abuse started coming in.   If it works
  874. with *your* browser, you should upgrade!
  875.  
  876.  
  877. ------------------------------
  878.  
  879. Subject: 3.8 Can I launch a long process and return a page before it's finished?
  880.  
  881.  
  882. [UNIX]
  883. You have to fork/spawn the long-running process.
  884. The important thing to remember is to close all its file descriptors;
  885. otherwise nothing will be returned to the browser until it's finished.
  886. The standard trick to accomplish this is redirection to/from /dev/null:
  887.  
  888.         exec ("long_process < /dev/null > /dev/null 2>&1 &")
  889.         print HTML page as usual
  890.  
  891. (don't take "exec" as literal in anything but a shell script - in
  892. C, Perl, etc use fork+exec or system() :-)
  893.  
  894.  
  895. ------------------------------
  896.  
  897. Subject: 3.9 Can I launch a long process which the user interacts with?
  898.  
  899.  
  900. This does not fit well with the basic mechanics of the Web, in which
  901. each transaction comprises a single request and response.
  902. If your processing can be done on the Client machine, you can use
  903. a clientside application; for example a Java applet.
  904.  
  905. For processing on the server, one trick that works well for Clients
  906. running an X server (and far more efficient than a JAVA solution) is:
  907.   if ( fork() ) {
  908.     print HTML page explaining what's going on and advising about xhost
  909.   } else {
  910.     exec ("xterm -display THEIR_DISPLAY -title MY_APP -e MY_PROG ARGS
  911.         < /dev/null > /dev/null 2>&1 &") ;
  912.   }
  913. NOTE: THEIR_DISPLAY is not necessarily the same as REMOTE_HOST or REMOTE_ADDR.
  914. You have to ask users to supply their display (set REMOTE_HOST as default).
  915.  
  916. [ Question: Is there a JAVA alternative to xterm yet, for platforms
  917.   which support JAVA but not X ? ]
  918.  
  919.  
  920. ------------------------------
  921.  
  922. Subject: 3.10 Can I password-protect my pages?
  923.  
  924.  
  925. Yes.   Use your HTTPD's authentication, just as you would a basic HTML page.
  926. Now you'll have the identity of every visitor in REMOTE_USER.
  927.  
  928.  
  929. ------------------------------
  930.  
  931. Subject: 3.11 Can I do HTTP authentication using CGI?
  932.  
  933.  
  934. It depends on which version of the question you asked.
  935.  
  936. Yes, you can use CGI to trigger the browser's standard Username/Password
  937. dialogue.   Send a response code 401, together with a "WWW-authenticate"
  938. header including details of the the authentication scheme and realm:
  939. e.g. (in a non-NPH script)
  940.  
  941.     Status: 401 Unauthorized to access the document
  942.     WWW-authenticate: Basic realm="foobar"
  943.     Content-type: text/plain
  944.  
  945.     Unauthorised to access this document
  946.  
  947. The use you can make of this is server-dependent, and harder,
  948. since most servers expect to deal with authentication before ever
  949. reaching the CGI (eg through .www_acl or .htaccess).
  950. Thus it cannot usefully replace the standard login sequence, although
  951. it can be applied to other situations, such as re-validating a user -
  952. e.g after a certain timeout period or if the same person may need to
  953. login under more than one userid.
  954.  
  955. What you can never get in CGI is the credentials returned by the user.
  956. The HTTPD takes care of this, and simply sets REMOTE_USER to the
  957. username if the correct password was entered.
  958.  
  959. For a much longer discussion of this question (with code extracts),
  960. see my discussion at http://www.webthing.com/tutorials/login.html
  961.  
  962.  
  963. ------------------------------
  964.  
  965. Subject: 3.12 Can I identify users/sessions without password protection?
  966.  
  967.  
  968. The most usual (but browser-dependent) way to do this is to set a cookie.
  969. If you do this, you are accepting that not all users will have a 'session'.
  970.  
  971. An alternative is to pass a session ID in every GET URL, and in hidden
  972. fields of POST requests.   This can be a big overhead unless _every_ page
  973. requires CGI in any case.
  974.  
  975. Another alternative is the Hyper-G solution of encoding a session-id in
  976. the URLs of pages returned:
  977.     http://hyper-g.server/session_id/real/path/to/page
  978. This has the drawback of making the URLs very confusing, and causes any
  979. bookmarked pages to generate old session_ids.
  980.  
  981. Note that a session ID based solely on REMOTE_HOST (or REMOTE_ADDR)
  982. will NOT work, as multiple users may access your pages concurrently
  983. from the same machine.
  984.  
  985.  
  986. ------------------------------
  987.  
  988. Subject: 3.13 Can I redirect users to another page?
  989.  
  990.  
  991. For permanent and simple redirection, use the HTTPD configuration file:
  992. it's much more efficient than doing it yourself.   Some servers enable
  993. you to do this using a file in your own directory (eg Apache) whereas
  994. others use a single configuration file (eg CERN).
  995.  
  996. For more complicated cases (eg process form inputs and conditionally
  997. redirect the user), use the "Location:" response header.
  998. If the redirection is itself a CGI script,  it is easy to URLencode
  999. parameters to it in a GET request, but don't forget to escape the URL!
  1000.  
  1001.  
  1002. ------------------------------
  1003.  
  1004. Subject: 3.14 Can I run a CGI script without returning a new page to the browser?
  1005.  
  1006.  
  1007. Yes, but think carefully first:  How are your readers going to know
  1008. that their "submit" has succeeded?   They may hit 'submit' many times!
  1009.  
  1010. The correct solution according to the HTTP specification is to
  1011. return HTTP status code 204.   As an NPH script, this would be:
  1012.  
  1013.     #!/bin/sh
  1014.     # do processing (or launch it as background job)
  1015.     echo "HTTP/1.0 204 No Change"
  1016.     echo
  1017.  
  1018. Alan J Flavell has pointed out that this will fail with certain
  1019. popular browsers, and suggests a workaround to accommodate them:
  1020.  
  1021. > 1. Send status 204, Content-type of text/html, and a short body content
  1022. > that (for those few browsers that display it) will tell the reader that
  1023. > their browser does not handle this reponse correctly, and invites them
  1024. > to use their browser's Back function (hey, if someone tells me to put
  1025. > a back button on the HTML page itself, I think I shall scream...).
  1026.  
  1027. His survey is at
  1028. http://ppewww.ph.gla.ac.uk/%7Eflavell/status204/results.html
  1029.  
  1030.  
  1031. ------------------------------
  1032.  
  1033. Subject: 3.15 Can I write output to a different Netscape frame?
  1034.  
  1035.  
  1036. Yep.   The fact you're using CGI makes no difference: use
  1037. "target=" in your links as usual.   Alternatively, the script
  1038. can print a "Window-target:" header.   Read Netscape's pages
  1039. for detail: these answer all the questions about things like
  1040. "getting rid of" or "breaking out of" frames, too.
  1041.  
  1042.  
  1043. ------------------------------
  1044.  
  1045. Subject: 3.16 Can I write output to several frames at once?
  1046.  
  1047.  
  1048. A single CGI script can only ever print to one frame.
  1049.  
  1050. However, this limitation may be overcome by using more than one script.
  1051. The first script (the URL of the "submit" button) prints a frameset,
  1052. typically to a "_parent" or "_top" target.   The sources for one or
  1053. more of the frames thus generated may also be CGI scripts, to which
  1054. you can easily pass parameters (eg encoded in URLs with method GET).
  1055. This hack is definitely not recommended.   If you find yourself wanting
  1056. to update several frames from a single user event, it probably means
  1057. you should review the design of your application at a higher level.
  1058.  
  1059. Warnings:
  1060.  1. Don't forget to escape your URLs.
  1061.  2. This technique results in your server being hit by multiple 
  1062.     concurrent CGI requests.   You'll need LOTS of memory, especially
  1063.     if you use a memory-hog like Perl.   It can be a good recipe
  1064.     for bringing a server to its knees.
  1065.  
  1066. Javascript is often a valid alternative here, but note just how silly
  1067. it can (and often does) look in a different browser.
  1068.  
  1069.  
  1070. ------------------------------
  1071.  
  1072. Subject: 3.17 Can I use a CGI script to generate both text and inline images?
  1073.  
  1074.  
  1075. Not directly.   One script generates one response to one request.
  1076.  
  1077. If you want to generate a dynamic page including dynamic images
  1078. (say, a report including graphs, all of which depend on user input)
  1079. then your primary script will print the usual
  1080.    <img src="[script-to-generate-image]" alt="[what you asked for]">
  1081. and, just as in the multiple frames case, you can pass data to the
  1082. image-generating program encoded in a GET URL.   Of course, the same
  1083. caveats apply: see above.
  1084.  
  1085.  
  1086. ------------------------------
  1087.  
  1088. Subject: 3.18 How can I use Caches to make CGI scripts faster and more Net-friendly?
  1089.  
  1090.  
  1091. This is currently beyond the scope of this FAQ (whose author urgently
  1092. needs to improve his own applications in this regard).   However,
  1093. there is an excellent introduction to net-friendly webpages, including
  1094. CGI pages, at http://vancouver-webpages.com/CacheNow/
  1095.  
  1096. A sample cacheing perl/cgi script by Andrew Daviel is available at
  1097. http://vancouver-webpages.com/proxy/log-tail.pl
  1098.  
  1099.  
  1100. ------------------------------
  1101.  
  1102. Subject: 3.19 How can I avoid users hitting "submit" twice?
  1103.  
  1104.  
  1105. You can't.   You just have to deal with it when they do.
  1106.  
  1107. You can avoid re-processing a submission by embedding a unique ID in your
  1108. Form each time it is displayed.   When you process the form, you enter
  1109. the ID in a database.  Or, if it's already there, you don't repeat the
  1110. processing.
  1111.  
  1112. You probably want to expire your database entries after a little time:
  1113. an hour should be fine in a typical situation.
  1114.  
  1115. If you're already using cookies (e.g. a shoppingcart), an alternative is
  1116. to use the cookie as a unique identifier.   This means you also have to
  1117. handle the situation where a user deliberately "goes round twice" and
  1118. submits the same form with different contents.
  1119.  
  1120. If your script may take some time to process, you should also consider
  1121. running it as a background job, and returning an immediate
  1122. acknowledgement to the user (see above if your "immediate" response
  1123. gets delayed until processing is complete in any case).
  1124.  
  1125.  
  1126. ------------------------------
  1127.  
  1128. Subject: 3.20 How can I stop my CGI script reading and writing files as "nobody"?
  1129.  
  1130.  
  1131. CGI scripts are run by the HTTPD, and therefore by the UID of the HTTPD
  1132. process, which is (by convention) usually a special user "nobody".
  1133.  
  1134. There are two basic ways to run a script under your own userid:
  1135. (1) The direct approach: use a setuid program.
  1136. (2) The double-server approach: have your CGI script communicate
  1137.     with a second process (e.g. a daemon) running under your userid,
  1138.     which is responsible for the actual file management.
  1139.  
  1140. The direct approach is usually faster, but the client-server architecture
  1141. may help with other problems, such as maintaining integrity of a database.
  1142.  
  1143. When running a compiled CGI program (e.g. C, C++), you can make it
  1144. setuid by simply setting the setuid bit:
  1145. e.g. "chmod 4755 myprog.cgi"
  1146.  
  1147. For security reasons, this is not possible with scripting languages
  1148. (eg Perl, Tcl, shell).   A workaround is to run them from a setuid
  1149. program, such as cgiwrap.
  1150.  
  1151. In most cases where you'd want to use the client-server approach,
  1152. the server is a finished product (such as an SQL server) with its
  1153. own CGI interface.
  1154. A lightweight alternative to this is Don Libes' "expect" package.
  1155.  
  1156. Note that any program running under your userid has access to all your
  1157. files, and could do serious damage if hacked.   Take care!
  1158.  
  1159.  
  1160. ------------------------------
  1161.  
  1162. Subject: 3.21 How can I prevent my CGI results being cached by the browser?
  1163.  
  1164.  
  1165. Firstly, we need to debunk a myth.  People asking this question usually
  1166. add that they tried "Pragma: no-cache".  Whilst this is not actively
  1167. wrong, there is no requirement on browsers to take any notice of it,
  1168. and most of them don't.
  1169.  
  1170. The "Pragma: no-cache" header (now superseded by HTTP/1.1 Cache-Control)
  1171. is a directive to proxies.  The browser sends it with an HTTP request
  1172. to indicate that it wants the request to be dealt with by the original
  1173. server and will not accept a proxy's cached document (e.g. when you
  1174. use a reload button).  The server may send it to tell a proxy not to
  1175. cache the document.
  1176.  
  1177. Having said all that, a practical hack to get round cacheing is
  1178. to use a different URL for your CGI script each time it's called.
  1179. This can easily be accomplished by adding a unique identifier such
  1180. as current time in the QUERY_STRING or PATH_INFO.  The browser will
  1181. see a different URL, but the script can just ignore it.  Note that
  1182. this can be very inefficient, and should be avoided where possible.
  1183.  
  1184.  
  1185. ------------------------------
  1186.  
  1187. Subject: 3.22 How can I control the default filename when downloading a file via CGI?
  1188.  
  1189.  
  1190.     (from a newsgroup post by Matthew Healy)
  1191.  
  1192. One option, assuming you aren't already using the PATH_INFO
  1193. environment variable, is just to call your CGI script with extra
  1194. path information.
  1195.  
  1196. For example, suppose the URL to your script is actually
  1197.  
  1198. http://server.com/scriptname?name1=value1&name2=value2
  1199.  
  1200. Instead, try calling it as
  1201.  
  1202. http://server.com/scriptname/filename.ext?name1=value1&name2=value2
  1203.  
  1204. And probably the browser will assign the name given in the last chunk
  1205. as the suggested filename for downloading.
  1206.  
  1207. This works because the http server looks for the program file to run,
  1208. then passes any extra path to the program as PATH_INFO variable; the
  1209. browser cannot tell where the SCRIPT_NAME part ends and the PATH_INFO
  1210. part begins.
  1211.  
  1212. This can also be very useful if you want one script to generate more
  1213. than one filename -- the script can check the PATH_INFO value and
  1214. alter its response accordingly...
  1215.  
  1216.  
  1217. -------------------------------------------------------------
  1218.  
  1219. Subject: SECTION 4 -   APPLICATIONS: IS THERE AN EXISTING SCRIPT TO ...
  1220.  
  1221. There are a lot of applications available.   For all the tasks
  1222. listed here, there are free systems you can download and install
  1223. yourself (at least if you're on UNIX).   Many are excellent.
  1224.  
  1225. Before ever *buying* software, do a Net search on what you want and
  1226. check what freeware is available.   Does the commercial system you
  1227. had in mind *really* have any advantages?   If you can't follow
  1228. the jargon they use to explain the merits of their system, insist
  1229. on some clarification (hey, that's not just for Web software :-)
  1230.  
  1231. Most questions under this heading are probably best answered by
  1232. reference to appropriate review sites on the Web (in many cases,
  1233. Thomas Boutell's WWW FAQ).   In cases where I know of one or more
  1234. good sites, I've referenced them.
  1235.  
  1236.  
  1237. ------------------------------
  1238.  
  1239. Subject: 4.1 Where to look for programs, scripts, and other resources?
  1240.  
  1241.  
  1242. Matt Wright - himself author of many popular CGI resources - has
  1243. recently (March.97) opened a new website dedicated to this subject:
  1244.  
  1245. http://www.cgi-resources.com/
  1246.  
  1247. I am happy to recommend this as a rich and well-organised collection,
  1248. and probably the best of its kind on the Web today.
  1249.  
  1250.  
  1251. ------------------------------
  1252.  
  1253. Subject: 4.2 Where to look for free scripts for my application?
  1254.  
  1255.  
  1256. (see also previous question, which should perhaps replace this one altogether)
  1257.  
  1258. Some popular places to look for a wide range of free CGI applications are:
  1259.  
  1260. Selena Sol's Public Domain CGI Scripts
  1261. http://www.extropia.com/Scripts/
  1262.  
  1263. Matt Wright's Script Archive
  1264. http://www.worldwidemart.com/scripts/
  1265.  
  1266. Dale Bewley has a much longer list of script archives
  1267. (along with his own scripts) at
  1268. http://www.engr.iupui.edu/~dbewley/perl/
  1269.  
  1270.  
  1271. ------------------------------
  1272.  
  1273. Subject: 4.3 Discussion group/bulletin board
  1274.  
  1275.  
  1276. David R Woolley maintains a list of currently around 100 systems at
  1277. http://freenet.msp.mn.us/~drwool/webconf.html
  1278. ("Conferencing on the Web").
  1279.  
  1280.  
  1281. ------------------------------
  1282.  
  1283. Subject: 4.4 CSCW/Groupware
  1284.  
  1285.  
  1286. There are several overview sites for this.   A few are:
  1287.  
  1288. The CSCW Yellow Pages, at
  1289. http://www11.informatik.tu-muenchen.de/cscw/yp/YP-index-type.html
  1290.  
  1291. NCSA Web Collaboration pages, at
  1292. http://union.ncsa.uiuc.edu/HyperNews/get/www/collaboration.html
  1293.  
  1294.  
  1295. ------------------------------
  1296.  
  1297. Subject: 4.5 Database
  1298.  
  1299.  
  1300. This subject deserves its own FAQ.   When someone recently asked about one,
  1301. Matthew.Healy@yale.edu (Matthew D. Healy) posted this answer (slightly chopped)
  1302.  
  1303. > : Is there a CGI and Database FAQ available?
  1304. > : If so, could someone tell me where can I get it?
  1305. > Dunno about a FAQ on that.  I can recommend a couple of published
  1306. > works, however:
  1307. > 1. I wrote a chapter about CGI/Database work for the book
  1308. > {Special Edition Using CGI}.  Fulltext is online at the
  1309. > publisher's WWW site:
  1310. > http://www.mcp.com/que/et/se_cgi/  The book
  1311. > http://www.mcp.com/que/et/se_cgi/Cgi13fi.htm  My chapter on WWW/DBMS
  1312. > 2. Jeff Rowe wrote an excellent book, {Building Internet Database
  1313. > Servers With CGI}.  URL for more info:
  1314. > http://cscsun1.larc.nasa.gov/~beowulf/db/existing_products.html
  1315. > Jeff's WWW site has scads of useful information on WWW/DBMS programming,
  1316. > and pointers to lots more sites.
  1317.  
  1318. Matthew's CGI links page at http://ycmi.med.yale.edu/~healy/cgilinks.html
  1319. expands the list, and includes links to popular packages including
  1320. Bo Frese Rasmussen's WDB at http://venus.dtv.dk/~bfr/wdb/
  1321.  
  1322.  
  1323. ------------------------------
  1324.  
  1325. Subject: 4.6 Is than a non-setuid script to allow users to change password?
  1326.  
  1327.  
  1328. Yes.  Here is an example:
  1329.  
  1330.         http://pitch.nist.gov/cgi-bin/cgi.tcl/passwd-form.cgi
  1331.  
  1332. It is an Expect script that wraps itself around the passwd command.
  1333. With this technique, there is no need to make scripts setuid (e.g.,
  1334. cgiwrap).  This same technique lends itself to many other scripts that
  1335. might otherwise need setuid.
  1336.  
  1337. (contributed by Don Libes <libes@cme.nist.gov>)
  1338.  
  1339.  
  1340. -------------------------------------------------------------
  1341.  
  1342. Subject: SECTION 5 -   TROUBLESHOOTING A CGI APPLICATION
  1343.  
  1344. Since this subject is quite well conered by other documents, this FAQ has
  1345. relatively little to say. 
  1346.  
  1347. Tom Christiansen's "Idiot's guide to solving Perl/CGI problems" is a
  1348. slightly tongue-in-cheek list of common problems, and how to track
  1349. them down.  Much of what Tom covers is not specifically Perl, but
  1350. applies equally to CGI programming in other languages. 
  1351.  
  1352. Marc Hedlund's CGI FAQ and Thomas Boutell's WWW FAQ also
  1353. deal with this subject. 
  1354.  
  1355. See "Further Reading" below (if you don't already know where to find these
  1356. documents). 
  1357.  
  1358.  
  1359. ------------------------------
  1360.  
  1361. Subject: 5.1 Are there some interactive debugging tools and services available?
  1362.  
  1363.  
  1364. (1) Several CGI programming libraries offer powerful interactive
  1365.     debugging facilities.   These include:
  1366.  
  1367.     - for Perl, Lincoln Stein's CGI.pm
  1368.     http://www-genome.wi.mit.edu/ftp/pub/software/WWW/cgi_docs.html
  1369.  
  1370.     - for Tcl, Don Libes' cgi.tcl
  1371.     http://expect.nist.gov/cgi.tcl
  1372.  
  1373.     - for C++, Nick Kew's CGI++
  1374.     http://www3.pair.com/webthing/cgiplusplus/
  1375.  
  1376. (2) Nathan Neulinger's cgiwrap is another package with debugging aids.
  1377. http://www.umr.edu/~cgiwrap/
  1378.  
  1379. (3) The "mod_cgi" Apache module (new with Apache 1.2) enables you to
  1380. capture script output and errors for diagnosis.
  1381.  
  1382. (4) "cg-eye" is an offline test harness for CGI, which will run your 
  1383. program or script and print diagnostics on problems it finds.
  1384. http://www.htmlhelp.org/tools/cg-eye/
  1385. http://www.webthing.com/software/cg-eye.html
  1386.  
  1387. See also the next question.
  1388.  
  1389.  
  1390. ------------------------------
  1391.  
  1392. Subject: 5.2 I'm having trouble with my headers.   What can I do?
  1393.  
  1394.  
  1395. For simple cases, examining your response headers "by hand" may suffice:
  1396. (1) telnet to the host and port where the server is running - e.g.
  1397.         telnet www.myhost.com 80
  1398. (2) Enter HTTP request.   The most useful for this purpose is usually HEAD; eg
  1399.         HEAD /index.html HTTP/1.0
  1400.         (optionally other headers)
  1401.         (followed by a blank line)
  1402. Now you'll get a full HTTP response header back.
  1403.  
  1404. For complex cases, such as sending a request with several headers
  1405. (as a browser does) or POSTing a form, there two free online diagnosis
  1406. services available:
  1407.   1. httpeek
  1408.     This gives you a nice interface to defining a customised
  1409.     HTTP request, sends it to your script, and prints
  1410.     diagnostics on the results.
  1411.      http://computerdog.com/httpeek/index.shtml
  1412.   2. The Header Dumper
  1413.     This will take a request from your browser (eg form inputs)
  1414.     and forward the identical request to your server, printing
  1415.     a full report of your request (request headers and form data)
  1416.     and the response from your server (response headers and data).
  1417.      http://www3.pair.com/webthing/docs/cgi/debug/headers.shtml
  1418.  
  1419.  
  1420. ------------------------------
  1421.  
  1422. Subject: 5.3 Why do I get Error 500 ("the script misbehaved", or "Internal Server Error")
  1423.  
  1424.  
  1425. Your script must follow the CGI interface, which requires it to print:
  1426. (1) One or more Header lines.
  1427. (2) A blank line
  1428. (3) (optional, but strongly advised) a document body.
  1429.  
  1430. This error means it didn't.
  1431.  
  1432. The Header lines can include anything that's valid under HTTP, but must
  1433. normally include at least one of the special CGI headers:
  1434.     Content-Type
  1435.     Location
  1436.     Status
  1437.  
  1438. Example (a very minimal HTML page via CGI)
  1439. Content-Type: text/html            <= Header
  1440.                     <= Blank Line
  1441. <title>HelloWorld</title>Hello World    <= Document Body
  1442.  
  1443. A common reason for scripts failing is that they crash before printing
  1444. the header and blank line (or while these are buffered).  Another possible
  1445. reason is that it printed something else - like an error message - in
  1446. the Headers.   Check error logs, put a dummy header right at the top (for
  1447. debugging only), check the "Idiot's Guide", and use the debug mode of your
  1448. CGI library.
  1449.  
  1450.  
  1451. ------------------------------
  1452.  
  1453. Subject: 5.4 I tried to use (Content-Type|Location|whatever), but it appears in my Browser?
  1454.  
  1455.  
  1456. That means you put the line in the wrong place.  It must appear in the
  1457. CGI Header, not the document body.  See previous question.
  1458.  
  1459. It's also possible that you didn't print a header at all, or had a blank
  1460. line or other noise before or in the header, but that the HTTPD has
  1461. corrected this error for you (servers which correct your errors may give
  1462. rise to the "works on A not on B" phenomenon).   See previous question.
  1463.  
  1464.  
  1465. -------------------------------------------------------------
  1466.  
  1467. Subject: SECTION 6 -   FURTHER READING
  1468.  
  1469.  
  1470. ------------------------------
  1471.  
  1472. Subject: 6.1 Other FAQs/collections (including online book)
  1473.  
  1474.  
  1475. ****    Lincoln Stein's FAQ is probably the most    ****
  1476. ****    important WWW document you will ever read.    ****
  1477.  
  1478. Special Edition Using CGI (full book text available online)
  1479. http://www.mcp.com/que/et/se_cgi/
  1480.  
  1481. The Web Authoring FAQ by 'Galactus' Engelfriet and John Pozadzides
  1482. http://htmlhelp.com/links/wdgfaq.htm
  1483. (although at the time of writing the online version appears to be a little
  1484. behind the updated drafts posted).
  1485.  
  1486. For general WWW issues, the World Wide Web FAQ by Thomas Boutell
  1487. http://www.boutell.com/faq/
  1488.  
  1489. Another CGI FAQ, by Marc Hedlund
  1490. http://www.best.com/~hedlund/cgi-faq/
  1491.  
  1492. Perl/CGI programming FAQ, by Shishir Gundavaram and Tom Christiansen
  1493. http://www.perl.com/perl/faq/perl-cgi-faq.html
  1494.  
  1495. The Idiot's Guide to solving Perl/CGI problems by Tom Christiansen
  1496. http://www.perl.com/perl/faq/idiots-guide.html
  1497.  
  1498. The WWW Security FAQ by Lincoln Stein
  1499. http://www-genome.wi.mit.edu/WWW/faqs/www-security-faq.html
  1500.  
  1501. CGI Resources Library
  1502. http://www.cgi-resources.com/
  1503.  
  1504. The WWW Virtual Library
  1505. http://WWW.Stars.com/Vlib/
  1506.  
  1507.  
  1508. ------------------------------
  1509.  
  1510. Subject: 6.2 Reference Pages
  1511.  
  1512.  
  1513. The Common Gateway Interface (CGI)
  1514. http://www.ast.cam.ac.uk/%7Edrtr/cgi-spec.html
  1515. http://hoohoo.ncsa.uiuc.edu/cgi/interface.html
  1516.  
  1517. HyperText Transfer Protocol (HTTP)
  1518. http://www.w3.org/pub/WWW/Protocols/HTTP/
  1519.  
  1520. HyperText Markup Language (HTML)
  1521. http://www.w3.org/pub/WWW/MarkUp/
  1522.  
  1523.  
  1524.  
  1525.  
  1526. ------------------------------
  1527.  
  1528. Subject: INDEX
  1529.  
  1530. The index is generated from an arbitrary list of keywords.
  1531. If I've missed anything obvious that should be here, please let me know.
  1532.  
  1533.  
  1534. APACHE            3.13, 5.1
  1535. AUTHENTICATION    3.10, 3.11
  1536. BACKGROUND        3.14, 3.19
  1537. BASIC             1, 1.10, 3.4, 3.9, 3.10, 3.11, 3.20
  1538. BROWSER           0.4, 2.2, 2.3, 2.8, 3.1, 3.6, 3.7, 3.8, 3.11, 3.12, 3.14,
  1539.                   3.16, 3.21, 3.22, 5.2
  1540. C                 1.4, 1.9, 1.10, 3.8, 3.20, 5.1
  1541. CACHE             3.6, 3.21
  1542. CERN              3.13
  1543. CGI               0.1, 0.3, 0.6, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.10,
  1544.                   1.12, 1.13, 1.14, 2.1, 2.2, 2.4, 2.8, 3.2, 3.7, 3.11,
  1545.                   3.12, 3.13, 3.15, 3.16, 3.18, 3.20, 3.21, 3.22, 4.1, 4.2, 4.5, 4.6, 5.1, 5.2, 5.3, 5.4, 6.1, 6.2
  1546. CGIWRAP           1.13, 3.20, 4.6, 5.1
  1547. CONFERENCING      4.3
  1548. COOKIE            2.4, 3.12, 3.19
  1549. CREDENTIALS       3.11
  1550. CSCW              4.4
  1551. DATABASE          1.4, 2.8, 3.19, 3.20, 4.5
  1552. EMAIL             0.3, 0.4, 3.1, 3.3, 3.4
  1553. ENVIRONMENT       2.1, 2.2, 2.8, 3.1, 3.5, 3.6, 3.22
  1554. EXPECT            0.5, 2.1, 3.11, 3.20, 4.6, 5.1
  1555. FAQ               0, 0.3, 0.4, 0.5, 0.6, 0.7, 1.7, 1.8, 3.4, 3.18, 4.5,
  1556.                   6.1
  1557. FORK              3.8, 3.9
  1558. FRAMES            3.15, 3.16, 3.17
  1559. GET               0.5, 1.7, 1.14, 2.1, 2.8, 3.1, 3.3, 3.11, 3.12, 3.13,
  1560.                   3.16, 3.17, 3.21, 4.4, 4.5, 5.2
  1561. HEAD              2.1, 5.2
  1562. HEADER            0.6, 2, 2.1, 2.4, 2.5, 2.8, 3.2, 3.11, 3.13, 3.15, 3.21,
  1563.                   5.2, 5.3, 5.4
  1564. HTML              0.3, 0.5, 1.1, 1.7, 1.8, 1.13, 1.14, 2.1, 2.2, 3.6, 3.8,
  1565.                   3.9, 3.10, 3.11, 3.14, 4.3, 4.4, 4.5, 5.1, 5.2, 5.3,
  1566.                   6.1, 6.2
  1567. HTTP              0.3, 0.4, 0.5, 1.1, 1.7, 1.8, 1.13, 1.14, 2, 2.1, 2.2,
  1568.                   2.4, 2.5, 2.6, 2.8, 3.4, 3.11, 3.12, 3.14, 3.18, 3.21,
  1569.                   3.22, 4.1, 4.2, 4.3, 4.4, 4.5, 4.6, 5.1, 5.2, 5.3, 6.1, 6.2
  1570. HTTPD             1.5, 1.6, 1.7, 2.1, 2.4, 2.5, 2.6, 3.7, 3.10, 3.11, 3.13,
  1571.                   3.20, 5.4
  1572. IMAGE             3.17
  1573. JAVA              0.1, 1.4, 3.9
  1574. JAVASCRIPT        3.7, 3.16
  1575. LOCATION          2.4, 2.6, 3.13, 5.3
  1576. MICROSOFT         3.6
  1577. MOZILLA           3.6
  1578. MULTIPART         1.14
  1579. NCSA              1.1, 1.5, 1.7, 2.2, 2.3, 2.7, 3.1, 4.4, 6.2
  1580. NETSCAPE          1.4, 2.4, 3.1, 3.7, 3.15
  1581. NOBODY            3.20
  1582. NPH               2, 2.4, 2.5, 2.6, 2.7, 3.11, 3.14
  1583. PASSWORD          3.11
  1584. PERL              1.4, 1.9, 1.10, 3.4, 3.8, 3.16, 3.18, 3.20, 4.2, 5, 5.1,
  1585.                   6.1
  1586. POST              0.4, 0.6, 1.14, 2.1, 2.8, 3.12, 3.22
  1587. PRAGMA            3.21
  1588. REDIRECT          2.4, 3.13
  1589. REFRESH           2.4
  1590. REQUEST           2.1, 2.2, 2.8, 3.9, 3.13, 3.17, 3.21, 5.2
  1591. RESPONSE          0.5, 2.1, 2.4, 2.5, 3.9, 3.11, 3.13, 3.17, 3.19, 3.22,
  1592.                   5.2
  1593. SECURITY          1.7, 1.8, 1.13, 3.20, 6.1
  1594. SERVER            0.3, 1.4, 1.5, 1.7, 1.12, 1.13, 2.1, 2.2, 2.3, 2.4, 2.7,
  1595.                   2.8, 3.5, 3.9, 3.11, 3.12, 3.16, 3.20, 3.21, 3.22, 5.2
  1596. SSI               1.5
  1597. STATUS            2.4, 2.6, 3.11, 3.14, 5.3
  1598. TCL               1.10, 3.20, 4.6, 5.1
  1599. UNIX              1.9, 2.2, 3.8, 4
  1600. URL               0.3, 1.7, 1.13, 2.8, 3.12, 3.13, 3.16, 3.17, 3.21, 3.22,
  1601.                   4.5
  1602. URLENCODE         3.13
  1603. WWW               0.3, 0.5, 0.6, 1.4, 1.7, 1.8, 1.10, 1.13, 2.6, 2.8, 3.4,
  1604.                   3.11, 4.1, 4.2, 4.4, 4.5, 5.1, 5.2, 6.1, 6.2
  1605.  
  1606.