granicus.if.org Git - apache/blob - docs/manual/howto/cgi.html.en

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
   4         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   5               This file is generated from xml source: DO NOT EDIT
   6         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   7       -->
   8 <title>Apache Tutorial: Dynamic Content with CGI - Apache HTTP Server</title>
   9 <link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
  10 <link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
  11 <link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link rel="stylesheet" type="text/css" href="../style/css/prettify.css" />
  12 <script src="../style/scripts/prettify.js" type="text/javascript">
  13 </script>
  14
  15 <link href="../images/favicon.ico" rel="shortcut icon" /></head>
  16 <body id="manual-page"><div id="page-header">
  17 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
  18 <p class="apache">Apache HTTP Server Version 2.5</p>
  19 <img alt="" src="../images/feather.gif" /></div>
  20 <div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div>
  21 <div id="path">
  22 <a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs/">Documentation</a> &gt; <a href="../">Version 2.5</a> &gt; <a href="./">How-To / Tutorials</a></div><div id="page-content"><div id="preamble"><h1>Apache Tutorial: Dynamic Content with CGI</h1>
  23 <div class="toplang">
  24 <p><span>Available Languages: </span><a href="../en/howto/cgi.html" title="English">&nbsp;en&nbsp;</a> |
  25 <a href="../fr/howto/cgi.html" hreflang="fr" rel="alternate" title="Français">&nbsp;fr&nbsp;</a> |
  26 <a href="../ja/howto/cgi.html" hreflang="ja" rel="alternate" title="Japanese">&nbsp;ja&nbsp;</a> |
  27 <a href="../ko/howto/cgi.html" hreflang="ko" rel="alternate" title="Korean">&nbsp;ko&nbsp;</a></p>
  28 </div>
  29 </div>
  30 <div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#intro">Introduction</a></li>
  31 <li><img alt="" src="../images/down.gif" /> <a href="#configuring">Configuring Apache to permit CGI</a></li>
  32 <li><img alt="" src="../images/down.gif" /> <a href="#writing">Writing a CGI program</a></li>
  33 <li><img alt="" src="../images/down.gif" /> <a href="#troubleshoot">But it's still not working!</a></li>
  34 <li><img alt="" src="../images/down.gif" /> <a href="#behindscenes">What's going on behind the scenes?</a></li>
  35 <li><img alt="" src="../images/down.gif" /> <a href="#libraries">CGI modules/libraries</a></li>
  36 <li><img alt="" src="../images/down.gif" /> <a href="#moreinfo">For more information</a></li>
  37 </ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
  38 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  39 <div class="section">
  40 <h2><a name="intro" id="intro">Introduction</a></h2>
  41
  42
  43     <table class="related"><tr><th>Related Modules</th><th>Related Directives</th></tr><tr><td><ul><li><code class="module"><a href="../mod/mod_alias.html">mod_alias</a></code></li><li><code class="module"><a href="../mod/mod_cgi.html">mod_cgi</a></code></li></ul></td><td><ul><li><code class="directive"><a href="../mod/mod_mime.html#addhandler">AddHandler</a></code></li><li><code class="directive"><a href="../mod/core.html#options">Options</a></code></li><li><code class="directive"><a href="../mod/mod_alias.html#scriptalias">ScriptAlias</a></code></li></ul></td></tr></table>
  44
  45     <p>The CGI (Common Gateway Interface) defines a way for a web
  46     server to interact with external content-generating programs,
  47     which are often referred to as CGI programs or CGI scripts. It
  48     is the simplest, and most common, way to put dynamic content on
  49     your web site. This document will be an introduction to setting
  50     up CGI on your Apache web server, and getting started writing
  51     CGI programs.</p>
  52   </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  53 <div class="section">
  54 <h2><a name="configuring" id="configuring">Configuring Apache to permit CGI</a></h2>
  55
  56
  57     <p>In order to get your CGI programs to work properly, you'll
  58     need to have Apache configured to permit CGI execution. There
  59     are several ways to do this.</p>
  60
  61     <div class="warning">Note: If Apache has been built with shared module
  62     support you need to ensure that the module is loaded; in your
  63     <code>httpd.conf</code> you need to make sure the
  64     <code class="directive"><a href="../mod/mod_so.html#loadmodule">LoadModule</a></code>
  65     directive has not been commented out.  A correctly configured directive
  66     may look like this:
  67
  68     <pre class="prettyprint lang-config">
  69       LoadModule cgi_module modules/mod_cgi.so
  70     </pre>
  71 </div>
  72
  73     <h3><a name="scriptalias" id="scriptalias">ScriptAlias</a></h3>
  74
  75
  76       <p>The
  77       <code class="directive"><a href="../mod/mod_alias.html#scriptalias">ScriptAlias</a></code>
  78
  79       directive tells Apache that a particular directory is set
  80       aside for CGI programs. Apache will assume that every file in
  81       this directory is a CGI program, and will attempt to execute
  82       it, when that particular resource is requested by a
  83       client.</p>
  84
  85       <p>The <code class="directive"><a href="../mod/mod_alias.html#scriptalias">ScriptAlias</a></code>
  86       directive looks like:</p>
  87
  88       <pre class="prettyprint lang-config">
  89         ScriptAlias /cgi-bin/ /usr/local/apache2/cgi-bin/
  90       </pre>
  91
  92
  93       <p>The example shown is from your default <code>httpd.conf</code>
  94       configuration file, if you installed Apache in the default
  95       location. The <code class="directive"><a href="../mod/mod_alias.html#scriptalias">ScriptAlias</a></code>
  96       directive is much like the <code class="directive"><a href="../mod/mod_alias.html#alias">Alias</a></code> directive, which defines a URL prefix that
  97       is to mapped to a particular directory. <code class="directive">Alias</code>
  98       and <code class="directive">ScriptAlias</code> are usually used for
  99       directories that are outside of the <code class="directive"><a href="../mod/core.html#documentroot">DocumentRoot</a></code> directory. The difference between
 100       <code class="directive">Alias</code> and <code class="directive">ScriptAlias</code>
 101       is that <code class="directive">ScriptAlias</code> has the added meaning
 102       that everything under that URL prefix will be considered a CGI
 103       program. So, the example above tells Apache that any request for a
 104       resource beginning with <code>/cgi-bin/</code> should be served from
 105       the directory  <code>/usr/local/apache2/cgi-bin/</code>, and should be
 106       treated as a CGI program.</p>
 107
 108       <p>For example, if the URL
 109       <code>http://www.example.com/cgi-bin/test.pl</code>
 110       is requested, Apache will attempt to execute the file
 111       <code>/usr/local/apache2/cgi-bin/test.pl</code>
 112       and return the output. Of course, the file will have to
 113       exist, and be executable, and return output in a particular
 114       way, or Apache will return an error message.</p>
 115
 116
 117     <h3><a name="nonscriptalias" id="nonscriptalias">CGI outside of ScriptAlias directories</a></h3>
 118
 119
 120       <p>CGI programs are often restricted to <code class="directive"><a href="../mod/mod_alias.html#scriptalias">ScriptAlias</a></code>'ed directories for security reasons.
 121       In this way, administrators can tightly control who is allowed to
 122       use CGI programs. However, if the proper security precautions are
 123       taken, there is no reason why CGI programs cannot be run from
 124       arbitrary directories. For example, you may wish to let users
 125       have web content in their home directories with the
 126       <code class="directive"><a href="../mod/mod_userdir.html#userdir">UserDir</a></code> directive.
 127       If they want to have their own CGI programs, but don't have access to
 128       the main <code>cgi-bin</code> directory, they will need to be able to
 129       run CGI programs elsewhere.</p>
 130
 131       <p>There are two steps to allowing CGI execution in an arbitrary
 132       directory.  First, the <code>cgi-script</code> handler must be
 133       activated using the <code class="directive"><a href="../mod/mod_mime.html#addhandler">AddHandler</a></code> or <code class="directive"><a href="../mod/core.html#sethandler">SetHandler</a></code> directive.  Second,
 134       <code>ExecCGI</code> must be specified in the <code class="directive"><a href="../mod/core.html#options">Options</a></code> directive.</p>
 135
 136
 137     <h3><a name="options" id="options">Explicitly using Options to permit CGI execution</a></h3>
 138
 139
 140       <p>You could explicitly use the <code class="directive"><a href="../mod/core.html#options">Options</a></code> directive, inside your main server configuration
 141       file, to specify that CGI execution was permitted in a particular
 142       directory:</p>
 143
 144       <pre class="prettyprint lang-config">
 145 &lt;Directory /usr/local/apache2/htdocs/somedir&gt;
 146     Options +ExecCGI
 147 &lt;/Directory&gt;
 148       </pre>
 149
 150
 151       <p>The above directive tells Apache to permit the execution
 152       of CGI files. You will also need to tell the server what
 153       files are CGI files. The following <code class="directive"><a href="../mod/mod_mime.html#addhandler">AddHandler</a></code> directive tells the server to treat all
 154       files with the <code>cgi</code> or <code>pl</code> extension as CGI
 155       programs:</p>
 156
 157       <pre class="prettyprint lang-config">
 158         AddHandler cgi-script .cgi .pl
 159       </pre>
 160
 161
 162
 163     <h3><a name="htaccess" id="htaccess">.htaccess files</a></h3>
 164
 165
 166       <p>The <a href="htaccess.html"><code>.htaccess</code> tutorial</a>
 167       shows how to activate CGI programs if you do not have
 168       access to <code>httpd.conf</code>.</p>
 169
 170
 171     <h3><a name="userdir" id="userdir">User Directories</a></h3>
 172
 173
 174       <p>To allow CGI program execution for any file ending in
 175       <code>.cgi</code> in users' directories, you can use the
 176       following configuration.</p>
 177
 178       <pre class="prettyprint lang-config">
 179 &lt;Directory /home/*/public_html&gt;
 180     Options +ExecCGI
 181     AddHandler cgi-script .cgi
 182 &lt;/Directory&gt;
 183       </pre>
 184
 185
 186       <p>If you wish designate a <code>cgi-bin</code> subdirectory of
 187       a user's directory where everything will be treated as a CGI
 188       program, you can use the following.</p>
 189
 190       <pre class="prettyprint lang-config">
 191 &lt;Directory /home/*/public_html/cgi-bin&gt;
 192     Options ExecCGI
 193     SetHandler cgi-script
 194 &lt;/Directory&gt;
 195       </pre>
 196
 197
 198
 199
 200   </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 201 <div class="section">
 202 <h2><a name="writing" id="writing">Writing a CGI program</a></h2>
 203
 204
 205     <p>There are two main differences between ``regular''
 206     programming, and CGI programming.</p>
 207
 208     <p>First, all output from your CGI program must be preceded by
 209     a <a class="glossarylink" href="../glossary.html#mime-type" title="see glossary">MIME-type</a> header. This is HTTP header that tells the client
 210     what sort of content it is receiving. Most of the time, this
 211     will look like:</p>
 212
 213     <div class="example"><p><code>
 214       Content-type: text/html
 215     </code></p></div>
 216
 217     <p>Secondly, your output needs to be in HTML, or some other
 218     format that a browser will be able to display. Most of the
 219     time, this will be HTML, but occasionally you might write a CGI
 220     program that outputs a gif image, or other non-HTML
 221     content.</p>
 222
 223     <p>Apart from those two things, writing a CGI program will look
 224     a lot like any other program that you might write.</p>
 225
 226     <h3><a name="firstcgi" id="firstcgi">Your first CGI program</a></h3>
 227
 228
 229       <p>The following is an example CGI program that prints one
 230       line to your browser. Type in the following, save it to a
 231       file called <code>first.pl</code>, and put it in your
 232       <code>cgi-bin</code> directory.</p>
 233
 234       <pre class="prettyprint lang-perl">
 235 #!/usr/bin/perl
 236 print "Content-type: text/html\r\n\r\n";
 237 print "Hello, World.";
 238       </pre>
 239
 240
 241       <p>Even if you are not familiar with Perl, you should be able
 242       to see what is happening here. The first line tells Apache
 243       (or whatever shell you happen to be running under) that this
 244       program can be executed by feeding the file to the
 245       interpreter found at the location <code>/usr/bin/perl</code>.
 246       The second line prints the content-type declaration we
 247       talked about, followed by two carriage-return newline pairs.
 248       This puts a blank line after the header, to indicate the end
 249       of the HTTP headers, and the beginning of the body. The third
 250       line prints the string "Hello, World.". And that's the end
 251       of it.</p>
 252
 253       <p>If you open your favorite browser and tell it to get the
 254       address</p>
 255
 256       <div class="example"><p><code>
 257         http://www.example.com/cgi-bin/first.pl
 258       </code></p></div>
 259
 260       <p>or wherever you put your file, you will see the one line
 261       <code>Hello, World.</code> appear in your browser window.
 262       It's not very exciting, but once you get that working, you'll
 263       have a good chance of getting just about anything working.</p>
 264
 265   </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 266 <div class="section">
 267 <h2><a name="troubleshoot" id="troubleshoot">But it's still not working!</a></h2>
 268
 269
 270     <p>There are four basic things that you may see in your browser
 271     when you try to access your CGI program from the web:</p>
 272
 273     <dl>
 274       <dt>The output of your CGI program</dt>
 275       <dd>Great! That means everything worked fine.  If the output is correct,
 276       but the browser is not processing it correctly, make sure you have the
 277       correct <code>Content-Type</code> set in your CGI program.</dd>
 278
 279       <dt>The source code of your CGI program or a "POST Method Not
 280       Allowed" message</dt>
 281       <dd>That means that you have not properly configured Apache
 282       to process your CGI program. Reread the section on
 283       <a href="#configuring">configuring
 284       Apache</a> and try to find what you missed.</dd>
 285
 286       <dt>A message starting with "Forbidden"</dt>
 287       <dd>That means that there is a permissions problem. Check the
 288       <a href="#errorlogs">Apache error log</a> and the section below on
 289       <a href="#permissions">file permissions</a>.</dd>
 290
 291       <dt>A message saying "Internal Server Error"</dt>
 292       <dd>If you check the
 293       <a href="#errorlogs">Apache error log</a>, you will probably
 294       find that it says "Premature end of
 295       script headers", possibly along with an error message
 296       generated by your CGI program. In this case, you will want to
 297       check each of the below sections to see what might be
 298       preventing your CGI program from emitting the proper HTTP
 299       headers.</dd>
 300     </dl>
 301
 302     <h3><a name="permissions" id="permissions">File permissions</a></h3>
 303
 304
 305       <p>Remember that the server does not run as you. That is,
 306       when the server starts up, it is running with the permissions
 307       of an unprivileged user - usually <code>nobody</code>, or
 308       <code>www</code> - and so it will need extra permissions to
 309       execute files that are owned by you. Usually, the way to give
 310       a file sufficient permissions to be executed by <code>nobody</code>
 311       is to give everyone execute permission on the file:</p>
 312
 313       <div class="example"><p><code>
 314         chmod a+x first.pl
 315       </code></p></div>
 316
 317       <p>Also, if your program reads from, or writes to, any other
 318       files, those files will need to have the correct permissions
 319       to permit this.</p>
 320
 321
 322
 323     <h3><a name="pathinformation" id="pathinformation">Path information and environment</a></h3>
 324
 325
 326       <p>When you run a program from your command line, you have
 327       certain information that is passed to the shell without you
 328       thinking about it. For example, you have a <code>PATH</code>,
 329       which tells the shell where it can look for files that you
 330       reference.</p>
 331
 332       <p>When a program runs through the web server as a CGI program,
 333       it may not have the same <code>PATH</code>. Any programs that you
 334       invoke in your CGI program (like <code>sendmail</code>, for
 335       example) will need to be specified by a full path, so that the
 336       shell can find them when it attempts to execute your CGI
 337       program.</p>
 338
 339       <p>A common manifestation of this is the path to the script
 340       interpreter (often <code>perl</code>) indicated in the first
 341       line of your CGI program, which will look something like:</p>
 342
 343       <pre class="prettyprint lang-perl">
 344         #!/usr/bin/perl
 345       </pre>
 346
 347
 348       <p>Make sure that this is in fact the path to the
 349       interpreter.</p>
 350       <div class="warning">
 351       When editing CGI scripts on Windows, end-of-line characters may be
 352       appended to the interpreter path. Ensure that files are then
 353       transferred to the server in ASCII mode. Failure to do so may
 354       result in "Command not found" warnings from the OS, due to the
 355       unrecognized end-of-line character being interpreted as a part of
 356       the interpreter filename.
 357       </div>
 358
 359
 360     <h3><a name="missingenv" id="missingenv">Missing environment variables</a></h3>
 361
 362
 363       <p>If your CGI program depends on non-standard <a href="#env">environment variables</a>, you will need to
 364       assure that those variables are passed by Apache.</p>
 365
 366       <p>When you miss HTTP headers from the environment, make
 367       sure they are formatted according to
 368       <a href="http://tools.ietf.org/html/rfc2616">RFC 2616</a>,
 369       section 4.2: Header names must start with a letter,
 370       followed only by letters, numbers or hyphen. Any header
 371       violating this rule will be dropped silently.</p>
 372
 373
 374
 375     <h3><a name="syntaxerrors" id="syntaxerrors">Program errors</a></h3>
 376
 377
 378       <p>Most of the time when a CGI program fails, it's because of
 379       a problem with the program itself. This is particularly true
 380       once you get the hang of this CGI stuff, and no longer make
 381       the above two mistakes.  The first thing to do is to make
 382       sure that your program runs from the command line before
 383       testing it via the web server.  For example, try:</p>
 384
 385       <div class="example"><p><code>
 386       cd /usr/local/apache2/cgi-bin<br />
 387       ./first.pl
 388       </code></p></div>
 389
 390       <p>(Do not call the <code>perl</code> interpreter.  The shell
 391       and Apache should find the interpreter using the <a href="#pathinformation">path information</a> on the first line of
 392       the script.)</p>
 393
 394       <p>The first thing you see written by your program should be
 395       a set of HTTP headers, including the <code>Content-Type</code>,
 396       followed by a blank line.  If you see anything else, Apache will
 397       return the <code>Premature end of script headers</code> error if
 398       you try to run it through the server. See <a href="#writing">Writing a CGI program</a> above for more
 399       details.</p>
 400
 401
 402     <h3><a name="errorlogs" id="errorlogs">Error logs</a></h3>
 403
 404
 405       <p>The error logs are your friend. Anything that goes wrong
 406       generates message in the error log. You should always look
 407       there first. If the place where you are hosting your web site
 408       does not permit you access to the error log, you should
 409       probably host your site somewhere else. Learn to read the
 410       error logs, and you'll find that almost all of your problems
 411       are quickly identified, and quickly solved.</p>
 412
 413
 414     <h3><a name="suexec" id="suexec">Suexec</a></h3>
 415
 416
 417       <p>The <a href="../suexec.html">suexec</a> support program
 418       allows CGI programs to be run under different user permissions,
 419       depending on which virtual host or user home directory they are
 420       located in. Suexec has very strict permission checking, and any
 421       failure in that checking will result in your CGI programs
 422       failing with <code>Premature end of script headers</code>.</p>
 423
 424       <p>To check if you are using suexec, run <code>apachectl
 425       -V</code> and check for the location of <code>SUEXEC_BIN</code>.
 426       If Apache finds an <code class="program"><a href="../programs/suexec.html">suexec</a></code> binary there on startup,
 427       suexec will be activated.</p>
 428
 429       <p>Unless you fully understand suexec, you should not be using it.
 430       To disable suexec, simply remove (or rename) the <code class="program"><a href="../programs/suexec.html">suexec</a></code>
 431       binary pointed to by <code>SUEXEC_BIN</code> and then restart the
 432       server.  If, after reading about <a href="../suexec.html">suexec</a>,
 433       you still wish to use it, then run <code>suexec -V</code> to find
 434       the location of the suexec log file, and use that log file to
 435       find what policy you are violating.</p>
 436
 437   </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 438 <div class="section">
 439 <h2><a name="behindscenes" id="behindscenes">What's going on behind the scenes?</a></h2>
 440
 441
 442     <p>As you become more advanced in CGI programming, it will
 443     become useful to understand more about what's happening behind
 444     the scenes. Specifically, how the browser and server
 445     communicate with one another. Because although it's all very
 446     well to write a program that prints "Hello, World.", it's not
 447     particularly useful.</p>
 448
 449     <h3><a name="env" id="env">Environment variables</a></h3>
 450
 451
 452       <p>Environment variables are values that float around you as
 453       you use your computer. They are useful things like your path
 454       (where the computer searches for the actual file
 455       implementing a command when you type it), your username, your
 456       terminal type, and so on. For a full list of your normal,
 457       every day environment variables, type
 458       <code>env</code> at a command prompt.</p>
 459
 460       <p>During the CGI transaction, the server and the browser
 461       also set environment variables, so that they can communicate
 462       with one another. These are things like the browser type
 463       (Netscape, IE, Lynx), the server type (Apache, IIS, WebSite),
 464       the name of the CGI program that is being run, and so on.</p>
 465
 466       <p>These variables are available to the CGI programmer, and
 467       are half of the story of the client-server communication. The
 468       complete list of required variables is at
 469       <a href="http://www.ietf.org/rfc/rfc3875">Common Gateway
 470       Interface RFC</a>.</p>
 471
 472       <p>This simple Perl CGI program will display all of the
 473       environment variables that are being passed around. Two
 474       similar programs are included in the
 475       <code>cgi-bin</code>
 476
 477       directory of the Apache distribution. Note that some
 478       variables are required, while others are optional, so you may
 479       see some variables listed that were not in the official list.
 480       In addition, Apache provides many different ways for you to
 481       <a href="../env.html">add your own environment variables</a>
 482       to the basic ones provided by default.</p>
 483
 484       <pre class="prettyprint lang-perl">
 485 #!/usr/bin/perl
 486 use strict;
 487 use warnings;
 488
 489 print "Content-type: text/html\r\n\r\n";
 490 foreach my $key (keys %ENV) {
 491     print "$key --&gt; $ENV{$key}&lt;br&gt;";
 492 }
 493       </pre>
 494
 495
 496
 497     <h3><a name="stdin" id="stdin">STDIN and STDOUT</a></h3>
 498
 499
 500       <p>Other communication between the server and the client
 501       happens over standard input (<code>STDIN</code>) and standard
 502       output (<code>STDOUT</code>). In normal everyday context,
 503       <code>STDIN</code> means the keyboard, or a file that a
 504       program is given to act on, and <code>STDOUT</code>
 505       usually means the console or screen.</p>
 506
 507       <p>When you <code>POST</code> a web form to a CGI program,
 508       the data in that form is bundled up into a special format
 509       and gets delivered to your CGI program over <code>STDIN</code>.
 510       The program then can process that data as though it was
 511       coming in from the keyboard, or from a file</p>
 512
 513       <p>The "special format" is very simple. A field name and
 514       its value are joined together with an equals (=) sign, and
 515       pairs of values are joined together with an ampersand
 516       (&amp;). Inconvenient characters like spaces, ampersands, and
 517       equals signs, are converted into their hex equivalent so that
 518       they don't gum up the works. The whole data string might look
 519       something like:</p>
 520
 521       <div class="example"><p><code>
 522         name=Rich%20Bowen&amp;city=Lexington&amp;state=KY&amp;sidekick=Squirrel%20Monkey
 523       </code></p></div>
 524
 525       <p>You'll sometimes also see this type of string appended to
 526       a URL. When that is done, the server puts that string
 527       into the environment variable called
 528       <code>QUERY_STRING</code>. That's called a <code>GET</code>
 529       request. Your HTML form specifies whether a <code>GET</code>
 530       or a <code>POST</code> is used to deliver the data, by setting the
 531       <code>METHOD</code> attribute in the <code>FORM</code> tag.</p>
 532
 533       <p>Your program is then responsible for splitting that string
 534       up into useful information. Fortunately, there are libraries
 535       and modules available to help you process this data, as well
 536       as handle other of the aspects of your CGI program.</p>
 537
 538   </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 539 <div class="section">
 540 <h2><a name="libraries" id="libraries">CGI modules/libraries</a></h2>
 541
 542
 543     <p>When you write CGI programs, you should consider using a
 544     code library, or module, to do most of the grunt work for you.
 545     This leads to fewer errors, and faster development.</p>
 546
 547     <p>If you're writing CGI programs in Perl, modules are
 548     available on <a href="http://www.cpan.org/">CPAN</a>. The most
 549     popular module for this purpose is <code>CGI.pm</code>. You might
 550     also consider <code>CGI::Lite</code>, which implements a minimal
 551     set of functionality, which is all you need in most programs.</p>
 552
 553     <p>If you're writing CGI programs in C, there are a variety of
 554     options. One of these is the <code>CGIC</code> library, from
 555     <a href="http://www.boutell.com/cgic/">http://www.boutell.com/cgic/</a>.</p>
 556   </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 557 <div class="section">
 558 <h2><a name="moreinfo" id="moreinfo">For more information</a></h2>
 559
 560
 561     <p>The current CGI specification is available in the
 562     <a href="http://www.ietf.org/rfc/rfc3875">Common Gateway
 563     Interface RFC</a>.</p>
 564
 565     <p>When you post a question about a CGI problem that you're
 566     having, whether to a mailing list, or to a newsgroup, make sure
 567     you provide enough information about what happened, what you
 568     expected to happen, and how what actually happened was
 569     different, what server you're running, what language your CGI
 570     program was in, and, if possible, the offending code. This will
 571     make finding your problem much simpler.</p>
 572
 573     <p>Note that questions about CGI problems should <strong>never</strong>
 574     be posted to the Apache bug database unless you are sure you
 575     have found a problem in the Apache source code.</p>
 576   </div></div>
 577 <div class="bottomlang">
 578 <p><span>Available Languages: </span><a href="../en/howto/cgi.html" title="English">&nbsp;en&nbsp;</a> |
 579 <a href="../fr/howto/cgi.html" hreflang="fr" rel="alternate" title="Français">&nbsp;fr&nbsp;</a> |
 580 <a href="../ja/howto/cgi.html" hreflang="ja" rel="alternate" title="Japanese">&nbsp;ja&nbsp;</a> |
 581 <a href="../ko/howto/cgi.html" hreflang="ko" rel="alternate" title="Korean">&nbsp;ko&nbsp;</a></p>
 582 </div><div class="top"><a href="#page-header"><img src="../images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>This section is experimental!</strong><br />Comments placed here should not be expected
 583 to last beyond the testing phase of this system, nor do we in any way guarantee that we'll read them.</div>
 584 <script type="text/javascript"><!--//--><![CDATA[//><!--
 585 var disqus_shortname = 'httpd';
 586 var disqus_identifier = 'http://httpd.apache.org/docs/2.4/howto/cgi.html.en';
 587 (function(w, d) {
 588     if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
 589         d.write('<div id="disqus_thread"><\/div>');
 590         var s = d.createElement('script');
 591         s.type = 'text/javascript';
 592         s.async = true;
 593         s.src = 'http' + '://' + disqus_shortname + '.disqus.com/embed.js';
 594         (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
 595     }
 596     else {
 597         d.write('<div id="disqus_thread">Comments have been disabled for offline viewing.<\/div>');
 598     }
 599 })(window, document);
 600 //--><!]]></script></div><div id="footer">
 601 <p class="apache">Copyright 2012 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
 602 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!--
 603 if (typeof(prettyPrint) !== 'undefined') {
 604     prettyPrint();
 605 }
 606 //--><!]]></script>
 607 </body></html>