aboutsummaryrefslogtreecommitdiff
path: root/docs/cgi
diff options
context:
space:
mode:
authorDenis Vlasenko <vda.linux@googlemail.com>2007-02-11 14:52:07 +0000
committerDenis Vlasenko <vda.linux@googlemail.com>2007-02-11 14:52:07 +0000
commit136f42f503cb3e9588e62332d043e92b7475ec4e (patch)
tree81c556d1a136112be07bbd2c19293e65fad03cdd /docs/cgi
parentad67a3925c78e7c9f8e61248f640c5cc7a5cf186 (diff)
downloadbusybox-w32-136f42f503cb3e9588e62332d043e92b7475ec4e.tar.gz
busybox-w32-136f42f503cb3e9588e62332d043e92b7475ec4e.tar.bz2
busybox-w32-136f42f503cb3e9588e62332d043e92b7475ec4e.zip
Add CGI docs
Diffstat (limited to 'docs/cgi')
-rw-r--r--docs/cgi/cl.html46
-rw-r--r--docs/cgi/env.html149
-rw-r--r--docs/cgi/in.html33
-rw-r--r--docs/cgi/interface.html29
-rw-r--r--docs/cgi/out.html126
5 files changed, 383 insertions, 0 deletions
diff --git a/docs/cgi/cl.html b/docs/cgi/cl.html
new file mode 100644
index 000000000..5779d623e
--- /dev/null
+++ b/docs/cgi/cl.html
@@ -0,0 +1,46 @@
1<html><head><title>CGI Command line options</title></head><body><h1><img alt="" src="cl_files/CGIlogo.gif"> CGI Command line options</h1>
2<hr> <p>
3
4</p><h2>Specification</h2>
5
6The command line is only used in the case of an ISINDEX query. It is
7not used in the case of an HTML form or any as yet undefined query
8type. The server should search the query information (the <code>QUERY_STRING</code> environment variable) for a non-encoded
9= character to determine if the command line is to be used, if it
10finds one, the command line is not to be used. This trusts the clients
11to encode the = sign in ISINDEX queries, a practice which was
12considered safe at the time of the design of this specification. <p>
13
14For example, use the <a href="http://hoohoo.ncsa.uiuc.edu/cgi-bin/finger">finger script</a> and the ISINDEX interface to look up "httpd". You will see that the script will call itself with <code>/cgi-bin/finger?httpd</code> and will actually execute "finger httpd" on the command line and output the results to you.
15</p><p>
16If the server does find a "=" in the <code>QUERY_STRING</code>,
17then the command line will not be used, and no decoding will be
18performed. The query then remains intact for processing by an
19appropriate FORM submission decoder.
20Again, as an example, use <a href="http://hoohoo.ncsa.uiuc.edu/cgi-bin/finger?httpd=name">this hyperlink</a> to submit <code>"httpd=name"</code> to the finger script. Since this <code>QUERY_STRING</code>
21contained an unencoded "=", nothing was decoded, the script didn't know
22it was being submitted a valid query, and just gave you the default
23finger form.
24</p><p>
25If the server finds that it cannot send the string due to internal
26limitations (such as exec() or /bin/sh command line restrictions) the
27server should include NO command line information and provide the
28non-decoded query information in the environment
29variable <a href="http://hoohoo.ncsa.uiuc.edu/cgi/env.html#query"><code>QUERY_STRING</code></a>. </p><p>
30</p><hr>
31<h2>Examples</h2>
32
33Examples of the command line usage are much better <a href="http://hoohoo.ncsa.uiuc.edu/cgi/examples.html">demonstrated</a> than explained. For these
34examples, pay close attention to the script output which says what
35argc and argv are. <p>
36
37</p><hr>
38
39<a href="http://hoohoo.ncsa.uiuc.edu/cgi/interface.html"><img alt="[Back]" src="cl_files/back.gif">Return to the
40interface specification</a> <p>
41
42CGI - Common Gateway Interface
43</p><address><a href="http://hoohoo.ncsa.uiuc.edu/cgi/mailtocgi.html">cgi@ncsa.uiuc.edu</a></address>
44
45
46</body></html> \ No newline at end of file
diff --git a/docs/cgi/env.html b/docs/cgi/env.html
new file mode 100644
index 000000000..961671aaa
--- /dev/null
+++ b/docs/cgi/env.html
@@ -0,0 +1,149 @@
1<html><head><title>CGI Environment Variables</title></head><body><h1><img alt="" src="env_files/CGIlogo.gif"> CGI Environment Variables</h1>
2<hr>
3
4<p>
5
6In order to pass data about the information request from the server to
7the script, the server uses command line arguments as well as
8environment variables. These environment variables are set when the
9server executes the gateway program. </p><p>
10
11</p><hr>
12<h2>Specification</h2>
13
14 <p>
15The following environment variables are not request-specific and are
16set for all requests: </p><p>
17
18</p><ul>
19<li> <code>SERVER_SOFTWARE</code> <p>
20
21 The name and version of the information server software answering
22 the request (and running the gateway). Format: name/version </p><p>
23
24</p></li><li> <code>SERVER_NAME</code> <p>
25 The server's hostname, DNS alias, or IP address as it would appear
26 in self-referencing URLs. </p><p>
27
28</p></li><li> <code>GATEWAY_INTERFACE</code> <p>
29 The revision of the CGI specification to which this server
30 complies. Format: CGI/revision</p><p>
31
32</p></li></ul>
33
34<hr>
35
36The following environment variables are specific to the request being
37fulfilled by the gateway program: <p>
38
39</p><ul>
40<li> <a name="protocol"><code>SERVER_PROTOCOL</code></a> <p>
41 The name and revision of the information protcol this request came
42 in with. Format: protocol/revision </p><p>
43
44</p></li><li> <code>SERVER_PORT</code> <p>
45 The port number to which the request was sent. </p><p>
46
47</p></li><li> <code>REQUEST_METHOD</code> <p>
48 The method with which the request was made. For HTTP, this is
49 "GET", "HEAD", "POST", etc. </p><p>
50
51</p></li><li> <code>PATH_INFO</code> <p>
52 The extra path information, as given by the client. In other
53 words, scripts can be accessed by their virtual pathname, followed
54 by extra information at the end of this path. The extra
55 information is sent as PATH_INFO. This information should be
56 decoded by the server if it comes from a URL before it is passed
57 to the CGI script.</p><p>
58
59</p></li><li> <code>PATH_TRANSLATED</code> <p>
60 The server provides a translated version of PATH_INFO, which takes
61 the path and does any virtual-to-physical mapping to it. </p><p>
62
63</p></li><li> <code>SCRIPT_NAME</code> <p>
64 A virtual path to the script being executed, used for
65 self-referencing URLs. </p><p>
66
67</p></li><li> <a name="query"><code>QUERY_STRING</code></a> <p>
68 The information which follows the ? in the <a href="http://www.ncsa.uiuc.edu/demoweb/url-primer.html">URL</a>
69 which referenced this script. This is the query information. It
70 should not be decoded in any fashion. This variable should always
71 be set when there is query information, regardless of <a href="http://hoohoo.ncsa.uiuc.edu/cgi/cl.html">command line decoding</a>. </p><p>
72
73</p></li><li> <code>REMOTE_HOST</code> <p>
74 The hostname making the request. If the server does not have this
75 information, it should set REMOTE_ADDR and leave this unset.</p><p>
76
77</p></li><li> <code>REMOTE_ADDR</code> <p>
78 The IP address of the remote host making the request. </p><p>
79
80</p></li><li> <code>AUTH_TYPE</code> <p>
81 If the server supports user authentication, and the script is
82 protects, this is the protocol-specific authentication method used
83 to validate the user. </p><p>
84
85</p></li><li> <code>REMOTE_USER</code> <p>
86 If the server supports user authentication, and the script is
87 protected, this is the username they have authenticated as. </p><p>
88</p></li><li> <code>REMOTE_IDENT</code> <p>
89 If the HTTP server supports RFC 931 identification, then this
90 variable will be set to the remote user name retrieved from the
91 server. Usage of this variable should be limited to logging only.
92 </p><p>
93
94</p></li><li> <a name="ct"><code>CONTENT_TYPE</code></a> <p>
95 For queries which have attached information, such as HTTP POST and
96 PUT, this is the content type of the data. </p><p>
97
98</p></li><li> <a name="cl"><code>CONTENT_LENGTH</code></a> <p>
99 The length of the said content as given by the client. </p><p>
100
101</p></li></ul>
102
103
104<a name="headers"><hr></a>
105
106In addition to these, the header lines received from the client, if
107any, are placed into the environment with the prefix HTTP_ followed by
108the header name. Any - characters in the header name are changed to _
109characters. The server may exclude any headers which it has already
110processed, such as Authorization, Content-type, and Content-length. If
111necessary, the server may choose to exclude any or all of these
112headers if including them would exceed any system environment
113limits. <p>
114
115An example of this is the HTTP_ACCEPT variable which was defined in
116CGI/1.0. Another example is the header User-Agent.</p><p>
117
118</p><ul>
119<li> <code>HTTP_ACCEPT</code> <p>
120 The MIME types which the client will accept, as given by HTTP
121 headers. Other protocols may need to get this information from
122 elsewhere. Each item in this list should be separated by commas as
123 per the HTTP spec. </p><p>
124
125 Format: type/subtype, type/subtype </p><p>
126
127
128</p></li><li> <code>HTTP_USER_AGENT</code><p>
129
130 The browser the client is using to send the request. General
131format: <code>software/version library/version</code>.</p><p>
132
133</p></li></ul>
134
135<hr>
136<h2>Examples</h2>
137
138Examples of the setting of environment variables are really much better
139<a href="http://hoohoo.ncsa.uiuc.edu/cgi/examples.html">demonstrated</a> than explained. <p>
140
141</p><hr>
142
143<a href="http://hoohoo.ncsa.uiuc.edu/cgi/interface.html"><img alt="[Back]" src="env_files/back.gif">Return to the
144interface specification</a> <p>
145
146CGI - Common Gateway Interface
147</p><address><a href="http://hoohoo.ncsa.uiuc.edu/cgi/mailtocgi.html">cgi@ncsa.uiuc.edu</a></address>
148
149</body></html> \ No newline at end of file
diff --git a/docs/cgi/in.html b/docs/cgi/in.html
new file mode 100644
index 000000000..679306aaa
--- /dev/null
+++ b/docs/cgi/in.html
@@ -0,0 +1,33 @@
1<html><head><title>CGI Script input</title></head><body><h1><img alt="" src="in_files/CGIlogo.gif"> CGI Script Input</h1>
2<hr>
3
4<h2>Specification</h2>
5
6For requests which have information attached after the header, such as
7HTTP POST or PUT, the information will be sent to the script on stdin.
8<p>
9
10The server will send <a href="http://hoohoo.ncsa.uiuc.edu/cgi/env.html#cl">CONTENT_LENGTH</a> bytes on
11this file descriptor. Remember that it will give the <a href="http://hoohoo.ncsa.uiuc.edu/cgi/env.html#ct">CONTENT_TYPE</a> of the data as well. The server is
12in no way obligated to send end-of-file after the script reads
13<code>CONTENT_LENGTH</code> bytes. </p><p>
14</p><hr>
15<h2>Example</h2>
16
17Let's take a form with METHOD="POST" as an example. Let's say the form
18results are 7 bytes encoded, and look like <code>a=b&amp;b=c</code>.
19<p>
20
21In this case, the server will set CONTENT_LENGTH to 7 and CONTENT_TYPE
22to application/x-www-form-urlencoded. The first byte on the script's
23standard input will be "a", followed by the rest of the encoded string.</p><p>
24
25</p><hr>
26
27<a href="http://hoohoo.ncsa.uiuc.edu/cgi/interface.html"><img alt="[Back]" src="in_files/back.gif">Return to the
28interface specification</a> <p>
29
30CGI - Common Gateway Interface
31</p><address><a href="http://hoohoo.ncsa.uiuc.edu/cgi/mailtocgi.html">cgi@ncsa.uiuc.edu</a></address>
32
33</body></html> \ No newline at end of file
diff --git a/docs/cgi/interface.html b/docs/cgi/interface.html
new file mode 100644
index 000000000..33f02881b
--- /dev/null
+++ b/docs/cgi/interface.html
@@ -0,0 +1,29 @@
1<html><head><title>The Common Gateway Interface Specification
2[http://hoohoo.ncsa.uiuc.edu/cgi/interface.html]
3</title></head><body><h1><img alt="" src="interface_files/CGIlogo.gif"> The CGI Specification</h1>
4
5<hr>
6
7This is the specification for CGI version 1.1, or CGI/1.1. Further
8revisions of this protocol are guaranteed to be backward compatible.
9<p>
10
11The server and the CGI script communicate in four major ways. Each of
12the following is a hotlink to graphic detail.</p><p>
13
14</p><ul>
15<li> <a href="env.html">Environment variables</a>
16</li><li> <a href="cl.html">The command line</a>
17</li><li> <a href="in.html">Standard input</a>
18</li><li> <a href="out.html">Standard output</a>
19</li></ul>
20<hr>
21
22
23<a href="http://hoohoo.ncsa.uiuc.edu/cgi/overview.html"><img alt="[Back]" src="interface_files/back.gif">Return to the overview</a> <p>
24
25
26
27CGI - Common Gateway Interface
28</p><address><a href="http://hoohoo.ncsa.uiuc.edu/cgi/mailtocgi.html">cgi@ncsa.uiuc.edu</a></address>
29</body></html> \ No newline at end of file
diff --git a/docs/cgi/out.html b/docs/cgi/out.html
new file mode 100644
index 000000000..2203ee5a0
--- /dev/null
+++ b/docs/cgi/out.html
@@ -0,0 +1,126 @@
1<html><head><title>CGI Script output</title></head><body><h1><img alt="" src="out_files/CGIlogo.gif"> CGI Script Output</h1>
2<hr>
3
4<h2>Script output</h2>
5
6The script sends its output to stdout. This output can either be a
7document generated by the script, or instructions to the server for
8retrieving the desired output. <p>
9</p><hr>
10
11<h2>Script naming conventions</h2>
12
13Normally, scripts produce output which is interpreted and sent back to
14the client. An advantage of this is that the scripts do not need to
15send a full HTTP/1.0 header for every request. <p>
16<a name="nph">
17Some scripts may want to avoid the extra overhead of the server
18parsing their output, and talk directly to the client. In order to
19distinguish these scripts from the other scripts, CGI requires that
20the script name begins with nph- if a script does not want the server
21to parse its header. In this case, it is the script's responsibility
22to return a valid HTTP/1.0 (or HTTP/0.9) response to the client. </a></p><p>
23
24</p><hr>
25<h2><a name="nph">Parsed headers</a></h2>
26
27<a name="nph">The output of scripts begins with a small header. This header consists
28of text lines, in the same format as an </a><a href="http://www.w3.org/hypertext/WWW/Protocols/HTTP/Object_Headers.html">
29HTTP header</a>, terminated by a blank line (a line with only a
30linefeed or CR/LF). <p>
31
32Any headers which are not server directives are sent directly back to
33the client. Currently, this specification defines three server
34directives:</p><p>
35
36</p><ul>
37<li> <code>Content-type</code> <p>
38
39 This is the MIME type of the document you are returning. </p><p>
40
41</p></li><li> <code>Location</code> <p>
42
43 This is used to specify to the server that you are returning a
44 reference to a document rather than an actual document. </p><p>
45
46 If the argument to this is a URL, the server will issue a redirect
47 to the client. </p><p>
48
49 If the argument to this is a virtual path, the server will
50 retrieve the document specified as if the client had requested
51 that document originally. ? directives will work in here, but #
52 directives must be redirected back to the client.</p><p>
53
54
55</p></li><li> <a name="status"><code>Status</code></a><p>
56
57 This is used to give the server an HTTP/1.0 <a href="http://www.w3.org/hypertext/WWW/Protocols/HTTP/HTRESP.html">status
58line</a> to send to the client. The format is <code>nnn xxxxx</code>,
59where <code>nnn</code> is the 3-digit status code, and
60<code>xxxxx</code> is the reason string, such as "Forbidden".</p><p>
61
62</p></li></ul>
63
64<hr>
65<h2>Examples</h2>
66
67Let's say I have a fromgratz to HTML converter. When my converter is
68finished with its work, it will output the following on stdout (note
69that the lines beginning and ending with --- are just for illustration
70and would not be output): <p>
71
72</p><pre>--- start of output ---
73Content-type: text/html
74
75--- end of output ---
76</pre>
77
78Note the blank line after Content-type. <p>
79
80Now, let's say I have a script which, in certain instances, wants to
81return the document <code>/path/doc.txt</code> from this server just
82as if the user had actually requested
83<code>http://server:port/path/doc.txt</code> to begin with. In this
84case, the script would output: </p><p>
85</p><pre>--- start of output ---
86Location: /path/doc.txt
87
88--- end of output ---
89</pre>
90
91The server would then perform the request and send it to the client.
92<p>
93
94Let's say that I have a script which wants to reference our gopher
95server. In this case, if the script wanted to refer the user to
96<code>gopher://gopher.ncsa.uiuc.edu/</code>, it would output: </p><p>
97
98</p><pre>--- start of output ---
99Location: gopher://gopher.ncsa.uiuc.edu/
100
101--- end of output ---
102</pre>
103
104Finally, I have a script which wants to talk to the client directly.
105In this case, if the script is referenced with <a href="http://hoohoo.ncsa.uiuc.edu/cgi/env.html#protocol"><code>SERVER_PROTOCOL</code></a> of HTTP/1.0,
106the script would output the following HTTP/1.0 response: <p>
107
108</p><pre>--- start of output ---
109HTTP/1.0 200 OK
110Server: NCSA/1.0a6
111Content-type: text/plain
112
113This is a plaintext document generated on the fly just for you.
114
115--- end of output ---
116</pre>
117
118
119<hr>
120
121<a href="http://hoohoo.ncsa.uiuc.edu/cgi/interface.html"><img alt="[Back]" src="out_files/back.gif">Return to the
122interface specification</a> <p>
123
124CGI - Common Gateway Interface
125</p><address><a href="http://hoohoo.ncsa.uiuc.edu/cgi/mailtocgi.html">cgi@ncsa.uiuc.edu</a></address>
126</body></html> \ No newline at end of file
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-03-17 00:41:27 +0000