vcs.maemo.org Git - busybox4maemo/blob - docs/cgi/out.html

   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
   6 The script sends its output to stdout. This output can either be a
   7 document generated by the script, or instructions to the server for
   8 retrieving the desired output. <p>
   9 </p><hr>
  10
  11 <h2>Script naming conventions</h2>
  12
  13 Normally, scripts produce output which is interpreted and sent back to
  14 the client. An advantage of this is that the scripts do not need to
  15 send a full HTTP/1.0 header for every request.  <p>
  16 <a name="nph">
  17 Some scripts may want to avoid the extra overhead of the server
  18 parsing their output, and talk directly to the client. In order to
  19 distinguish these scripts from the other scripts, CGI requires that
  20 the script name begins with nph- if a script does not want the server
  21 to parse its header. In this case, it is the script's responsibility
  22 to 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
  28 of text lines, in the same format as an </a><a href="http://www.w3.org/hypertext/WWW/Protocols/HTTP/Object_Headers.html">
  29 HTTP header</a>, terminated by a blank line (a line with only a
  30 linefeed or CR/LF). <p>
  31
  32 Any headers which are not server directives are sent directly back to
  33 the client. Currently, this specification defines three server
  34 directives:</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
  58 line</a> to send to the client. The format is <code>nnn xxxxx</code>,
  59 where <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
  67 Let's say I have a fromgratz to HTML converter. When my converter is
  68 finished with its work, it will output the following on stdout (note
  69 that the lines beginning and ending with --- are just for illustration
  70 and would not be output): <p>
  71
  72 </p><pre>--- start of output ---
  73 Content-type: text/html
  74
  75 --- end of output ---
  76 </pre>
  77
  78 Note the blank line after Content-type. <p>
  79
  80 Now, let's say I have a script which, in certain instances, wants to
  81 return the document <code>/path/doc.txt</code> from this server just
  82 as if the user had actually requested
  83 <code>http://server:port/path/doc.txt</code> to begin with. In this
  84 case, the script would output: </p><p>
  85 </p><pre>--- start of output ---
  86 Location: /path/doc.txt
  87
  88 --- end of output ---
  89 </pre>
  90
  91 The server would then perform the request and send it to the client.
  92 <p>
  93
  94 Let's say that I have a script which wants to reference our gopher
  95 server. 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 ---
  99 Location: gopher://gopher.ncsa.uiuc.edu/
 100
 101 --- end of output ---
 102 </pre>
 103
 104 Finally, I have a script which wants to talk to the client directly.
 105 In 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,
 106 the script would output the following HTTP/1.0 response: <p>
 107
 108 </p><pre>--- start of output ---
 109 HTTP/1.0 200 OK
 110 Server: NCSA/1.0a6
 111 Content-type: text/plain
 112
 113 This 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
 122 interface specification</a> <p>
 123
 124 CGI - 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>