# man > CGI

---
type: CommandReference
command: CGI
mode: perldoc
section: 3pm
source: perldoc
---

## Quick Reference
- `my $q = CGI->new;` — parse incoming request parameters (GET/POST)
- `my $val = $q->param('name');` — get first value of a parameter
- `my @vals = $q->multi_param('name');` — get all values of a multi-valued parameter
- `my $fh = $q->upload('file_field');` — get filehandle for an uploaded file
- `print $q->header('text/html');` — output HTTP header
- `my $cookie = $q->cookie(-name => 'id', -value => 'xyz', -expires => '+1h');` — create a cookie
- `print $q->header(-type => 'text/html', -cookie => [$c1,$c2]);` — send multiple cookies
- `print $q->redirect('https://example.com');` — redirect the browser

## Name
CGI — Handle Common Gateway Interface requests and responses

## Synopsis
perl
use CGI;

my $q = CGI->new;                     # parse query

# Read parameters
my $val   = $q->param('param_name');
my @vals  = $q->multi_param('form_field');
my $fh    = $q->upload('file_field');

# HTTP header with cookies
my $cookie = $q->cookie(-name => 'riddle', -value => "The Sphynx's Question");
print $q->header(-type => 'image/gif', -expires => '+3d', -cookie => $cookie);

# Redirect
print $q->redirect('https://somewhere.else/in/movie/land');
## Options
### Constructor
- `new()` — parse request (STDIN, filehandle, hashref, string, or another CGI object)
- `new(\&hook, $data, $use_tempfile)` — set upload hook callback

### Parameter Access
- `param($name)` — scalar context: first value; list context (deprecated) returns all values
- `multi_param($name)` — always returns a list of all values
- `param(-name => $name, -value => $val)` — set/replace parameter value(s)
- `append(-name => $name, -values => \@vals)` — append values to a parameter
- `delete(@names)` — remove parameters
- `delete_all()` — clear all parameters
- `param_fetch($name)` — return array reference to parameter list
- `Vars()` — return all parameters as a tied hash (multivalued packed with "\0")
- `url_param($name)` — read parameters from the URL query string (GET parameters only)
- `keywords()` — ISINDEX keywords as list
- `import_names($namespace)` — import parameters into a namespace (risky; avoid main)

### HTTP Header Generation
- `header()` / `header($mime_type)` / `header(-type => …, -status => …, -expires => …, -cookie => …, -charset => …, -nph => …, -attachment => …, -p3p => …)` — generate Content-type and optional HTTP headers
- `redirect($url)` / `redirect(-uri => $url, -status => 301, -nph => 1)` — send redirect header
- `nph($bool)` — toggle NPH mode (for IIS)

### URL and State
- `self_url()` — URL that preserves all current parameters
- `url(-absolute => 1)` / `url(-relative => 1)` / `url(-full => 1)` — script URL in various forms
- `query_string()` — current object state as query string
- `env_query_string()` — raw QUERY_STRING environment variable

### Cookies
- `cookie(-name => $n, -value => $v, -expires => …, -path => …, -domain => …, -secure => 1)` — create a cookie
- `cookie($name)` — retrieve cookie value (supports scalars, arrays, hashes)
- `cookie()` — list all cookie names
- `raw_cookie()` / `raw_cookie($name)` — access raw, unescaped cookies

### File Uploads
- `upload($field_name)` — returns an IO::Handle‑compatible filehandle
- `tmpFileName($handle)` — path to the temporary file
- `uploadInfo($handle)` — returns hashref with upload headers (e.g., Content-Type)
- `upload_hook(\&hook, $data, $use_tempfile)` — set callback for upload progress/custom handling

### Environment & Miscellaneous
- `cgi_error()` — return error string (e.g., “400 Bad request”, “413 POST too large”)
- `save($filehandle)` — write current parameters to filehandle
- `http($header)` — fetch arbitrary HTTP request header (e.g., `Accept-language`)
- `https($header)` — fetch HTTPS environment variable
- `path_info()`, `remote_addr()`, `request_method()`, `user_agent()`, etc.— named accessors for common CGI environment variables

### Pragmas (import flags)
- `-no_undef_params` — exclude undef parameters
- `-utf8` — decode parameters as UTF‑8 text
- `-nph` — produce NPH headers by default
- `-newstyle_urls` / `-oldstyle_urls` — semicolon vs ampersand separators
- `-debug` / `-no_debug` — enable/disable command‑line parameter input

### Security
- `$CGI::POST_MAX` — maximum bytes accepted for POST (0 = unlimited)
- `$CGI::DISABLE_UPLOADS` — disable file upload processing

## Examples
**Basic request handling**
perl
use CGI;
my $q = CGI->new;
print $q->header('text/html');
print "Hello, ", $q->param('user'), "!";
**File upload with error check**
perl
use autodie;
my $fh = $q->upload('resume');
if (!$fh && $q->cgi_error) {
    print $q->header(-status => $q->cgi_error);
    exit;
}
open my $out, '>>', '/var/uploads/resume.pdf';
while (my $bytes = $fh->read(my $buf, 1024)) { print $out $buf; }
**Setting and retrieving cookies**
perl
# Set
my $c = $q->cookie(-name => 'lang', -value => 'en', -expires => '+1M');
print $q->header(-cookie => $c);

# Retrieve
my $lang = $q->cookie('lang');
**Redirect**
perl
print $q->redirect(-uri => 'https://new.example.com', -status => 301);
## See Also
- [CGI::Carp](https://metacpan.org/pod/CGI::Carp) – CGI‑aware error handling
- [CGI::Fast](https://metacpan.org/pod/CGI::Fast) – FastCGI support
- [CGI::Alternatives](https://metacpan.org/pod/CGI::Alternatives) – modern web framework suggestions
- [CGI::Push](https://metacpan.org/pod/CGI::Push) – server push helpers
- [CGI::Cookie](https://metacpan.org/pod/CGI::Cookie) – low‑level cookie parsing

## Exit Codes
Not documented.