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