note strict/lax version requirements in documentation
[p5sagit/p5-mst-13.2.git] / pod / perlfaq9.pod
1 =head1 NAME
2
3 perlfaq9 - Networking
4
5 =head1 DESCRIPTION
6
7 This section deals with questions related to networking, the internet,
8 and a few on the web.
9
10 =head2 What is the correct form of response from a CGI script?
11
12 (Alan Flavell <flavell+www@a5.ph.gla.ac.uk> answers...)
13
14 The Common Gateway Interface (CGI) specifies a software interface between
15 a program ("CGI script") and a web server (HTTPD). It is not specific
16 to Perl, and has its own FAQs and tutorials, and usenet group,
17 comp.infosystems.www.authoring.cgi
18
19 The CGI specification is outlined in an informational RFC:
20 http://www.ietf.org/rfc/rfc3875
21
22 Other relevant documentation listed in: http://www.perl.org/CGI_MetaFAQ.html
23
24 These Perl FAQs very selectively cover some CGI issues. However, Perl
25 programmers are strongly advised to use the C<CGI.pm> module, to take care
26 of the details for them.
27
28 The similarity between CGI response headers (defined in the CGI
29 specification) and HTTP response headers (defined in the HTTP
30 specification, RFC2616) is intentional, but can sometimes be confusing.
31
32 The CGI specification defines two kinds of script: the "Parsed Header"
33 script, and the "Non Parsed Header" (NPH) script. Check your server
34 documentation to see what it supports. "Parsed Header" scripts are
35 simpler in various respects. The CGI specification allows any of the
36 usual newline representations in the CGI response (it's the server's
37 job to create an accurate HTTP response based on it). So "\n" written in
38 text mode is technically correct, and recommended. NPH scripts are more
39 tricky: they must put out a complete and accurate set of HTTP
40 transaction response headers; the HTTP specification calls for records
41 to be terminated with carriage-return and line-feed, i.e ASCII \015\012
42 written in binary mode.
43
44 Using C<CGI.pm> gives excellent platform independence, including EBCDIC
45 systems. C<CGI.pm> selects an appropriate newline representation
46 (C<$CGI::CRLF>) and sets binmode as appropriate.
47
48 =head2 My CGI script runs from the command line but not the browser.  (500 Server Error)
49
50 Several things could be wrong.  You can go through the "Troubleshooting
51 Perl CGI scripts" guide at
52
53         http://www.perl.org/troubleshooting_CGI.html
54
55 If, after that, you can demonstrate that you've read the FAQs and that
56 your problem isn't something simple that can be easily answered, you'll
57 probably receive a courteous and useful reply to your question if you
58 post it on comp.infosystems.www.authoring.cgi (if it's something to do
59 with HTTP or the CGI protocols).  Questions that appear to be Perl
60 questions but are really CGI ones that are posted to comp.lang.perl.misc
61 are not so well received.
62
63 The useful FAQs, related documents, and troubleshooting guides are
64 listed in the CGI Meta FAQ:
65
66         http://www.perl.org/CGI_MetaFAQ.html
67
68 =head2 How can I get better error messages from a CGI program?
69
70 Use the C<CGI::Carp> module.  It replaces C<warn> and C<die>, plus the
71 normal C<Carp> modules C<carp>, C<croak>, and C<confess> functions with
72 more verbose and safer versions.  It still sends them to the normal
73 server error log.
74
75         use CGI::Carp;
76         warn "This is a complaint";
77         die "But this one is serious";
78
79 The following use of C<CGI::Carp> also redirects errors to a file of your choice,
80 placed in a C<BEGIN> block to catch compile-time warnings as well:
81
82         BEGIN {
83                 use CGI::Carp qw(carpout);
84                 open(LOG, ">>/var/local/cgi-logs/mycgi-log")
85                         or die "Unable to append to mycgi-log: $!\n";
86                 carpout(*LOG);
87         }
88
89 You can even arrange for fatal errors to go back to the client browser,
90 which is nice for your own debugging, but might confuse the end user.
91
92         use CGI::Carp qw(fatalsToBrowser);
93         die "Bad error here";
94
95 Even if the error happens before you get the HTTP header out, the module
96 will try to take care of this to avoid the dreaded server 500 errors.
97 Normal warnings still go out to the server error log (or wherever
98 you've sent them with C<carpout>) with the application name and date
99 stamp prepended.
100
101 =head2 How do I remove HTML from a string?
102
103 The most correct way (albeit not the fastest) is to use C<HTML::Parser>
104 from CPAN.  Another mostly correct
105 way is to use C<HTML::FormatText> which not only removes HTML but also
106 attempts to do a little simple formatting of the resulting plain text.
107
108 Many folks attempt a simple-minded regular expression approach, like
109 C<< s/<.*?>//g >>, but that fails in many cases because the tags
110 may continue over line breaks, they may contain quoted angle-brackets,
111 or HTML comment may be present.  Plus, folks forget to convert
112 entities--like C<&lt;> for example.
113
114 Here's one "simple-minded" approach, that works for most files:
115
116         #!/usr/bin/perl -p0777
117         s/<(?:[^>'"]*|(['"]).*?\1)*>//gs
118
119 If you want a more complete solution, see the 3-stage striphtml
120 program in
121 http://www.cpan.org/authors/Tom_Christiansen/scripts/striphtml.gz
122 .
123
124 Here are some tricky cases that you should think about when picking
125 a solution:
126
127         <IMG SRC = "foo.gif" ALT = "A > B">
128
129         <IMG SRC = "foo.gif"
130          ALT = "A > B">
131
132         <!-- <A comment> -->
133
134         <script>if (a<b && a>c)</script>
135
136         <# Just data #>
137
138         <![INCLUDE CDATA [ >>>>>>>>>>>> ]]>
139
140 If HTML comments include other tags, those solutions would also break
141 on text like this:
142
143         <!-- This section commented out.
144                 <B>You can't see me!</B>
145         -->
146
147 =head2 How do I extract URLs?
148
149 You can easily extract all sorts of URLs from HTML with
150 C<HTML::SimpleLinkExtor> which handles anchors, images, objects,
151 frames, and many other tags that can contain a URL.  If you need
152 anything more complex, you can create your own subclass of
153 C<HTML::LinkExtor> or C<HTML::Parser>.  You might even use
154 C<HTML::SimpleLinkExtor> as an example for something specifically
155 suited to your needs.
156
157 You can use C<URI::Find> to extract URLs from an arbitrary text document.
158
159 Less complete solutions involving regular expressions can save
160 you a lot of processing time if you know that the input is simple.  One
161 solution from Tom Christiansen runs 100 times faster than most
162 module based approaches but only extracts URLs from anchors where the first
163 attribute is HREF and there are no other attributes.
164
165         #!/usr/bin/perl -n00
166         # qxurl - tchrist@perl.com
167         print "$2\n" while m{
168                 < \s*
169                   A \s+ HREF \s* = \s* (["']) (.*?) \1
170                 \s* >
171         }gsix;
172
173 =head2 How do I download a file from the user's machine?  How do I open a file on another machine?
174
175 In this case, download means to use the file upload feature of HTML
176 forms.  You allow the web surfer to specify a file to send to your web
177 server.  To you it looks like a download, and to the user it looks
178 like an upload.  No matter what you call it, you do it with what's
179 known as B<multipart/form-data> encoding.  The C<CGI.pm> module (which
180 comes with Perl as part of the Standard Library) supports this in the
181 C<start_multipart_form()> method, which isn't the same as the C<startform()>
182 method.
183
184 See the section in the C<CGI.pm> documentation on file uploads for code
185 examples and details.
186
187 =head2 How do I make an HTML pop-up menu with Perl?
188
189 (contributed by brian d foy)
190
191 The C<CGI.pm> module (which comes with Perl) has functions to create
192 the HTML form widgets. See the C<CGI.pm> documentation for more
193 examples.
194
195         use CGI qw/:standard/;
196         print header,
197                 start_html('Favorite Animals'),
198
199                 start_form,
200                         "What's your favorite animal? ",
201                 popup_menu(
202                         -name   => 'animal',
203                         -values => [ qw( Llama Alpaca Camel Ram ) ]
204                         ),
205                 submit,
206
207                 end_form,
208                 end_html;
209
210 =head2 How do I fetch an HTML file?
211
212 (contributed by brian d foy)
213
214 Use the libwww-perl distribution. The C<LWP::Simple> module can fetch web
215 resources and give their content back to you as a string:
216
217         use LWP::Simple qw(get);
218
219         my $html = get( "http://www.example.com/index.html" );
220
221 It can also store the resource directly in a file:
222
223         use LWP::Simple qw(getstore);
224
225         getstore( "http://www.example.com/index.html", "foo.html" );
226
227 If you need to do something more complicated, you can use
228 C<LWP::UserAgent> module to create your own user-agent (e.g. browser)
229 to get the job done. If you want to simulate an interactive web
230 browser, you can use the C<WWW::Mechanize> module.
231
232 =head2 How do I automate an HTML form submission?
233
234 If you are doing something complex, such as moving through many pages
235 and forms or a web site, you can use C<WWW::Mechanize>.  See its
236 documentation for all the details.
237
238 If you're submitting values using the GET method, create a URL and encode
239 the form using the C<query_form> method:
240
241         use LWP::Simple;
242         use URI::URL;
243
244         my $url = url('http://www.perl.com/cgi-bin/cpan_mod');
245         $url->query_form(module => 'DB_File', readme => 1);
246         $content = get($url);
247
248 If you're using the POST method, create your own user agent and encode
249 the content appropriately.
250
251         use HTTP::Request::Common qw(POST);
252         use LWP::UserAgent;
253
254         $ua = LWP::UserAgent->new();
255         my $req = POST 'http://www.perl.com/cgi-bin/cpan_mod',
256                                    [ module => 'DB_File', readme => 1 ];
257         $content = $ua->request($req)->as_string;
258
259 =head2 How do I decode or create those %-encodings on the web?
260 X<URI> X<CGI.pm> X<CGI> X<URI::Escape> X<RFC 2396>
261
262 (contributed by brian d foy)
263
264 Those C<%> encodings handle reserved characters in URIs, as described
265 in RFC 2396, Section 2. This encoding replaces the reserved character
266 with the hexadecimal representation of the character's number from
267 the US-ASCII table. For instance, a colon, C<:>, becomes C<%3A>.
268
269 In CGI scripts, you don't have to worry about decoding URIs if you are
270 using C<CGI.pm>. You shouldn't have to process the URI yourself,
271 either on the way in or the way out.
272
273 If you have to encode a string yourself, remember that you should
274 never try to encode an already-composed URI. You need to escape the
275 components separately then put them together. To encode a string, you
276 can use the the C<URI::Escape> module. The C<uri_escape> function
277 returns the escaped string:
278
279         my $original = "Colon : Hash # Percent %";
280
281         my $escaped = uri_escape( $original );
282
283         print "$escaped\n"; # 'Colon%20%3A%20Hash%20%23%20Percent%20%25'
284
285 To decode the string, use the C<uri_unescape> function:
286
287         my $unescaped = uri_unescape( $escaped );
288
289         print $unescaped; # back to original
290
291 If you wanted to do it yourself, you simply need to replace the
292 reserved characters with their encodings. A global substitution
293 is one way to do it:
294
295         # encode
296         $string =~ s/([^^A-Za-z0-9\-_.!~*'()])/ sprintf "%%%0x", ord $1 /eg;
297
298         #decode
299         $string =~ s/%([A-Fa-f\d]{2})/chr hex $1/eg;
300
301 =head2 How do I redirect to another page?
302
303 Specify the complete URL of the destination (even if it is on the same
304 server). This is one of the two different kinds of CGI "Location:"
305 responses which are defined in the CGI specification for a Parsed Headers
306 script. The other kind (an absolute URLpath) is resolved internally to
307 the server without any HTTP redirection. The CGI specifications do not
308 allow relative URLs in either case.
309
310 Use of C<CGI.pm> is strongly recommended.  This example shows redirection
311 with a complete URL. This redirection is handled by the web browser.
312
313         use CGI qw/:standard/;
314
315         my $url = 'http://www.cpan.org/';
316         print redirect($url);
317
318 This example shows a redirection with an absolute URLpath.  This
319 redirection is handled by the local web server.
320
321         my $url = '/CPAN/index.html';
322         print redirect($url);
323
324 But if coded directly, it could be as follows (the final "\n" is
325 shown separately, for clarity), using either a complete URL or
326 an absolute URLpath.
327
328         print "Location: $url\n";   # CGI response header
329         print "\n";                 # end of headers
330
331 =head2 How do I put a password on my web pages?
332
333 To enable authentication for your web server, you need to configure
334 your web server.  The configuration is different for different sorts
335 of web servers--apache does it differently from iPlanet which does
336 it differently from IIS.  Check your web server documentation for
337 the details for your particular server.
338
339 =head2 How do I edit my .htpasswd and .htgroup files with Perl?
340
341 The C<HTTPD::UserAdmin> and C<HTTPD::GroupAdmin> modules provide a
342 consistent OO interface to these files, regardless of how they're
343 stored.  Databases may be text, dbm, Berkeley DB or any database with
344 a DBI compatible driver.  C<HTTPD::UserAdmin> supports files used by the
345 "Basic" and "Digest" authentication schemes.  Here's an example:
346
347         use HTTPD::UserAdmin ();
348         HTTPD::UserAdmin
349           ->new(DB => "/foo/.htpasswd")
350           ->add($username => $password);
351
352 =head2 How do I make sure users can't enter values into a form that cause my CGI script to do bad things?
353
354 See the security references listed in the CGI Meta FAQ
355
356         http://www.perl.org/CGI_MetaFAQ.html
357
358 =head2 How do I parse a mail header?
359
360 For a quick-and-dirty solution, try this solution derived
361 from L<perlfunc/split>:
362
363         $/ = '';
364         $header = <MSG>;
365         $header =~ s/\n\s+/ /g;  # merge continuation lines
366         %head = ( UNIX_FROM_LINE, split /^([-\w]+):\s*/m, $header );
367
368 That solution doesn't do well if, for example, you're trying to
369 maintain all the Received lines.  A more complete approach is to use
370 the C<Mail::Header> module from CPAN (part of the C<MailTools> package).
371
372 =head2 How do I decode a CGI form?
373
374 (contributed by brian d foy)
375
376 Use the C<CGI.pm> module that comes with Perl.  It's quick,
377 it's easy, and it actually does quite a bit of work to
378 ensure things happen correctly.  It handles GET, POST, and
379 HEAD requests, multipart forms, multivalued fields, query
380 string and message body combinations, and many other things
381 you probably don't want to think about.
382
383 It doesn't get much easier: the C<CGI.pm> module automatically
384 parses the input and makes each value available through the
385 C<param()> function.
386
387         use CGI qw(:standard);
388
389         my $total = param( 'price' ) + param( 'shipping' );
390
391         my @items = param( 'item' ); # multiple values, same field name
392
393 If you want an object-oriented approach, C<CGI.pm> can do that too.
394
395         use CGI;
396
397         my $cgi = CGI->new();
398
399         my $total = $cgi->param( 'price' ) + $cgi->param( 'shipping' );
400
401         my @items = $cgi->param( 'item' );
402
403 You might also try C<CGI::Minimal> which is a lightweight version
404 of the same thing.  Other CGI::* modules on CPAN might work better
405 for you, too.
406
407 Many people try to write their own decoder (or copy one from
408 another program) and then run into one of the many "gotchas"
409 of the task.  It's much easier and less hassle to use C<CGI.pm>.
410
411 =head2 How do I check a valid mail address?
412
413 (partly contributed by Aaron Sherman)
414
415 This isn't as simple a question as it sounds.  There are two parts:
416
417 a) How do I verify that an email address is correctly formatted?
418
419 b) How do I verify that an email address targets a valid recipient?
420
421 Without sending mail to the address and seeing whether there's a human
422 on the other end to answer you, you cannot fully answer part I<b>, but
423 either the C<Email::Valid> or the C<RFC::RFC822::Address> module will do
424 both part I<a> and part I<b> as far as you can in real-time.
425
426 If you want to just check part I<a> to see that the address is valid
427 according to the mail header standard with a simple regular expression,
428 you can have problems, because there are deliverable addresses that
429 aren't RFC-2822 (the latest mail header standard) compliant, and
430 addresses that aren't deliverable which, are compliant.  However,  the
431 following will match valid RFC-2822 addresses that do not have comments,
432 folding whitespace, or any other obsolete or non-essential elements.
433 This I<just> matches the address itself:
434
435         my $atom       = qr{[a-zA-Z0-9_!#\$\%&'*+/=?\^`{}~|\-]+};
436         my $dot_atom   = qr{$atom(?:\.$atom)*};
437         my $quoted     = qr{"(?:\\[^\r\n]|[^\\"])*"};
438         my $local      = qr{(?:$dot_atom|$quoted)};
439         my $quotedpair = qr{\\[\x00-\x09\x0B-\x0c\x0e-\x7e]};
440         my $domain_lit = qr{\[(?:$quotedpair|[\x21-\x5a\x5e-\x7e])*\]};
441         my $domain     = qr{(?:$dot_atom|$domain_lit)};
442         my $addr_spec  = qr{$local\@$domain};
443
444 Just match an address against C</^${addr_spec}$/> to see if it follows
445 the RFC2822 specification.  However, because it is impossible to be
446 sure that such a correctly formed address is actually the correct way
447 to reach a particular person or even has a mailbox associated with it,
448 you must be very careful about how you use this.
449
450 Our best advice for verifying a person's mail address is to have them
451 enter their address twice, just as you normally do to change a
452 password. This usually weeds out typos. If both versions match, send
453 mail to that address with a personal message. If you get the message
454 back and they've followed your directions, you can be reasonably
455 assured that it's real.
456
457 A related strategy that's less open to forgery is to give them a PIN
458 (personal ID number).  Record the address and PIN (best that it be a
459 random one) for later processing. In the mail you send, ask them to
460 include the PIN in their reply.  But if it bounces, or the message is
461 included via a "vacation" script, it'll be there anyway.  So it's
462 best to ask them to mail back a slight alteration of the PIN, such as
463 with the characters reversed, one added or subtracted to each digit, etc.
464
465 =head2 How do I decode a MIME/BASE64 string?
466
467 The C<MIME-Base64> package (available from CPAN) handles this as well as
468 the MIME/QP encoding.  Decoding BASE64 becomes as simple as:
469
470         use MIME::Base64;
471         $decoded = decode_base64($encoded);
472
473 The C<MIME-Tools> package (available from CPAN) supports extraction with
474 decoding of BASE64 encoded attachments and content directly from email
475 messages.
476
477 If the string to decode is short (less than 84 bytes long)
478 a more direct approach is to use the C<unpack()> function's "u"
479 format after minor transliterations:
480
481         tr#A-Za-z0-9+/##cd;                   # remove non-base64 chars
482         tr#A-Za-z0-9+/# -_#;                  # convert to uuencoded format
483         $len = pack("c", 32 + 0.75*length);   # compute length byte
484         print unpack("u", $len . $_);         # uudecode and print
485
486 =head2 How do I return the user's mail address?
487
488 On systems that support getpwuid, the C<< $< >> variable, and the
489 C<Sys::Hostname> module (which is part of the standard perl distribution),
490 you can probably try using something like this:
491
492         use Sys::Hostname;
493         $address = sprintf('%s@%s', scalar getpwuid($<), hostname);
494
495 Company policies on mail address can mean that this generates addresses
496 that the company's mail system will not accept, so you should ask for
497 users' mail addresses when this matters.  Furthermore, not all systems
498 on which Perl runs are so forthcoming with this information as is Unix.
499
500 The C<Mail::Util> module from CPAN (part of the C<MailTools> package) provides a
501 C<mailaddress()> function that tries to guess the mail address of the user.
502 It makes a more intelligent guess than the code above, using information
503 given when the module was installed, but it could still be incorrect.
504 Again, the best way is often just to ask the user.
505
506 =head2 How do I send mail?
507
508 Use the C<sendmail> program directly:
509
510         open(SENDMAIL, "|/usr/lib/sendmail -oi -t -odq")
511                 or die "Can't fork for sendmail: $!\n";
512         print SENDMAIL <<"EOF";
513         From: User Originating Mail <me\@host>
514         To: Final Destination <you\@otherhost>
515         Subject: A relevant subject line
516
517         Body of the message goes here after the blank line
518         in as many lines as you like.
519         EOF
520         close(SENDMAIL)     or warn "sendmail didn't close nicely";
521
522 The B<-oi> option prevents C<sendmail> from interpreting a line consisting
523 of a single dot as "end of message".  The B<-t> option says to use the
524 headers to decide who to send the message to, and B<-odq> says to put
525 the message into the queue.  This last option means your message won't
526 be immediately delivered, so leave it out if you want immediate
527 delivery.
528
529 Alternate, less convenient approaches include calling C<mail> (sometimes
530 called C<mailx>) directly or simply opening up port 25 have having an
531 intimate conversation between just you and the remote SMTP daemon,
532 probably C<sendmail>.
533
534 Or you might be able use the CPAN module C<Mail::Mailer>:
535
536         use Mail::Mailer;
537
538         $mailer = Mail::Mailer->new();
539         $mailer->open({ From    => $from_address,
540                                         To      => $to_address,
541                                         Subject => $subject,
542                                   })
543                 or die "Can't open: $!\n";
544         print $mailer $body;
545         $mailer->close();
546
547 The C<Mail::Internet> module uses C<Net::SMTP> which is less Unix-centric than
548 C<Mail::Mailer>, but less reliable.  Avoid raw SMTP commands.  There
549 are many reasons to use a mail transport agent like C<sendmail>.  These
550 include queuing, MX records, and security.
551
552 =head2 How do I use MIME to make an attachment to a mail message?
553
554 This answer is extracted directly from the C<MIME::Lite> documentation.
555 Create a multipart message (i.e., one with attachments).
556
557         use MIME::Lite;
558
559         ### Create a new multipart message:
560         $msg = MIME::Lite->new(
561                                  From    =>'me@myhost.com',
562                                  To      =>'you@yourhost.com',
563                                  Cc      =>'some@other.com, some@more.com',
564                                  Subject =>'A message with 2 parts...',
565                                  Type    =>'multipart/mixed'
566                                  );
567
568         ### Add parts (each "attach" has same arguments as "new"):
569         $msg->attach(Type     =>'TEXT',
570                                  Data     =>"Here's the GIF file you wanted"
571                                  );
572         $msg->attach(Type     =>'image/gif',
573                                  Path     =>'aaa000123.gif',
574                                  Filename =>'logo.gif'
575                                  );
576
577         $text = $msg->as_string;
578
579 C<MIME::Lite> also includes a method for sending these things.
580
581         $msg->send;
582
583 This defaults to using L<sendmail> but can be customized to use
584 SMTP via L<Net::SMTP>.
585
586 =head2 How do I read mail?
587
588 While you could use the C<Mail::Folder> module from CPAN (part of the
589 C<MailFolder> package) or the C<Mail::Internet> module from CPAN (part
590 of the C<MailTools> package), often a module is overkill.  Here's a
591 mail sorter.
592
593         #!/usr/bin/perl
594
595         my(@msgs, @sub);
596         my $msgno = -1;
597         $/ = '';                    # paragraph reads
598         while (<>) {
599                 if (/^From /m) {
600                         /^Subject:\s*(?:Re:\s*)*(.*)/mi;
601                         $sub[++$msgno] = lc($1) || '';
602                 }
603                 $msgs[$msgno] .= $_;
604         }
605         for my $i (sort { $sub[$a] cmp $sub[$b] || $a <=> $b } (0 .. $#msgs)) {
606                 print $msgs[$i];
607         }
608
609 Or more succinctly,
610
611         #!/usr/bin/perl -n00
612         # bysub2 - awkish sort-by-subject
613         BEGIN { $msgno = -1 }
614         $sub[++$msgno] = (/^Subject:\s*(?:Re:\s*)*(.*)/mi)[0] if /^From/m;
615         $msg[$msgno] .= $_;
616         END { print @msg[ sort { $sub[$a] cmp $sub[$b] || $a <=> $b } (0 .. $#msg) ] }
617
618 =head2 How do I find out my hostname, domainname, or IP address?
619 X<hostname, domainname, IP address, host, domain, hostfqdn, inet_ntoa,
620 gethostbyname, Socket, Net::Domain, Sys::Hostname>
621
622 (contributed by brian d foy)
623
624 The C<Net::Domain> module, which is part of the standard distribution starting
625 in perl5.7.3, can get you the fully qualified domain name (FQDN), the host
626 name, or the domain name.
627
628         use Net::Domain qw(hostname hostfqdn hostdomain);
629
630         my $host = hostfqdn();
631
632 The C<Sys::Hostname> module, included in the standard distribution since
633 perl5.6, can also get the hostname.
634
635         use Sys::Hostname;
636
637         $host = hostname();
638
639 To get the IP address, you can use the C<gethostbyname> built-in function
640 to turn the name into a number. To turn that number into the dotted octet
641 form (a.b.c.d) that most people expect, use the C<inet_ntoa> function
642 from the C<Socket> module, which also comes with perl.
643
644         use Socket;
645
646         my $address = inet_ntoa(
647                 scalar gethostbyname( $host || 'localhost' )
648                 );
649
650 =head2 How do I fetch a news article or the active newsgroups?
651
652 Use the C<Net::NNTP> or C<News::NNTPClient> modules, both available from CPAN.
653 This can make tasks like fetching the newsgroup list as simple as
654
655         perl -MNews::NNTPClient
656           -e 'print News::NNTPClient->new->list("newsgroups")'
657
658 =head2 How do I fetch/put an FTP file?
659
660 C<LWP::Simple> (available from CPAN) can fetch but not put.  C<Net::FTP> (also
661 available from CPAN) is more complex but can put as well as fetch.
662
663 =head2 How can I do RPC in Perl?
664
665 (Contributed by brian d foy)
666
667 Use one of the RPC modules you can find on CPAN (
668 http://search.cpan.org/search?query=RPC&mode=all ).
669
670 =head1 AUTHOR AND COPYRIGHT
671
672 Copyright (c) 1997-2010 Tom Christiansen, Nathan Torkington, and
673 other authors as noted. All rights reserved.
674
675 This documentation is free; you can redistribute it and/or modify it
676 under the same terms as Perl itself.
677
678 Irrespective of its distribution, all code examples in this file
679 are hereby placed into the public domain.  You are permitted and
680 encouraged to use this code in your own programs for fun
681 or for profit as you see fit.  A simple comment in the code giving
682 credit would be courteous but is not required.