This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Two doublewords less
[perl5.git] / pod / perlfaq9.pod
CommitLineData
68dc0745
PP
1=head1 NAME
2
3fe9a6f1 3perlfaq9 - Networking ($Revision: 1.15 $, $Date: 1997/03/25 18:17:20 $)
68dc0745
PP
4
5=head1 DESCRIPTION
6
7This section deals with questions related to networking, the internet,
8and a few on the web.
9
10=head2 My CGI script runs from the command line but not the browser. Can you help me fix it?
11
12Sure, but you probably can't afford our contracting rates :-)
13
14Seriously, if you can demonstrate that you've read the following FAQs
15and that your problem isn't something simple that can be easily
16answered, you'll probably receive a courteous and useful reply to your
17question if you post it on comp.infosystems.www.authoring.cgi (if it's
18something to do with HTTP, HTML, or the CGI protocols). Questions that
19appear to be Perl questions but are really CGI ones that are posted to
20comp.lang.perl.misc may not be so well received.
21
22The useful FAQs are:
23
24 http://www.perl.com/perl/faq/idiots-guide.html
25 http://www3.pair.com/webthing/docs/cgi/faqs/cgifaq.shtml
26 http://www.perl.com/perl/faq/perl-cgi-faq.html
27 http://www-genome.wi.mit.edu/WWW/faqs/www-security-faq.html
28 http://www.boutell.com/faq/
29
30=head2 How do I remove HTML from a string?
31
32The most correct way (albeit not the fastest) is to use HTML::Parse
33from CPAN (part of the libwww-perl distribution, which is a must-have
34module for all web hackers).
35
36Many folks attempt a simple-minded regular expression approach, like
37C<s/E<lt>.*?E<gt>//g>, but that fails in many cases because the tags
38may continue over line breaks, they may contain quoted angle-brackets,
39or HTML comment may be present. Plus folks forget to convert
40entities, like C<&lt;> for example.
41
42Here's one "simple-minded" approach, that works for most files:
43
44 #!/usr/bin/perl -p0777
45 s/<(?:[^>'"]*|(['"]).*?\1)*>//gs
46
47If you want a more complete solution, see the 3-stage striphtml
48program in
49http://www.perl.com/CPAN/authors/Tom_Christiansen/scripts/striphtml.gz
50.
51
52=head2 How do I extract URLs?
53
54310121 54A quick but imperfect approach is
68dc0745
PP
55
56 #!/usr/bin/perl -n00
57 # qxurl - tchrist@perl.com
58 print "$2\n" while m{
59 < \s*
60 A \s+ HREF \s* = \s* (["']) (.*?) \1
61 \s* >
62 }gsix;
63
64This version does not adjust relative URLs, understand alternate
65bases, deal with HTML comments, or accept URLs themselves as
66arguments. It also runs about 100x faster than a more "complete"
67solution using the LWP suite of modules, such as the
68http://www.perl.com/CPAN/authors/Tom_Christiansen/scripts/xurl.gz
69program.
70
71=head2 How do I download a file from the user's machine? How do I open a file on another machine?
72
73In the context of an HTML form, you can use what's known as
74B<multipart/form-data> encoding. The CGI.pm module (available from
75CPAN) supports this in the start_multipart_form() method, which isn't
76the same as the startform() method.
77
78=head2 How do I make a pop-up menu in HTML?
79
80Use the B<E<lt>SELECTE<gt>> and B<E<lt>OPTIONE<gt>> tags. The CGI.pm
81module (available from CPAN) supports this widget, as well as many
82others, including some that it cleverly synthesizes on its own.
83
84=head2 How do I fetch an HTML file?
85
86Use the LWP::Simple module available from CPAN, part of the excellent
87libwww-perl (LWP) package. On the other hand, and if you have the
88lynx text-based HTML browser installed on your system, this isn't too
89bad:
90
91 $html_code = `lynx -source $url`;
92 $text_data = `lynx -dump $url`;
93
94=head2 how do I decode or create those %-encodings on the web?
95
96Here's an example of decoding:
97
98 $string = "http://altavista.digital.com/cgi-bin/query?pg=q&what=news&fmt=.&q=%2Bcgi-bin+%2Bperl.exe";
99 $string =~ s/%([a-fA-F0-9]{2})/chr(hex($1))/ge;
100
101Encoding is a bit harder, because you can't just blindly change
102all the non-alphanumunder character (C<\W>) into their hex escapes.
103It's important that characters with special meaning like C</> and C<?>
104I<not> be translated. Probably the easiest way to get this right is
105to avoid reinventing the wheel and just use the URI::Escape module,
106which is part of the libwww-perl package (LWP) available from CPAN.
107
108=head2 How do I redirect to another page?
109
110Instead of sending back a C<Content-Type> as the headers of your
111reply, send back a C<Location:> header. Officially this should be a
112C<URI:> header, so the CGI.pm module (available from CPAN) sends back
113both:
114
115 Location: http://www.domain.com/newpage
116 URI: http://www.domain.com/newpage
117
118Note that relative URLs in these headers can cause strange effects
119because of "optimizations" that servers do.
120
121=head2 How do I put a password on my web pages?
122
123That depends. You'll need to read the documentation for your web
124server, or perhaps check some of the other FAQs referenced above.
125
126=head2 How do I edit my .htpasswd and .htgroup files with Perl?
127
128The HTTPD::UserAdmin and HTTPD::GroupAdmin modules provide a
129consistent OO interface to these files, regardless of how they're
54310121 130stored. Databases may be text, dbm, Berkeley DB or any database with a
68dc0745
PP
131DBI compatible driver. HTTPD::UserAdmin supports files used by the
132`Basic' and `Digest' authentication schemes. Here's an example:
133
134 use HTTPD::UserAdmin ();
135 HTTPD::UserAdmin
136 ->new(DB => "/foo/.htpasswd")
137 ->add($username => $password);
138
139=head2 How do I parse an email header?
140
141For a quick-and-dirty solution, try this solution derived
142from page 222 of the 2nd edition of "Programming Perl":
143
144 $/ = '';
145 $header = <MSG>;
146 $header =~ s/\n\s+/ /g; # merge continuation lines
147 %head = ( UNIX_FROM_LINE, split /^([-\w]+):\s*/m, $header );
148
149That solution doesn't do well if, for example, you're trying to
150maintain all the Received lines. A more complete approach is to use
151the Mail::Header module from CPAN (part of the MailTools package).
152
153=head2 How do I decode a CGI form?
154
155A lot of people are tempted to code this up themselves, so you've
156probably all seen a lot of code involving C<$ENV{CONTENT_LENGTH}> and
157C<$ENV{QUERY_STRING}>. It's true that this can work, but there are
158also a lot of versions of this floating around that are quite simply
159broken!
160
161Please do not be tempted to reinvent the wheel. Instead, use the
162CGI.pm or CGI_Lite.pm (available from CPAN), or if you're trapped in
163the module-free land of perl1 .. perl4, you might look into cgi-lib.pl
164(available from http://www.bio.cam.ac.uk/web/form.html).
165
166=head2 How do I check a valid email address?
167
168You can't.
169
170Without sending mail to the address and seeing whether it bounces (and
171even then you face the halting problem), you cannot determine whether
172an email address is valid. Even if you apply the email header
173standard, you can have problems, because there are deliverable
174addresses that aren't RFC-822 (the mail header standard) compliant,
175and addresses that aren't deliverable which are compliant.
176
177Many are tempted to try to eliminate many frequently-invalid email
178addresses with a simple regexp, such as
179C</^[\w.-]+\@([\w.-]\.)+\w+$/>. However, this also throws out many
180valid ones, and says nothing about potential deliverability, so is not
181suggested. Instead, see
182http://www.perl.com/CPAN/authors/Tom_Christiansen/scripts/ckaddr.gz ,
183which actually checks against the full RFC spec (except for nested
184comments), looks for addresses you may not wish to accept email to
185(say, Bill Clinton or your postmaster), and then makes sure that the
186hostname given can be looked up in DNS. It's not fast, but it works.
187
188=head2 How do I decode a MIME/BASE64 string?
189
190The MIME-tools package (available from CPAN) handles this and a lot
191more. Decoding BASE64 becomes as simple as:
192
193 use MIME::base64;
194 $decoded = decode_base64($encoded);
195
196A more direct approach is to use the unpack() function's "u"
197format after minor transliterations:
198
199 tr#A-Za-z0-9+/##cd; # remove non-base64 chars
200 tr#A-Za-z0-9+/# -_#; # convert to uuencoded format
201 $len = pack("c", 32 + 0.75*length); # compute length byte
202 print unpack("u", $len . $_); # uudecode and print
203
204=head2 How do I return the user's email address?
205
206On systems that support getpwuid, the $E<lt> variable and the
207Sys::Hostname module (which is part of the standard perl distribution),
208you can probably try using something like this:
209
210 use Sys::Hostname;
211 $address = sprintf('%s@%s', getpwuid($<), hostname);
212
213Company policies on email address can mean that this generates addresses
214that the company's email system will not accept, so you should ask for
215users' email addresses when this matters. Furthermore, not all systems
216on which Perl runs are so forthcoming with this information as is Unix.
217
218The Mail::Util module from CPAN (part of the MailTools package) provides a
219mailaddress() function that tries to guess the mail address of the user.
220It makes a more intelligent guess than the code above, using information
221given when the module was installed, but it could still be incorrect.
222Again, the best way is often just to ask the user.
223
224=head2 How do I send/read mail?
225
226Sending mail: the Mail::Mailer module from CPAN (part of the MailTools
54310121
PP
227package) is Unix-centric, while Mail::Internet uses Net::SMTP which is
228not Unix-centric. Reading mail: use the Mail::Folder module from CPAN
68dc0745
PP
229(part of the MailFolder package) or the Mail::Internet module from
230CPAN (also part of the MailTools package).
231
3fe9a6f1
PP
232 # sending mail
233 use Mail::Internet;
234 use Mail::Header;
235 # say which mail host to use
236 $ENV{SMTPHOSTS} = 'mail.frii.com';
237 # create headers
238 $header = new Mail::Header;
239 $header->add('From', 'gnat@frii.com');
240 $header->add('Subject', 'Testing');
241 $header->add('To', 'gnat@frii.com');
242 # create body
243 $body = 'This is a test, ignore';
244 # create mail object
245 $mail = new Mail::Internet(undef, Header => $header, Body => \[$body]);
246 # send it
247 $mail->smtpsend or die;
248
68dc0745
PP
249=head2 How do I find out my hostname/domainname/IP address?
250
251A lot of code has historically cavalierly called the C<`hostname`>
252program. While sometimes expedient, this isn't very portable. It's
253one of those tradeoffs of convenience versus portability.
254
255The Sys::Hostname module (part of the standard perl distribution) will
256give you the hostname after which you can find out the IP address
257(assuming you have working DNS) with a gethostbyname() call.
258
259 use Socket;
260 use Sys::Hostname;
261 my $host = hostname();
262 my $addr = inet_ntoa(scalar(gethostbyname($name)) || 'localhost');
263
264Probably the simplest way to learn your DNS domain name is to grok
265it out of /etc/resolv.conf, at least under Unix. Of course, this
266assumes several things about your resolv.conf configuration, including
267that it exists.
268
269(We still need a good DNS domain name-learning method for non-Unix
270systems.)
271
272=head2 How do I fetch a news article or the active newsgroups?
273
274Use the Net::NNTP or News::NNTPClient modules, both available from CPAN.
275This can make tasks like fetching the newsgroup list as simple as:
276
277 perl -MNews::NNTPClient
278 -e 'print News::NNTPClient->new->list("newsgroups")'
279
280=head2 How do I fetch/put an FTP file?
281
282LWP::Simple (available from CPAN) can fetch but not put. Net::FTP (also
283available from CPAN) is more complex but can put as well as fetch.
284
285=head2 How can I do RPC in Perl?
286
287A DCE::RPC module is being developed (but is not yet available), and
288will be released as part of the DCE-Perl package (available from
289CPAN). No ONC::RPC module is known.
290
291=head1 AUTHOR AND COPYRIGHT
292
293Copyright (c) 1997 Tom Christiansen and Nathan Torkington.
294All rights reserved. See L<perlfaq> for distribution information.