Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 |
2 | .\" | |
3 | .\" Standard preamble: | |
4 | .\" ======================================================================== | |
5 | .de Sh \" Subsection heading | |
6 | .br | |
7 | .if t .Sp | |
8 | .ne 5 | |
9 | .PP | |
10 | \fB\\$1\fR | |
11 | .PP | |
12 | .. | |
13 | .de Sp \" Vertical space (when we can't use .PP) | |
14 | .if t .sp .5v | |
15 | .if n .sp | |
16 | .. | |
17 | .de Vb \" Begin verbatim text | |
18 | .ft CW | |
19 | .nf | |
20 | .ne \\$1 | |
21 | .. | |
22 | .de Ve \" End verbatim text | |
23 | .ft R | |
24 | .fi | |
25 | .. | |
26 | .\" Set up some character translations and predefined strings. \*(-- will | |
27 | .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left | |
28 | .\" double quote, and \*(R" will give a right double quote. | will give a | |
29 | .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to | |
30 | .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' | |
31 | .\" expand to `' in nroff, nothing in troff, for use with C<>. | |
32 | .tr \(*W-|\(bv\*(Tr | |
33 | .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' | |
34 | .ie n \{\ | |
35 | . ds -- \(*W- | |
36 | . ds PI pi | |
37 | . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch | |
38 | . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch | |
39 | . ds L" "" | |
40 | . ds R" "" | |
41 | . ds C` "" | |
42 | . ds C' "" | |
43 | 'br\} | |
44 | .el\{\ | |
45 | . ds -- \|\(em\| | |
46 | . ds PI \(*p | |
47 | . ds L" `` | |
48 | . ds R" '' | |
49 | 'br\} | |
50 | .\" | |
51 | .\" If the F register is turned on, we'll generate index entries on stderr for | |
52 | .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index | |
53 | .\" entries marked with X<> in POD. Of course, you'll have to process the | |
54 | .\" output yourself in some meaningful fashion. | |
55 | .if \nF \{\ | |
56 | . de IX | |
57 | . tm Index:\\$1\t\\n%\t"\\$2" | |
58 | .. | |
59 | . nr % 0 | |
60 | . rr F | |
61 | .\} | |
62 | .\" | |
63 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes | |
64 | .\" way too many mistakes in technical documents. | |
65 | .hy 0 | |
66 | .if n .na | |
67 | .\" | |
68 | .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). | |
69 | .\" Fear. Run. Save yourself. No user-serviceable parts. | |
70 | . \" fudge factors for nroff and troff | |
71 | .if n \{\ | |
72 | . ds #H 0 | |
73 | . ds #V .8m | |
74 | . ds #F .3m | |
75 | . ds #[ \f1 | |
76 | . ds #] \fP | |
77 | .\} | |
78 | .if t \{\ | |
79 | . ds #H ((1u-(\\\\n(.fu%2u))*.13m) | |
80 | . ds #V .6m | |
81 | . ds #F 0 | |
82 | . ds #[ \& | |
83 | . ds #] \& | |
84 | .\} | |
85 | . \" simple accents for nroff and troff | |
86 | .if n \{\ | |
87 | . ds ' \& | |
88 | . ds ` \& | |
89 | . ds ^ \& | |
90 | . ds , \& | |
91 | . ds ~ ~ | |
92 | . ds / | |
93 | .\} | |
94 | .if t \{\ | |
95 | . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" | |
96 | . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' | |
97 | . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' | |
98 | . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' | |
99 | . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' | |
100 | . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' | |
101 | .\} | |
102 | . \" troff and (daisy-wheel) nroff accents | |
103 | .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' | |
104 | .ds 8 \h'\*(#H'\(*b\h'-\*(#H' | |
105 | .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] | |
106 | .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' | |
107 | .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' | |
108 | .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] | |
109 | .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] | |
110 | .ds ae a\h'-(\w'a'u*4/10)'e | |
111 | .ds Ae A\h'-(\w'A'u*4/10)'E | |
112 | . \" corrections for vroff | |
113 | .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' | |
114 | .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' | |
115 | . \" for low resolution devices (crt and lpr) | |
116 | .if \n(.H>23 .if \n(.V>19 \ | |
117 | \{\ | |
118 | . ds : e | |
119 | . ds 8 ss | |
120 | . ds o a | |
121 | . ds d- d\h'-1'\(ga | |
122 | . ds D- D\h'-1'\(hy | |
123 | . ds th \o'bp' | |
124 | . ds Th \o'LP' | |
125 | . ds ae ae | |
126 | . ds Ae AE | |
127 | .\} | |
128 | .rm #[ #] #H #V #F C | |
129 | .\" ======================================================================== | |
130 | .\" | |
131 | .IX Title "PERLFAQ9 1" | |
132 | .TH PERLFAQ9 1 "2006-01-07" "perl v5.8.8" "Perl Programmers Reference Guide" | |
133 | .SH "NAME" | |
134 | perlfaq9 \- Networking ($Revision: 1.28 $, $Date: 2005/12/31 00:54:37 $) | |
135 | .SH "DESCRIPTION" | |
136 | .IX Header "DESCRIPTION" | |
137 | This section deals with questions related to networking, the internet, | |
138 | and a few on the web. | |
139 | .Sh "What is the correct form of response from a \s-1CGI\s0 script?" | |
140 | .IX Subsection "What is the correct form of response from a CGI script?" | |
141 | (Alan Flavell <flavell+www@a5.ph.gla.ac.uk> answers...) | |
142 | .PP | |
143 | The Common Gateway Interface (\s-1CGI\s0) specifies a software interface between | |
144 | a program (\*(L"\s-1CGI\s0 script\*(R") and a web server (\s-1HTTPD\s0). It is not specific | |
145 | to Perl, and has its own FAQs and tutorials, and usenet group, | |
146 | comp.infosystems.www.authoring.cgi | |
147 | .PP | |
148 | The \s-1CGI\s0 specification is outlined in an informational \s-1RFC:\s0 | |
149 | http://www.ietf.org/rfc/rfc3875 | |
150 | .PP | |
151 | Other relevant documentation listed in: http://www.perl.org/CGI_MetaFAQ.html | |
152 | .PP | |
153 | These Perl FAQs very selectively cover some \s-1CGI\s0 issues. However, Perl | |
154 | programmers are strongly advised to use the \s-1CGI\s0.pm module, to take care | |
155 | of the details for them. | |
156 | .PP | |
157 | The similarity between \s-1CGI\s0 response headers (defined in the \s-1CGI\s0 | |
158 | specification) and \s-1HTTP\s0 response headers (defined in the \s-1HTTP\s0 | |
159 | specification, \s-1RFC2616\s0) is intentional, but can sometimes be confusing. | |
160 | .PP | |
161 | The \s-1CGI\s0 specification defines two kinds of script: the \*(L"Parsed Header\*(R" | |
162 | script, and the \*(L"Non Parsed Header\*(R" (\s-1NPH\s0) script. Check your server | |
163 | documentation to see what it supports. \*(L"Parsed Header\*(R" scripts are | |
164 | simpler in various respects. The \s-1CGI\s0 specification allows any of the | |
165 | usual newline representations in the \s-1CGI\s0 response (it's the server's | |
166 | job to create an accurate \s-1HTTP\s0 response based on it). So \*(L"\en\*(R" written in | |
167 | text mode is technically correct, and recommended. \s-1NPH\s0 scripts are more | |
168 | tricky: they must put out a complete and accurate set of \s-1HTTP\s0 | |
169 | transaction response headers; the \s-1HTTP\s0 specification calls for records | |
170 | to be terminated with carriage-return and line\-feed, i.e \s-1ASCII\s0 \e015\e012 | |
171 | written in binary mode. | |
172 | .PP | |
173 | Using \s-1CGI\s0.pm gives excellent platform independence, including \s-1EBCDIC\s0 | |
174 | systems. \s-1CGI\s0.pm selects an appropriate newline representation | |
175 | ($CGI::CRLF) and sets binmode as appropriate. | |
176 | .Sh "My \s-1CGI\s0 script runs from the command line but not the browser. (500 Server Error)" | |
177 | .IX Subsection "My CGI script runs from the command line but not the browser. (500 Server Error)" | |
178 | Several things could be wrong. You can go through the \*(L"Troubleshooting | |
179 | Perl \s-1CGI\s0 scripts\*(R" guide at | |
180 | .PP | |
181 | .Vb 1 | |
182 | \& http://www.perl.org/troubleshooting_CGI.html | |
183 | .Ve | |
184 | .PP | |
185 | If, after that, you can demonstrate that you've read the FAQs and that | |
186 | your problem isn't something simple that can be easily answered, you'll | |
187 | probably receive a courteous and useful reply to your question if you | |
188 | post it on comp.infosystems.www.authoring.cgi (if it's something to do | |
189 | with \s-1HTTP\s0 or the \s-1CGI\s0 protocols). Questions that appear to be Perl | |
190 | questions but are really \s-1CGI\s0 ones that are posted to comp.lang.perl.misc | |
191 | are not so well received. | |
192 | .PP | |
193 | The useful FAQs, related documents, and troubleshooting guides are | |
194 | listed in the \s-1CGI\s0 Meta \s-1FAQ:\s0 | |
195 | .PP | |
196 | .Vb 1 | |
197 | \& http://www.perl.org/CGI_MetaFAQ.html | |
198 | .Ve | |
199 | .Sh "How can I get better error messages from a \s-1CGI\s0 program?" | |
200 | .IX Subsection "How can I get better error messages from a CGI program?" | |
201 | Use the CGI::Carp module. It replaces \f(CW\*(C`warn\*(C'\fR and \f(CW\*(C`die\*(C'\fR, plus the | |
202 | normal Carp modules \f(CW\*(C`carp\*(C'\fR, \f(CW\*(C`croak\*(C'\fR, and \f(CW\*(C`confess\*(C'\fR functions with | |
203 | more verbose and safer versions. It still sends them to the normal | |
204 | server error log. | |
205 | .PP | |
206 | .Vb 3 | |
207 | \& use CGI::Carp; | |
208 | \& warn "This is a complaint"; | |
209 | \& die "But this one is serious"; | |
210 | .Ve | |
211 | .PP | |
212 | The following use of CGI::Carp also redirects errors to a file of your choice, | |
213 | placed in a \s-1BEGIN\s0 block to catch compile-time warnings as well: | |
214 | .PP | |
215 | .Vb 6 | |
216 | \& BEGIN { | |
217 | \& use CGI::Carp qw(carpout); | |
218 | \& open(LOG, ">>/var/local/cgi-logs/mycgi-log") | |
219 | \& or die "Unable to append to mycgi-log: $!\en"; | |
220 | \& carpout(*LOG); | |
221 | \& } | |
222 | .Ve | |
223 | .PP | |
224 | You can even arrange for fatal errors to go back to the client browser, | |
225 | which is nice for your own debugging, but might confuse the end user. | |
226 | .PP | |
227 | .Vb 2 | |
228 | \& use CGI::Carp qw(fatalsToBrowser); | |
229 | \& die "Bad error here"; | |
230 | .Ve | |
231 | .PP | |
232 | Even if the error happens before you get the \s-1HTTP\s0 header out, the module | |
233 | will try to take care of this to avoid the dreaded server 500 errors. | |
234 | Normal warnings still go out to the server error log (or wherever | |
235 | you've sent them with \f(CW\*(C`carpout\*(C'\fR) with the application name and date | |
236 | stamp prepended. | |
237 | .Sh "How do I remove \s-1HTML\s0 from a string?" | |
238 | .IX Subsection "How do I remove HTML from a string?" | |
239 | The most correct way (albeit not the fastest) is to use HTML::Parser | |
240 | from \s-1CPAN\s0. Another mostly correct | |
241 | way is to use HTML::FormatText which not only removes \s-1HTML\s0 but also | |
242 | attempts to do a little simple formatting of the resulting plain text. | |
243 | .PP | |
244 | Many folks attempt a simple-minded regular expression approach, like | |
245 | \&\f(CW\*(C`s/<.*?>//g\*(C'\fR, but that fails in many cases because the tags | |
246 | may continue over line breaks, they may contain quoted angle\-brackets, | |
247 | or \s-1HTML\s0 comment may be present. Plus, folks forget to convert | |
248 | entities\*(--like \f(CW\*(C`<\*(C'\fR for example. | |
249 | .PP | |
250 | Here's one \*(L"simple\-minded\*(R" approach, that works for most files: | |
251 | .PP | |
252 | .Vb 2 | |
253 | \& #!/usr/bin/perl -p0777 | |
254 | \& s/<(?:[^>'"]*|(['"]).*?\e1)*>//gs | |
255 | .Ve | |
256 | .PP | |
257 | If you want a more complete solution, see the 3\-stage striphtml | |
258 | program in | |
259 | http://www.cpan.org/authors/Tom_Christiansen/scripts/striphtml.gz | |
260 | \&. | |
261 | .PP | |
262 | Here are some tricky cases that you should think about when picking | |
263 | a solution: | |
264 | .PP | |
265 | .Vb 1 | |
266 | \& <IMG SRC = "foo.gif" ALT = "A > B"> | |
267 | .Ve | |
268 | .PP | |
269 | .Vb 2 | |
270 | \& <IMG SRC = "foo.gif" | |
271 | \& ALT = "A > B"> | |
272 | .Ve | |
273 | .PP | |
274 | .Vb 1 | |
275 | \& <!-- <A comment> --> | |
276 | .Ve | |
277 | .PP | |
278 | .Vb 1 | |
279 | \& <script>if (a<b && a>c)</script> | |
280 | .Ve | |
281 | .PP | |
282 | .Vb 1 | |
283 | \& <# Just data #> | |
284 | .Ve | |
285 | .PP | |
286 | .Vb 1 | |
287 | \& <![INCLUDE CDATA [ >>>>>>>>>>>> ]]> | |
288 | .Ve | |
289 | .PP | |
290 | If \s-1HTML\s0 comments include other tags, those solutions would also break | |
291 | on text like this: | |
292 | .PP | |
293 | .Vb 3 | |
294 | \& <!-- This section commented out. | |
295 | \& <B>You can't see me!</B> | |
296 | \& --> | |
297 | .Ve | |
298 | .Sh "How do I extract URLs?" | |
299 | .IX Subsection "How do I extract URLs?" | |
300 | You can easily extract all sorts of URLs from \s-1HTML\s0 with | |
301 | \&\f(CW\*(C`HTML::SimpleLinkExtor\*(C'\fR which handles anchors, images, objects, | |
302 | frames, and many other tags that can contain a \s-1URL\s0. If you need | |
303 | anything more complex, you can create your own subclass of | |
304 | \&\f(CW\*(C`HTML::LinkExtor\*(C'\fR or \f(CW\*(C`HTML::Parser\*(C'\fR. You might even use | |
305 | \&\f(CW\*(C`HTML::SimpleLinkExtor\*(C'\fR as an example for something specifically | |
306 | suited to your needs. | |
307 | .PP | |
308 | You can use URI::Find to extract URLs from an arbitrary text document. | |
309 | .PP | |
310 | Less complete solutions involving regular expressions can save | |
311 | you a lot of processing time if you know that the input is simple. One | |
312 | solution from Tom Christiansen runs 100 times faster than most | |
313 | module based approaches but only extracts URLs from anchors where the first | |
314 | attribute is \s-1HREF\s0 and there are no other attributes. | |
315 | .PP | |
316 | .Vb 7 | |
317 | \& #!/usr/bin/perl -n00 | |
318 | \& # qxurl - tchrist@perl.com | |
319 | \& print "$2\en" while m{ | |
320 | \& < \es* | |
321 | \& A \es+ HREF \es* = \es* (["']) (.*?) \e1 | |
322 | \& \es* > | |
323 | \& }gsix; | |
324 | .Ve | |
325 | .Sh "How do I download a file from the user's machine? How do I open a file on another machine?" | |
326 | .IX Subsection "How do I download a file from the user's machine? How do I open a file on another machine?" | |
327 | In this case, download means to use the file upload feature of \s-1HTML\s0 | |
328 | forms. You allow the web surfer to specify a file to send to your web | |
329 | server. To you it looks like a download, and to the user it looks | |
330 | like an upload. No matter what you call it, you do it with what's | |
331 | known as \fBmultipart/form\-data\fR encoding. The \s-1CGI\s0.pm module (which | |
332 | comes with Perl as part of the Standard Library) supports this in the | |
333 | \&\fIstart_multipart_form()\fR method, which isn't the same as the \fIstartform()\fR | |
334 | method. | |
335 | .PP | |
336 | See the section in the \s-1CGI\s0.pm documentation on file uploads for code | |
337 | examples and details. | |
338 | .Sh "How do I make a pop-up menu in \s-1HTML\s0?" | |
339 | .IX Subsection "How do I make a pop-up menu in HTML?" | |
340 | Use the \fB<\s-1SELECT\s0>\fR and \fB<\s-1OPTION\s0>\fR tags. The \s-1CGI\s0.pm | |
341 | module (available from \s-1CPAN\s0) supports this widget, as well as many | |
342 | others, including some that it cleverly synthesizes on its own. | |
343 | .Sh "How do I fetch an \s-1HTML\s0 file?" | |
344 | .IX Subsection "How do I fetch an HTML file?" | |
345 | One approach, if you have the lynx text-based \s-1HTML\s0 browser installed | |
346 | on your system, is this: | |
347 | .PP | |
348 | .Vb 2 | |
349 | \& $html_code = `lynx -source $url`; | |
350 | \& $text_data = `lynx -dump $url`; | |
351 | .Ve | |
352 | .PP | |
353 | The libwww-perl (\s-1LWP\s0) modules from \s-1CPAN\s0 provide a more powerful way | |
354 | to do this. They don't require lynx, but like lynx, can still work | |
355 | through proxies: | |
356 | .PP | |
357 | .Vb 3 | |
358 | \& # simplest version | |
359 | \& use LWP::Simple; | |
360 | \& $content = get($URL); | |
361 | .Ve | |
362 | .PP | |
363 | .Vb 3 | |
364 | \& # or print HTML from a URL | |
365 | \& use LWP::Simple; | |
366 | \& getprint "http://www.linpro.no/lwp/"; | |
367 | .Ve | |
368 | .PP | |
369 | .Vb 11 | |
370 | \& # or print ASCII from HTML from a URL | |
371 | \& # also need HTML-Tree package from CPAN | |
372 | \& use LWP::Simple; | |
373 | \& use HTML::Parser; | |
374 | \& use HTML::FormatText; | |
375 | \& my ($html, $ascii); | |
376 | \& $html = get("http://www.perl.com/"); | |
377 | \& defined $html | |
378 | \& or die "Can't fetch HTML from http://www.perl.com/"; | |
379 | \& $ascii = HTML::FormatText->new->format(parse_html($html)); | |
380 | \& print $ascii; | |
381 | .Ve | |
382 | .Sh "How do I automate an \s-1HTML\s0 form submission?" | |
383 | .IX Subsection "How do I automate an HTML form submission?" | |
384 | If you are doing something complex, such as moving through many pages | |
385 | and forms or a web site, you can use \f(CW\*(C`WWW::Mechanize\*(C'\fR. See its | |
386 | documentation for all the details. | |
387 | .PP | |
388 | If you're submitting values using the \s-1GET\s0 method, create a \s-1URL\s0 and encode | |
389 | the form using the \f(CW\*(C`query_form\*(C'\fR method: | |
390 | .PP | |
391 | .Vb 2 | |
392 | \& use LWP::Simple; | |
393 | \& use URI::URL; | |
394 | .Ve | |
395 | .PP | |
396 | .Vb 3 | |
397 | \& my $url = url('http://www.perl.com/cgi-bin/cpan_mod'); | |
398 | \& $url->query_form(module => 'DB_File', readme => 1); | |
399 | \& $content = get($url); | |
400 | .Ve | |
401 | .PP | |
402 | If you're using the \s-1POST\s0 method, create your own user agent and encode | |
403 | the content appropriately. | |
404 | .PP | |
405 | .Vb 2 | |
406 | \& use HTTP::Request::Common qw(POST); | |
407 | \& use LWP::UserAgent; | |
408 | .Ve | |
409 | .PP | |
410 | .Vb 4 | |
411 | \& $ua = LWP::UserAgent->new(); | |
412 | \& my $req = POST 'http://www.perl.com/cgi-bin/cpan_mod', | |
413 | \& [ module => 'DB_File', readme => 1 ]; | |
414 | \& $content = $ua->request($req)->as_string; | |
415 | .Ve | |
416 | .Sh "How do I decode or create those %\-encodings on the web?" | |
417 | .IX Subsection "How do I decode or create those %-encodings on the web?" | |
418 | If you are writing a \s-1CGI\s0 script, you should be using the \s-1CGI\s0.pm module | |
419 | that comes with perl, or some other equivalent module. The \s-1CGI\s0 module | |
420 | automatically decodes queries for you, and provides an \fIescape()\fR | |
421 | function to handle encoding. | |
422 | .PP | |
423 | The best source of detailed information on \s-1URI\s0 encoding is \s-1RFC\s0 2396. | |
424 | Basically, the following substitutions do it: | |
425 | .PP | |
426 | .Vb 1 | |
427 | \& s/([^\ew()'*~!.-])/sprintf '%%%02x', ord $1/eg; # encode | |
428 | .Ve | |
429 | .PP | |
430 | .Vb 2 | |
431 | \& s/%([A-Fa-f\ed]{2})/chr hex $1/eg; # decode | |
432 | \& s/%([[:xdigit:]]{2})/chr hex $1/eg; # same thing | |
433 | .Ve | |
434 | .PP | |
435 | However, you should only apply them to individual \s-1URI\s0 components, not | |
436 | the entire \s-1URI\s0, otherwise you'll lose information and generally mess | |
437 | things up. If that didn't explain it, don't worry. Just go read | |
438 | section 2 of the \s-1RFC\s0, it's probably the best explanation there is. | |
439 | .PP | |
440 | \&\s-1RFC\s0 2396 also contains a lot of other useful information, including a | |
441 | regexp for breaking any arbitrary \s-1URI\s0 into components (Appendix B). | |
442 | .Sh "How do I redirect to another page?" | |
443 | .IX Subsection "How do I redirect to another page?" | |
444 | Specify the complete \s-1URL\s0 of the destination (even if it is on the same | |
445 | server). This is one of the two different kinds of \s-1CGI\s0 \*(L"Location:\*(R" | |
446 | responses which are defined in the \s-1CGI\s0 specification for a Parsed Headers | |
447 | script. The other kind (an absolute URLpath) is resolved internally to | |
448 | the server without any \s-1HTTP\s0 redirection. The \s-1CGI\s0 specifications do not | |
449 | allow relative URLs in either case. | |
450 | .PP | |
451 | Use of \s-1CGI\s0.pm is strongly recommended. This example shows redirection | |
452 | with a complete \s-1URL\s0. This redirection is handled by the web browser. | |
453 | .PP | |
454 | .Vb 1 | |
455 | \& use CGI qw/:standard/; | |
456 | .Ve | |
457 | .PP | |
458 | .Vb 2 | |
459 | \& my $url = 'http://www.cpan.org/'; | |
460 | \& print redirect($url); | |
461 | .Ve | |
462 | .PP | |
463 | This example shows a redirection with an absolute URLpath. This | |
464 | redirection is handled by the local web server. | |
465 | .PP | |
466 | .Vb 2 | |
467 | \& my $url = '/CPAN/index.html'; | |
468 | \& print redirect($url); | |
469 | .Ve | |
470 | .PP | |
471 | But if coded directly, it could be as follows (the final \*(L"\en\*(R" is | |
472 | shown separately, for clarity), using either a complete \s-1URL\s0 or | |
473 | an absolute URLpath. | |
474 | .PP | |
475 | .Vb 2 | |
476 | \& print "Location: $url\en"; # CGI response header | |
477 | \& print "\en"; # end of headers | |
478 | .Ve | |
479 | .Sh "How do I put a password on my web pages?" | |
480 | .IX Subsection "How do I put a password on my web pages?" | |
481 | To enable authentication for your web server, you need to configure | |
482 | your web server. The configuration is different for different sorts | |
483 | of web servers\-\-\-apache does it differently from iPlanet which does | |
484 | it differently from \s-1IIS\s0. Check your web server documentation for | |
485 | the details for your particular server. | |
486 | .Sh "How do I edit my .htpasswd and .htgroup files with Perl?" | |
487 | .IX Subsection "How do I edit my .htpasswd and .htgroup files with Perl?" | |
488 | The HTTPD::UserAdmin and HTTPD::GroupAdmin modules provide a | |
489 | consistent \s-1OO\s0 interface to these files, regardless of how they're | |
490 | stored. Databases may be text, dbm, Berkeley \s-1DB\s0 or any database with | |
491 | a \s-1DBI\s0 compatible driver. HTTPD::UserAdmin supports files used by the | |
492 | \&\*(L"Basic\*(R" and \*(L"Digest\*(R" authentication schemes. Here's an example: | |
493 | .PP | |
494 | .Vb 4 | |
495 | \& use HTTPD::UserAdmin (); | |
496 | \& HTTPD::UserAdmin | |
497 | \& ->new(DB => "/foo/.htpasswd") | |
498 | \& ->add($username => $password); | |
499 | .Ve | |
500 | .Sh "How do I make sure users can't enter values into a form that cause my \s-1CGI\s0 script to do bad things?" | |
501 | .IX Subsection "How do I make sure users can't enter values into a form that cause my CGI script to do bad things?" | |
502 | See the security references listed in the \s-1CGI\s0 Meta \s-1FAQ\s0 | |
503 | .PP | |
504 | .Vb 1 | |
505 | \& http://www.perl.org/CGI_MetaFAQ.html | |
506 | .Ve | |
507 | .Sh "How do I parse a mail header?" | |
508 | .IX Subsection "How do I parse a mail header?" | |
509 | For a quick-and-dirty solution, try this solution derived | |
510 | from \*(L"split\*(R" in perlfunc: | |
511 | .PP | |
512 | .Vb 4 | |
513 | \& $/ = ''; | |
514 | \& $header = <MSG>; | |
515 | \& $header =~ s/\en\es+/ /g; # merge continuation lines | |
516 | \& %head = ( UNIX_FROM_LINE, split /^([-\ew]+):\es*/m, $header ); | |
517 | .Ve | |
518 | .PP | |
519 | That solution doesn't do well if, for example, you're trying to | |
520 | maintain all the Received lines. A more complete approach is to use | |
521 | the Mail::Header module from \s-1CPAN\s0 (part of the MailTools package). | |
522 | .Sh "How do I decode a \s-1CGI\s0 form?" | |
523 | .IX Subsection "How do I decode a CGI form?" | |
524 | (contributed by brian d foy) | |
525 | .PP | |
526 | Use the \s-1CGI\s0.pm module that comes with Perl. It's quick, | |
527 | it's easy, and it actually does quite a bit of work to | |
528 | ensure things happen correctly. It handles \s-1GET\s0, \s-1POST\s0, and | |
529 | \&\s-1HEAD\s0 requests, multipart forms, multivalued fields, query | |
530 | string and message body combinations, and many other things | |
531 | you probably don't want to think about. | |
532 | .PP | |
533 | It doesn't get much easier: the \s-1CGI\s0 module automatically | |
534 | parses the input and makes each value available through the | |
535 | \&\f(CW\*(C`param()\*(C'\fR function. | |
536 | .PP | |
537 | .Vb 1 | |
538 | \& use CGI qw(:standard); | |
539 | .Ve | |
540 | .PP | |
541 | .Vb 1 | |
542 | \& my $total = param( 'price' ) + param( 'shipping' ); | |
543 | .Ve | |
544 | .PP | |
545 | .Vb 1 | |
546 | \& my @items = param( 'item' ); # multiple values, same field name | |
547 | .Ve | |
548 | .PP | |
549 | If you want an object-oriented approach, \s-1CGI\s0.pm can do that too. | |
550 | .PP | |
551 | .Vb 1 | |
552 | \& use CGI; | |
553 | .Ve | |
554 | .PP | |
555 | .Vb 1 | |
556 | \& my $cgi = CGI->new(); | |
557 | .Ve | |
558 | .PP | |
559 | .Vb 1 | |
560 | \& my $total = $cgi->param( 'price' ) + $cgi->param( 'shipping' ); | |
561 | .Ve | |
562 | .PP | |
563 | .Vb 1 | |
564 | \& my @items = $cgi->param( 'item' ); | |
565 | .Ve | |
566 | .PP | |
567 | You might also try CGI::Minimal which is a lightweight version | |
568 | of the same thing. Other CGI::* modules on \s-1CPAN\s0 might work better | |
569 | for you, too. | |
570 | .PP | |
571 | Many people try to write their own decoder (or copy one from | |
572 | another program) and then run into one of the many \*(L"gotchas\*(R" | |
573 | of the task. It's much easier and less hassle to use \s-1CGI\s0.pm. | |
574 | .Sh "How do I check a valid mail address?" | |
575 | .IX Subsection "How do I check a valid mail address?" | |
576 | You can't, at least, not in real time. Bummer, eh? | |
577 | .PP | |
578 | Without sending mail to the address and seeing whether there's a human | |
579 | on the other end to answer you, you cannot determine whether a mail | |
580 | address is valid. Even if you apply the mail header standard, you | |
581 | can have problems, because there are deliverable addresses that aren't | |
582 | \&\s-1RFC\-822\s0 (the mail header standard) compliant, and addresses that aren't | |
583 | deliverable which are compliant. | |
584 | .PP | |
585 | You can use the Email::Valid or RFC::RFC822::Address which check | |
586 | the format of the address, although they cannot actually tell you | |
587 | if it is a deliverable address (i.e. that mail to the address | |
588 | will not bounce). Modules like Mail::CheckUser and Mail::EXPN | |
589 | try to interact with the domain name system or particular | |
590 | mail servers to learn even more, but their methods do not | |
591 | work everywhere\-\-\-especially for security conscious administrators. | |
592 | .PP | |
593 | Many are tempted to try to eliminate many frequently-invalid | |
594 | mail addresses with a simple regex, such as | |
595 | \&\f(CW\*(C`/^[\ew.\-]+\e@(?:[\ew\-]+\e.)+\ew+$/\*(C'\fR. It's a very bad idea. However, | |
596 | this also throws out many valid ones, and says nothing about | |
597 | potential deliverability, so it is not suggested. Instead, see | |
598 | http://www.cpan.org/authors/Tom_Christiansen/scripts/ckaddr.gz , | |
599 | which actually checks against the full \s-1RFC\s0 spec (except for nested | |
600 | comments), looks for addresses you may not wish to accept mail to | |
601 | (say, Bill Clinton or your postmaster), and then makes sure that the | |
602 | hostname given can be looked up in the \s-1DNS\s0 \s-1MX\s0 records. It's not fast, | |
603 | but it works for what it tries to do. | |
604 | .PP | |
605 | Our best advice for verifying a person's mail address is to have them | |
606 | enter their address twice, just as you normally do to change a password. | |
607 | This usually weeds out typos. If both versions match, send | |
608 | mail to that address with a personal message that looks somewhat like: | |
609 | .PP | |
610 | .Vb 1 | |
611 | \& Dear someuser@host.com, | |
612 | .Ve | |
613 | .PP | |
614 | .Vb 5 | |
615 | \& Please confirm the mail address you gave us Wed May 6 09:38:41 | |
616 | \& MDT 1998 by replying to this message. Include the string | |
617 | \& "Rumpelstiltskin" in that reply, but spelled in reverse; that is, | |
618 | \& start with "Nik...". Once this is done, your confirmed address will | |
619 | \& be entered into our records. | |
620 | .Ve | |
621 | .PP | |
622 | If you get the message back and they've followed your directions, | |
623 | you can be reasonably assured that it's real. | |
624 | .PP | |
625 | A related strategy that's less open to forgery is to give them a \s-1PIN\s0 | |
626 | (personal \s-1ID\s0 number). Record the address and \s-1PIN\s0 (best that it be a | |
627 | random one) for later processing. In the mail you send, ask them to | |
628 | include the \s-1PIN\s0 in their reply. But if it bounces, or the message is | |
629 | included via a \*(L"vacation\*(R" script, it'll be there anyway. So it's | |
630 | best to ask them to mail back a slight alteration of the \s-1PIN\s0, such as | |
631 | with the characters reversed, one added or subtracted to each digit, etc. | |
632 | .Sh "How do I decode a \s-1MIME/BASE64\s0 string?" | |
633 | .IX Subsection "How do I decode a MIME/BASE64 string?" | |
634 | The MIME\-Base64 package (available from \s-1CPAN\s0) handles this as well as | |
635 | the \s-1MIME/QP\s0 encoding. Decoding \s-1BASE64\s0 becomes as simple as: | |
636 | .PP | |
637 | .Vb 2 | |
638 | \& use MIME::Base64; | |
639 | \& $decoded = decode_base64($encoded); | |
640 | .Ve | |
641 | .PP | |
642 | The MIME-Tools package (available from \s-1CPAN\s0) supports extraction with | |
643 | decoding of \s-1BASE64\s0 encoded attachments and content directly from email | |
644 | messages. | |
645 | .PP | |
646 | If the string to decode is short (less than 84 bytes long) | |
647 | a more direct approach is to use the \fIunpack()\fR function's \*(L"u\*(R" | |
648 | format after minor transliterations: | |
649 | .PP | |
650 | .Vb 4 | |
651 | \& tr#A-Za-z0-9+/##cd; # remove non-base64 chars | |
652 | \& tr#A-Za-z0-9+/# -_#; # convert to uuencoded format | |
653 | \& $len = pack("c", 32 + 0.75*length); # compute length byte | |
654 | \& print unpack("u", $len . $_); # uudecode and print | |
655 | .Ve | |
656 | .Sh "How do I return the user's mail address?" | |
657 | .IX Subsection "How do I return the user's mail address?" | |
658 | On systems that support getpwuid, the $< variable, and the | |
659 | Sys::Hostname module (which is part of the standard perl distribution), | |
660 | you can probably try using something like this: | |
661 | .PP | |
662 | .Vb 2 | |
663 | \& use Sys::Hostname; | |
664 | \& $address = sprintf('%s@%s', scalar getpwuid($<), hostname); | |
665 | .Ve | |
666 | .PP | |
667 | Company policies on mail address can mean that this generates addresses | |
668 | that the company's mail system will not accept, so you should ask for | |
669 | users' mail addresses when this matters. Furthermore, not all systems | |
670 | on which Perl runs are so forthcoming with this information as is Unix. | |
671 | .PP | |
672 | The Mail::Util module from \s-1CPAN\s0 (part of the MailTools package) provides a | |
673 | \&\fImailaddress()\fR function that tries to guess the mail address of the user. | |
674 | It makes a more intelligent guess than the code above, using information | |
675 | given when the module was installed, but it could still be incorrect. | |
676 | Again, the best way is often just to ask the user. | |
677 | .Sh "How do I send mail?" | |
678 | .IX Subsection "How do I send mail?" | |
679 | Use the \f(CW\*(C`sendmail\*(C'\fR program directly: | |
680 | .PP | |
681 | .Vb 6 | |
682 | \& open(SENDMAIL, "|/usr/lib/sendmail -oi -t -odq") | |
683 | \& or die "Can't fork for sendmail: $!\en"; | |
684 | \& print SENDMAIL <<"EOF"; | |
685 | \& From: User Originating Mail <me\e@host> | |
686 | \& To: Final Destination <you\e@otherhost> | |
687 | \& Subject: A relevant subject line | |
688 | .Ve | |
689 | .PP | |
690 | .Vb 4 | |
691 | \& Body of the message goes here after the blank line | |
692 | \& in as many lines as you like. | |
693 | \& EOF | |
694 | \& close(SENDMAIL) or warn "sendmail didn't close nicely"; | |
695 | .Ve | |
696 | .PP | |
697 | The \fB\-oi\fR option prevents sendmail from interpreting a line consisting | |
698 | of a single dot as \*(L"end of message\*(R". The \fB\-t\fR option says to use the | |
699 | headers to decide who to send the message to, and \fB\-odq\fR says to put | |
700 | the message into the queue. This last option means your message won't | |
701 | be immediately delivered, so leave it out if you want immediate | |
702 | delivery. | |
703 | .PP | |
704 | Alternate, less convenient approaches include calling mail (sometimes | |
705 | called mailx) directly or simply opening up port 25 have having an | |
706 | intimate conversation between just you and the remote \s-1SMTP\s0 daemon, | |
707 | probably sendmail. | |
708 | .PP | |
709 | Or you might be able use the \s-1CPAN\s0 module Mail::Mailer: | |
710 | .PP | |
711 | .Vb 1 | |
712 | \& use Mail::Mailer; | |
713 | .Ve | |
714 | .PP | |
715 | .Vb 8 | |
716 | \& $mailer = Mail::Mailer->new(); | |
717 | \& $mailer->open({ From => $from_address, | |
718 | \& To => $to_address, | |
719 | \& Subject => $subject, | |
720 | \& }) | |
721 | \& or die "Can't open: $!\en"; | |
722 | \& print $mailer $body; | |
723 | \& $mailer->close(); | |
724 | .Ve | |
725 | .PP | |
726 | The Mail::Internet module uses Net::SMTP which is less Unix-centric than | |
727 | Mail::Mailer, but less reliable. Avoid raw \s-1SMTP\s0 commands. There | |
728 | are many reasons to use a mail transport agent like sendmail. These | |
729 | include queuing, \s-1MX\s0 records, and security. | |
730 | .Sh "How do I use \s-1MIME\s0 to make an attachment to a mail message?" | |
731 | .IX Subsection "How do I use MIME to make an attachment to a mail message?" | |
732 | This answer is extracted directly from the MIME::Lite documentation. | |
733 | Create a multipart message (i.e., one with attachments). | |
734 | .PP | |
735 | .Vb 1 | |
736 | \& use MIME::Lite; | |
737 | .Ve | |
738 | .PP | |
739 | .Vb 8 | |
740 | \& ### Create a new multipart message: | |
741 | \& $msg = MIME::Lite->new( | |
742 | \& From =>'me@myhost.com', | |
743 | \& To =>'you@yourhost.com', | |
744 | \& Cc =>'some@other.com, some@more.com', | |
745 | \& Subject =>'A message with 2 parts...', | |
746 | \& Type =>'multipart/mixed' | |
747 | \& ); | |
748 | .Ve | |
749 | .PP | |
750 | .Vb 8 | |
751 | \& ### Add parts (each "attach" has same arguments as "new"): | |
752 | \& $msg->attach(Type =>'TEXT', | |
753 | \& Data =>"Here's the GIF file you wanted" | |
754 | \& ); | |
755 | \& $msg->attach(Type =>'image/gif', | |
756 | \& Path =>'aaa000123.gif', | |
757 | \& Filename =>'logo.gif' | |
758 | \& ); | |
759 | .Ve | |
760 | .PP | |
761 | .Vb 1 | |
762 | \& $text = $msg->as_string; | |
763 | .Ve | |
764 | .PP | |
765 | MIME::Lite also includes a method for sending these things. | |
766 | .PP | |
767 | .Vb 1 | |
768 | \& $msg->send; | |
769 | .Ve | |
770 | .PP | |
771 | This defaults to using sendmail but can be customized to use | |
772 | \&\s-1SMTP\s0 via Net::SMTP. | |
773 | .Sh "How do I read mail?" | |
774 | .IX Subsection "How do I read mail?" | |
775 | While you could use the Mail::Folder module from \s-1CPAN\s0 (part of the | |
776 | MailFolder package) or the Mail::Internet module from \s-1CPAN\s0 (part | |
777 | of the MailTools package), often a module is overkill. Here's a | |
778 | mail sorter. | |
779 | .PP | |
780 | .Vb 1 | |
781 | \& #!/usr/bin/perl | |
782 | .Ve | |
783 | .PP | |
784 | .Vb 13 | |
785 | \& my(@msgs, @sub); | |
786 | \& my $msgno = -1; | |
787 | \& $/ = ''; # paragraph reads | |
788 | \& while (<>) { | |
789 | \& if (/^From /m) { | |
790 | \& /^Subject:\es*(?:Re:\es*)*(.*)/mi; | |
791 | \& $sub[++$msgno] = lc($1) || ''; | |
792 | \& } | |
793 | \& $msgs[$msgno] .= $_; | |
794 | \& } | |
795 | \& for my $i (sort { $sub[$a] cmp $sub[$b] || $a <=> $b } (0 .. $#msgs)) { | |
796 | \& print $msgs[$i]; | |
797 | \& } | |
798 | .Ve | |
799 | .PP | |
800 | Or more succinctly, | |
801 | .PP | |
802 | .Vb 6 | |
803 | \& #!/usr/bin/perl -n00 | |
804 | \& # bysub2 - awkish sort-by-subject | |
805 | \& BEGIN { $msgno = -1 } | |
806 | \& $sub[++$msgno] = (/^Subject:\es*(?:Re:\es*)*(.*)/mi)[0] if /^From/m; | |
807 | \& $msg[$msgno] .= $_; | |
808 | \& END { print @msg[ sort { $sub[$a] cmp $sub[$b] || $a <=> $b } (0 .. $#msg) ] } | |
809 | .Ve | |
810 | .Sh "How do I find out my hostname, domainname, or \s-1IP\s0 address?" | |
811 | .IX Xref "hostname, domainname, IP address, host, domain, hostfqdn, inet_ntoa, | |
812 | gethostbyname, Socket, Net::Domain, Sys::Hostname" | |
813 | .IX Subsection "How do I find out my hostname, domainname, or IP address?" | |
814 | (contributed by brian d foy) | |
815 | .PP | |
816 | The Net::Domain module, which is part of the standard distribution starting | |
817 | in perl5.7.3, can get you the fully qualified domain name (\s-1FQDN\s0), the host | |
818 | name, or the domain name. | |
819 | .PP | |
820 | .Vb 1 | |
821 | \& use Net::Domain qw(hostname hostfqdn hostdomain); | |
822 | .Ve | |
823 | .PP | |
824 | .Vb 1 | |
825 | \& my $host = hostfqdn(); | |
826 | .Ve | |
827 | .PP | |
828 | The \f(CW\*(C`Sys::Hostname\*(C'\fR module, included in the standard distribution since | |
829 | perl5.6, can also get the hostname. | |
830 | .PP | |
831 | .Vb 1 | |
832 | \& use Sys::Hostname; | |
833 | .Ve | |
834 | .PP | |
835 | .Vb 1 | |
836 | \& $host = hostname(); | |
837 | .Ve | |
838 | .PP | |
839 | To get the \s-1IP\s0 address, you can use the \f(CW\*(C`gethostbyname\*(C'\fR built-in function | |
840 | to turn the name into a number. To turn that number into the dotted octet | |
841 | form (a.b.c.d) that most people expect, use the \f(CW\*(C`inet_ntoa\*(C'\fR function | |
842 | from the <Socket> module, which also comes with perl. | |
843 | .PP | |
844 | .Vb 1 | |
845 | \& use Socket; | |
846 | .Ve | |
847 | .PP | |
848 | .Vb 3 | |
849 | \& my $address = inet_ntoa( | |
850 | \& scalar gethostbyname( $host || 'localhost' ) | |
851 | \& ); | |
852 | .Ve | |
853 | .Sh "How do I fetch a news article or the active newsgroups?" | |
854 | .IX Subsection "How do I fetch a news article or the active newsgroups?" | |
855 | Use the Net::NNTP or News::NNTPClient modules, both available from \s-1CPAN\s0. | |
856 | This can make tasks like fetching the newsgroup list as simple as | |
857 | .PP | |
858 | .Vb 2 | |
859 | \& perl -MNews::NNTPClient | |
860 | \& -e 'print News::NNTPClient->new->list("newsgroups")' | |
861 | .Ve | |
862 | .Sh "How do I fetch/put an \s-1FTP\s0 file?" | |
863 | .IX Subsection "How do I fetch/put an FTP file?" | |
864 | LWP::Simple (available from \s-1CPAN\s0) can fetch but not put. Net::FTP (also | |
865 | available from \s-1CPAN\s0) is more complex but can put as well as fetch. | |
866 | .Sh "How can I do \s-1RPC\s0 in Perl?" | |
867 | .IX Subsection "How can I do RPC in Perl?" | |
868 | (Contributed by brian d foy) | |
869 | .PP | |
870 | Use one of the \s-1RPC\s0 modules you can find on \s-1CPAN\s0 ( | |
871 | http://search.cpan.org/search?query=RPC&mode=all ). | |
872 | .SH "AUTHOR AND COPYRIGHT" | |
873 | .IX Header "AUTHOR AND COPYRIGHT" | |
874 | Copyright (c) 1997\-2006 Tom Christiansen, Nathan Torkington, and | |
875 | other authors as noted. All rights reserved. | |
876 | .PP | |
877 | This documentation is free; you can redistribute it and/or modify it | |
878 | under the same terms as Perl itself. | |
879 | .PP | |
880 | Irrespective of its distribution, all code examples in this file | |
881 | are hereby placed into the public domain. You are permitted and | |
882 | encouraged to use this code in your own programs for fun | |
883 | or for profit as you see fit. A simple comment in the code giving | |
884 | credit would be courteous but is not required. |