📄 cgi_guide.html
字号:
<HEAD>
<Title>Netprog Guide to CGI Programming</Title>
<LINK rel=stylesheet type="text/css" HREF=../../style/proj.css>
</HEAD>
<BODY BGCOLOR=WHITE MARGINHEIGHT=0 MARGINWIDTH=0 TOPMARGIN=0 LEFTMARGIN=0>
<TABLE bgColor=#8899aa border=0 cellPadding=4 cellSpacing=0 width="100%">
<TR>
<TD class=title>  NetProg 2002 Guide to CGI Programming<BR>
<FONT SIZE=-1>With information about using the web
servers cgi.cs.rpi.edu and cgi2.cs.rpi.edu</FONT>
</TD>
</TR>
<TR BGCOLOR=BLACK>
<TD CLASS=menu>  
</TD></TR>
</TABLE>
<DIV CLASS=page>
<H3>Overview</H3>
<P>This document assumes you already understand the basics of the HTTP
protocol, are familiar with HTML and Unix system programming.</P>
<P>CGI stands for
<FONT SIZE=+1 COLOR=GREEN><B>C</B></FONT>ommon
<FONT SIZE=+1 COLOR=GREEN><B>G</B></FONT>ateway
<FONT SIZE=+1 COLOR=GREEN><B>I</B></FONT>nterface, a standard mechanism
used by many Web servers to support the creation of dynamic documents
by external programs. </P>
<P>There are many issues involved with the creation of CGI programs:</P>
<UL>
<LI><A HREF=#start>How a client (browser) tells the server to start your program.</A>
<LI><A HREF=#format>How the client will format a query.</A>
<LI><A HREF=#query>How the Web server will pass the query on to your CGI program.</A>
<LI><A HREF=#content>How your progam can send content back to the browser.</A>
<LI><A HREF=#security>Security implications.</A>
<LI><A HREF=#cookies>Cookies.</A>
<LI><A HREF=#forms>HTML Forms.</A>
</UL>
<HR>
<A NAME=start>
<H3>How does a browser tell the Web server to start your program?</H3>
</A>
<P>Before the answer, there are a few things that we need to assume
are understood.</P>
<OL>
<LI><P>By <I>Web Server</I> I mean an HTTP server running on a machine
that you have access to. There are many general purpose Web servers
available, including servers from Netscape, Microsoft and a free
server commonly used on Unix machines named Apache. These servers
handle requests for static HTML documents (or images, or whatever
content is stored in files accessable to the server process) in addition to
providing access to CGI programs.</P> </LI>
<LI><P>Before you can start thinking about creating and using a CGI program,
you need to know how to make your files available through the Web
server. On most Unix systems, the Web server will direct HTTP
requests for URLs that start with <CODE>/~yourname</CODE> to a special
place within the home directory for the user whose name is
<CODE><I>yourname</I></CODE>. Typically the special place is a directory named
<CODE>public.html</CODE> or <CODE>public_html</CODE>. If you want a
file (or CGI program, or image, or whatever) to be available through
your Web server, you have to put the file in this special place.</P>
<P>Most Web servers are configured to automatically respond to a request
that maps to a directory name with either:</P>
<UL>
<LI> if there is a file in the requested directory named
<CODE>index.html</CODE> the contents of that file are sent to the
browser.</LI>
<BR><CENTER>-or-</CENTER><BR>
<LI> An HTML rendering of the contents of the directory (a list of
files and subdirectories).</LI>
</UL>
<P>To create a home page for <I>username</I> you create the file
<CODE>~/username/public.html/index.html</CODE>, put some HTML
"stuff" in it and make sure that the file (and the directory
public.html) are readable by anyone.</P>
<PRE>
> cd ~
> mkdir public.html
> emacs public.html/index.html
> chmod go+r public.html public.html/index.html
</PRE>
<P>Now anyone in the world can view this home page by requesting the document
at <CODE>http://yourmachine/~username/</CODE> </P></LI>
</OL>
<P>OK, back to the original question. A browser will send your Web server
an HTTP request (GET or POST) in which the resource name specified
corresponds to your executable CGI program. So if you have a CGI
program in your <CODE>public.html</CODE> directory named
<CODE>mycgi.cgi</CODE> the browser would send a request that asks for
<CODE>/~username/mycgi.cgi</CODE>. Some folks configure their Web
server to only allow requests for CGI programs in the directory
<CODE>/cgi-bin</CODE>. In this case you need to be able to put your
program there, otherwise the Web server will simply send back the
contents of your program (the file itself) rather than running your
program and sending back it's output. </P>
<P>Most servers that are configured to allow users to have CGI programs
in their home directory (really somewhere in
<CODE>~/public.html</CODE>) require that the file name of a CGI
program ends in the suffix <CODE>.cgi</CODE>. The Web server looks for
this suffix and decides whether to run the program in the requested
file, or whether to simply return the contents of the file.</P>
<P>The web server cgi.cs.rpi.edu look for your files in
<CODE>~/public.html</CODE> and require that your filenames end in
<CODE>.cgi</CODE></P>
<P>The web server cgi2.cs.rpi.edu looks for your files in
<CODE>~/public.html</CODE> and requires that CGI programs are in
the directory <CODE>~/public.html/cgi-bin</CODE>.
<HR>
<A NAME=format>
<H3>How does a browser format a query?</H3>
</A>
<P>There are two major ways the query is constructed:
<TABLE>
<TR>
<TD ALIGN=RIGHT VALIGN=TOP> <B>1)  </B></TD>
<TD>
<P>If the query is created by the browser based on an ISINDEX tag
(where the user can enter a single line of text and press Enter to
submit the request), the browser submits a GET request specifying
a resource (filename) that is either :</P>
<UL>
<LI><P>specified in the ISINDEX tag as the ACTION</P>
<LI><P>if no ACTION is specified in the ISINDEX tag the browser will
specify the name of the current document as the resource (the document that
contains the ISINDEX tag).</P>
</UL>
<P>In both cases the browser will append a '?' to the resource name,
followed by the string the user typed in (possibly encoded - see the
next section for details on the encoding).</P>
<P><B>Examples:</B><P>
<P>The following HTML contains an ISINDEX tag with an ACTION property:</P>
<PRE>
<H2>Enter a search string and I'll find what you are looking for</H2>
<ISINDEX ACTION=http://foo.com/search.cgi><BR>
<CENTER>press Enter to submit your query</CENTER>
</PRE>
<P>If the user types in "blahblah" and presses Enter the browser will
connect to the web server on foo.com and submit something like
this:</P>
<PRE>
GET /search.cgi?blahblah HTTP/1.0
</PRE>
<HR>
<P>The following HTML contains an ISINDEX tag with no ACTION
property. The generated request will use the same resource name that
the document itself came from. The document containing this HTML was
retrieved from the URL <CODE>http://foo.org/count</CODE>.</P>
<PRE>
<H2>Enter a string and I'll count the letters for you</H2>
<ISINDEX ><BR>
<CENTER>press Enter to submit your query</CENTER>
</PRE>
<P>If the user types in "abcdef" and presses Enter the browser will
connect to the web server on foo.com and submit something like
this:</P>
<PRE>
GET /count?blahblah HTTP/1.0
</PRE>
<P>In this case the resource <CODE>/count</CODE> seems to refer to both a
document and to a CGI program. This can be accomplished by having a
CGI program that simply returns a document if no query is submitted
(an empty query).</P>
<P><B>Q:</B> I thought you said my CGI program had to be named <CODE>*.cgi</CODE> - this example has a CGI program named <CODE>count</CODE>!</P>
<P><B>A:</B> I said "Most server's that are configured ...", not all
servers. Many CGI programs are named something else.</P>
<HR>
</TD>
</TR>
<TR>
<TD ALIGN=RIGHT VALIGN=TOP> <B>2)  </B></TD>
<TD>
<P>If the query is constructed based on the content of an HTML form, the
form itself specifies whether the request will be a GET or a POST.
GET is usually used only for small requests, this is because the
mechanism used by the web server to send the query from a GET request
to the CGI program has size limitations (more on this later).</P>
<P>If a GET method is specified in the HTML form, the browser creates a
query string based on the values the user typed in the form fields and
appends it to the resource name just like we saw with an ISINDEX tag.</P>
<P>If a POST method is used, the browser creates a query string based on
the values the user typed in the form fields and sends this string
(which may be large) as the content part of an HTTP POST query.</P>
<P>The query string itself is more complicated than with an ISINDEX based
query since there may be many fields in the FORM. Each field in an
HTML form has a name which is specified in the form itself (whoever
created the form has to specify a name for each field in the
form). Each field also has a value that the user can change by typing
in a new value or by clicking on checkboxes or radio buttons or
whatever. Once the user presses on the SUBMIT button, the browser
constructs a query string that contains a sequence of
<CODE>name=value</CODE> strings seperated by the '<CODE>&</CODE>'
character. A few issues arise:</P>
<UL>
<LI><P>Since the '<CODE>=</CODE>' character seperates the name of a field
from the user specified value, the '<CODE>=</CODE>' obviously can't be
part of the name or part of the value. We can control the name (if we
create the form), but we can't control the value the user types in.</P>
<LI><P>Ditto for the '<CODE>&</CODE>' character.
</P>
<LI><P>If the query is submitted as part of a GET request, we can't have
any spaces in the query or it will confuse the web server (the web
server will think it has reached the end of the resource in the HTTP
GET request).</P>
</UL>
<P>The above issues are handled by having the browser <I>encode</I> the query
in a way that avoids the problems. This is what happens:</P>
<UL>
<LI><P> All spaces are replaced by the '<CODE>+</CODE>' character. </P>
<LI><P> If the character '<CODE>&</CODE>' is part of any field value it
is replaced with the string "<CODE>%26</CODE>". This string is used
because the ASCII '<CODE>&</CODE>' character has hexadecimal value 26.</P>
<LI><P> If '<CODE>=</CODE>' is part of anything, it is replaced by
"<CODE>%3D</CODE>" (the ASCII hex code again).</P>
<LI><P> Just about any non-alphanumeric character is replaced by it's
ASCII hex equivalent in the same manner.</P>
</UL>
<P>The encoded string is now sent to the web server, which will pass this
mess on to your CGI program. You CGI program will have to undo all
this encoding!</P>
<P class=in1><B>NOTE:</B> The encoding described above is done by default, you can
override this encoding by specifying an alternative encoding type in
the form itself. To do this you set a value for the ENCTYPE attribute
of a FORM tag. As far as I known the only other encoding supported is
the type (this is a MIME type) <CODE>multipart/form-data</CODE>. This
results in the browser sending you the form field names and values
unencoded, although wrapped in a MIME multipart document. The only use I've
seen for this is when an entire file is sent from the browser to the server
as can happen with a INPUT field of type FILE. See the getfile CGI program
and HTML form for an example of how to do this.</P>
<P><B>Examples:</B></P>
<P>The following HTML form contains 2 fields, one named fname that we
hope the user will use to submit his first name, and a field named
lname for his last name.</P>
<PRE>
<FORM METHOD=GET ACTION=http://www.foo.com/register.cgi>
First Name: <INPUT TYPE=TEXT NAME=fname><BR>
Last Name: <INPUT TYPE=TEXT NAME=lname><BR>
<INPUT TYPE=SUBMIT VALUE="press to submit">
</FORM>
</PRE>
<P>If the user types "dave or joe" as the first name and enters "lastname=foo"
as the last name (remember that users can and will enter anything!),
the browser will connect to the web server on www.foo.com and submit
something like this:</P>
<PRE>
GET /register.cgi?fname=dave+or+joe&lname=lastname%3Dfoo HTTP/1.0
</PRE>
<P><HR>
<P>The following HTML form contains the same 2 fields, but the method
specified in the form is POST.</P>
<PRE>
<FORM METHOD=POST ACTION=http://www.foo.com/register.cgi>
First Name: <INPUT TYPE=TEXT NAME=fname><BR>
Last Name: <INPUT TYPE=TEXT NAME=lname><BR>
<INPUT TYPE=SUBMIT VALUE="press to submit">
</FORM>
</PRE>
<P>If the user types "John" as the first name and enters "Doe a Deer" as the
last name the browser will connect to the web server on www.foo.com
and submit something like this: </P>
<PRE>
GET /register.cgi HTTP/1.0
⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -