CGI - Handle Common Gateway Interface requests & responses
#SYNOPSIS use CGI; my $q = CGI->new; # Process an HTTP request
values = $q->param('form_field'); $fh = $q->upload('file_field'); $riddle = $query->cookie('riddle_name'); %answers = $query->cookie('answers'); # Prepare various HTTP responses print $q->header(); print $q->header('application/json');$cookie1 = $q->cookie(-name=>'riddle_name', -value=>"The Sphynx's Question");$cookie2 = $q->cookie(-name=>'answers', -value=>\%answers); print $q->header( -type => 'image/gif', -expires => '+3d', -cookie => <$cookie1,$cookie2> ); print $q->redirect('http://somewhere.else/in/movie/land');#DESCRIPTIONCGI.pm is a stable, complete và mature solution for processing & preparing HTTP requests and responses. Major features including processing khung submissions, tệp tin uploads, reading & writing cookies, query string generation and manipulation, and processing and preparing HTTP headers. Some HTML generation utilities are included as well.
Bạn đang xem: Perl
CGI.pm performs very well in in a vanilla CGI.pm environment và also comes with built-in support for mod_perl và mod_perl2 as well as Fast
CGI.
It has the benefit of having developed và refined over 10 years with đầu vào from dozens of contributors & being deployed on thousands of websites. CGI.pm has been included in the Perl distribution since Perl 5.4, & has become a de-facto standard.
#PROGRAMMING STYLE
There are two styles of programming with CGI.pm, an object-oriented style và a function-oriented style. In the object-oriented style you create one or more CGI objects and then use object methods khổng lồ create the various elements of the page. Each CGI object starts out with the danh sách of named parameters that were passed khổng lồ your CGI script by the server. You can modify the objects, save them to a tệp tin or database and recreate them. Because each object corresponds to the "state" of the CGI script, & because each object's parameter menu is independent of the others, this allows you to lớn save the state of the script và restore it later.
For example, using the object oriented style, here is how you create a simple "Hello World" HTML page:
#!/usr/local/bin/perl -wuse CGI; # load CGI routines$q = CGI->new; # create new CGI objectprint $q->header, # create the HTTP header $q->start_html('hello world'), # start the HTML $q->h1('hello world'), # level 1 header $q->end_html; # over the HTMLIn the function-oriented style, there is one default CGI object that you rarely deal with directly. Instead you just call functions to retrieve CGI parameters, create HTML tags, manage cookies, và so on. This provides you with a cleaner programming interface, but limits you khổng lồ using one CGI object at a time. The following example prints the same page, but uses the function-oriented interface. The main differences are that we now need lớn import a phối of functions into our name space (usually the "standard" functions), và we don't need lớn create the CGI object.
#!/usr/local/bin/perluse CGI qw/:standard/; # load standard CGI routinesprint header, # create the HTTP header start_html('hello world'), # start the HTML h1('hello world'), # cấp độ 1 header end_html; # over the HTMLThe examples in this document mainly use the object-oriented style. See HOW khổng lồ IMPORT FUNCTIONS for important information on function-oriented programming in CGI.pm
#CALLING CGI.PM ROUTINES
Most CGI.pm routines accept several arguments, sometimes as many as đôi mươi optional ones! to simplify this interface, all routines use a named argument calling style that looks like this:
print $q->header(-type=>'image/gif',-expires=>'+3d');Each argument name is preceded by a dash. Neither case nor order matters in the argument list. -type, -Type, and -TYPE are all acceptable. In fact, only the first argument needs lớn begin with a dash. If a dash is present in the first argument, CGI.pm assumes dashes for the subsequent ones.
Several routines are commonly called with just one argument. In the case of these routines you can provide the single argument without an argument name. Header() happens to be one of these routines. In this case, the single argument is the document type.
print $q->header('text/html');Other such routines are documented below.
Sometimes named arguments expect a scalar, sometimes a reference to an array, and sometimes a reference to lớn a hash. Often, you can pass any type of argument và the routine will vày whatever is most appropriate. For example, the param() routine is used khổng lồ set a CGI parameter to a single or a multi-valued value. The two cases are shown below:
$q->param(-name=>'veggie',-value=>'tomato');$q->param(-name=>'veggie',-value=><'tomato','tomahto','potato','potahto'>);A large number of routines in CGI.pm actually aren't specifically defined in the module, but are generated automatically as needed. These are the "HTML shortcuts," routines that generate HTML tags for use in dynamically-generated pages. HTML tags have both attributes (the attribute="value" pairs within the tag itself) và contents (the part between the opening và closing pairs.) lớn distinguish between attributes & contents, CGI.pm uses the convention of passing HTML attributes as a hash reference as the first argument, and the contents, if any, as any subsequent arguments. It works out lượt thích this:
Code Generated HTML---- --------------h1() h1('some','contents'); some contentsh1(-align=>left); h1(-align=>left,'contents'); contents
HTML tags are described in more detail later.
Many newcomers to CGI.pm are puzzled by the difference between the calling conventions for the HTML shortcuts, which require curly braces around the HTML tag attributes, and the calling conventions for other routines, which manage to lớn generate attributes without the curly brackets. Don't be confused. As a convenience the curly braces are optional in all but the HTML shortcuts. If you like, you can use curly braces when calling any routine that takes named arguments. For example:
print $q->header( -type=>'image/gif',-expires=>'+3d' );If you use the -w switch, you will be warned that some CGI.pm argument names conflict with built-in Perl functions. The most frequent of these is the -values argument, used khổng lồ create multi-valued menus, radio button clusters và the like. Khổng lồ get around this warning, you have several choices:
Use another name for the argument, if one is available. For example, -value is an alias for -values.
Change the capitalization, e.g. -Values
Put quotes around the argument name, e.g. '-values'
Many routines will vì chưng something useful with a named argument that it doesn't recognize. For example, you can produce non-standard HTTP header fields by providing them as named arguments:
print $q->header(-type => 'text/html', -cost => 'Three smackers', -annoyance_level => 'high', -complaints_to => 'bit bucket');This will produce the following nonstandard HTTP header:
HTTP/1.0 200 OKCost: Three smackers
Annoyance-level: high
Complaints-to: bit bucket
Content-type: text/html
Notice the way that underscores are translated automatically into hyphens. HTML-generating routines perform a different type of translation.
This feature allows you lớn keep up with the rapidly changing HTTP and HTML "standards".
#CREATING A NEW QUERY OBJECT (OBJECT-ORIENTED STYLE):
$query = CGI->new;This will parse the đầu vào (from POST, GET and DELETE methods) & store it into a perl5 object called $query.
Any filehandles from tệp tin uploads will have their position reset to lớn the beginning of the file.
#CREATING A NEW QUERY OBJECT FROM AN input FILE
$query = CGI->new(INPUTFILE);If you provide a tệp tin handle khổng lồ the new() method, it will read parameters from the file (or STDIN, or whatever). The file can be in any of the forms describing below under debugging (i.e. A series of newline delimited TAG=VALUE pairs will work). Conveniently, this type of tệp tin is created by the save() method (see below). Multiple records can be saved và restored.
Perl purists will be pleased to know that this syntax accepts references to tệp tin handles, or even references to filehandle globs, which is the "official" way lớn pass a filehandle:
$query = CGI->new(*STDIN);You can also initialize the CGI object with a File
Handle or IO::File object.
If you are using the function-oriented interface and want lớn initialize CGI state from a file handle, the way to vày this is with restore_parameters(). This will (re)initialize the default CGI object from the indicated tệp tin handle.
open (IN,"test.in") || die;restore_parameters(IN);close IN;You can also initialize the query object from a hash reference:
$query = CGI->new( 'dinosaur'=>'barney', 'song'=>'I love you', 'friends'=>
$query = CGI->new('dinosaur=barney&color=purple');or from a previously existing CGI object (currently this clones the parameter list, but none of the other object-specific fields, such as autoescaping):
$old_query = CGI->new;$new_query = CGI->new($old_query);To create an empty query, initialize it from an empty string or hash:
$empty_query = CGI->new(""); -or-$empty_query = CGI->new();
#FETCHING A các mục OF từ khoá FROM THE QUERY:
BSD | Linux | Cisco |Cisco Exam
  | CGI Programming with Perl |  |
3.3. CGI Output
Every CGI script must print a header line, which theserver uses to build the full HTTP headers of its response. If your
CGI script produces invalid headers or no headers, the web serverwill generate a valid response for the client -- generally a500 Internal hệ thống Error message.
Your CGI has the option of displaying full or partial headers. Bydefault, CGI scripts should return only partial headers.
3.3.1. Partial Headers
CGI scripts must output one of the following threeheaders:
A Content-type header specifying the truyền thông type ofthe nội dung that will follow
A Location header specifying a URL to redirectthe client to
A Status header with a status that does notrequire additional data, such as 204 No Response
Let"s đánh giá each of these options.
3.3.1.1. Outputting documents
The most commonresponse for CGI scripts is lớn return HTML. A script must indicate tothe hệ thống the truyền thông type of content it is returning prior tooutputting any content. This is why all of the CGI scripts you haveseen in the previous examples contained the following line:
print "Content-type: text/html ";You can send other HTTP headers from a CGI script, but this headerfield is the minimum necessary in order to output đầu ra a document. HTMLdocuments are by no means the only khung of truyền thông media type that may beoutputted by CGI scripts. By specifying a different media type, youcan output any type of document that you can imagine. For example,Example 3-4 later in this chapter shows how toreturn a dynamic image.
The two newlines at the end theContent-type header tell the web hệ thống thatthis is the last header line và that subsequent lines are part ofthe toàn thân of the message. This correlates lớn the extra CRLF that wediscussed in the last chapter, which separates HTTP headers from thecontent toàn thân (see the upcoming sidebar, the sidebar "Line Endings").
Line EndingsMany operating systemsuse different combinationsof line feeds and carriage returns lớn represent the end of a line oftext. Unix systems use a line feed; Macintosh systems use a carriagereturn; và Microsoft systems use both acarriage return & a line feed, often abbreviated asCRLF.HTTP headers require a CRLF aswell -- each header line must kết thúc with a carriage return và aline feed.
In Perl (on Unix), a line feed is represented as" ", and a carriage return isrepresented as " ". Thus, you maywonder why our previous examples have included this:
print "Content-type: text/html ";and not this:
print "Content-type: text/html
";The second format would work, but only if your script runs on
Unix. Because Perl both began on Unix and has become a cross-platformlanguage, printing "
" in a script will alwaysoutput the operating system"s default line ending.
There is a simple solution. CGI requires that the website servertranslate your operating system"s conventional line ending intoa CRLF for you. Thus for the sake of portability, it is always bestpractice to lớn print a simple line feed(" "): Perl will output the operatingsystem"s mặc định line ending, and the web hệ thống willautomatically convert this lớn the CRLF required by HTTP.
3.3.1.2. Forwarding khổng lồ another URL
Sometimes, it"s not necessary to lớn build an HTMLdocument with your CGI script. In fact, unless the output đầu ra varies fromone visit to another, it is a good idea khổng lồ create a simple, static
HTML page (in addition to the CGIscript), and forward the user lớn that page by using theLocation header. Why? Interface changes are farmore common than program xúc tích và ngắn gọn changes, and it is much easier toreformat an HTML page than khổng lồ make changes khổng lồ a CGI script. Plus, ifyou have multiple CGI scripts that return the same message, thenhaving them all forward khổng lồ a common document reduces the number ofresources you need khổng lồ maintain. Finally, you get better performance.Perl is fast, but your web hệ thống will always be faster. It"s agood idea to lớn take advantage of any opportunity you have lớn shift workfrom your CGI scripts to lớn your website server.
Xem thêm: Đi seoul ăn gì - ăn gì ở đường phố seoul
To forward a user khổng lồ another URL, simply print theLocation header with the URL khổng lồ the newlocation:
print "Location: static_response.html ";The URL may be absolute or relative. An absolute URL or arelative URL with a relative path is sent back to the browser, whichthen creates another request for the new URL. A relative URL with afull path produces an internal redirect. Aninternal redirect is handled by the web server without talking lớn thebrowser. It gets the contents of the new resource as if it hadreceived a new request, but it then returns the nội dung for the newresource as if it is the output of your CGI script. This avoids anetwork response andrequest; the only difference lớn users is a faster response. The URLdisplayed by their browser does not change for internal redirects; itcontinues to show the URL of the original CGI script. See Figure 3-4 for a visual display of hệ thống redirection.
Figure 3-4. Hệ thống redirection
When redirecting to lớn absolute URLs, you may include aContent-type header & content body for thesake of older browsers, which may not forward automatically. Modernbrowsers will immediately fetch the new URL without displaying thiscontent.
3.3.1.3. Specifying status codes
The Status header isdifferent than the other headers because it does not map directly toan HTTP header, although it is associated with the status line. Thisfield is used only to exchange information between the CGI script andthe website server. It specifies the status code the server should include inthe status line of the request. This field is optional: if you vị notprint it, the web server will automatically add astatus of 200 OK toyour output đầu ra if you print a Content-type header,and a status of 302 Found if you print aLocation header.
If you bởi vì print a status code, you are not bound khổng lồ use the statuscode"s associated message, but you should not try to use astatus code for something other than for which it was intended. Forexample, if your CGI script must connect to a database in order togenerate its output, you might return 503 Database
Unavailable if the database has no freeconnections. The standard error message for503 messages is Service
Unavailable, so our database message is anappropriately similar use of this status code.
Whenever you return an error status code, you should also return aContent-type header và amessage toàn thân describing the reason forthe error in human terms. Some browsers provide their own messages tousers when they receive status codes indicating an error, but most donot. So unless you provide a message, many users will get an emptypage or a message telling them "The document contains nodata." If you don"t want lớn admit khổng lồ having a problem,you can always fall back to the ever-popular slogan, "Thesystem is currently unavailable while we perform routinemaintenance."
Here is the code khổng lồ report our database error:
print 503 Database Unavailable Error Sorry, the database is currently not available. Please try again later.END_OF_HTMLBelow is a short mô tả tìm kiếm of the common status headers along withwhen (and whether) to lớn use them in your CGI scripts:
200 OK200 is by far the most common status code returned by website servers; itindicates that the request was understood, it was processedsuccessfully, và a response is included in the content. As wediscussed earlier, the web hệ thống automatically adds this header whenyou print the required Content-type header, sothe only time you need to lớn print this status yourself is to outputcomplete nph- headers, which we discuss in thenext section.
204 No Response204 indicates that the request was okay, it was processedsuccessfully, but no response is provided. When a browser receivesthis status code, it does nothing. It simply continues khổng lồ displaywhatever page it was displaying before the request. A 200 responsewithout a nội dung body, on the other hand, may produce a"Document contains no data" error in the user"sbrowser. Website users generally expect feedback, but there are someinstances when this response (or lack of response) makes sense. Oneexample is a situation when you need client code such as Java
Scriptor Java to lớn report something lớn the web server without updating thecurrent page.
301 indicates that the URL of the requested resourcehas changed. All 300-level responses must contain aLocation header field specifying a new URL for theresource. If the browser receives a 301 response to lớn a
GET request, it shouldautomatically fetch the resource from the new location. If thebrowser receives a 301 response khổng lồ a POST request, however, the browser shouldconfirm with the user before redirecting the POST request. Not allbrowsers bởi vì this, và many even change the request method of the newrequest to lớn GET.
Responses with this status code may include a message for the user incase the browser does not handle redirection automatically. Becausethis status code indicates a permanent move, a proxy or a browserthat has a cached copy of this response will simply use it in thefuture instead of reconfirming the change with the website server.
302 Found302 responses function just lượt thích 301 responses, except that the moveis temporary, so browsers should directall future requests to lớn the original URL. This is the status code thatis returned to lớn browsers when your script prints aLocation header (except for full paths, see
Section 3.3.1.2, "Forwarding to lớn another URL" earlier). As with 301 statuscodes, browsers should check with the user before forwarding a POSTrequest khổng lồ another URL. Because the 302 status has become so popular,and because so many browsers have been guilty of silently changing
POST requests lớn GET requests during the redirect, HTTP/1.1 more orless gave up on trying khổng lồ get compliance on this status code anddefines two new status codes: 303 See Other and307 Temporary Redirect.
303 is new for HTTP/1.1. It indicates that the resource hastemporarily moved & that it should be obtained from the new URL viaa GET request, even if the original request method was POST. Thisstatus code allows the web hệ thống (and the CGI script developer) toexplicitly request the incorrect behavior that 302 responses causedin most browsers.
307 Temporary Redirect307 is new for HTTP/1.1. It also indicates a temporary redirection.However, HTTP/1.1 browsers that tư vấn this status codemust prompt the user if they receive this statuscode in response lớn a POST request & must notautomatically change the request method khổng lồ GET. This isthe same behavior required for 302 status codes, but browsers thatimplement this code should actually bởi the right thing.
Thus 302, 303, & 307 all indicate the same thing except when therequest was a POST. In that case, the browser should fetch the new
URL with a GET request for 303, confirm with the user và then fetchthe new URL with a POST request for 307, & do either of those for302.
400 is a general error indicating that the browser sent an invalid request dueto bad syntax. Examples include an invalid Hostheader field or a request with nội dung but without aContent-type header. You should not have toreturn a 400 status because the web vps should recognize theseproblems và reply with this error status code for you instead ofcalling your CGI script.
401 Unauthorized401 indicates that the requested resource is in a protected realm.When browsers receive this response, they should ask the user for alogin and password andresend the original request with this additional information. If thebrowser again receives a 401 status code, then the login wasdeclined. The browser generally notifies the user và allows the userto reenter the login information. 401 responses should include aWWW-Authenticate header field indicating the name of theprotected realm.
The web hệ thống handles authentication for you (althoughmod_perl lets you dig into it if you wish)before invoking your CGI scripts. Therefore, you should not returnthis status code from CGI scripts; use 403Forbidden instead.
403 Forbidden403 indicates that the client is not allowed khổng lồ access the requestedresource for some reason other than needing a valid HTTP login.Remember reading in Chapter 1, "Getting Started ", that
CGI scripts must have the correctpermissions phối up in order khổng lồ run? Your browser will receive a 403status if you attempt khổng lồ run CGI scripts that do not have the correctexecute permissions.
You might return this status code for certain protected CGI scriptsif the user fails khổng lồ meet some criteria such as having a particular
IP address, a particular browser cookie, etc.
Undoubtedly, you have run across this status code. It"s theonline equivalent of a disconnected phone number. 404 indicates thatthe web server can"t find the resource you asked for. Eitheryou misentered a URL or you followed a liên kết that is old andno longer accurate.
You might use this status code in CGI scripts if the user passesextra path information that is invalid.
405 Not Allowed405 indicates that the resource requested does not support therequest method used. Some CGI scripts are written to support only
POST requests or only GET requests. This status would be anappropriate response if the wrong request method is received; inpractice, this status code is not often used. 405 replies mustinclude an Allow header containing a các mục ofvalid request methods for the resource.
When a transaction takes a long time, the website browser usually givesup before the website server. Otherwise, the server will return a 408status when it has grown tired of waiting. You should not return thisstatus from CGI scripts. Use 504 Gateway Timed
Out instead.
As you begin writing CGI scripts, you will become far too familiarwith this status. It indicates that something happened on the serverthat caused the transaction to lớn fail. This almost always means a CGIscript did something wrong. What could a CGI script vì wrong you ask?
Lots: syntax errors, runtime errors, or invalid output đầu ra all mightgenerate this response. We"ll discuss strategies for debuggingunruly CGI scripts in Chapter 15, "Debugging CGI Applications".
503 indicates that the web server is unable lớn respond to the requestdue to lớn a high volume of traffic. These responses may include aRetry-After header with the date & time thatthe browser should wait until before retrying. Generally website serversmanage this themselves, but you might issue this status if your CGIscript recognizes that another resource (such as a database) requiredby the script has too much traffic.
504 Gateway Timed Out504 indicates that some gateway along the request cycle timed outwhile waiting for another resource. This gateway could be your CGIscript. If your CGI script implements a time-out handler when callinganother resource, such as a database or another internet server, thenit should return a 504 response.
We danh sách these status codes here lớn becomplete, but keep in mind that you vì chưng not have lớn print your ownstatus code, even for errors. Although sending a status code toreport an error might be the most appropriate action according khổng lồ the
HTTP protocol, you may prefer to simply redirect users lớn a help pageor return a summary of the error as normal output đầu ra (with a 200OK status).
