COOKIES

       Netscape browsers versions 1.1 and higher, and all versions of Internet
       Explorer, support a so-called "cookie" designed to help maintain state
       within a browser session.  CGI.pm has several methods that support
       cookies.

       A cookie is a name=value pair much like the named parameters in a CGI
       query string.  CGI scripts create one or more cookies and send them to
       the browser in the HTTP header.	The browser maintains a list of cook-
       ies that belong to a particular Web server, and returns them to the CGI
       script during subsequent interactions.

       In addition to the required name=value pair, each cookie has several
       optional attributes:

       1. an expiration time
	   This is a time/date string (in a special GMT format) that indicates
	   when a cookie expires.  The cookie will be saved and returned to
	   your script until this expiration date is reached if the user exits
	   the browser and restarts it.	 If an expiration date isn't speci-
	   fied, the cookie will remain active until the user quits the
	   browser.

       2. a domain
	   This is a partial or complete domain name for which the cookie is
	   valid.  The browser will return the cookie to any host that matches
	   the partial domain name.  For example, if you specify a domain name
	   of ".capricorn.com", then the browser will return the cookie to Web
	   servers running on any of the machines "www.capricorn.com",
	   "www2.capricorn.com", "feckless.capricorn.com", etc.	 Domain names
	   must contain at least two periods to prevent attempts to match on
	   top level domains like ".edu".  If no domain is specified, then the
	   browser will only return the cookie to servers on the host the
	   cookie originated from.

       3. a path
	   If you provide a cookie path attribute, the browser will check it
	   against your script's URL before returning the cookie.  For exam-
	   ple, if you specify the path "/cgi-bin", then the cookie will be
	   returned to each of the scripts "/cgi-bin/tally.pl",
	   "/cgi-bin/order.pl", and "/cgi-bin/customer_service/complain.pl",
	   but not to the script "/cgi-private/site_admin.pl".	By default,
	   path is set to "/", which causes the cookie to be sent to any CGI
	   script on your site.

       4. a "secure" flag
	   If the "secure" attribute is set, the cookie will only be sent to
	   your script if the CGI request is occurring on a secure channel,
	   such as SSL.

	   The interface to HTTP cookies is the _cc_oo_oo_kk_ii_ee_((_)) method:

	       $cookie = $query->cookie(-name=>'sessionID',
					-value=>'xyzzy',
					-expires=>'+1h',
					-path=>'/cgi-bin/database',
					-domain=>'.capricorn.org',
					-secure=>1);
	       print $query->header(-cookie=>$cookie);

	   _cc_oo_oo_kk_ii_ee_((_)) creates a new cookie.  Its parameters include:

	   --nnaammee
	       The name of the cookie (required).  This can be any string at
	       all.  Although browsers limit their cookie names to non-whites-
	       pace alphanumeric characters, CGI.pm removes this restriction
	       by escaping and unescaping cookies behind the scenes.

	   --vvaalluuee
	       The value of the cookie.	 This can be any scalar value, array
	       reference, or even associative array reference.	For example,
	       you can store an entire associative array into a cookie this
	       way:

		       $cookie=$query->cookie(-name=>'family information',
					      -value=>\%childrens_ages);

	   --ppaatthh
	       The optional partial path for which this cookie will be valid,
	       as described above.

	   --ddoommaaiinn
	       The optional partial domain for which this cookie will be
	       valid, as described above.

	   --eexxppiirreess
	       The optional expiration date for this cookie.  The format is as
	       described in the section on the _hh_ee_aa_dd_ee_rr_((_)) method:

		       "+1h"  one hour from now

	   --sseeccuurree
	       If set to true, this cookie will only be used within a secure
	       SSL session.

	   The cookie created by _c_o_o_k_i_e_(_) must be incorporated into the HTTP
	   header within the string returned by the _h_e_a_d_e_r_(_) method:

		   print $query->header(-cookie=>$my_cookie);

	   To create multiple cookies, give _h_e_a_d_e_r_(_) an array reference:

		   $cookie1 = $query->cookie(-name=>'riddle_name',
					     -value=>"The Sphynx's Question");
		   $cookie2 = $query->cookie(-name=>'answers',
					     -value=>\%answers);
		   print $query->header(-cookie=>[$cookie1,$cookie2]);

	   To retrieve a cookie, request it by name by calling _c_o_o_k_i_e_(_) method
	   without the --vvaalluuee parameter:

		   use CGI;
		   $query = new CGI;
		   $riddle = $query->cookie('riddle_name');
		   %answers = $query->cookie('answers');

	   Cookies created with a single scalar value, such as the "rid-
	   dle_name" cookie, will be returned in that form.  Cookies with
	   array and hash values can also be retrieved.

	   The cookie and CGI namespaces are separate.	If you have a parame-
	   ter named 'answers' and a cookie named 'answers', the values
	   retrieved by _p_a_r_a_m_(_) and _c_o_o_k_i_e_(_) are independent of each other.
	   However, it's simple to turn a CGI parameter into a cookie, and
	   vice-versa:

	      # turn a CGI parameter into a cookie
	      $c=$q->cookie(-name=>'answers',-value=>[$q->param('answers')]);
	      # vice-versa
	      $q->param(-name=>'answers',-value=>[$q->cookie('answers')]);

	   See the ccooookkiiee..ccggii example script for some ideas on how to use
	   cookies effectively.