# sum-cgi -- summary of CGI - common gateway interface # $Id$ # Carlos Duarte , 990610/991219 Description ----------- CGI provides a method of generating dynamic web contents. On requesting a CGI, the server runs a given program, passing some information through standard input and/or environ. In its turn, CGI is responsabile for producing valid http data, which is sent to the client. stdin \ => CGI APP => stdout environ / Environ available to the CGI program ------------------------------------ (same may not be available, while others might be empty) (ref: http://hoohoo.ncsa.uiuc.edu/cgi/env.html ) AUTH_TYPE authentification method used to validate a user CONTENT_LENGTH number of bytes CGI is receiving via stdin used by POST methods (see REQUEST_METHOD) CONTENT_TYPE the mime type of the query data ex: "application/x-www-form-urlencoded" DOCUMENT_ROOT document root directory of this website GATEWAY_INTERFACE CGI version that webserver is capable of. ex: "CGI/1.1" HTTP_ACCEPT list of mime types that client accepts (comma separated) ex: "image/*, text/html, text/plain" HTTP_ACCEPT_ENCODING comma separated list of encodings that client can handle (ex: "gzip, compress") HTTP_ACCEPT_LANGUAGE language client talks (ex: "en") HTTP_COOKIE holds cookies sent by client. same format as QUERY_STRING, except name=value are separated by "; " HTTP_FROM email address of whom made the request HTTP_HOST hostname of webserver's machine HTTP_REFERER last URL that client was at, before calling this CGI HTTP_USER_AGENT client's software information ex: "Lynx/2.7 libwww-FM/2.14" PATH_INFO extra information sent on via command line ex -- a 'http://www.foo.bar/my.cgi/x/p/t/o' request, sets this to: "/x/p/t/o" PATH_TRANSLATED translated path on the local filesystem QUERY_STRING data sent to our cgi, via GET request method REMOTE_ADDR IP address of who made the request REMOTE_HOST hostname who issued the request (if available) REMOTE_PORT port (tcp) used to talk to client REMOTE_USER authenticated name of the user REQUEST_METHOD method used on issuing the request, usually "GET" or "POST" REQUEST_URI URL used to request this CGI SCRIPT_FILENAME full pathname, on local filesystem, of this CGI SCRIPT_NAME a valid HREF value to call this CGI again SERVER_ADMIN email of this webserver administrator SERVER_NAME hostname that this webserver's is responding for SERVER_PORT port (tcp) on which webserver is listening, usually 80 SERVER_PROTOCOL name/version of the protocol that carried the request exs: "HTTP/1.0", "HTTP/1.1" SERVER_SIGNATURE text added by webserver SERVER_SOFTWARE info about webserver software ex: "Apache/1.3.6 (Unix)" Generating requests ------------------- A request can be made via command line, or via html. Via command line: http://www.foo.bar/my.cgi?a=b&c=d&e=a+d generates a GET request, and passes "a=b&c=d&e=a+d" on QUERY_STRING (without the quotes) query_string format: VAR=CONTENT&VAR2=CONTENT2&... any non printable char, appears as %XX, where XX is its hexadecimal code space appears as a plus ("+") Via html: requests can be sent via HREFs, which works just like via command line my cgi or submited via FORMs:
this would generate a POST request, and would pass "name=xxxx&email=yyyy" via stdin (without the quotes) xxxx and yyyy were the things typed in the format and coding rules applies as for query_string, which is the MIME type: application/x-www-form-urlencoded. that, is the default "ENCTYPE" is missing on FORM tag. however, to upload files, other MIME type must be used, that only works with POST method: multipart/form-data in this case, a boundary is specified on the CONTENT_TYPE (...; boundary=my_boundary[; ...]), and data received on stdin, will be separated by "--my_boundary\r\n". example, to upload a file: html (the hidden types, are just to see how several name/value pairs are encoded):
[file uploaded is X.TXT] foo.cgi: CONTENT_TYPE = "multipart/form-data; boundary=my_bound" (without the dquotes) stdin: --my_bound\r\n Content-Disposition: form-data; name=foo1\r\n \r\n bar1\r\n --my_bound\r\n Content-Disposition: form-data; name=my_file; filename=X.TXT\r\n \r\n [contents of X.TXT] \r\n --my_bound\r\n Content-Disposition: form-data; name=foo2\r\n \r\n bar2\r\n --my_bound-- Cookies ------- cookies are exchanged between server-client. server -> client, on the HTTP headers (before body) server -> cgi, via HTTP_COOKIE (see above) how cgi get cookies: fetch env var HTTP_COOKIE each name[=value] is separated by "; " each name[=value] (value is optional) is url-encoded how cgi sends cookies: emit on the header, information about the cookie ("Set-Cookie: name=pair; path=/; expires=date_spec") Example on how to make client forget cookies (delete): print "Set-Cookie: c1= ; path=/; expires=Sun, 30-Jun-80 00:00:00 GMT\n" print "Set-Cookie: c2= ; path=/; expires=Sun, 30-Jun-80 00:00:00 GMT\n" ... print "Content-type: text/html\n\n" print "\n" ... NPH --- Non-parsable-headers CGIs. Works like a common CGI, except server expects a full HTTP response, instead just the MIME content. The name of CGI, must have the prefix nph- : nph-xxxx and one possible output (to stdout) would be: HTTP/1.0 200 Okay Content-Type: text/html
test For sending more than on content-type: print "HTTP/1.0 200 Okay\n"; print "Content-Type: multipart/x-mixed-replace;boundary=myboundary\n\n"; print "--myboundary\n"; print "Content-Type: image/gif\n\n"; [gif contents] print "--myboundary\n"; ...