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