When you run a CGI on the server, it has access to various information that the server and Perl interpreter make available to it. This makes up a part of the environment in which the CGI runs. It contains all sorts of information, such as the name of the web server, the name and path of the CGI file, the users browser type and more. All of this information is contained in a special associative array called "%ENV", which you can access at any place in your CGI.
While you can access this data at any time, you should be aware of a few restrictions.
- The server may be set up to not include particular information in the environment.
- Some environment data comes directly from the web browser viewing the site. Not all web browsers send all the possible information in all situations. See the HTTP_REFERRER note below as an example.
You need to access the environment variables in the same manner you access data in other associative arrays:
$data = $ENV{'VARIABLE_NAME'};
Simply replace VARIABLE_NAME with the environment variable that you want to use. Then you can print it out in your output to the browser or a file or do whatever else you want with it.
Here is the list of all the environment variables and what they contain. (NOTE: Some won't contain any info):
- AUTH_TYPE
Ex:
If the server supports user authentication, and the script is protected, this is the protocol-specific authentication method used to validate the user.
- CONTENT_LENGTH
Ex:
The length of the content given by the client.
- CONTENT_TYPE
Ex:
For queries which have attached information, such as HTTP POST and PUT, this is the content type of the data.
- DOCUMENT_NAME
Ex: g_env.shtml
The name of the document being referenced.
- DOCUMENT_ROOT
Ex: /usr/local/www/data
The root directory for the document being referenced.
- GATEWAY_INTERFACE
Ex: CGI/1.1
The revision of the CGI specification to which this server complies. Format: CGI/revision
- HTTP_ACCEPT
Ex: text/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
The MIME types which the client will accept, as given by HTTP headers.
- HTTP_ACCEPT_ENCODING
Ex: gzip
The encoding type which the client will accept, as given by HTTP headers.
- HTTP_ACCEPT_LANGUAGE
Ex: en-us,en;q=0.5
The language which the client will accept, as given by HTTP headers.
- HTTP_CONNECTION
Ex: Keep-Alive
???
- HTTP_FORM
Ex:
??? Not supported by most browsers.
- HTTP_HOST
Ex: jove.prohosting.com
The server's name, as supplied by the browser.
- HTTP_REFERER
Ex:
The URL of the page that refers to the CGI. The HTTP_REFERRER variable must be sent by the web browser, otherwise the server has no way to know how you arrived at the web site. However, the browser will only, usually, send something for this variable when the site is visited by clicking a link in a web page. The browser will not send anything when you type the URL directly into the location field of the browser or if the link that is clicked on is in a HTML page in your local file system. So when testing a CGI that makes use of HTTP_REFERRER, you'll have to put a web page on your site to link to the CGI for testing, otherwise HTTP_REFERRER will be empty.
- HTTP_USER_AGENT
Ex: CCBot/1.0 (+http://www.commoncrawl.org/bot.html)
The browser the client is using to send the request. Format: software/version library/version
- PATH
Ex: /bin:/usr/bin
The system paths to the executables directories.
- PATH_INFO
Ex:
The extra path information, as given by the client. In other words, scripts can be accessed by their virtual pathname, followed by extra information at the end of this path. The extra information is sent as PATH_INFO. This information should be decoded by the server if it comes from a URL before it is passed to the CGI script. (?name=value&key=test for example)
- PATH_TRANSLATED
Ex:
The server provides a translated version of PATH_INFO, which takes the path and does any virtual-to-physical mapping to it.
- QUERY_STRING
Ex: stuff=things
The information which follows the ? in the URL which referenced this script (?name=value&key=test for example).
- REMOTE_ADDR
Ex: 69.12.127.10
The IP address of the remote host making the request.
- REMOTE_HOST
Ex:
The hostname making the request. If the server does not have this information, you can use REMOTE_ADDR to get the name of the remote host machine (Host Name = mjolnir.dns-solutions.net) with this code:
# Resolve REMOTE_HOST into name
$ip_address = $ENV{'REMOTE_ADDR'};
@numbers = split(/\./, $ip_address);
$ip_number = pack("C4", @numbers);
$hostname = (gethostbyaddr($ip_number, 2))[0];
- REMOTE_INDENT
Ex:
If the HTTP server supports RFC 931 identification, then this variable will be set to the remote user name retrieved from the server. Usage of this variable should be limited to logging only.
- REMOTE_PORT
Ex: 58711
The port of the remote user.
- REMOTE_USER
Ex:
If the server supports user authentication, and the script is protected, this is the username they have authenticated as. Not generally known except on a network.
- REQUEST_METHOD
Ex: GET
The method with which the request was made. For HTTP, this is "GET", "HEAD", "POST", etc.
- REQUEST_URI
Ex: /sampieri/freefaq/g_env.shtml
The URL path of the file being requested.
- SCRIPT_FILENAME
Ex: /usr/home/web/s/sampieri/cgi-bin/faq_envir.cgi
The name of the CGI being executed.
- SCRIPT_NAME
Ex: /~sampieri/cgi-bin/faq_envir.cgi
A virtual path to the script being executed, used for self-referencing URLs.
- SERVER_ADMIN
Ex: webmaster@prohosting.com
The e-mail address of the server administrator.
- SERVER_NAME
Ex: jove.prohosting.com
The server's hostname, DNS alias, or IP address as it would appear in self-referencing URLs.
- SERVER_PORT
Ex: 80
The port number to which the request was sent.
- SERVER_PROTOCOL
Ex: INCLUDED
The name and revision of the information protcol this request came in with. Format: protocol/revision
- SERVER_SOFTWARE
Ex: Apache
The name and version of the information server software answering the request (and running the gateway). Format: name/version
- TZ
Ex:
The time zone of the server.