source: branches/3.2/mindi-busybox/docs/draft-coar-cgi-v11-03-clean.html

Last change on this file was 1765, checked in by Bruno Cornec, 13 years ago

Update to busybox 1.7.2

File size: 84.7 KB
Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
2 "http://www.w3.org/TR/REC-html40/loose.dtd">
3<HTML>
4 <HEAD>
5  <TITLE>Common Gateway Interface - 1.1 *Draft 03* [http://cgi-spec.golux.com/draft-coar-cgi-v11-03-clean.html]
6  </TITLE>
7<!--#if expr="$HTTP_USER_AGENT != /Lynx/" -->
8 <!--#set var="GUI" value="1" -->
9<!--#endif -->
10  <LINK HREF="mailto:Ken.Coar@Golux.Com" rev="revised">
11  <LINK REL="STYLESHEET" HREF="cgip-style-rfc.css" TYPE="text/css">
12  <META name="latexstyle" content="rfc">
13  <META name="author" content="Ken A L Coar">
14  <META name="institute" content="IBM Corporation">
15  <META name="date" content="25 June 1999">
16  <META name="expires" content="Expires 31 December 1999">
17  <META name="document" content="INTERNET-DRAFT">
18  <META name="file" content="&lt;draft-coar-cgi-v11-03.txt&gt;">
19  <META name="group" content="INTERNET-DRAFT">
20<!--
21    There are a lot of BNF fragments in this document.  To make it work
22    in all possible browsers (including Lynx, which is used to turn it
23    into text/plain), we handle these by using PREformatted blocks with
24    a universal internal margin of 2, inside one-level DL blocks.
25 -->
26 </HEAD>
27 <BODY>
28  <!--
29    HTML doesn't do paper pagination, so we need to fake it out.  Basing
30    our formatting upon RFC2068, there are four (4) lines of header and
31    four (4) lines of footer for each page.
32
33<DIV ALIGN="CENTER">
34 <PRE>
35
36
37
38
39Coar, et al.               CGI/1.1 Specification                     May, 1998
40INTERNET-DRAFT             Expires 1 December 1998                    [Page 2]
41
42
43 </PRE>
44</DIV>
45  -->
46  <!--
47    The following weirdness wrt non-breaking spaces is to get Lynx
48    (which is barely TABLE-aware) to line the left/right justified
49    text up properly.
50  -->
51  <DIV ALIGN="CENTER">
52   <TABLE WIDTH="100%" CELLPADDING=0 CELLSPACING=0>
53    <TR VALIGN="TOP">
54     <TD ALIGN="LEFT">
55      INTERNET-DRAFT&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
56     </TD>
57     <TD ALIGN="RIGHT">
58      &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Ken A L Coar
59     </TD>
60    </TR>
61    <TR VALIGN="TOP">
62     <TD ALIGN="LEFT">
63      draft-coar-cgi-v11-03.{html,txt}&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
64     </TD>
65     <TD ALIGN="RIGHT">
66      &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;IBM Corporation
67     </TD>
68    </TR>
69    <TR VALIGN="TOP">
70     <TD ALIGN="LEFT">
71      &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
72     </TD>
73     <TD ALIGN="RIGHT">
74      &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;D.R.T. Robinson
75     </TD>
76    </TR>
77    <TR VALIGN="TOP">
78     <TD ALIGN="LEFT">
79      &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
80     </TD>
81     <TD ALIGN="RIGHT">
82      &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;E*TRADE&nbsp;UK&nbsp;Ltd.
83     </TD>
84    </TR>
85    <TR VALIGN="TOP">
86     <TD ALIGN="LEFT">
87      &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
88     </TD>
89     <TD ALIGN="RIGHT">
90      &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;25 June 1999
91     </TD>
92    </TR>
93   </TABLE>
94  </DIV>
95
96  <H1 ALIGN="CENTER">
97   The WWW Common Gateway Interface
98   <BR>
99   Version 1.1
100  </H1>
101
102<!--#include virtual="I-D-statement" -->
103
104  <H2>
105   <A NAME="Abstract">
106    Abstract
107   </A>
108  </H2>
109  <P>
110  The Common Gateway Interface (CGI) is a simple interface for running
111  external programs, software or gateways under an information server
112  in a platform-independent manner. Currently, the supported information
113  servers are HTTP servers.
114  </P>
115  <P>
116  The interface has been in use by the World-Wide Web since 1993. This
117  specification defines the
118  "current practice" parameters of the
119  'CGI/1.1' interface developed and documented at the U.S. National
120  Centre for Supercomputing Applications [NCSA-CGI].
121  This document also defines the use of the CGI/1.1 interface
122  on the Unix and AmigaDOS(tm) systems.
123  </P>
124  <P>
125  Discussion of this draft occurs on the CGI-WG mailing list; see the
126  project Web page at
127  <SAMP>&lt;URL:<A HREF="http://CGI-Spec.Golux.Com/"
128                >http://CGI-Spec.Golux.Com/</A>&gt;</SAMP>
129  for details on the mailing list and the status of the project.
130  </P>
131
132<!--#if expr="$GUI" -->
133  <H2>
134   Revision History
135  </H2>
136  <P>
137  The revision history of this draft is being maintained using Web-based
138  GUI notation, such as struck-through characters and colour-coded
139  sections.  The following legend describes how to determine the origin
140  of a particular revision according to the colour of the text:
141  </P>
142  <DL COMPACT>
143   <DT>Black
144   </DT>
145   <DD>Revision 00, released 28 May 1998
146   </DD>
147   <DT>Green
148   </DT>
149   <DD>Revision 01, released 28 December 1998
150    <BR>
151    Major structure change: Section 4, "Request Metadata (Meta-Variables)"
152    was moved entirely under <A HREF="#7.0">Section 7</A>, "Data Input to the
153    CGI Script."
154    Due to the size of this change, it is noted here and the text in its
155    former location does <EM>not</EM> appear as struckthrough.  This has
156    caused major <A HREF="#6.0">sections 5</A> and following to decrement
157    by one.  Other
158    large text movements are likewise not marked up.  References to RFC
159    1738 were changed to 2396 (1738's replacement).
160   </DD>
161   <DT>Red
162   </DT>
163   <DD>Revision 02, released 2 April, 1999
164    <BR>
165    Added text to <A HREF="#8.3">section 8.3</A> defining correct handling
166    of HTTP/1.1
167    requests using "chunked" Transfer-Encoding.  Labelled metavariable
168    names in <A HREF="#8.0">section 8</A> with the appropriate detail section
169    numbers.
170    Clarified allowed usage of <SAMP>Status</SAMP> and
171    <SAMP>Location</SAMP> response header fields.  Included new
172    Internet-Draft language.
173   </DD>
174   <DT>Fuchsia
175   </DT>
176   <DD>Revision 03, released 25 June 1999
177    <BR>
178    Changed references from "HTTP" to "Protocol-Specific" for the listing of
179    things like HTTP_ACCEPT.  Changed 'entity-body' and 'content-body' to
180    'message-body.'  Added a note that response headers must comply with
181    requirements of the protocol level in use.  Added a lot of stuff about
182    security (section 11).  Clarified a bunch of productions.  Pointed out
183    that zero-length and omitted values are indistinguishable in this
184    specification.  Clarified production describing order of fields in
185    script response header.  Clarified issues surrounding encoding of
186    data.  Acknowledged additional contributors, and changed one of
187    the authors' addresses.
188   </DD>
189  </DL>
190<!--#endif -->
191
192  <H2>
193   <A NAME="Contents">
194    Table of Contents
195   </A>
196  </H2>
197  <DIV ALIGN="CENTER">
198   <PRE>
199  1 Introduction..............................................<A
200                                                               HREF="#1.0"
201                                                              >TBD</A>
202   1.1 Purpose................................................<A
203                                                               HREF="#1.1"
204                                                              >TBD</A>
205   1.2 Requirements...........................................<A
206                                                               HREF="#1.2"
207                                                              >TBD</A>
208   1.3 Specifications.........................................<A
209                                                               HREF="#1.3"
210                                                              >TBD</A>
211   1.4 Terminology............................................<A
212                                                               HREF="#1.4"
213                                                              >TBD</A>
214  2 Notational Conventions and Generic Grammar................<A
215                                                               HREF="#2.0"
216                                                              >TBD</A>
217   2.1 Augmented BNF..........................................<A
218                                                               HREF="#2.1"
219                                                              >TBD</A>
220   2.2 Basic Rules............................................<A
221                                                               HREF="#2.2"
222                                                              >TBD</A>
223  3 Protocol Parameters.......................................<A
224                                                               HREF="#3.0"
225                                                              >TBD</A>
226   3.1 URL Encoding...........................................<A
227                                                               HREF="#3.1"
228                                                              >TBD</A>
229   3.2 The Script-URI.........................................<A
230                                                               HREF="#3.2"
231                                                              >TBD</A>
232  4 Invoking the Script.......................................<A
233                                                               HREF="#4.0"
234                                                              >TBD</A>
235  5 The CGI Script Command Line...............................<A
236                                                               HREF="#5.0"
237                                                              >TBD</A>
238  6 Data Input to the CGI Script..............................<A
239                                                               HREF="#6.0"
240                                                              >TBD</A>
241   6.1 Request Metadata (Metavariables).......................<A
242                                                               HREF="#6.1"
243                                                              >TBD</A>
244    6.1.1 AUTH_TYPE...........................................<A
245                                                               HREF="#6.1.1"
246                                                              >TBD</A>
247    6.1.2 CONTENT_LENGTH......................................<A
248                                                               HREF="#6.1.2"
249                                                              >TBD</A>
250    6.1.3 CONTENT_TYPE........................................<A
251                                                               HREF="#6.1.3"
252                                                              >TBD</A>
253    6.1.4 GATEWAY_INTERFACE...................................<A
254                                                               HREF="#6.1.4"
255                                                              >TBD</A>
256    6.1.5 Protocol-Specific Metavariables.....................<A
257                                                               HREF="#6.1.5"
258                                                              >TBD</A>
259    6.1.6 PATH_INFO...........................................<A
260                                                               HREF="#6.1.6"
261                                                              >TBD</A>
262    6.1.7 PATH_TRANSLATED.....................................<A
263                                                               HREF="#6.1.7"
264                                                              >TBD</A>
265    6.1.8 QUERY_STRING........................................<A
266                                                               HREF="#6.1.8"
267                                                              >TBD</A>
268    6.1.9 REMOTE_ADDR.........................................<A
269                                                               HREF="#6.1.9"
270                                                              >TBD</A>
271    6.1.10 REMOTE_HOST........................................<A
272                                                               HREF="#6.1.10"
273                                                              >TBD</A>
274    6.1.11 REMOTE_IDENT.......................................<A
275                                                               HREF="#6.1.11"
276                                                              >TBD</A>
277    6.1.12 REMOTE_USER........................................<A
278                                                               HREF="#6.1.12"
279                                                              >TBD</A>
280    6.1.13 REQUEST_METHOD.....................................<A
281                                                               HREF="#6.1.13"
282                                                              >TBD</A>
283    6.1.14 SCRIPT_NAME........................................<A
284                                                               HREF="#6.1.14"
285                                                              >TBD</A>
286    6.1.15 SERVER_NAME........................................<A
287                                                               HREF="#6.1.15"
288                                                              >TBD</A>
289    6.1.16 SERVER_PORT........................................<A
290                                                               HREF="#6.1.16"
291                                                              >TBD</A>
292    6.1.17 SERVER_PROTOCOL....................................<A
293                                                               HREF="#6.1.17"
294                                                              >TBD</A>
295    6.1.18 SERVER_SOFTWARE....................................<A
296                                                               HREF="#6.1.18"
297                                                              >TBD</A>
298    6.2 Request Message-Bodies................................<A
299                                                               HREF="#6.2"
300                                                              >TBD</A>
301  7 Data Output from the CGI Script...........................<A
302                                                               HREF="#7.0"
303                                                              >TBD</A>
304   7.1 Non-Parsed Header Output...............................<A
305                                                               HREF="#7.1"
306                                                              >TBD</A>
307   7.2 Parsed Header Output...................................<A
308                                                               HREF="#7.2"
309                                                              >TBD</A>
310    7.2.1 CGI header fields...................................<A
311                                                               HREF="#7.2.1"
312                                                              >TBD</A>
313     7.2.1.1 Content-Type.....................................<A
314                                                               HREF="#7.2.1.1"
315                                                              >TBD</A>
316     7.2.1.2 Location.........................................<A
317                                                               HREF="#7.2.1.2"
318                                                              >TBD</A>
319     7.2.1.3 Status...........................................<A
320                                                               HREF="#7.2.1.3"
321                                                              >TBD</A>
322     7.2.1.4 Extension header fields..........................<A
323                                                               HREF="#7.2.1.3"
324                                                              >TBD</A>
325    7.2.2 HTTP header fields..................................<A
326                                                               HREF="#7.2.2"
327                                                              >TBD</A>
328  8 Server Implementation.....................................<A
329                                                               HREF="#8.0"
330                                                              >TBD</A>
331   8.1 Requirements for Servers...............................<A
332                                                               HREF="#8.1"
333                                                              >TBD</A>
334    8.1.1 Script-URI..........................................<A
335                                                               HREF="#8.1"
336                                                              >TBD</A>
337    8.1.2 Request Message-body Handling.......................<A
338                                                               HREF="#8.1.2"
339                                                              >TBD</A>
340    8.1.3 Required Metavariables..............................<A
341                                                               HREF="#8.1.3"
342                                                              >TBD</A>
343    8.1.4 Response Compliance.................................<A
344                                                               HREF="#8.1.4"
345                                                              >TBD</A>
346   8.2 Recommendations for Servers............................<A
347                                                               HREF="#8.2"
348                                                              >TBD</A>
349   8.3 Summary of Metavariables...............................<A
350                                                               HREF="#8.3"
351                                                              >TBD</A>
352  9 Script Implementation.....................................<A
353                                                               HREF="#9.0"
354                                                              >TBD</A>
355   9.1 Requirements for Scripts...............................<A
356                                                               HREF="#9.1"
357                                                              >TBD</A>
358   9.2 Recommendations for Scripts............................<A
359                                                               HREF="#9.2"
360                                                              >TBD</A>
361  10 System Specifications....................................<A
362                                                               HREF="#10.0"
363                                                              >TBD</A>
364   10.1 AmigaDOS..............................................<A
365                                                               HREF="#10.1"
366                                                              >TBD</A>
367   10.2 Unix..................................................<A
368                                                               HREF="#10.2"
369                                                              >TBD</A>
370  11 Security Considerations..................................<A
371                                                               HREF="#11.0"
372                                                              >TBD</A>
373   11.1 Safe Methods..........................................<A
374                                                               HREF="#11.1"
375                                                              >TBD</A>
376   11.2 HTTP Header Fields Containing Sensitive Information...<A
377                                                               HREF="#11.2"
378                                                              >TBD</A>
379   11.3 Script Interference with the Server...................<A
380                                                               HREF="#11.3"
381                                                              >TBD</A>
382   11.4 Data Length and Buffering Considerations..............<A
383                                                               HREF="#11.4"
384                                                              >TBD</A>
385   11.5 Stateless Processing..................................<A
386                                                               HREF="#11.5"
387                                                              >TBD</A>
388  12 Acknowledgments..........................................<A
389                                                               HREF="#12.0"
390                                                              >TBD</A>
391  13 References...............................................<A
392                                                               HREF="#13.0"
393                                                              >TBD</A>
394  14 Authors' Addresses.......................................<A
395                                                               HREF="#14.0"
396                                                              >TBD</A>
397     </PRE>
398  </DIV>
399
400  <H2>
401   <A NAME="1.0">
402    1. Introduction
403   </A>
404  </H2>
405
406  <H3>
407   <A NAME="1.1">
408    1.1. Purpose
409   </A>
410  </H3>
411  <P>
412  Together the HTTP [<A HREF="#[3]">3</A>,<A HREF="#[8]">8</A>] server
413  and the CGI script are responsible
414  for servicing a client
415  request by sending back responses. The client
416  request comprises a Universal Resource Identifier (URI)
417  [<A HREF="#[1]">1</A>], a
418  request method, and various ancillary
419  information about the request
420  provided by the transport mechanism.
421  </P>
422  <P>
423  The CGI defines the abstract parameters, known as
424  metavariables,
425  which describe the client's
426  request. Together with a
427  concrete programmer interface this specifies a platform-independent
428  interface between the script and the HTTP server.
429  </P>
430
431  <H3>
432   <A NAME="1.2">
433    1.2. Requirements
434   </A>
435  </H3>
436  <P>
437  This specification uses the same words as RFC 1123
438  [<A HREF="#[5]">5</A>] to define the
439  significance of each particular requirement. These are:
440  </P><!--#if expr="! $GUI" -->
441  <P></P><!--#endif -->
442  <DL>
443   <DT><EM>MUST</EM>
444   </DT>
445   <DD>
446    <P>
447    This word or the adjective 'required' means that the item is an
448    absolute requirement of the specification.
449    </P>
450   </DD>
451   <DT><EM>SHOULD</EM>
452   </DT>
453   <DD>
454    <P>
455    This word or the adjective 'recommended' means that there may
456    exist valid reasons in particular circumstances to ignore this
457    item, but the full implications should be understood and the case
458    carefully weighed before choosing a different course.
459    </P>
460   </DD>
461   <DT><EM>MAY</EM>
462   </DT>
463   <DD>
464    <P>
465    This word or the adjective 'optional' means that this item is
466    truly optional. One vendor may choose to include the item because
467    a particular marketplace requires it or because it enhances the
468    product, for example; another vendor may omit the same item.
469    </P>
470   </DD>
471  </DL>
472  <P>
473  An implementation is not compliant if it fails to satisfy one or more
474  of the 'must' requirements for the protocols it implements. An
475  implementation that satisfies all of the 'must' and all of the
476  'should' requirements for its features is said to be 'unconditionally
477  compliant'; one that satisfies all of the 'must' requirements but not
478  all of the 'should' requirements for its features is said to be
479  'conditionally compliant.'
480  </P>
481
482  <H3>
483   <A NAME="1.3">
484    1.3. Specifications
485   </A>
486  </H3>
487  <P>
488  Not all of the functions and features of the CGI are defined in the
489  main part of this specification. The following phrases are used to
490  describe the features which are not specified:
491  </P>
492  <DL>
493   <DT><EM>system defined</EM>
494   </DT>
495   <DD>
496    <P>
497    The feature may differ between systems, but must be the same for
498    different implementations using the same system. A system will
499    usually identify a class of operating-systems. Some systems are
500    defined in
501    <A HREF="#10.0"
502    >section 10</A> of this document.
503    New systems may be defined
504    by new specifications without revision of this document.
505    </P>
506   </DD>
507   <DT><EM>implementation defined</EM>
508   </DT>
509   <DD>
510    <P>
511    The behaviour of the feature may vary from implementation to
512    implementation, but a particular implementation must document its
513    behaviour.
514    </P>
515   </DD>
516  </DL>
517
518  <H3>
519   <A NAME="1.4">
520    1.4. Terminology
521   </A>
522  </H3>
523  <P>
524  This specification uses many terms defined in the HTTP/1.1
525  specification [<A HREF="#[8]">8</A>]; however, the following terms are
526  used here in a
527  sense which may not accord with their definitions in that document,
528  or with their common meaning.
529  </P>
530
531  <DL>
532   <DT><EM>metavariable</EM>
533   </DT>
534   <DD>
535    <P>
536    A named parameter that carries information from the server to the
537    script. It is not necessarily a variable in the operating-system's
538    environment, although that is the most common implementation.
539    </P>
540   </DD>
541
542   <DT><EM>script</EM>
543   </DT>
544   <DD>
545    <P>
546    The software which is invoked by the server <EM>via</EM> this
547    interface. It
548    need not be a standalone program, but could be a
549    dynamically-loaded or shared library, or even a subroutine in the
550    server.  It <EM>may</EM> be a set of statements
551    interpreted at run-time, as the term 'script' is frequently
552    understood, but that is not a requirement and within the context
553    of this specification the term has the broader definition stated.
554    </P>
555   </DD>
556   <DT><EM>server</EM>
557   </DT>
558   <DD>
559    <P>
560    The application program which invokes the script in order to service
561    requests.
562    </P>
563   </DD>
564  </DL>
565
566  <H2>
567   <A NAME="2.0">
568    2. Notational Conventions and Generic Grammar
569   </A>
570  </H2>
571
572  <H3>
573   <A NAME="2.1">
574    2.1. Augmented BNF
575   </A>
576  </H3>
577  <P>
578  All of the mechanisms specified in this document are described in
579  both prose and an augmented Backus-Naur Form (BNF) similar to that
580  used by RFC 822 [<A HREF="#[6]">6</A>]. This augmented BNF contains
581  the following constructs:
582  </P>
583  <DL>
584   <DT>name = definition
585   </DT>
586   <DD>
587    <P>
588    The
589    definition by the equal character ("="). Whitespace is only
590    significant in that continuation lines of a definition are
591    indented.
592    </P>
593   </DD>
594   <DT>"literal"
595   </DT>
596   <DD>
597    <P>
598    Quotation marks (") surround literal text, except for a literal
599    quotation mark, which is surrounded by angle-brackets ("&lt;" and "&gt;").
600    Unless stated otherwise, the text is case-sensitive.
601    </P>
602   </DD>
603   <DT>rule1 | rule2
604   </DT>
605   <DD>
606    <P>
607    Alternative rules are separated by a vertical bar ("|").
608    </P>
609   </DD>
610   <DT>(rule1 rule2 rule3)
611   </DT>
612   <DD>
613    <P>
614    Elements enclosed in parentheses are treated as a single element.
615    </P>
616   </DD>
617   <DT>*rule
618   </DT>
619   <DD>
620    <P>
621    A rule preceded by an asterisk ("*") may have zero or more
622    occurrences. A rule preceded by an integer followed by an asterisk
623    must occur at least the specified number of times.
624    </P>
625   </DD>
626   <DT>[rule]
627   </DT>
628   <DD>
629    <P>
630    An element enclosed in square
631    brackets ("[" and "]") is optional.
632    </P>
633   </DD>
634  </DL>
635
636  <H3>
637   <A NAME="2.2">
638    2.2. Basic Rules
639   </A>
640  </H3>
641  <P>
642  The following rules are used throughout this specification to
643  describe basic parsing constructs.
644  </P><!--#if expr="! $GUI" -->
645  <P></P><!--#endif -->
646  <PRE>
647    alpha         = lowalpha | hialpha
648    alphanum      = alpha | digit
649    lowalpha      = "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h"
650                    | "i" | "j" | "k" | "l" | "m" | "n" | "o" | "p"
651                    | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x"
652                    | "y" | "z"
653    hialpha       = "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H"
654                    | "I" | "J" | "K" | "L" | "M" | "N" | "O" | "P"
655                    | "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X"
656                    | "Y" | "Z"
657    digit         = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7"
658                    | "8" | "9"
659    hex           = digit | "A" | "B" | "C" | "D" | "E" | "F" | "a"
660                    | "b" | "c" | "d" | "e" | "f"
661    escaped       = "%" hex hex
662    OCTET         = &lt;any 8-bit sequence of data&gt;
663    CHAR          = &lt;any US-ASCII character (octets 0 - 127)&gt;
664    CTL           = &lt;any US-ASCII control character
665                    (octets 0 - 31) and DEL (127)&gt;
666    CR            = &lt;US-ASCII CR, carriage return (13)&gt;
667    LF            = &lt;US-ASCII LF, linefeed (10)&gt;
668    SP            = &lt;US-ASCII SP, space (32)&gt;
669    HT            = &lt;US-ASCII HT, horizontal tab (9)&gt;
670    NL            = CR | LF
671    LWSP          = SP | HT | NL
672    tspecial      = "(" | ")" | "@" | "," | ";" | ":" | "\" | &lt;"&gt;
673                    | "/" | "[" | "]" | "?" | "&lt;" | "&gt;" | "{" | "}"
674                    | SP | HT | NL
675    token         = 1*&lt;any CHAR except CTLs or tspecials&gt;
676    quoted-string = ( &lt;"&gt; *qdtext &lt;"&gt; ) | ( "&lt;" *qatext "&gt;")
677    qdtext        = &lt;any CHAR except &lt;"&gt; and CTLs but including LWSP&gt;
678    qatext        = &lt;any CHAR except "&lt;", "&gt;" and CTLs but
679                    including LWSP&gt;
680    mark          = "-" | "_" | "." | "!" | "~" | "*" | "'" | "(" | ")"
681    unreserved    = alphanum | mark
682    reserved      = ";" | "/" | "?" | ":" | "@" | "&amp;" | "=" |
683                    "$" | ","
684    uric          = reserved | unreserved | escaped
685  </PRE>
686  <P>
687  Note that newline (NL) need not be a single character, but can be a
688  character sequence.
689  </P>
690
691  <H2>
692   <A NAME="3.0">
693    3. Protocol Parameters
694   </A>
695  </H2>
696
697  <H3>
698   <A NAME="3.1">
699    3.1. URL Encoding
700   </A>
701  </H3>
702  <P>
703  Some variables and constructs used here are described as being
704  'URL-encoded'. This encoding is described in section
705  2 of RFC
706  2396
707  [<A HREF="#[4]">4</A>].
708  </P>
709  <P>
710  An alternate "shortcut" encoding for representing the space
711  character exists and is in common use.  Scripts MUST be prepared to
712  recognise both '+' and '%20' as an encoded space in a
713  URL-encoded value.
714  </P>
715  <P>
716  Note that some unsafe characters may have different semantics if
717  they are encoded. The definition of which characters are unsafe
718  depends on the context.
719  For example, the following two URLs do not
720  necessarily refer to the same resource:
721  </P><!--#if expr="! $GUI" -->
722  <P></P><!--#endif -->
723  <PRE>
724    http://somehost.com/somedir%2Fvalue
725    http://somehost.com/somedir/value
726  </PRE>
727  <P>
728  See section
729  2 of RFC
730  2396 [<A HREF="#[4]">4</A>]
731  for authoritative treatment of this issue.
732  </P>
733
734  <H3>
735   <A NAME="3.2">
736    3.2. The Script-URI
737   </A>
738  </H3>
739  <P>
740  The 'Script-URI' is defined as the URI of the resource identified
741  by the metavariables.   Often,
742  this URI will be the same as
743  the URI requested by the client (the 'Client-URI'); however, it need
744  not be. Instead, it could be a URI invented by the server, and so it
745  can only be used in the context of the server and its CGI interface.
746  </P>
747  <P>
748  The Script-URI has the syntax of generic-RL as defined in section 2.1
749  of RFC 1808 [<A HREF="#[7]">7</A>], with the exception that object
750  parameters and
751  fragment identifiers are not permitted:
752  </P><!--#if expr="! $GUI" -->
753  <P></P><!--#endif -->
754  <PRE>
755    &lt;scheme&gt;://&lt;host&gt;&lt;port&gt;/&lt;path&gt;?&lt;query&gt;
756  </PRE>
757  <P>
758  The various components of the
759  Script-URI
760  are defined by some of the
761  metavariables (see
762  <A HREF="#4.0">section 4</A>
763  below);
764  </P><!--#if expr="! $GUI" -->
765  <P></P><!--#endif -->
766  <PRE>
767    script-uri = protocol "://" SERVER_NAME ":" SERVER_PORT enc-script
768                 enc-path-info "?" QUERY_STRING
769  </PRE>
770  <P>
771  where 'protocol' is obtained
772  from SERVER_PROTOCOL, 'enc-script' is a
773  URL-encoded version of SCRIPT_NAME and 'enc-path-info' is a
774  URL-encoded version of PATH_INFO.  See
775  <A HREF="#4.6">section 4.6</A> for more information about the PATH_INFO
776  metavariable.
777  </P>
778  <P>
779  Note that the scheme and the protocol are <EM>not</EM> identical;
780  for instance, a resource accessed <EM>via</EM> an SSL mechanism
781  may have a Client-URI with a scheme of "<SAMP>https</SAMP>"
782  rather than "<SAMP>http</SAMP>".   CGI/1.1 provides no means
783  for the script to reconstruct this, and therefore
784  the Script-URI includes the base protocol used.
785  </P>
786
787  <H2>
788   <A NAME="4.0">
789    4. Invoking the Script
790   </A>
791  </H2>
792  <P>
793  The
794  script is invoked in a system defined manner. Unless specified
795  otherwise, the file containing the script will be invoked as an
796  executable program.
797  </P>
798
799  <H2>
800   <A NAME="5.0">
801    5. The CGI Script Command Line
802   </A>
803  </H2>
804  <P>
805  Some systems support a method for supplying an array of strings to
806  the CGI script. This is only used in the case of an 'indexed' query.
807  This is identified by a "GET" or "HEAD" HTTP request with a URL
808  query
809  string not containing any unencoded "=" characters. For such a
810  request,
811  servers SHOULD parse the search string
812  into words, using the following rules:
813  </P><!--#if expr="! $GUI" -->
814  <P></P><!--#endif -->
815  <PRE>
816    search-string = search-word *( "+" search-word )
817    search-word   = 1*schar
818    schar         = xunreserved | escaped | xreserved
819    xunreserved   = alpha | digit | xsafe | extra
820    xsafe         = "$" | "-" | "_" | "."
821    xreserved     = ";" | "/" | "?" | ":" | "@" | "&"
822  </PRE>
823  <P>
824  After parsing, each word is URL-decoded, optionally encoded in a
825  system defined manner,
826  and then the argument list is set to the list
827  of words.
828  </P>
829  <P>
830  If the server cannot create any part of the argument list, then the
831  server SHOULD NOT generate any command line information. For example, the
832  number of arguments may be greater than operating system or server
833  limitations permit, or one of the words may not be representable as an
834  argument.
835  </P>
836  <P>
837  Scripts SHOULD check to see if the QUERY_STRING value contains an
838  unencoded "=" character, and SHOULD NOT use the command line arguments
839  if it does.
840  </P>
841
842  <H2>
843   <A NAME="6.0">
844    6. Data Input to the CGI Script
845   </A>
846  </H2>
847  <P>
848  Information about a request comes from two different sources: the
849  request header, and any associated
850  message-body.
851  Servers MUST
852  make portions of this information available to
853   scripts.
854  </P>
855
856  <H3>
857   <A NAME="6.1">
858    6.1. Request Metadata
859    (Metavariables)
860   </A>
861  </H3>
862  <P>
863  Each CGI server
864  implementation MUST define a mechanism
865  to pass data about the request from
866  the server to the script.
867  The metavariables containing these
868  data
869  are accessed by the script in a system
870  defined manner.
871  The
872  representation of the characters in the
873  metavariables is
874  system defined.
875  </P>
876  <P>
877  This specification does not distinguish between the representation of
878  null values and missing ones.  Whether null or missing values
879  (such as a query component of "?" or "", respectively) are represented
880  by undefined metavariables or by metavariables with values of "" is
881  implementation-defined.
882  </P>
883  <P>
884  Case is not significant in the
885  metavariable
886  names, in that there cannot be two
887  different variables
888  whose names differ in case only. Here they are
889  shown using a canonical representation of capitals plus underscore
890  ("_"). The actual representation of the names is system defined; for
891  a particular system the representation MAY be defined differently
892  than this.
893  </P>
894  <P>
895  Metavariable
896  values MUST be
897  considered case-sensitive except as noted
898  otherwise.
899  </P>
900  <P>
901  The canonical
902  metavariables
903  defined by this specification are:
904  </P><!--#if expr="! $GUI" -->
905  <P></P><!--#endif -->
906  <PRE>
907    AUTH_TYPE
908    CONTENT_LENGTH
909    CONTENT_TYPE
910    GATEWAY_INTERFACE
911    PATH_INFO
912    PATH_TRANSLATED
913    QUERY_STRING
914    REMOTE_ADDR
915    REMOTE_HOST
916    REMOTE_IDENT
917    REMOTE_USER
918    REQUEST_METHOD
919    SCRIPT_NAME
920    SERVER_NAME
921    SERVER_PORT
922    SERVER_PROTOCOL
923    SERVER_SOFTWARE
924  </PRE>
925  <P>
926  Metavariables with names beginning with the protocol name (<EM>e.g.</EM>,
927  "HTTP_ACCEPT") are also canonical in their description of request header
928  fields.  The number and meaning of these fields may change independently
929  of this specification.  (See also <A HREF="#6.1.5">section 6.1.5</A>.)
930  </P>
931
932  <H4>
933   <A NAME="6.1.1">
934    6.1.1. AUTH_TYPE
935   </A>
936  </H4>
937  <P>
938  This variable is specific to requests made
939  <EM>via</EM> the
940  "<CODE>http</CODE>"
941  scheme.
942  </P>
943  <P>
944  If the Script-URI
945  required access authentication for external
946  access, then the server
947  MUST set
948  the value of
949  this variable
950  from the '<SAMP>auth-scheme</SAMP>' token in
951  the request's "<SAMP>Authorization</SAMP>" header
952  field.
953  Otherwise
954  it is
955  set to NULL.
956  </P><!--#if expr="! $GUI" -->
957  <P></P><!--#endif -->
958  <PRE>
959    AUTH_TYPE   = "" | auth-scheme
960    auth-scheme = "Basic" | "Digest" | token
961  </PRE>
962  <P>
963  HTTP access authentication schemes are described in section 11 of the
964  HTTP/1.1 specification [<A HREF="#[8]">8</A>]. The auth-scheme is
965  not case-sensitive.
966  </P>
967  <P>
968  Servers
969  MUST
970  provide this metavariable
971  to scripts if the request
972  header included an "<SAMP>Authorization</SAMP>" field
973  that was authenticated.
974  </P>
975
976  <H4>
977   <A NAME="6.1.2">
978    6.1.2. CONTENT_LENGTH
979   </A>
980  </H4>
981  <P>
982  This
983  metavariable
984  is set to the
985  size of the message-body
986  entity attached to the request, if any, in decimal
987  number of octets. If no data are attached, then this
988  metavariable
989  is either NULL or not
990  defined. The syntax is
991  the same as for
992  the HTTP "<SAMP>Content-Length</SAMP>" header field (section 14.14, HTTP/1.1
993  specification [<A HREF="#[8]">8</A>]).
994  </P><!--#if expr="! $GUI" -->
995  <P></P><!--#endif -->
996  <PRE>
997    CONTENT_LENGTH = "" | 1*digit
998  </PRE>
999  <P>
1000  Servers MUST provide this metavariable
1001  to scripts if the request
1002  was accompanied by a
1003  message-body entity.
1004  </P>
1005
1006  <H4>
1007   <A NAME="6.1.3">
1008    6.1.3. CONTENT_TYPE
1009   </A>
1010  </H4>
1011  <P>
1012  If the request includes a
1013  message-body,
1014  CONTENT_TYPE is set
1015  to
1016  the Internet Media Type
1017  [<A HREF="#[9]">9</A>] of the attached
1018  entity if the type was provided <EM>via</EM>
1019  a "<SAMP>Content-type</SAMP>" field in the
1020  request header, or if the server can determine it in the absence
1021  of a supplied "<SAMP>Content-type</SAMP>" field. The syntax is the
1022  same as for the HTTP
1023  "<SAMP>Content-Type</SAMP>" header field.
1024  </P><!--#if expr="! $GUI" -->
1025  <P></P><!--#endif -->
1026  <PRE>
1027    CONTENT_TYPE = "" | media-type
1028    media-type   = type "/" subtype *( ";" parameter)
1029    type         = token
1030    subtype      = token
1031    parameter    = attribute "=" value
1032    attribute    = token
1033    value        = token | quoted-string
1034  </PRE>
1035  <P>
1036  The type, subtype,
1037  and parameter attribute names are not
1038  case-sensitive. Parameter values MAY be case sensitive.
1039  Media types and their use in HTTP are described
1040  in section 3.7 of the
1041  HTTP/1.1 specification [<A HREF="#[8]">8</A>].
1042  </P>
1043  <P>
1044  Example:
1045  </P><!--#if expr="! $GUI" -->
1046  <P></P><!--#endif -->
1047  <PRE>
1048    application/x-www-form-urlencoded
1049  </PRE>
1050  <P>
1051  There is no default value for this variable. If and only if it is
1052  unset, then the script MAY attempt to determine the media type from
1053  the data received. If the type remains unknown, then
1054  the script MAY choose to either assume a
1055  content-type of
1056  <SAMP>application/octet-stream</SAMP>
1057  or reject the request with  a 415 ("Unsupported Media Type")
1058  error.  See <A HREF="#7.2.1.3">section 7.2.1.3</A>
1059  for more information about returning error status values.
1060  </P>
1061  <P>
1062  Servers MUST provide this metavariable
1063  to scripts if
1064  a "<SAMP>Content-Type</SAMP>" field was present
1065  in the original request header.  If the server receives a request
1066  with an attached entity but no "<SAMP>Content-Type</SAMP>"
1067  header field, it MAY attempt to
1068  determine the correct datatype, or it MAY omit this
1069  metavariable when
1070  communicating the request information to the script.
1071  </P>
1072
1073  <H4>
1074   <A NAME="6.1.4">
1075    6.1.4. GATEWAY_INTERFACE
1076   </A>
1077  </H4>
1078  <P>
1079  This
1080  metavariable
1081  is set to
1082  the dialect of CGI being used
1083  by the server to communicate with the script.
1084  Syntax:
1085  </P><!--#if expr="! $GUI" -->
1086  <P></P><!--#endif -->
1087  <PRE>
1088    GATEWAY_INTERFACE = "CGI" "/" major "." minor
1089    major             = 1*digit
1090    minor             = 1*digit
1091  </PRE>
1092  <P>
1093  Note that the major and minor numbers are treated as separate
1094  integers and hence each may be
1095  more than a single
1096  digit. Thus CGI/2.4 is a lower version than CGI/2.13 which in turn
1097  is lower than CGI/12.3. Leading zeros in either
1098  the major or the minor number MUST be ignored by scripts and
1099  SHOULD NOT be generated by servers.
1100  </P>
1101  <P>
1102  This document defines the 1.1 version of the CGI interface
1103  ("CGI/1.1").
1104  </P>
1105  <P>
1106  Servers MUST provide this metavariable
1107  to scripts.
1108  </P>
1109
1110  <H4>
1111   <A NAME="6.1.5">
1112    6.1.5. Protocol-Specific Metavariables
1113   </A>
1114  </H4>
1115  <P>
1116  These metavariables are specific to
1117  the protocol
1118  <EM>via</EM> which the request is made.
1119  Interpretation of these variables depends on the value of
1120  the
1121  SERVER_PROTOCOL
1122  metavariable
1123  (see
1124  <A HREF="#6.1.17">section 6.1.17</A>).
1125  </P>
1126  <P>
1127  Metavariables
1128  with names beginning with "HTTP_" contain
1129  values from the request header, if the
1130  scheme used was HTTP.
1131  Each
1132  HTTP header field name is converted to upper case, has all occurrences of
1133  "-" replaced with "_",
1134  and has "HTTP_" prepended to  form
1135  the metavariable name.
1136  Similar transformations are applied for other
1137  protocols.
1138  The header data MAY be presented as sent
1139  by the client, or MAY be rewritten in ways which do not change its
1140  semantics. If multiple header fields with the same field-name are received
1141  then  the server
1142  MUST  rewrite them as though they
1143  had been received as a single header field having the same
1144  semantics before being represented in a
1145  metavariable.
1146  Similarly, a header field that is received on more than one line
1147  MUST be merged into a single line. The server MUST, if necessary,
1148  change the representation of the data (for example, the character
1149  set) to be appropriate for a CGI
1150  metavariable.
1151  <!-- ###NOTE: See if 2068 describes this thoroughly, and
1152  point there if so. -->
1153  </P>
1154  <P>
1155  Servers are
1156  not required to create
1157  metavariables for all
1158  the request
1159  header fields that they
1160  receive. In particular,
1161  they MAY
1162  decline to make available any
1163  header fields carrying authentication information, such as
1164  "<SAMP>Authorization</SAMP>", or
1165  which are available to the script
1166  <EM>via</EM> other metavariables,
1167  such as "<SAMP>Content-Length</SAMP>" and "<SAMP>Content-Type</SAMP>".
1168  </P>
1169
1170  <H4>
1171   <A NAME="6.1.6">
1172    6.1.6. PATH_INFO
1173   </A>
1174  </H4>
1175  <P>
1176  The PATH_INFO
1177  metavariable
1178  specifies
1179  a path to be interpreted by the CGI script. It identifies the
1180  resource or sub-resource to be returned
1181  by the CGI
1182  script, and it is derived from the portion
1183  of the URI path following the script name but preceding
1184  any query data.
1185  The syntax
1186  and semantics are similar to a decoded HTTP URL
1187  'path' token
1188  (defined in
1189  RFC 2396
1190  [<A HREF="#[4]">4</A>]), with the exception
1191  that a PATH_INFO of "/"
1192  represents a single void path segment.
1193  </P><!--#if expr="! $GUI" -->
1194  <P></P><!--#endif -->
1195  <PRE>
1196    PATH_INFO = "" | ( "/" path )
1197    path      = segment *( "/" segment )
1198    segment   = *pchar
1199    pchar     = &lt;any CHAR except "/"&gt;
1200  </PRE>
1201  <P>
1202  The PATH_INFO string is the trailing part of the &lt;path&gt; component of
1203  the Script-URI
1204  (see <A HREF="#3.2">section 3.2</A>)
1205  that follows the SCRIPT_NAME
1206  portion of the path.
1207  </P>
1208  <P>
1209  Servers MAY impose their own restrictions and
1210  limitations on what values they will accept for PATH_INFO, and MAY
1211  reject or edit any values they
1212  consider objectionable before passing
1213  them to the script.
1214  </P>
1215  <P>
1216  Servers MUST make this URI component available
1217  to CGI scripts.  The PATH_INFO
1218  value is case-sensitive, and the
1219  server MUST preserve the case of the PATH_INFO element of the URI
1220  when making it available to scripts.
1221  </P>
1222
1223  <H4>
1224   <A NAME="6.1.7">
1225    6.1.7. PATH_TRANSLATED
1226   </A>
1227  </H4>
1228  <P>
1229  PATH_TRANSLATED is derived by taking any path-info component of the
1230  request URI (see
1231  <A HREF="#6.1.6">section 6.1.6</A>), decoding it
1232  (see <A HREF="#3.1">section 3.1</A>), parsing it as a URI in its own
1233  right, and performing any virtual-to-physical
1234  translation appropriate to map it onto the
1235  server's document repository structure.
1236  If the request URI includes no path-info
1237  component, the PATH_TRANSLATED metavariable SHOULD NOT be defined.
1238  </P><!--#if expr="! $GUI" -->
1239  <P></P><!--#endif -->
1240  <PRE>
1241    PATH_TRANSLATED = *CHAR
1242  </PRE>
1243  <P>
1244  For a request such as the following:
1245  </P><!--#if expr="! $GUI" -->
1246  <P></P><!--#endif -->
1247  <PRE>
1248    http://somehost.com/cgi-bin/somescript/this%2eis%2epath%2einfo
1249  </PRE>
1250  <P>
1251  the PATH_INFO component would be decoded, and the result
1252  parsed as though it were a request for the following:
1253  </P><!--#if expr="! $GUI" -->
1254  <P></P><!--#endif -->
1255  <PRE>
1256    http://somehost.com/this.is.the.path.info
1257  </PRE>
1258  <P>
1259  This would then be translated to a
1260  location in the server's document repository,
1261  perhaps a filesystem path something
1262  like this:
1263  </P><!--#if expr="! $GUI" -->
1264  <P></P><!--#endif -->
1265  <PRE>
1266    /usr/local/www/htdocs/this.is.the.path.info
1267  </PRE>
1268  <P>
1269  The result of the translation is the value of PATH_TRANSLATED.
1270  </P>
1271  <P>
1272  The value of PATH_TRANSLATED may or may not map to a valid
1273  repository
1274  location.
1275  Servers MUST preserve the case of the path-info
1276  segment if and only if the underlying
1277  repository
1278  supports case-sensitive
1279  names.  If the
1280  repository
1281  is only case-aware, case-preserving, or case-blind
1282  with regard to
1283  document names,
1284  servers are not required to preserve the
1285  case of the original segment through the translation.
1286  </P>
1287  <P>
1288  The
1289  translation
1290  algorithm the server uses to derive PATH_TRANSLATED is
1291  implementation defined; CGI scripts which use this variable may
1292  suffer limited portability.
1293  </P>
1294  <P>
1295  Servers SHOULD provide this metavariable
1296  to scripts if and only if the request URI includes a
1297  path-info component.
1298  </P>
1299
1300  <H4>
1301   <A NAME="6.1.8">
1302    6.1.8. QUERY_STRING
1303   </A>
1304  </H4>
1305  <P>
1306  A URL-encoded
1307  string; the &lt;query&gt; part of the
1308  Script-URI.
1309  (See
1310  <A HREF="#3.2">section 3.2</A>.)
1311  </P><!--#if expr="! $GUI" -->
1312  <P></P><!--#endif -->
1313  <PRE>
1314    QUERY_STRING = query-string
1315    query-string = *uric
1316  </PRE>
1317  <P>
1318  The URL syntax for a  query
1319  string is described in
1320  section 3 of
1321  RFC 2396
1322  [<A HREF="#[4]">4</A>].
1323  </P>
1324  <P>
1325  Servers MUST supply this value to scripts.
1326  The QUERY_STRING value is case-sensitive.
1327  If the Script-URI does not include a query component,
1328  the QUERY_STRING metavariable MUST be defined as an empty string ("").
1329  </P>
1330
1331  <H4>
1332   <A NAME="6.1.9">
1333    6.1.9. REMOTE_ADDR
1334   </A>
1335  </H4>
1336  <P>
1337  The IP address of the client
1338  sending the request to the server. This
1339  is not necessarily that of the user
1340  agent
1341  (such as if the request came through a proxy).
1342  </P><!--#if expr="! $GUI" -->
1343  <P></P><!--#endif -->
1344  <PRE>
1345    REMOTE_ADDR  = hostnumber
1346    hostnumber   = ipv4-address | ipv6-address
1347  </PRE>
1348  <P>
1349  The definitions of <SAMP>ipv4-address</SAMP> and <SAMP>ipv6-address</SAMP>
1350  are provided in Appendix B of RFC 2373 [<A HREF="#[13]">13</A>].
1351  </P>
1352  <P>
1353  Servers MUST supply this value to scripts.
1354  </P>
1355
1356  <H4>
1357   <A NAME="6.1.10">
1358    6.1.10. REMOTE_HOST
1359   </A>
1360  </H4>
1361  <P>
1362  The fully qualified domain name of the
1363  client sending the request to
1364  the server, if available, otherwise NULL.
1365  (See <A HREF="#6.1.9">section 6.1.9</A>.)
1366  Fully qualified domain names take the form as described in
1367  section 3.5 of RFC 1034 [<A HREF="#[10]">10</A>] and section 2.1 of
1368  RFC 1123 [<A HREF="#[5]">5</A>].  Domain names are not case sensitive.
1369  </P>
1370  <P>
1371  Servers SHOULD provide this information to
1372  scripts.
1373  </P>
1374
1375  <H4>
1376   <A NAME="6.1.11">
1377    6.1.11. REMOTE_IDENT
1378   </A>
1379  </H4>
1380  <P>
1381  The identity information reported about the connection by a
1382  RFC 1413 [<A HREF="#[11]">11</A>] request to the remote agent, if
1383  available. Servers
1384  MAY choose not
1385  to support this feature, or not to request the data
1386  for efficiency reasons.
1387  </P><!--#if expr="! $GUI" -->
1388  <P></P><!--#endif -->
1389  <PRE>
1390    REMOTE_IDENT = *CHAR
1391  </PRE>
1392  <P>
1393  The data returned
1394  may be used for authentication purposes, but the level
1395  of trust reposed in them should be minimal.
1396  </P>
1397  <P>
1398  Servers MAY supply this information to scripts if the
1399  RFC1413 [<A HREF="#[11]">11</A>] lookup is performed.
1400  </P>
1401
1402  <H4>
1403   <A NAME="6.1.12">
1404    6.1.12. REMOTE_USER
1405   </A>
1406  </H4>
1407  <P>
1408  If the request required authentication using the "Basic"
1409  mechanism (<EM>i.e.</EM>, the AUTH_TYPE
1410  metavariable is set
1411  to "Basic"), then the value of the REMOTE_USER
1412  metavariable is set to the
1413  user-ID supplied.  In all other cases
1414  the value of this metavariable
1415  is undefined.
1416  </P><!--#if expr="! $GUI" -->
1417  <P></P><!--#endif -->
1418  <PRE>
1419    REMOTE_USER = *OCTET
1420  </PRE>
1421  <P>
1422  This variable is specific to requests made <EM>via</EM> the
1423  HTTP protocol.
1424  </P>
1425  <P>
1426  Servers SHOULD provide this metavariable
1427  to scripts.
1428  </P>
1429
1430  <H4>
1431   <A NAME="6.1.13">
1432    6.1.13. REQUEST_METHOD
1433   </A>
1434  </H4>
1435  <P>
1436  The REQUEST_METHOD
1437  metavariable
1438  is set to the
1439  method with which the request was made, as described in section
1440  5.1.1 of the HTTP/1.0 specification [<A HREF="#[3]">3</A>] and
1441  section 5.1.1 of the
1442  HTTP/1.1 specification [<A HREF="#[8]">8</A>].
1443  </P><!--#if expr="! $GUI" -->
1444  <P></P><!--#endif -->
1445  <PRE>
1446    REQUEST_METHOD   = http-method
1447    http-method      = "GET" | "HEAD" | "POST" | "PUT" | "DELETE"
1448                       | "OPTIONS" | "TRACE" | extension-method
1449    extension-method = token
1450  </PRE>
1451  <P>
1452  The method is case sensitive.
1453  CGI/1.1 servers MAY choose to process some methods
1454  directly rather than passing them to scripts.
1455  </P>
1456  <P>
1457  This variable is specific to requests made with HTTP.
1458  </P>
1459  <P>
1460  Servers MUST provide this metavariable
1461  to scripts.
1462  </P>
1463
1464  <H4>
1465   <A NAME="6.1.14">
1466    6.1.14. SCRIPT_NAME
1467   </A>
1468  </H4>
1469  <P>
1470  The SCRIPT_NAME
1471  metavariable
1472  is
1473  set to a URL path that could identify the CGI script (rather than the
1474  script's
1475  output). The syntax and semantics are identical to a
1476  decoded HTTP URL 'path' token
1477  (see RFC 2396
1478  [<A HREF="#[4]">4</A>]).
1479  </P><!--#if expr="! $GUI" -->
1480  <P></P><!--#endif -->
1481  <PRE>
1482    SCRIPT_NAME = "" | ( "/" [ path ] )
1483  </PRE>
1484  <P>
1485  The SCRIPT_NAME string is some leading part of the &lt;path&gt; component
1486  of the Script-URI derived in some
1487  implementation defined manner.
1488  No PATH_INFO or QUERY_STRING segments
1489  (see sections <A HREF="#6.1.6">6.1.6</A> and
1490  <A HREF="#6.1.8">6.1.8</A>) are included
1491  in the SCRIPT_NAME value.
1492  </P>
1493  <P>
1494  Servers MUST provide this metavariable
1495  to scripts.
1496  </P>
1497
1498  <H4>
1499   <A NAME="6.1.15">
1500    6.1.15. SERVER_NAME
1501   </A>
1502  </H4>
1503  <P>
1504  The SERVER_NAME
1505  metavariable
1506  is set to the
1507  name  of the
1508  server, as
1509  derived from the &lt;host&gt; part of the
1510  Script-URI
1511  (see <A HREF="#3.2">section 3.2</A>).
1512  </P><!--#if expr="! $GUI" -->
1513  <P></P><!--#endif -->
1514  <PRE>
1515    SERVER_NAME = hostname | hostnumber
1516  </PRE>
1517  <P>
1518  Servers MUST provide this metavariable
1519  to scripts.
1520  </P>
1521
1522  <H4>
1523   <A NAME="6.1.16">
1524    6.1.16. SERVER_PORT
1525   </A>
1526  </H4>
1527  <P>
1528  The SERVER_PORT
1529  metavariable
1530  is set to the
1531  port on which the
1532  request was received, as used in the &lt;port&gt;
1533  part of the Script-URI.
1534  </P><!--#if expr="! $GUI" -->
1535  <P></P><!--#endif -->
1536  <PRE>
1537    SERVER_PORT = 1*digit
1538  </PRE>
1539  <P>
1540  If the &lt;port&gt; portion of the script-URI is blank, the actual
1541  port number upon which the request was received MUST be supplied.
1542  </P>
1543  <P>
1544  Servers MUST provide this metavariable
1545  to scripts.
1546  </P>
1547
1548  <H4>
1549   <A NAME="6.1.17">
1550    6.1.17. SERVER_PROTOCOL
1551   </A>
1552  </H4>
1553  <P>
1554  The SERVER_PROTOCOL
1555  metavariable
1556  is set to
1557  the
1558  name and revision of the information protocol with which
1559  the
1560  request
1561  arrived.  This is not necessarily the same as the protocol version used by
1562  the server in its response to the client.
1563  </P><!--#if expr="! $GUI" -->
1564  <P></P><!--#endif -->
1565  <PRE>
1566    SERVER_PROTOCOL   = HTTP-Version | extension-version
1567                        | extension-token
1568    HTTP-Version      = "HTTP" "/" 1*digit "." 1*digit
1569    extension-version = protocol "/" 1*digit "." 1*digit
1570    protocol          = 1*( alpha | digit | "+" | "-" | "." )
1571    extension-token   = token
1572  </PRE>
1573  <P>
1574  'protocol' is a version of the &lt;scheme&gt; part of the
1575  Script-URI, but is
1576  not identical to it.  For example, the scheme of a request may be
1577  "<SAMP>https</SAMP>" while the protocol remains "<SAMP>http</SAMP>".
1578  The protocol is not case sensitive, but
1579  by convention, 'protocol' is in
1580  upper case.
1581  </P>
1582  <P>
1583  A well-known extension token value is "INCLUDED",
1584  which signals that the current document is being included as part of
1585  a composite document, rather than being the direct target of the
1586  client request.
1587  </P>
1588  <P>
1589  Servers MUST provide this metavariable
1590  to scripts.
1591  </P>
1592
1593  <H4>
1594   <A NAME="6.1.18">
1595    6.1.18. SERVER_SOFTWARE
1596   </A>
1597  </H4>
1598  <P>
1599  The SERVER_SOFTWARE
1600  metavariable
1601  is set to the
1602  name and version of the information server software answering the
1603  request (and running the gateway).
1604  </P><!--#if expr="! $GUI" -->
1605  <P></P><!--#endif -->
1606  <PRE>
1607    SERVER_SOFTWARE = 1*product
1608    product         = token [ "/" product-version ]
1609    product-version = token
1610  </PRE>
1611  <P>
1612  Servers MUST provide this metavariable
1613  to scripts.
1614  </P>
1615
1616  <H3>
1617   <A NAME="6.2">
1618    6.2. Request Message-Bodies
1619   </A>
1620  </H3>
1621  <P>
1622  As there may be a data entity attached to the request, there MUST be
1623  a system defined method for the script to read
1624  these data. Unless
1625  defined otherwise, this will be <EM>via</EM> the 'standard input' file
1626  descriptor.
1627  </P>
1628  <P>
1629  If the CONTENT_LENGTH value (see <A HREF="#6.1.2">section 6.1.2</A>)
1630  is non-NULL, the server MUST supply at least that many bytes to
1631  scripts on the standard input stream.
1632  Scripts are
1633  not obliged to read the data.
1634  Servers MAY signal an EOF condition after CONTENT_LENGTH bytes have been
1635  read, but are
1636  not obligated to do so.  Therefore, scripts
1637  MUST NOT
1638  attempt to read more than CONTENT_LENGTH bytes, even if more data
1639  are available.
1640  </P>
1641  <P>
1642  For non-parsed header (NPH) scripts (see
1643  <A HREF="#7.1">section 7.1</A>
1644  below),
1645  servers SHOULD
1646  attempt to ensure that the data
1647  supplied to the script are precisely
1648  as supplied by the client and unaltered by
1649  the server.
1650  </P>
1651  <P>
1652  <A HREF="#8.1.2">Section 8.1.2</A> describes the requirements of
1653  servers with regard to requests that include
1654  message-bodies.
1655  </P>
1656
1657  <H2>
1658   <A NAME="7.0">
1659    7. Data Output from the CGI Script
1660   </A>
1661  </H2>
1662  <P>
1663  There MUST be a system defined method for the script to send data
1664  back to the server or client; a script MUST always return some data.
1665  Unless defined otherwise, this will be <EM>via</EM> the 'standard
1666  output' file descriptor.
1667  </P>
1668  <P>
1669  There are two forms of output that  scripts can supply to servers: non-parsed
1670  header (NPH) output, and parsed header output.
1671  Servers MUST support parsed header
1672  output and MAY support NPH output.  The method of
1673  distinguishing between the two
1674  types of output (or scripts) is implementation defined.
1675  </P>
1676  <P>
1677  Servers MAY implement a timeout period within which data must be
1678  received from scripts.  If a server implementation defines such
1679  a timeout and receives no data from a script within the timeout
1680  period, the server MAY terminate the script process and SHOULD
1681  abort the client request with
1682  either a
1683  '504 Gateway Timed Out' or a
1684  '500 Internal Server Error' response.
1685  </P>
1686
1687  <H3>
1688   <A NAME="7.1">
1689    7.1. Non-Parsed Header Output
1690   </A>
1691  </H3>
1692  <P>
1693  Scripts using the NPH output form
1694  MUST return a complete HTTP response message, as described
1695  in Section 6 of the HTTP specifications
1696  [<A HREF="#[3]">3</A>,<A HREF="#[8]">8</A>].
1697   NPH scripts
1698  MUST use the SERVER_PROTOCOL variable to determine the appropriate format
1699  for a response.
1700  </P>
1701  <P>
1702  Servers
1703  SHOULD attempt to ensure that the script output is sent
1704  directly to the client, with minimal
1705  internal and no transport-visible
1706  buffering.
1707  </P>
1708
1709  <H3>
1710   <A NAME="7.2">
1711    7.2. Parsed Header Output
1712   </A>
1713  </H3>
1714  <P>
1715  Scripts using the parsed header output form MUST supply
1716  a CGI response message to the server
1717  as follows:
1718  </P><!--#if expr="! $GUI" -->
1719  <P></P><!--#endif -->
1720  <PRE>
1721    CGI-Response   = *optional-field CGI-Field *optional-field NL [ Message-Body ]
1722    optional-field = ( CGI-Field | HTTP-Field )
1723    CGI-Field      = Content-type
1724                   | Location
1725                   | Status
1726                   | extension-header
1727  </PRE>
1728  <P><!-- ##### If HTTP defines x-headers, remove ours except x-cgi- -->
1729  The response comprises a header and a body, separated by a blank line.
1730  The body may be NULL.
1731  The header fields are either CGI header fields to be interpreted by
1732  the server, or HTTP header fields
1733  to be included in the response returned
1734  to the client
1735  if the request method is HTTP. At least one
1736  CGI-Field MUST be
1737  supplied, but no CGI  field name may be used more than once
1738  in a response.
1739  If a body is supplied, then a "<SAMP>Content-type</SAMP>"
1740  header field MUST be
1741  supplied by the script,
1742  otherwise the script MUST send a "<SAMP>Location</SAMP>"
1743  or "<SAMP>Status</SAMP>" header field. If a
1744  <SAMP>Location</SAMP> CGI-Field
1745  is returned, then the script MUST NOT supply
1746  any HTTP-Fields.
1747  </P>
1748  <P>
1749  Each header field in a CGI-Response MUST be specified on a single line;
1750  CGI/1.1 does not support continuation lines.
1751  </P>
1752
1753  <H4>
1754   <A NAME="7.2.1">
1755    7.2.1. CGI header fields
1756   </A>
1757  </H4>
1758  <P>
1759  The CGI header fields have the generic syntax:
1760  </P><!--#if expr="! $GUI" -->
1761  <P></P><!--#endif -->
1762  <PRE>
1763    generic-field  = field-name ":" [ field-value ] NL
1764    field-name     = token
1765    field-value    = *( field-content | LWSP )
1766    field-content  = *( token | tspecial | quoted-string )
1767  </PRE>
1768  <P>
1769  The field-name is not case sensitive; a NULL field value is
1770  equivalent to the header field not being sent.
1771  </P>
1772
1773  <H4>
1774   <A NAME="7.2.1.1">
1775    7.2.1.1. Content-Type
1776   </A>
1777  </H4>
1778  <P>
1779  The Internet Media Type [<A HREF="#[9]">9</A>] of the entity
1780  body, which is to be sent unmodified to the client.
1781  </P><!--#if expr="! $GUI" -->
1782  <P></P><!--#endif -->
1783  <PRE>
1784    Content-Type = "Content-Type" ":" media-type NL
1785  </PRE>
1786  <P>
1787  This is actually an HTTP-Field
1788  rather than a CGI-Field, but
1789  it is listed here because of its importance in the CGI dialogue as
1790  a member of the "one of these is required" set of header
1791  fields.
1792  </P>
1793
1794  <H4>
1795   <A NAME="7.2.1.2">
1796    7.2.1.2. Location
1797   </A>
1798  </H4>
1799  <P>
1800  This is used to specify to the server that the script is returning a
1801  reference to a document rather than an actual document.
1802  </P><!--#if expr="! $GUI" -->
1803  <P></P><!--#endif -->
1804  <PRE>
1805    Location         = "Location" ":"
1806                       ( fragment-URI | rel-URL-abs-path ) NL
1807    fragment-URI     = URI [ # fragmentid ]
1808    URI              = scheme ":" *qchar
1809    fragmentid       = *qchar
1810    rel-URL-abs-path = "/" [ hpath ] [ "?" query-string ]
1811    hpath            = fpsegment *( "/" psegment )
1812    fpsegment        = 1*hchar
1813    psegment         = *hchar
1814    hchar            = alpha | digit | safe | extra
1815                       | ":" | "@" | "& | "="
1816  </PRE>
1817  <P>
1818  The Location
1819  value is either an absolute URI with optional fragment,
1820  as defined in RFC 1630 [<A HREF="#[1]">1</A>], or an absolute path
1821  within the server's URI space (<EM>i.e.</EM>,
1822  omitting the scheme and network-related fields) and optional
1823  query-string. If an absolute URI is returned by the script,
1824  then the
1825  server MUST generate a
1826  '302 redirect' HTTP response
1827  message unless the script has supplied an
1828  explicit Status response header field.
1829  Scripts returning an absolute URI MAY choose to
1830  provide a message-body.  Servers MUST make any appropriate modifications
1831  to the script's output to ensure the response to the user-agent complies
1832  with the response protocol version.
1833  If the Location value is a path, then the server
1834  MUST generate
1835  the response that it would have produced in response to a request
1836  containing the URL
1837  </P><!--#if expr="! $GUI" -->
1838  <P></P><!--#endif -->
1839  <PRE>
1840    scheme "://" SERVER_NAME ":" SERVER_PORT rel-URL-abs-path
1841  </PRE>
1842  <P>
1843  Note: If the request was accompanied by a
1844  message-body
1845  (such as for a POST request), and the script
1846  redirects the request with a Location field, the
1847  message-body
1848  may not be
1849  available to the resource that is the target of the redirect.
1850  </P>
1851
1852  <H4>
1853   <A NAME="7.2.1.3">
1854    7.2.1.3. Status
1855   </A>
1856  </H4>
1857  <P>
1858  The "<SAMP>Status</SAMP>" header field is used to indicate to the server what
1859  status code the server MUST use in the response message.
1860  </P><!--#if expr="! $GUI" -->
1861  <P></P><!--#endif -->
1862  <PRE>
1863    Status        = "Status" ":" digit digit digit SP reason-phrase NL
1864    reason-phrase = *&lt;CHAR, excluding CTLs, NL&gt;
1865  </PRE>
1866  <P>
1867  The valid status codes are listed in section 6.1.1 of the HTTP/1.0
1868  specifications [<A HREF="#[3]">3</A>]. If the SERVER_PROTOCOL is
1869  "HTTP/1.1", then the status codes defined in the HTTP/1.1
1870  specification [<A HREF="#[8]">8</A>] may
1871  be used. If the script does not return a "<SAMP>Status</SAMP>" header
1872  field, then "200 OK" SHOULD be assumed by the server.
1873  </P>
1874  <P>
1875  If a script is being used to handle a particular error or condition
1876  encountered by the server, such as a '404 Not Found' error, the script
1877  SHOULD use the "<SAMP>Status</SAMP>" CGI header field to propagate the error
1878  condition back to the client.  <EM>E.g.</EM>, in the example mentioned it
1879  SHOULD include a "Status:&nbsp;404&nbsp;Not&nbsp;Found" in the
1880  header data returned to the server.
1881  </P>
1882
1883  <H4>
1884   <A NAME="7.2.1.4">
1885    7.2.1.4. Extension header fields
1886   </A>
1887  </H4>
1888  <P>
1889  Scripts MAY include in their CGI response header additional fields
1890  not defined in this or the HTTP specification.
1891  These are called "extension" fields,
1892  and have the syntax of a <SAMP>generic-field</SAMP> as defined in
1893  <A HREF="#7.2.1">section 7.2.1</A>.  The name of an extension field
1894  MUST NOT conflict with a field name defined in this or any other
1895  specification; extension field names SHOULD begin with "X-CGI-"
1896  to ensure uniqueness.
1897  </P>
1898
1899  <H4>
1900   <A NAME="7.2.2">
1901    7.2.2. HTTP header fields
1902   </A>
1903  </H4>
1904  <P>
1905  The script MAY return any other header fields defined by the
1906  specification
1907  for the SERVER_PROTOCOL (HTTP/1.0 [<A HREF="#[3]">3</A>] or HTTP/1.1
1908  [<A HREF="#[8]">8</A>]).
1909  Servers MUST resolve conflicts beteen CGI header
1910  and HTTP header formats or names (see <A HREF="#8.0">section 8</A>).
1911  </P>
1912
1913  <H2>
1914   <A NAME="8.0">
1915    8. Server Implementation
1916   </A>
1917  </H2>
1918  <P>
1919  This section defines the requirements that must be met by HTTP
1920  servers in order to provide a coherent and correct CGI/1.1
1921  environment in which scripts may function.  It is intended
1922  primarily for server implementors, but it is useful for
1923  script authors to be familiar with the information as well.
1924  </P>
1925
1926  <H3>
1927   <A NAME="8.1">
1928    8.1. Requirements for Servers
1929   </A>
1930  </H3>
1931  <P>
1932  In order to be considered CGI/1.1-compliant, a server must meet
1933  certain basic criteria and provide certain minimal functionality.
1934  The details of these requirements are described in the following sections.
1935  </P>
1936
1937  <H3>
1938   <A NAME="8.1.1">
1939    8.1.1. Script-URI
1940   </A>
1941  </H3>
1942  <P>
1943  Servers MUST support the standard mechanism (described below) which
1944  allows
1945  script authors to determine
1946  what URL to use in documents
1947  which reference the script;
1948  specifically, what URL to use in order to
1949  achieve particular settings of the
1950  metavariables. This
1951  mechanism is as follows:
1952  </P>
1953  <P>
1954  The server
1955  MUST translate the header data from the CGI header field syntax to
1956  the HTTP
1957  header field syntax if these differ. For example, the character
1958  sequence for
1959  newline (such as Unix's ASCII NL) used by CGI scripts may not be the
1960  same as that used by HTTP (ASCII CR followed by LF). The server MUST
1961  also resolve any conflicts between header fields returned by the script
1962  and header fields that it would otherwise send itself.
1963  </P>
1964
1965  <H3>
1966   <A NAME="8.1.2">
1967    8.1.2. Request Message-body Handling
1968   </A>
1969  </H3>
1970  <P>
1971  These are the requirements for server handling of message-bodies directed
1972  to CGI/1.1 resources:
1973  </P>
1974  <OL>
1975   <LI>The message-body the server provides to the CGI script MUST
1976    have any transfer encodings removed.
1977   </LI>
1978   <LI>The server MUST derive and provide a value for the CONTENT_LENGTH
1979    metavariable that reflects the length of the message-body after any
1980    transfer decoding.
1981   </LI>
1982   <LI>The server MUST leave intact any content-encodings of the message-body.
1983   </LI>
1984  </OL>
1985
1986  <H3>
1987   <A NAME="8.1.3">
1988    8.1.3. Required Metavariables
1989   </A>
1990  </H3>
1991  <P>
1992  Servers MUST provide scripts with certain information and
1993  metavariables
1994  as described in <A HREF="#8.3">section 8.3</A>.
1995  </P>
1996
1997  <H3>
1998   <A NAME="8.1.4">
1999    8.1.4. Response Compliance
2000   </A>
2001  </H3>
2002  <P>
2003  Servers MUST ensure that responses sent to the user-agent meet all
2004  requirements of the protocol level in effect.  This may involve
2005  modifying, deleting, or augmenting any header
2006  fields and/or message-body supplied by the script.
2007  </P>
2008
2009  <H3>
2010   <A NAME="8.2">
2011    8.2. Recommendations for Servers
2012   </A>
2013  </H3>
2014  <P>
2015  Servers SHOULD provide the "<SAMP>query</SAMP>" component of the script-URI
2016  as command-line arguments to scripts if it does not
2017  contain any unencoded '=' characters and the command-line arguments can
2018  be generated in an unambiguous manner.
2019  (See <A HREF="#5.0">section 5</A>.)
2020  </P>
2021  <P>
2022  Servers SHOULD set the AUTH_TYPE
2023  metavariable to the value of the
2024  '<SAMP>auth-scheme</SAMP>' token of the "<SAMP>Authorization</SAMP>"
2025  field if it was supplied as part of the request header.
2026  (See <A HREF="#6.1.1">section 6.1.1</A>.)
2027  </P>
2028  <P>
2029  Where applicable, servers SHOULD set the current working directory
2030  to the directory in which the script is located before invoking
2031  it.
2032  </P>
2033  <P>
2034  Servers MAY reject with error '404 Not Found'
2035  any requests that would result in
2036  an encoded "/" being decoded into PATH_INFO or SCRIPT_NAME, as this
2037  might represent a loss of information to the script.
2038  </P>
2039  <P>
2040  Although the server and the CGI script need not be consistent in
2041  their handling of URL paths (client URLs and the PATH_INFO data,
2042  respectively), server authors may wish to impose consistency.
2043  So the server implementation SHOULD define its behaviour for the
2044  following cases:
2045  </P>
2046  <OL>
2047   <LI>define any restrictions on allowed characters, in particular
2048    whether ASCII NUL is permitted;
2049   </LI>
2050   <LI>define any restrictions on allowed path segments, in particular
2051    whether non-terminal NULL segments are permitted;
2052   </LI>
2053   <LI>define the behaviour for <SAMP>"."</SAMP> or <SAMP>".."</SAMP> path
2054    segments; <EM>i.e.</EM>, whether they are prohibited, treated as
2055    ordinary path
2056    segments or interpreted in accordance with the relative URL
2057    specification [<A HREF="#[7]">7</A>];
2058   </LI>
2059   <LI>define any limits of the implementation, including limits on path or
2060    search string lengths, and limits on the volume of header data the server
2061    will parse.
2062   </LI><!-- ##### Move the field resolution/translation para below here -->
2063  </OL>
2064  <P>
2065  Servers MAY generate the
2066  Script-URI in
2067  any way from the client URI,
2068  or from any other data (but the behaviour SHOULD be documented).
2069  </P>
2070  <P>
2071  For non-parsed header (NPH) scripts (see
2072  <A HREF="#7.1">section 7.1</A>), servers SHOULD
2073  attempt to ensure that the script input comes directly from the
2074  client, with minimal buffering. For all scripts the data will be
2075  as supplied by the client.
2076  </P>
2077
2078  <H3>
2079   <A NAME="8.3">
2080    8.3. Summary of
2081    MetaVariables
2082   </A>
2083  </H3>
2084  <P>
2085  Servers MUST provide the following
2086  metavariables to
2087  scripts.  See the individual descriptions for exceptions and semantics.
2088  </P><!--#if expr="! $GUI" -->
2089  <P></P><!--#endif -->
2090  <PRE>
2091    CONTENT_LENGTH (section <A HREF="#6.1.2">6.1.2</A>)
2092    CONTENT_TYPE (section <A HREF="#6.1.3">6.1.3</A>)
2093    GATEWAY_INTERFACE (section <A HREF="#6.1.4">6.1.4</A>)
2094    PATH_INFO (section <A HREF="#6.1.6">6.1.6</A>)
2095    QUERY_STRING (section <A HREF="#6.1.8">6.1.8</A>)
2096    REMOTE_ADDR (section <A HREF="#6.1.9">6.1.9</A>)
2097    REQUEST_METHOD (section <A HREF="#6.1.13">6.1.13</A>)
2098    SCRIPT_NAME (section <A HREF="#6.1.14">6.1.14</A>)
2099    SERVER_NAME (section <A HREF="#6.1.15">6.1.15</A>)
2100    SERVER_PORT (section <A HREF="#6.1.16">6.1.16</A>)
2101    SERVER_PROTOCOL (section <A HREF="#6.1.17">6.1.17</A>)
2102    SERVER_SOFTWARE (section <A HREF="#6.1.18">6.1.18</A>)
2103  </PRE>
2104  <P>
2105  Servers SHOULD define the following
2106  metavariables for scripts.
2107  See the individual descriptions for exceptions and semantics.
2108  </P><!--#if expr="! $GUI" -->
2109  <P></P><!--#endif -->
2110  <PRE>
2111    AUTH_TYPE (section <A HREF="#6.1.1">6.1.1</A>)
2112    REMOTE_HOST (section <A HREF="#6.1.10">6.1.10</A>)
2113  </PRE>
2114  <P>
2115  In addition, servers SHOULD provide
2116  metavariables for all fields present
2117  in the HTTP request header, with the exception of those involved with
2118  access control.  Servers MAY at their discretion provide
2119  metavariables
2120  for access control fields.
2121  </P>
2122  <P>
2123  Servers MAY define the following
2124  metavariables.  See the individual
2125  descriptions for exceptions and semantics.
2126  </P><!--#if expr="! $GUI" -->
2127  <P></P><!--#endif -->
2128  <PRE>
2129    PATH_TRANSLATED (section <A HREF="#6.1.7">6.1.7</A>)
2130    REMOTE_IDENT (section <A HREF="#6.1.11">6.1.11</A>)
2131    REMOTE_USER (section <A HREF="#6.1.12">6.1.12</A>)
2132  </PRE>
2133  <P>
2134  Servers MAY
2135  at their discretion define additional implementation-specific
2136  extension metavariables
2137  provided their names do not
2138  conflict with defined header field names.  Implementation-specific
2139  metavariable names SHOULD
2140  be prefixed with "X_" (<EM>e.g.</EM>,
2141  "X_DBA") to avoid the potential for such conflicts.
2142  </P>
2143
2144  <H2>
2145   <A NAME="9.0">
2146    9.
2147    Script Implementation
2148   </A>
2149  </H2>
2150  <P>
2151  This section defines the requirements and recommendations for scripts
2152  that are intended to function in a CGI/1.1 environment.  It is intended
2153  primarily as a reference for script authors, but server implementors
2154  should be familiar with these issues as well.
2155  </P>
2156
2157  <H3>
2158   <A NAME="9.1">
2159    9.1. Requirements for Scripts
2160   </A>
2161  </H3>
2162  <P>
2163  Scripts using the parsed-header method to communicate with servers
2164  MUST supply a response header to the server.
2165  (See <A HREF="#7.0">section 7</A>.)
2166  </P>
2167  <P>
2168  Scripts using the NPH method to communicate with servers MUST
2169  provide complete HTTP responses, and MUST use the value of the
2170  SERVER_PROTOCOL metavariable
2171  to determine the appropriate format.
2172  (See <A HREF="#7.1">section 7.1</A>.)
2173  </P>
2174  <P>
2175  Scripts MUST check the value of the REQUEST_METHOD
2176  metavariable in order
2177  to provide an appropriate response.
2178  (See <A HREF="#6.1.13">section 6.1.13</A>.)
2179  </P>
2180  <P>
2181  Scripts MUST be prepared to handled URL-encoded values in
2182  metavariables.
2183  In addition, they MUST recognise both "+" and "%20" in URL-encoded
2184  quantities as representing the space character.
2185  (See <A HREF="#3.1">section 3.1</A>.)
2186  </P>
2187  <P>
2188  Scripts MUST ignore leading zeros in the major and minor version numbers
2189  in the GATEWAY_INTERFACE
2190  metavariable value. (See
2191  <A HREF="#6.1.4">section 6.1.4</A>.)
2192  </P>
2193  <P>
2194  When processing requests that include a
2195  message-body, scripts
2196  MUST NOT read more than CONTENT_LENGTH bytes from the input stream.
2197  (See sections <A HREF="#6.1.2">6.1.2</A> and <A HREF="#6.2">6.2</A>.)
2198  </P>
2199
2200  <H3>
2201   <A NAME="9.2">
2202    9.2. Recommendations for Scripts
2203   </A>
2204  </H3>
2205  <P>
2206  Servers may interrupt or terminate script execution at any time
2207  and without warning, so scripts SHOULD be prepared to deal with
2208  abnormal termination.
2209  </P>
2210  <P>
2211  Scripts MUST
2212  reject with
2213  error '405 Method Not
2214  Allowed' requests
2215  made using methods that they do not support. If the script does
2216  not intend
2217  processing the PATH_INFO data, then it SHOULD reject the request with
2218  '404 Not
2219  Found' if PATH_INFO is not NULL.
2220  </P>
2221  <P>
2222  If a script is processing the output of a form, it SHOULD
2223  verify that the CONTENT_TYPE
2224  is "<SAMP>application/x-www-form-urlencoded</SAMP>" [<A HREF="#[2]">2</A>]
2225  or whatever other media type is expected.
2226  </P>
2227  <P>
2228  Scripts parsing PATH_INFO,
2229  PATH_TRANSLATED, or SCRIPT_NAME
2230  SHOULD be careful
2231  of void path segments ("<SAMP>//</SAMP>") and special path segments
2232  (<SAMP>"."</SAMP> and
2233  <SAMP>".."</SAMP>). They SHOULD either be removed from the path before
2234  use in OS
2235  system calls, or the request SHOULD be rejected with
2236  '404 Not Found'.
2237  </P>
2238  <P>
2239  As it is impossible for
2240  scripts to determine the client URI that
2241  initiated  a
2242  request without knowledge of the specific server in
2243  use, the script SHOULD NOT return "<SAMP>text/html</SAMP>"
2244  documents containing
2245  relative URL links without including a "<SAMP>&lt;BASE&gt;</SAMP>"
2246  tag in the document.
2247  </P>
2248  <P>
2249  When returning header fields,
2250  scripts SHOULD try to send the CGI
2251  header fields (see section
2252  <A HREF="#7.2">7.2</A>) as soon as possible, and
2253  SHOULD send them
2254  before any HTTP header fields. This may
2255  help reduce the server's memory requirements.
2256  </P>
2257
2258  <H2>
2259   <A NAME="10.0">
2260    10. System Specifications
2261   </A>
2262  </H2>
2263
2264  <H3>
2265   <A NAME="10.1">
2266    10.1. AmigaDOS
2267   </A>
2268  </H3>
2269  <P>
2270  The implementation of the CGI on an AmigaDOS operating system platform
2271  SHOULD use environment variables as the mechanism of providing
2272  request metadata to CGI scripts.
2273  </P>
2274  <DL>
2275   <DT><STRONG>Environment variables</STRONG>
2276   </DT>
2277   <DD>
2278    <P>
2279    These are accessed by the DOS library routine <SAMP>GetVar</SAMP>. The
2280    flags argument SHOULD be 0. Case is ignored, but upper case is
2281    recommended for compatibility with case-sensitive systems.
2282    </P>
2283   </DD>
2284   <DT><STRONG>The current working directory</STRONG>
2285   </DT>
2286   <DD>
2287    <P>
2288    The current working directory for the script is set to the directory
2289    containing the script.
2290    </P>
2291   </DD>
2292   <DT><STRONG>Character set</STRONG>
2293   </DT>
2294   <DD>
2295    <P>
2296    The US-ASCII character set is used for the definition of environment
2297    variable names and header
2298    field names; the newline (NL) sequence is LF;
2299    servers SHOULD also accept CR LF as a newline.
2300    </P>
2301   </DD>
2302  </DL>
2303
2304  <H3>
2305   <A NAME="10.2">
2306    10.2. Unix
2307   </A>
2308  </H3>
2309  <P>
2310  The implementation of the CGI on a UNIX operating system platform
2311  SHOULD use environment variables as the mechanism of providing
2312  request metadata to CGI scripts.
2313  </P>
2314  <P>
2315  For Unix compatible operating systems, the following are defined:
2316  </P>
2317  <DL>
2318   <DT><STRONG>Environment variables</STRONG>
2319   </DT>
2320   <DD>
2321    <P>
2322    These are accessed by the C library routine <SAMP>getenv</SAMP>.
2323    </P>
2324   </DD>
2325   <DT><STRONG>The command line</STRONG>
2326   </DT>
2327   <DD>
2328    <P>
2329    This is accessed using the
2330    <SAMP>argc</SAMP> and <SAMP>argv</SAMP>
2331    arguments to <SAMP>main()</SAMP>. The words have any characters
2332    that
2333    are 'active' in the Bourne shell escaped with a backslash.
2334    If the value of the QUERY_STRING
2335    metavariable
2336    contains an unencoded equals-sign '=', then the command line
2337    SHOULD NOT be used by the script.
2338    </P>
2339   </DD>
2340   <DT><STRONG>The current working directory</STRONG>
2341   </DT>
2342   <DD>
2343    <P>
2344    The current working directory for the script
2345    SHOULD be set to the directory
2346    containing the script.
2347    </P>
2348   </DD>
2349   <DT><STRONG>Character set</STRONG>
2350   </DT>
2351   <DD>
2352    <P>
2353    The US-ASCII character set is used for the definition of environment
2354    variable names and header field names; the newline (NL) sequence is LF;
2355    servers SHOULD also accept CR LF as a newline.
2356    </P>
2357   </DD>
2358  </DL>
2359
2360  <H2>
2361   <A NAME="11.0">
2362    11. Security Considerations
2363   </A>
2364  </H2>
2365
2366  <H3>
2367   <A NAME="11.1">
2368    11.1. Safe Methods
2369   </A>
2370  </H3>
2371  <P>
2372  As discussed in the security considerations of the HTTP
2373  specifications [<A HREF="#[3]">3</A>,<A HREF="#[8]">8</A>], the
2374  convention has been established that the
2375  GET and HEAD methods should be 'safe'; they should cause no
2376  side-effects and only have the significance of resource retrieval.
2377  </P>
2378  <P>
2379  CGI scripts are responsible for enforcing any HTTP security considerations
2380  [<A HREF="#[3]">3</A>,<A HREF="#[8]">8</A>]
2381  with respect to the protocol version level of the request and
2382  any side effects generated by the scripts on behalf of
2383  the server.  Primary
2384  among these
2385  are the considerations of safe and idempotent methods.  Idempotent
2386  requests are those that may be repeated an arbitrary number of times
2387  and produce side effects identical to a single request.
2388  </P>
2389
2390  <H3>
2391   <A NAME="11.2">
2392    11.2. HTTP Header
2393    Fields Containing Sensitive Information
2394   </A>
2395  </H3>
2396  <P>
2397  Some HTTP header fields may carry sensitive information which the server
2398  SHOULD NOT pass on to the script unless explicitly configured to do
2399  so. For example, if the server protects the script using the
2400  "<SAMP>Basic</SAMP>"
2401  authentication scheme, then the client will send an
2402  "<SAMP>Authorization</SAMP>"
2403  header field containing a username and password. If the server, rather
2404  than the script, validates this information then the password SHOULD
2405  NOT be passed on to the script <EM>via</EM> the HTTP_AUTHORIZATION
2406  metavariable
2407  without careful consideration.
2408  This also applies to the
2409  Proxy-Authorization header field and the corresponding
2410  HTTP_PROXY_AUTHORIZATION
2411  metavariable.
2412  </P>
2413
2414  <H3>
2415   <A NAME="11.3">
2416    11.3. Script
2417    Interference with the Server
2418   </A>
2419  </H3>
2420  <P>
2421  The most common implementation of CGI invokes the script as a child
2422  process using the same user and group as the server process. It
2423  SHOULD therefore be ensured that the script cannot interfere with the
2424  server process, its configuration, or documents.
2425  </P>
2426  <P>
2427  If the script is executed by calling a function linked in to the
2428  server software (either at compile-time or run-time) then precautions
2429  SHOULD be taken to protect the core memory of the server, or to
2430  ensure that untrusted code cannot be executed.
2431  </P>
2432
2433  <H3>
2434   <A NAME="11.4">
2435    11.4. Data Length and Buffering Considerations
2436   </A>
2437  </H3>
2438  <P>
2439  This specification places no limits on the length of message-bodies
2440  presented to the script.  Scripts should not assume that statically
2441  allocated buffers of any size are sufficient to contain the entire
2442  submission at one time.  Use of a fixed length buffer without careful
2443  overflow checking may result in an attacker exploiting 'stack-smashing'
2444  or 'stack-overflow' vulnerabilities of the operating system.
2445  Scripts may spool large submissions to disk or other buffering media,
2446  but a rapid succession of large submissions may result in denial of
2447  service conditions.  If the CONTENT_LENGTH of a message-body is larger
2448  than resource considerations allow, scripts should respond with an
2449  error status appropriate for the protocol version; potentially applicable
2450  status codes include '503 Service Unavailable' (HTTP/1.0 and HTTP/1.1),
2451  '413 Request Entity Too Large' (HTTP/1.1), and
2452  '414 Request-URI Too Long' (HTTP/1.1).
2453  </P>
2454
2455  <H3>
2456   <A NAME="11.5">
2457    11.5. Stateless Processing
2458   </A>
2459  </H3>
2460  <P>
2461  The stateless nature of the Web makes each script execution and resource
2462  retrieval independent of all others even when multiple requests constitute a
2463  single conceptual Web transaction.  Because of this, a script should not
2464  make any assumptions about the context of the user-agent submitting a
2465  request.  In particular, scripts should examine data obtained from the client
2466  and verify that they are valid, both in form and content, before allowing
2467  them to be used for sensitive purposes such as input to other
2468  applications, commands, or operating system services.  These uses
2469  include, but are not
2470  limited to: system call arguments, database writes, dynamically evaluated
2471  source code, and input to billing or other secure processes.  It is important
2472  that applications be protected from invalid input regardless of whether
2473  the invalidity is the result of user error, logic error, or malicious action.
2474  </P>
2475  <P>
2476  Authors of scripts involved in multi-request transactions should be
2477  particularly cautios about validating the state information;
2478  undesirable effects may result from the substitution of dangerous
2479  values for portions of the submission which might otherwise be
2480  presumed safe.  Subversion of this type occurs when alterations
2481  are made to data from a prior stage of the transaction that were
2482  not meant to be controlled by the client (<EM>e.g.</EM>, hidden
2483  HTML form elements, cookies, embedded URLs, <EM>etc.</EM>).
2484  </P>
2485
2486  <H2>
2487   <A NAME="12.0">
2488    12. Acknowledgements
2489   </A>
2490  </H2>
2491  <P>
2492  This work is based on a draft published in 1997 by David R. Robinson,
2493  which in turn was based on the original CGI interface that arose out of
2494  discussions on the <EM>www-talk</EM> mailing list. In particular,
2495  Rob McCool, John Franks, Ari Luotonen,
2496  George Phillips and
2497  Tony Sanders deserve special recognition for their efforts in
2498  defining and implementing the early versions of this interface.
2499  </P>
2500  <P>
2501  This document has also greatly benefited from the comments and
2502  suggestions made by  Chris Adie, Dave Kristol,
2503  Mike Meyer, David Morris, Jeremy Madea,
2504  Patrick M<SUP>c</SUP>Manus, Adam Donahue,
2505  Ross Patterson, and Harald Alvestrand.
2506  </P>
2507
2508  <H2>
2509   <A NAME="13.0">
2510    13. References
2511   </A>
2512  </H2>
2513  <DL COMPACT>
2514   <DT><A NAME="[1]">[1]</A>
2515   </DT>
2516   <DD>Berners-Lee, T., 'Universal Resource Identifiers in WWW: A
2517       Unifying Syntax for the Expression of Names and Addresses of
2518       Objects on the Network as used in the World-Wide Web', RFC 1630,
2519       CERN, June 1994.
2520       <P>
2521       </P>
2522   </DD>
2523   <DT><A NAME="[2]">[2]</A>
2524   </DT>
2525   <DD>Berners-Lee, T. and Connolly, D., 'Hypertext Markup Language -
2526        2.0', RFC 1866, MIT/W3C, November 1995.
2527       <P>
2528       </P>
2529   </DD>
2530   <DT><A NAME="[3]">[3]</A>
2531   </DT>
2532   <DD>Berners-Lee, T., Fielding, R. T. and Frystyk, H.,
2533          'Hypertext Transfer Protocol -- HTTP/1.0', RFC 1945, MIT/LCS,
2534          UC Irvine, May 1996.
2535       <P>
2536       </P>
2537   </DD>
2538
2539  <DT><A NAME="[4]">[4]</A>
2540  </DT>
2541  <DD>Berners-Lee, T., Fielding, R., and Masinter, L., Editors,
2542   'Uniform Resource Identifiers (URI): Generic Syntax', RFC 2396,
2543   MIT, U.C. Irvine, Xerox Corporation, August 1996.
2544   <P>
2545   </P>
2546  </DD>
2547
2548  <DT><A NAME="[5]">[5]</A>
2549  </DT>
2550  <DD>Braden, R., Editor, 'Requirements for Internet Hosts --
2551          Application and Support', STD 3, RFC 1123, IETF, October 1989.
2552       <P>
2553       </P>
2554   </DD>
2555   <DT><A NAME="[6]">[6]</A>
2556   </DT>
2557   <DD>Crocker, D.H., 'Standard for the Format of ARPA Internet Text
2558          Messages', STD 11, RFC 822, University of Delaware, August 1982.
2559       <P>
2560       </P>
2561   </DD>
2562  <DT><A NAME="[7]">[7]</A>
2563  </DT>
2564  <DD>Fielding, R., 'Relative Uniform Resource Locators', RFC 1808,
2565          UC Irvine, June 1995.
2566       <P>
2567       </P>
2568   </DD>
2569   <DT><A NAME="[8]">[8]</A>
2570   </DT>
2571   <DD>Fielding, R., Gettys, J., Mogul, J., Frystyk, H. and
2572          Berners-Lee, T., 'Hypertext Transfer Protocol -- HTTP/1.1',
2573          RFC 2068, UC Irvine, DEC,
2574      MIT/LCS, January 1997.
2575       <P>
2576       </P>
2577   </DD>
2578   <DT><A NAME="[9]">[9]</A>
2579   </DT>
2580   <DD>Freed, N. and Borenstein N., 'Multipurpose Internet Mail
2581          Extensions (MIME) Part Two: Media Types', RFC 2046, Innosoft,
2582          First Virtual, November 1996.
2583       <P>
2584       </P>
2585   </DD>
2586   <DT><A NAME="[10]">[10]</A>
2587   </DT>
2588   <DD>Mockapetris, P., 'Domain Names - Concepts and Facilities',
2589          STD 13, RFC 1034, ISI, November 1987.
2590       <P>
2591       </P>
2592   </DD>
2593   <DT><A NAME="[11]">[11]</A>
2594   </DT>
2595   <DD>St. Johns, M., 'Identification Protocol', RFC 1431, US
2596          Department of Defense, February 1993.
2597       <P>
2598       </P>
2599   </DD>
2600   <DT><A NAME="[12]">[12]</A>
2601   </DT>
2602   <DD>'Coded Character Set -- 7-bit American Standard Code for
2603          Information Interchange', ANSI X3.4-1986.
2604       <P>
2605       </P>
2606   </DD>
2607   <DT><A NAME="[13]">[13]</A>
2608   </DT>
2609   <DD>Hinden, R. and Deering, S.,
2610          'IP Version 6 Addressing Architecture', RFC 2373,
2611      Nokia, Cisco Systems,
2612          July 1998.
2613       <P>
2614       </P>
2615   </DD>
2616  </DL>
2617
2618  <H2>
2619   <A NAME="14.0">
2620    14. Authors' Addresses
2621   </A>
2622  </H2>
2623  <ADDRESS>
2624   <P>
2625   Ken A L Coar
2626   <BR>
2627   MeepZor Consulting
2628   <BR>
2629   7824 Mayfaire Crest Lane, Suite 202
2630   <BR>
2631   Raleigh, NC   27615-4875
2632   <BR>
2633   U.S.A.
2634   </P>
2635   <P>
2636   Tel: +1 (919) 254.4237
2637   <BR>
2638   Fax: +1 (919) 254.5250
2639   <BR>
2640   Email:
2641   <A
2642    HREF="mailto:Ken.Coar@Golux.Com"
2643   ><SAMP>Ken.Coar@Golux.Com</SAMP></A>
2644   </P>
2645  </ADDRESS>
2646  <ADDRESS>
2647   <P>
2648   David Robinson
2649   <BR>
2650   E*TRADE UK Ltd
2651   <BR>
2652   Mount Pleasant House
2653   <BR>
2654   2 Mount Pleasant
2655   <BR>
2656   Huntingdon Road
2657   <BR>
2658   Cambridge CB3 0RN
2659   <BR>
2660   UK
2661   </P>
2662   <P>
2663   Tel: +44 (1223) 566926
2664   <BR>
2665   Fax: +44 (1223) 506288
2666   <BR>
2667   Email:
2668   <A
2669    HREF="mailto:drtr@etrade.co.uk"
2670   ><SAMP>drtr@etrade.co.uk</SAMP></A>
2671  </ADDRESS>
2672
2673 </BODY>
2674</HTML>
Note: See TracBrowser for help on using the repository browser.