This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Document a bit that UDP is not what you might think.
[perl5.git] / pod / perlipc.pod
1 =head1 NAME
2
3 perlipc - Perl interprocess communication (signals, fifos, pipes, safe subprocesses, sockets, and semaphores)
4
5 =head1 DESCRIPTION
6
7 The basic IPC facilities of Perl are built out of the good old Unix
8 signals, named pipes, pipe opens, the Berkeley socket routines, and SysV
9 IPC calls.  Each is used in slightly different situations.
10
11 =head1 Signals
12
13 Perl uses a simple signal handling model: the %SIG hash contains names or
14 references of user-installed signal handlers.  These handlers will be called
15 with an argument which is the name of the signal that triggered it.  A
16 signal may be generated intentionally from a particular keyboard sequence like
17 control-C or control-Z, sent to you from another process, or
18 triggered automatically by the kernel when special events transpire, like
19 a child process exiting, your process running out of stack space, or
20 hitting file size limit.
21
22 For example, to trap an interrupt signal, set up a handler like this.
23 Do as little as you possibly can in your handler; notice how all we do is
24 set a global variable and then raise an exception.  That's because on most
25 systems, libraries are not re-entrant; particularly, memory allocation and
26 I/O routines are not.  That means that doing nearly I<anything> in your
27 handler could in theory trigger a memory fault and subsequent core dump.
28
29     sub catch_zap {
30         my $signame = shift;
31         $shucks++;
32         die "Somebody sent me a SIG$signame";
33     }
34     $SIG{INT} = 'catch_zap';  # could fail in modules
35     $SIG{INT} = \&catch_zap;  # best strategy
36
37 The names of the signals are the ones listed out by C<kill -l> on your
38 system, or you can retrieve them from the Config module.  Set up an
39 @signame list indexed by number to get the name and a %signo table
40 indexed by name to get the number:
41
42     use Config;
43     defined $Config{sig_name} || die "No sigs?";
44     foreach $name (split(' ', $Config{sig_name})) {
45         $signo{$name} = $i;
46         $signame[$i] = $name;
47         $i++;
48     }
49
50 So to check whether signal 17 and SIGALRM were the same, do just this:
51
52     print "signal #17 = $signame[17]\n";
53     if ($signo{ALRM}) {
54         print "SIGALRM is $signo{ALRM}\n";
55     }
56
57 You may also choose to assign the strings C<'IGNORE'> or C<'DEFAULT'> as
58 the handler, in which case Perl will try to discard the signal or do the
59 default thing.
60
61 On most Unix platforms, the C<CHLD> (sometimes also known as C<CLD>) signal
62 has special behavior with respect to a value of C<'IGNORE'>.
63 Setting C<$SIG{CHLD}> to C<'IGNORE'> on such a platform has the effect of
64 not creating zombie processes when the parent process fails to C<wait()>
65 on its child processes (i.e. child processes are automatically reaped).
66 Calling C<wait()> with C<$SIG{CHLD}> set to C<'IGNORE'> usually returns
67 C<-1> on such platforms.
68
69 Some signals can be neither trapped nor ignored, such as
70 the KILL and STOP (but not the TSTP) signals.  One strategy for
71 temporarily ignoring signals is to use a local() statement, which will be
72 automatically restored once your block is exited.  (Remember that local()
73 values are "inherited" by functions called from within that block.)
74
75     sub precious {
76         local $SIG{INT} = 'IGNORE';
77         &more_functions;
78     }
79     sub more_functions {
80         # interrupts still ignored, for now...
81     }
82
83 Sending a signal to a negative process ID means that you send the signal
84 to the entire Unix process-group.  This code sends a hang-up signal to all
85 processes in the current process group (and sets $SIG{HUP} to IGNORE so
86 it doesn't kill itself):
87
88     {
89         local $SIG{HUP} = 'IGNORE';
90         kill HUP => -$$;
91         # snazzy writing of: kill('HUP', -$$)
92     }
93
94 Another interesting signal to send is signal number zero.  This doesn't
95 actually affect another process, but instead checks whether it's alive
96 or has changed its UID.
97
98     unless (kill 0 => $kid_pid) {
99         warn "something wicked happened to $kid_pid";
100     }
101
102 You might also want to employ anonymous functions for simple signal
103 handlers:
104
105     $SIG{INT} = sub { die "\nOutta here!\n" };
106
107 But that will be problematic for the more complicated handlers that need
108 to reinstall themselves.  Because Perl's signal mechanism is currently
109 based on the signal(3) function from the C library, you may sometimes be so
110 misfortunate as to run on systems where that function is "broken", that
111 is, it behaves in the old unreliable SysV way rather than the newer, more
112 reasonable BSD and POSIX fashion.  So you'll see defensive people writing
113 signal handlers like this:
114
115     sub REAPER {
116         $waitedpid = wait;
117         # loathe sysV: it makes us not only reinstate
118         # the handler, but place it after the wait
119         $SIG{CHLD} = \&REAPER;
120     }
121     $SIG{CHLD} = \&REAPER;
122     # now do something that forks...
123
124 or even the more elaborate:
125
126     use POSIX ":sys_wait_h";
127     sub REAPER {
128         my $child;
129         while (($child = waitpid(-1,WNOHANG)) > 0) {
130             $Kid_Status{$child} = $?;
131         }
132         $SIG{CHLD} = \&REAPER;  # still loathe sysV
133     }
134     $SIG{CHLD} = \&REAPER;
135     # do something that forks...
136
137 Signal handling is also used for timeouts in Unix,   While safely
138 protected within an C<eval{}> block, you set a signal handler to trap
139 alarm signals and then schedule to have one delivered to you in some
140 number of seconds.  Then try your blocking operation, clearing the alarm
141 when it's done but not before you've exited your C<eval{}> block.  If it
142 goes off, you'll use die() to jump out of the block, much as you might
143 using longjmp() or throw() in other languages.
144
145 Here's an example:
146
147     eval {
148         local $SIG{ALRM} = sub { die "alarm clock restart" };
149         alarm 10;
150         flock(FH, 2);   # blocking write lock
151         alarm 0;
152     };
153     if ($@ and $@ !~ /alarm clock restart/) { die }
154
155 If the operation being timed out is system() or qx(), this technique
156 is liable to generate zombies.    If this matters to you, you'll
157 need to do your own fork() and exec(), and kill the errant child process.
158
159 For more complex signal handling, you might see the standard POSIX
160 module.  Lamentably, this is almost entirely undocumented, but
161 the F<t/lib/posix.t> file from the Perl source distribution has some
162 examples in it.
163
164 =head1 Named Pipes
165
166 A named pipe (often referred to as a FIFO) is an old Unix IPC
167 mechanism for processes communicating on the same machine.  It works
168 just like a regular, connected anonymous pipes, except that the
169 processes rendezvous using a filename and don't have to be related.
170
171 To create a named pipe, use the Unix command mknod(1) or on some
172 systems, mkfifo(1).  These may not be in your normal path.
173
174     # system return val is backwards, so && not ||
175     #
176     $ENV{PATH} .= ":/etc:/usr/etc";
177     if  (      system('mknod',  $path, 'p')
178             && system('mkfifo', $path) )
179     {
180         die "mk{nod,fifo} $path failed";
181     }
182
183
184 A fifo is convenient when you want to connect a process to an unrelated
185 one.  When you open a fifo, the program will block until there's something
186 on the other end.
187
188 For example, let's say you'd like to have your F<.signature> file be a
189 named pipe that has a Perl program on the other end.  Now every time any
190 program (like a mailer, news reader, finger program, etc.) tries to read
191 from that file, the reading program will block and your program will
192 supply the new signature.  We'll use the pipe-checking file test B<-p>
193 to find out whether anyone (or anything) has accidentally removed our fifo.
194
195     chdir; # go home
196     $FIFO = '.signature';
197     $ENV{PATH} .= ":/etc:/usr/games";
198
199     while (1) {
200         unless (-p $FIFO) {
201             unlink $FIFO;
202             system('mknod', $FIFO, 'p')
203                 && die "can't mknod $FIFO: $!";
204         }
205
206         # next line blocks until there's a reader
207         open (FIFO, "> $FIFO") || die "can't write $FIFO: $!";
208         print FIFO "John Smith (smith\@host.org)\n", `fortune -s`;
209         close FIFO;
210         sleep 2;    # to avoid dup signals
211     }
212
213 =head2 WARNING
214
215 By installing Perl code to deal with signals, you're exposing yourself
216 to danger from two things.  First, few system library functions are
217 re-entrant.  If the signal interrupts while Perl is executing one function
218 (like malloc(3) or printf(3)), and your signal handler then calls the
219 same function again, you could get unpredictable behavior--often, a
220 core dump.  Second, Perl isn't itself re-entrant at the lowest levels.
221 If the signal interrupts Perl while Perl is changing its own internal
222 data structures, similarly unpredictable behaviour may result.
223
224 There are two things you can do, knowing this: be paranoid or be
225 pragmatic.  The paranoid approach is to do as little as possible in your
226 signal handler.  Set an existing integer variable that already has a
227 value, and return.  This doesn't help you if you're in a slow system call,
228 which will just restart.  That means you have to C<die> to longjump(3) out
229 of the handler.  Even this is a little cavalier for the true paranoiac,
230 who avoids C<die> in a handler because the system I<is> out to get you.
231 The pragmatic approach is to say ``I know the risks, but prefer the
232 convenience'', and to do anything you want in your signal handler,
233 prepared to clean up core dumps now and again.
234
235 To forbid signal handlers altogether would bars you from
236 many interesting programs, including virtually everything in this manpage,
237 since you could no longer even write SIGCHLD handlers.  
238
239
240 =head1 Using open() for IPC
241
242 Perl's basic open() statement can also be used for unidirectional interprocess
243 communication by either appending or prepending a pipe symbol to the second
244 argument to open().  Here's how to start something up in a child process you
245 intend to write to:
246
247     open(SPOOLER, "| cat -v | lpr -h 2>/dev/null")
248                     || die "can't fork: $!";
249     local $SIG{PIPE} = sub { die "spooler pipe broke" };
250     print SPOOLER "stuff\n";
251     close SPOOLER || die "bad spool: $! $?";
252
253 And here's how to start up a child process you intend to read from:
254
255     open(STATUS, "netstat -an 2>&1 |")
256                     || die "can't fork: $!";
257     while (<STATUS>) {
258         next if /^(tcp|udp)/;
259         print;
260     }
261     close STATUS || die "bad netstat: $! $?";
262
263 If one can be sure that a particular program is a Perl script that is
264 expecting filenames in @ARGV, the clever programmer can write something
265 like this:
266
267     % program f1 "cmd1|" - f2 "cmd2|" f3 < tmpfile
268
269 and irrespective of which shell it's called from, the Perl program will
270 read from the file F<f1>, the process F<cmd1>, standard input (F<tmpfile>
271 in this case), the F<f2> file, the F<cmd2> command, and finally the F<f3>
272 file.  Pretty nifty, eh?
273
274 You might notice that you could use backticks for much the
275 same effect as opening a pipe for reading:
276
277     print grep { !/^(tcp|udp)/ } `netstat -an 2>&1`;
278     die "bad netstat" if $?;
279
280 While this is true on the surface, it's much more efficient to process the
281 file one line or record at a time because then you don't have to read the
282 whole thing into memory at once.  It also gives you finer control of the
283 whole process, letting you to kill off the child process early if you'd
284 like.
285
286 Be careful to check both the open() and the close() return values.  If
287 you're I<writing> to a pipe, you should also trap SIGPIPE.  Otherwise,
288 think of what happens when you start up a pipe to a command that doesn't
289 exist: the open() will in all likelihood succeed (it only reflects the
290 fork()'s success), but then your output will fail--spectacularly.  Perl
291 can't know whether the command worked because your command is actually
292 running in a separate process whose exec() might have failed.  Therefore,
293 while readers of bogus commands return just a quick end of file, writers
294 to bogus command will trigger a signal they'd better be prepared to
295 handle.  Consider:
296
297     open(FH, "|bogus")  or die "can't fork: $!";
298     print FH "bang\n"   or die "can't write: $!";
299     close FH            or die "can't close: $!";
300
301 That won't blow up until the close, and it will blow up with a SIGPIPE.
302 To catch it, you could use this:
303
304     $SIG{PIPE} = 'IGNORE';
305     open(FH, "|bogus")  or die "can't fork: $!";
306     print FH "bang\n"   or die "can't write: $!";
307     close FH            or die "can't close: status=$?";
308
309 =head2 Filehandles
310
311 Both the main process and any child processes it forks share the same
312 STDIN, STDOUT, and STDERR filehandles.  If both processes try to access
313 them at once, strange things can happen.  You may also want to close
314 or reopen the filehandles for the child.  You can get around this by
315 opening your pipe with open(), but on some systems this means that the
316 child process cannot outlive the parent.
317
318 =head2 Background Processes
319
320 You can run a command in the background with:
321
322     system("cmd &");
323
324 The command's STDOUT and STDERR (and possibly STDIN, depending on your
325 shell) will be the same as the parent's.  You won't need to catch
326 SIGCHLD because of the double-fork taking place (see below for more
327 details).
328
329 =head2 Complete Dissociation of Child from Parent
330
331 In some cases (starting server processes, for instance) you'll want to
332 completely dissociate the child process from the parent.  This is
333 often called daemonization.  A well behaved daemon will also chdir()
334 to the root directory (so it doesn't prevent unmounting the filesystem
335 containing the directory from which it was launched) and redirect its
336 standard file descriptors from and to F</dev/null> (so that random
337 output doesn't wind up on the user's terminal).
338
339     use POSIX 'setsid';
340
341     sub daemonize {
342         chdir '/'               or die "Can't chdir to /: $!";
343         open STDIN, '/dev/null' or die "Can't read /dev/null: $!";
344         open STDOUT, '>/dev/null'
345                                 or die "Can't write to /dev/null: $!";
346         defined(my $pid = fork) or die "Can't fork: $!";
347         exit if $pid;
348         setsid                  or die "Can't start a new session: $!";
349         open STDERR, '>&STDOUT' or die "Can't dup stdout: $!";
350     }
351
352 The fork() has to come before the setsid() to ensure that you aren't a
353 process group leader (the setsid() will fail if you are).  If your
354 system doesn't have the setsid() function, open F</dev/tty> and use the
355 C<TIOCNOTTY> ioctl() on it instead.  See L<tty(4)> for details.
356
357 Non-Unix users should check their Your_OS::Process module for other
358 solutions.
359
360 =head2 Safe Pipe Opens
361
362 Another interesting approach to IPC is making your single program go
363 multiprocess and communicate between (or even amongst) yourselves.  The
364 open() function will accept a file argument of either C<"-|"> or C<"|-">
365 to do a very interesting thing: it forks a child connected to the
366 filehandle you've opened.  The child is running the same program as the
367 parent.  This is useful for safely opening a file when running under an
368 assumed UID or GID, for example.  If you open a pipe I<to> minus, you can
369 write to the filehandle you opened and your kid will find it in his
370 STDIN.  If you open a pipe I<from> minus, you can read from the filehandle
371 you opened whatever your kid writes to his STDOUT.
372
373     use English;
374     my $sleep_count = 0;
375
376     do {
377         $pid = open(KID_TO_WRITE, "|-");
378         unless (defined $pid) {
379             warn "cannot fork: $!";
380             die "bailing out" if $sleep_count++ > 6;
381             sleep 10;
382         }
383     } until defined $pid;
384
385     if ($pid) {  # parent
386         print KID_TO_WRITE @some_data;
387         close(KID_TO_WRITE) || warn "kid exited $?";
388     } else {     # child
389         ($EUID, $EGID) = ($UID, $GID); # suid progs only
390         open (FILE, "> /safe/file")
391             || die "can't open /safe/file: $!";
392         while (<STDIN>) {
393             print FILE; # child's STDIN is parent's KID
394         }
395         exit;  # don't forget this
396     }
397
398 Another common use for this construct is when you need to execute
399 something without the shell's interference.  With system(), it's
400 straightforward, but you can't use a pipe open or backticks safely.
401 That's because there's no way to stop the shell from getting its hands on
402 your arguments.   Instead, use lower-level control to call exec() directly.
403
404 Here's a safe backtick or pipe open for read:
405
406     # add error processing as above
407     $pid = open(KID_TO_READ, "-|");
408
409     if ($pid) {   # parent
410         while (<KID_TO_READ>) {
411             # do something interesting
412         }
413         close(KID_TO_READ) || warn "kid exited $?";
414
415     } else {      # child
416         ($EUID, $EGID) = ($UID, $GID); # suid only
417         exec($program, @options, @args)
418             || die "can't exec program: $!";
419         # NOTREACHED
420     }
421
422
423 And here's a safe pipe open for writing:
424
425     # add error processing as above
426     $pid = open(KID_TO_WRITE, "|-");
427     $SIG{ALRM} = sub { die "whoops, $program pipe broke" };
428
429     if ($pid) {  # parent
430         for (@data) {
431             print KID_TO_WRITE;
432         }
433         close(KID_TO_WRITE) || warn "kid exited $?";
434
435     } else {     # child
436         ($EUID, $EGID) = ($UID, $GID);
437         exec($program, @options, @args)
438             || die "can't exec program: $!";
439         # NOTREACHED
440     }
441
442 Note that these operations are full Unix forks, which means they may not be
443 correctly implemented on alien systems.  Additionally, these are not true
444 multithreading.  If you'd like to learn more about threading, see the
445 F<modules> file mentioned below in the SEE ALSO section.
446
447 =head2 Bidirectional Communication with Another Process
448
449 While this works reasonably well for unidirectional communication, what
450 about bidirectional communication?  The obvious thing you'd like to do
451 doesn't actually work:
452
453     open(PROG_FOR_READING_AND_WRITING, "| some program |")
454
455 and if you forget to use the C<use warnings> pragma or the B<-w> flag,
456 then you'll miss out entirely on the diagnostic message:
457
458     Can't do bidirectional pipe at -e line 1.
459
460 If you really want to, you can use the standard open2() library function
461 to catch both ends.  There's also an open3() for tridirectional I/O so you
462 can also catch your child's STDERR, but doing so would then require an
463 awkward select() loop and wouldn't allow you to use normal Perl input
464 operations.
465
466 If you look at its source, you'll see that open2() uses low-level
467 primitives like Unix pipe() and exec() calls to create all the connections.
468 While it might have been slightly more efficient by using socketpair(), it
469 would have then been even less portable than it already is.  The open2()
470 and open3() functions are  unlikely to work anywhere except on a Unix
471 system or some other one purporting to be POSIX compliant.
472
473 Here's an example of using open2():
474
475     use FileHandle;
476     use IPC::Open2;
477     $pid = open2(*Reader, *Writer, "cat -u -n" );
478     print Writer "stuff\n";
479     $got = <Reader>;
480
481 The problem with this is that Unix buffering is really going to
482 ruin your day.  Even though your C<Writer> filehandle is auto-flushed,
483 and the process on the other end will get your data in a timely manner,
484 you can't usually do anything to force it to give it back to you
485 in a similarly quick fashion.  In this case, we could, because we
486 gave I<cat> a B<-u> flag to make it unbuffered.  But very few Unix
487 commands are designed to operate over pipes, so this seldom works
488 unless you yourself wrote the program on the other end of the
489 double-ended pipe.
490
491 A solution to this is the nonstandard F<Comm.pl> library.  It uses
492 pseudo-ttys to make your program behave more reasonably:
493
494     require 'Comm.pl';
495     $ph = open_proc('cat -n');
496     for (1..10) {
497         print $ph "a line\n";
498         print "got back ", scalar <$ph>;
499     }
500
501 This way you don't have to have control over the source code of the
502 program you're using.  The F<Comm> library also has expect()
503 and interact() functions.  Find the library (and we hope its
504 successor F<IPC::Chat>) at your nearest CPAN archive as detailed
505 in the SEE ALSO section below.
506
507 The newer Expect.pm module from CPAN also addresses this kind of thing.
508 This module requires two other modules from CPAN: IO::Pty and IO::Stty.
509 It sets up a pseudo-terminal to interact with programs that insist on
510 using talking to the terminal device driver.  If your system is 
511 amongst those supported, this may be your best bet.
512
513 =head2 Bidirectional Communication with Yourself
514
515 If you want, you may make low-level pipe() and fork()
516 to stitch this together by hand.  This example only
517 talks to itself, but you could reopen the appropriate
518 handles to STDIN and STDOUT and call other processes.
519
520     #!/usr/bin/perl -w
521     # pipe1 - bidirectional communication using two pipe pairs
522     #         designed for the socketpair-challenged
523     use IO::Handle;     # thousands of lines just for autoflush :-(
524     pipe(PARENT_RDR, CHILD_WTR);                # XXX: failure?
525     pipe(CHILD_RDR,  PARENT_WTR);               # XXX: failure?
526     CHILD_WTR->autoflush(1);
527     PARENT_WTR->autoflush(1);
528
529     if ($pid = fork) {
530         close PARENT_RDR; close PARENT_WTR;
531         print CHILD_WTR "Parent Pid $$ is sending this\n";
532         chomp($line = <CHILD_RDR>);
533         print "Parent Pid $$ just read this: `$line'\n";
534         close CHILD_RDR; close CHILD_WTR;
535         waitpid($pid,0);
536     } else {
537         die "cannot fork: $!" unless defined $pid;
538         close CHILD_RDR; close CHILD_WTR;
539         chomp($line = <PARENT_RDR>);
540         print "Child Pid $$ just read this: `$line'\n";
541         print PARENT_WTR "Child Pid $$ is sending this\n";
542         close PARENT_RDR; close PARENT_WTR;
543         exit;
544     }
545
546 But you don't actually have to make two pipe calls.  If you 
547 have the socketpair() system call, it will do this all for you.
548
549     #!/usr/bin/perl -w
550     # pipe2 - bidirectional communication using socketpair
551     #   "the best ones always go both ways"
552
553     use Socket;
554     use IO::Handle;     # thousands of lines just for autoflush :-(
555     # We say AF_UNIX because although *_LOCAL is the
556     # POSIX 1003.1g form of the constant, many machines
557     # still don't have it.
558     socketpair(CHILD, PARENT, AF_UNIX, SOCK_STREAM, PF_UNSPEC)
559                                 or  die "socketpair: $!";
560
561     CHILD->autoflush(1);
562     PARENT->autoflush(1);
563
564     if ($pid = fork) {
565         close PARENT;
566         print CHILD "Parent Pid $$ is sending this\n";
567         chomp($line = <CHILD>);
568         print "Parent Pid $$ just read this: `$line'\n";
569         close CHILD;
570         waitpid($pid,0);
571     } else {
572         die "cannot fork: $!" unless defined $pid;
573         close CHILD;
574         chomp($line = <PARENT>);
575         print "Child Pid $$ just read this: `$line'\n";
576         print PARENT "Child Pid $$ is sending this\n";
577         close PARENT;
578         exit;
579     }
580
581 =head1 Sockets: Client/Server Communication
582
583 While not limited to Unix-derived operating systems (e.g., WinSock on PCs
584 provides socket support, as do some VMS libraries), you may not have
585 sockets on your system, in which case this section probably isn't going to do
586 you much good.  With sockets, you can do both virtual circuits (i.e., TCP
587 streams) and datagrams (i.e., UDP packets).  You may be able to do even more
588 depending on your system.
589
590 The Perl function calls for dealing with sockets have the same names as
591 the corresponding system calls in C, but their arguments tend to differ
592 for two reasons: first, Perl filehandles work differently than C file
593 descriptors.  Second, Perl already knows the length of its strings, so you
594 don't need to pass that information.
595
596 One of the major problems with old socket code in Perl was that it used
597 hard-coded values for some of the constants, which severely hurt
598 portability.  If you ever see code that does anything like explicitly
599 setting C<$AF_INET = 2>, you know you're in for big trouble:  An
600 immeasurably superior approach is to use the C<Socket> module, which more
601 reliably grants access to various constants and functions you'll need.
602
603 If you're not writing a server/client for an existing protocol like
604 NNTP or SMTP, you should give some thought to how your server will
605 know when the client has finished talking, and vice-versa.  Most
606 protocols are based on one-line messages and responses (so one party
607 knows the other has finished when a "\n" is received) or multi-line
608 messages and responses that end with a period on an empty line
609 ("\n.\n" terminates a message/response).
610
611 =head2 Internet Line Terminators
612
613 The Internet line terminator is "\015\012".  Under ASCII variants of
614 Unix, that could usually be written as "\r\n", but under other systems,
615 "\r\n" might at times be "\015\015\012", "\012\012\015", or something
616 completely different.  The standards specify writing "\015\012" to be
617 conformant (be strict in what you provide), but they also recommend
618 accepting a lone "\012" on input (but be lenient in what you require).
619 We haven't always been very good about that in the code in this manpage,
620 but unless you're on a Mac, you'll probably be ok.
621
622 =head2 Internet TCP Clients and Servers
623
624 Use Internet-domain sockets when you want to do client-server
625 communication that might extend to machines outside of your own system.
626
627 Here's a sample TCP client using Internet-domain sockets:
628
629     #!/usr/bin/perl -w
630     use strict;
631     use Socket;
632     my ($remote,$port, $iaddr, $paddr, $proto, $line);
633
634     $remote  = shift || 'localhost';
635     $port    = shift || 2345;  # random port
636     if ($port =~ /\D/) { $port = getservbyname($port, 'tcp') }
637     die "No port" unless $port;
638     $iaddr   = inet_aton($remote)               || die "no host: $remote";
639     $paddr   = sockaddr_in($port, $iaddr);
640
641     $proto   = getprotobyname('tcp');
642     socket(SOCK, PF_INET, SOCK_STREAM, $proto)  || die "socket: $!";
643     connect(SOCK, $paddr)    || die "connect: $!";
644     while (defined($line = <SOCK>)) {
645         print $line;
646     }
647
648     close (SOCK)            || die "close: $!";
649     exit;
650
651 And here's a corresponding server to go along with it.  We'll
652 leave the address as INADDR_ANY so that the kernel can choose
653 the appropriate interface on multihomed hosts.  If you want sit
654 on a particular interface (like the external side of a gateway
655 or firewall machine), you should fill this in with your real address
656 instead.
657
658     #!/usr/bin/perl -Tw
659     use strict;
660     BEGIN { $ENV{PATH} = '/usr/ucb:/bin' }
661     use Socket;
662     use Carp;
663     $EOL = "\015\012";
664
665     sub logmsg { print "$0 $$: @_ at ", scalar localtime, "\n" }
666
667     my $port = shift || 2345;
668     my $proto = getprotobyname('tcp');
669
670     ($port) = $port =~ /^(\d+)$/                        || die "invalid port";
671
672     socket(Server, PF_INET, SOCK_STREAM, $proto)        || die "socket: $!";
673     setsockopt(Server, SOL_SOCKET, SO_REUSEADDR,
674                                         pack("l", 1))   || die "setsockopt: $!";
675     bind(Server, sockaddr_in($port, INADDR_ANY))        || die "bind: $!";
676     listen(Server,SOMAXCONN)                            || die "listen: $!";
677
678     logmsg "server started on port $port";
679
680     my $paddr;
681
682     $SIG{CHLD} = \&REAPER;
683
684     for ( ; $paddr = accept(Client,Server); close Client) {
685         my($port,$iaddr) = sockaddr_in($paddr);
686         my $name = gethostbyaddr($iaddr,AF_INET);
687
688         logmsg "connection from $name [",
689                 inet_ntoa($iaddr), "]
690                 at port $port";
691
692         print Client "Hello there, $name, it's now ",
693                         scalar localtime, $EOL;
694     }
695
696 And here's a multithreaded version.  It's multithreaded in that
697 like most typical servers, it spawns (forks) a slave server to
698 handle the client request so that the master server can quickly
699 go back to service a new client.
700
701     #!/usr/bin/perl -Tw
702     use strict;
703     BEGIN { $ENV{PATH} = '/usr/ucb:/bin' }
704     use Socket;
705     use Carp;
706     $EOL = "\015\012";
707
708     sub spawn;  # forward declaration
709     sub logmsg { print "$0 $$: @_ at ", scalar localtime, "\n" }
710
711     my $port = shift || 2345;
712     my $proto = getprotobyname('tcp');
713
714     ($port) = $port =~ /^(\d+)$/                        || die "invalid port";
715
716     socket(Server, PF_INET, SOCK_STREAM, $proto)        || die "socket: $!";
717     setsockopt(Server, SOL_SOCKET, SO_REUSEADDR,
718                                         pack("l", 1))   || die "setsockopt: $!";
719     bind(Server, sockaddr_in($port, INADDR_ANY))        || die "bind: $!";
720     listen(Server,SOMAXCONN)                            || die "listen: $!";
721
722     logmsg "server started on port $port";
723
724     my $waitedpid = 0;
725     my $paddr;
726
727     sub REAPER {
728         $waitedpid = wait;
729         $SIG{CHLD} = \&REAPER;  # loathe sysV
730         logmsg "reaped $waitedpid" . ($? ? " with exit $?" : '');
731     }
732
733     $SIG{CHLD} = \&REAPER;
734
735     for ( $waitedpid = 0;
736           ($paddr = accept(Client,Server)) || $waitedpid;
737           $waitedpid = 0, close Client)
738     {
739         next if $waitedpid and not $paddr;
740         my($port,$iaddr) = sockaddr_in($paddr);
741         my $name = gethostbyaddr($iaddr,AF_INET);
742
743         logmsg "connection from $name [",
744                 inet_ntoa($iaddr), "]
745                 at port $port";
746
747         spawn sub {
748             print "Hello there, $name, it's now ", scalar localtime, $EOL;
749             exec '/usr/games/fortune'           # XXX: `wrong' line terminators
750                 or confess "can't exec fortune: $!";
751         };
752
753     }
754
755     sub spawn {
756         my $coderef = shift;
757
758         unless (@_ == 0 && $coderef && ref($coderef) eq 'CODE') {
759             confess "usage: spawn CODEREF";
760         }
761
762         my $pid;
763         if (!defined($pid = fork)) {
764             logmsg "cannot fork: $!";
765             return;
766         } elsif ($pid) {
767             logmsg "begat $pid";
768             return; # I'm the parent
769         }
770         # else I'm the child -- go spawn
771
772         open(STDIN,  "<&Client")   || die "can't dup client to stdin";
773         open(STDOUT, ">&Client")   || die "can't dup client to stdout";
774         ## open(STDERR, ">&STDOUT") || die "can't dup stdout to stderr";
775         exit &$coderef();
776     }
777
778 This server takes the trouble to clone off a child version via fork() for
779 each incoming request.  That way it can handle many requests at once,
780 which you might not always want.  Even if you don't fork(), the listen()
781 will allow that many pending connections.  Forking servers have to be
782 particularly careful about cleaning up their dead children (called
783 "zombies" in Unix parlance), because otherwise you'll quickly fill up your
784 process table.
785
786 We suggest that you use the B<-T> flag to use taint checking (see L<perlsec>)
787 even if we aren't running setuid or setgid.  This is always a good idea
788 for servers and other programs run on behalf of someone else (like CGI
789 scripts), because it lessens the chances that people from the outside will
790 be able to compromise your system.
791
792 Let's look at another TCP client.  This one connects to the TCP "time"
793 service on a number of different machines and shows how far their clocks
794 differ from the system on which it's being run:
795
796     #!/usr/bin/perl  -w
797     use strict;
798     use Socket;
799
800     my $SECS_of_70_YEARS = 2208988800;
801     sub ctime { scalar localtime(shift) }
802
803     my $iaddr = gethostbyname('localhost');
804     my $proto = getprotobyname('tcp');
805     my $port = getservbyname('time', 'tcp');
806     my $paddr = sockaddr_in(0, $iaddr);
807     my($host);
808
809     $| = 1;
810     printf "%-24s %8s %s\n",  "localhost", 0, ctime(time());
811
812     foreach $host (@ARGV) {
813         printf "%-24s ", $host;
814         my $hisiaddr = inet_aton($host)     || die "unknown host";
815         my $hispaddr = sockaddr_in($port, $hisiaddr);
816         socket(SOCKET, PF_INET, SOCK_STREAM, $proto)   || die "socket: $!";
817         connect(SOCKET, $hispaddr)          || die "bind: $!";
818         my $rtime = '    ';
819         read(SOCKET, $rtime, 4);
820         close(SOCKET);
821         my $histime = unpack("N", $rtime) - $SECS_of_70_YEARS ;
822         printf "%8d %s\n", $histime - time, ctime($histime);
823     }
824
825 =head2 Unix-Domain TCP Clients and Servers
826
827 That's fine for Internet-domain clients and servers, but what about local
828 communications?  While you can use the same setup, sometimes you don't
829 want to.  Unix-domain sockets are local to the current host, and are often
830 used internally to implement pipes.  Unlike Internet domain sockets, Unix
831 domain sockets can show up in the file system with an ls(1) listing.
832
833     % ls -l /dev/log
834     srw-rw-rw-  1 root            0 Oct 31 07:23 /dev/log
835
836 You can test for these with Perl's B<-S> file test:
837
838     unless ( -S '/dev/log' ) {
839         die "something's wicked with the log system";
840     }
841
842 Here's a sample Unix-domain client:
843
844     #!/usr/bin/perl -w
845     use Socket;
846     use strict;
847     my ($rendezvous, $line);
848
849     $rendezvous = shift || '/tmp/catsock';
850     socket(SOCK, PF_UNIX, SOCK_STREAM, 0)       || die "socket: $!";
851     connect(SOCK, sockaddr_un($rendezvous))     || die "connect: $!";
852     while (defined($line = <SOCK>)) {
853         print $line;
854     }
855     exit;
856
857 And here's a corresponding server.  You don't have to worry about silly
858 network terminators here because Unix domain sockets are guaranteed
859 to be on the localhost, and thus everything works right.
860
861     #!/usr/bin/perl -Tw
862     use strict;
863     use Socket;
864     use Carp;
865
866     BEGIN { $ENV{PATH} = '/usr/ucb:/bin' }
867     sub logmsg { print "$0 $$: @_ at ", scalar localtime, "\n" }
868
869     my $NAME = '/tmp/catsock';
870     my $uaddr = sockaddr_un($NAME);
871     my $proto = getprotobyname('tcp');
872
873     socket(Server,PF_UNIX,SOCK_STREAM,0)        || die "socket: $!";
874     unlink($NAME);
875     bind  (Server, $uaddr)                      || die "bind: $!";
876     listen(Server,SOMAXCONN)                    || die "listen: $!";
877
878     logmsg "server started on $NAME";
879
880     my $waitedpid;
881
882     sub REAPER {
883         $waitedpid = wait;
884         $SIG{CHLD} = \&REAPER;  # loathe sysV
885         logmsg "reaped $waitedpid" . ($? ? " with exit $?" : '');
886     }
887
888     $SIG{CHLD} = \&REAPER;
889
890
891     for ( $waitedpid = 0;
892           accept(Client,Server) || $waitedpid;
893           $waitedpid = 0, close Client)
894     {
895         next if $waitedpid;
896         logmsg "connection on $NAME";
897         spawn sub {
898             print "Hello there, it's now ", scalar localtime, "\n";
899             exec '/usr/games/fortune' or die "can't exec fortune: $!";
900         };
901     }
902
903 As you see, it's remarkably similar to the Internet domain TCP server, so
904 much so, in fact, that we've omitted several duplicate functions--spawn(),
905 logmsg(), ctime(), and REAPER()--which are exactly the same as in the
906 other server.
907
908 So why would you ever want to use a Unix domain socket instead of a
909 simpler named pipe?  Because a named pipe doesn't give you sessions.  You
910 can't tell one process's data from another's.  With socket programming,
911 you get a separate session for each client: that's why accept() takes two
912 arguments.
913
914 For example, let's say that you have a long running database server daemon
915 that you want folks from the World Wide Web to be able to access, but only
916 if they go through a CGI interface.  You'd have a small, simple CGI
917 program that does whatever checks and logging you feel like, and then acts
918 as a Unix-domain client and connects to your private server.
919
920 =head1 TCP Clients with IO::Socket
921
922 For those preferring a higher-level interface to socket programming, the
923 IO::Socket module provides an object-oriented approach.  IO::Socket is
924 included as part of the standard Perl distribution as of the 5.004
925 release.  If you're running an earlier version of Perl, just fetch
926 IO::Socket from CPAN, where you'll also find modules providing easy
927 interfaces to the following systems: DNS, FTP, Ident (RFC 931), NIS and
928 NISPlus, NNTP, Ping, POP3, SMTP, SNMP, SSLeay, Telnet, and Time--just
929 to name a few.
930
931 =head2 A Simple Client
932
933 Here's a client that creates a TCP connection to the "daytime"
934 service at port 13 of the host name "localhost" and prints out everything
935 that the server there cares to provide.
936
937     #!/usr/bin/perl -w
938     use IO::Socket;
939     $remote = IO::Socket::INET->new(
940                         Proto    => "tcp",
941                         PeerAddr => "localhost",
942                         PeerPort => "daytime(13)",
943                     )
944                   or die "cannot connect to daytime port at localhost";
945     while ( <$remote> ) { print }
946
947 When you run this program, you should get something back that
948 looks like this:
949
950     Wed May 14 08:40:46 MDT 1997
951
952 Here are what those parameters to the C<new> constructor mean:
953
954 =over
955
956 =item C<Proto>
957
958 This is which protocol to use.  In this case, the socket handle returned
959 will be connected to a TCP socket, because we want a stream-oriented
960 connection, that is, one that acts pretty much like a plain old file.
961 Not all sockets are this of this type.  For example, the UDP protocol
962 can be used to make a datagram socket, used for message-passing.
963
964 =item C<PeerAddr>
965
966 This is the name or Internet address of the remote host the server is
967 running on.  We could have specified a longer name like C<"www.perl.com">,
968 or an address like C<"204.148.40.9">.  For demonstration purposes, we've
969 used the special hostname C<"localhost">, which should always mean the
970 current machine you're running on.  The corresponding Internet address
971 for localhost is C<"127.1">, if you'd rather use that.
972
973 =item C<PeerPort>
974
975 This is the service name or port number we'd like to connect to.
976 We could have gotten away with using just C<"daytime"> on systems with a
977 well-configured system services file,[FOOTNOTE: The system services file
978 is in I</etc/services> under Unix] but just in case, we've specified the
979 port number (13) in parentheses.  Using just the number would also have
980 worked, but constant numbers make careful programmers nervous.
981
982 =back
983
984 Notice how the return value from the C<new> constructor is used as
985 a filehandle in the C<while> loop?  That's what's called an indirect
986 filehandle, a scalar variable containing a filehandle.  You can use
987 it the same way you would a normal filehandle.  For example, you
988 can read one line from it this way:
989
990     $line = <$handle>;
991
992 all remaining lines from is this way:
993
994     @lines = <$handle>;
995
996 and send a line of data to it this way:
997
998     print $handle "some data\n";
999
1000 =head2 A Webget Client
1001
1002 Here's a simple client that takes a remote host to fetch a document
1003 from, and then a list of documents to get from that host.  This is a
1004 more interesting client than the previous one because it first sends
1005 something to the server before fetching the server's response.
1006
1007     #!/usr/bin/perl -w
1008     use IO::Socket;
1009     unless (@ARGV > 1) { die "usage: $0 host document ..." }
1010     $host = shift(@ARGV);
1011     $EOL = "\015\012";
1012     $BLANK = $EOL x 2;
1013     foreach $document ( @ARGV ) {
1014         $remote = IO::Socket::INET->new( Proto     => "tcp",
1015                                          PeerAddr  => $host,
1016                                          PeerPort  => "http(80)",
1017                                         );
1018         unless ($remote) { die "cannot connect to http daemon on $host" }
1019         $remote->autoflush(1);
1020         print $remote "GET $document HTTP/1.0" . $BLANK;
1021         while ( <$remote> ) { print }
1022         close $remote;
1023     }
1024
1025 The web server handing the "http" service, which is assumed to be at
1026 its standard port, number 80.  If the web server you're trying to
1027 connect to is at a different port (like 1080 or 8080), you should specify
1028 as the named-parameter pair, C<< PeerPort => 8080 >>.  The C<autoflush>
1029 method is used on the socket because otherwise the system would buffer
1030 up the output we sent it.  (If you're on a Mac, you'll also need to
1031 change every C<"\n"> in your code that sends data over the network to
1032 be a C<"\015\012"> instead.)
1033
1034 Connecting to the server is only the first part of the process: once you
1035 have the connection, you have to use the server's language.  Each server
1036 on the network has its own little command language that it expects as
1037 input.  The string that we send to the server starting with "GET" is in
1038 HTTP syntax.  In this case, we simply request each specified document.
1039 Yes, we really are making a new connection for each document, even though
1040 it's the same host.  That's the way you always used to have to speak HTTP.
1041 Recent versions of web browsers may request that the remote server leave
1042 the connection open a little while, but the server doesn't have to honor
1043 such a request.
1044
1045 Here's an example of running that program, which we'll call I<webget>:
1046
1047     % webget www.perl.com /guanaco.html
1048     HTTP/1.1 404 File Not Found
1049     Date: Thu, 08 May 1997 18:02:32 GMT
1050     Server: Apache/1.2b6
1051     Connection: close
1052     Content-type: text/html
1053
1054     <HEAD><TITLE>404 File Not Found</TITLE></HEAD>
1055     <BODY><H1>File Not Found</H1>
1056     The requested URL /guanaco.html was not found on this server.<P>
1057     </BODY>
1058
1059 Ok, so that's not very interesting, because it didn't find that
1060 particular document.  But a long response wouldn't have fit on this page.
1061
1062 For a more fully-featured version of this program, you should look to
1063 the I<lwp-request> program included with the LWP modules from CPAN.
1064
1065 =head2 Interactive Client with IO::Socket
1066
1067 Well, that's all fine if you want to send one command and get one answer,
1068 but what about setting up something fully interactive, somewhat like
1069 the way I<telnet> works?  That way you can type a line, get the answer,
1070 type a line, get the answer, etc.
1071
1072 This client is more complicated than the two we've done so far, but if
1073 you're on a system that supports the powerful C<fork> call, the solution
1074 isn't that rough.  Once you've made the connection to whatever service
1075 you'd like to chat with, call C<fork> to clone your process.  Each of
1076 these two identical process has a very simple job to do: the parent
1077 copies everything from the socket to standard output, while the child
1078 simultaneously copies everything from standard input to the socket.
1079 To accomplish the same thing using just one process would be I<much>
1080 harder, because it's easier to code two processes to do one thing than it
1081 is to code one process to do two things.  (This keep-it-simple principle
1082 a cornerstones of the Unix philosophy, and good software engineering as
1083 well, which is probably why it's spread to other systems.)
1084
1085 Here's the code:
1086
1087     #!/usr/bin/perl -w
1088     use strict;
1089     use IO::Socket;
1090     my ($host, $port, $kidpid, $handle, $line);
1091
1092     unless (@ARGV == 2) { die "usage: $0 host port" }
1093     ($host, $port) = @ARGV;
1094
1095     # create a tcp connection to the specified host and port
1096     $handle = IO::Socket::INET->new(Proto     => "tcp",
1097                                     PeerAddr  => $host,
1098                                     PeerPort  => $port)
1099            or die "can't connect to port $port on $host: $!";
1100
1101     $handle->autoflush(1);              # so output gets there right away
1102     print STDERR "[Connected to $host:$port]\n";
1103
1104     # split the program into two processes, identical twins
1105     die "can't fork: $!" unless defined($kidpid = fork());
1106
1107     # the if{} block runs only in the parent process
1108     if ($kidpid) {
1109         # copy the socket to standard output
1110         while (defined ($line = <$handle>)) {
1111             print STDOUT $line;
1112         }
1113         kill("TERM", $kidpid);                  # send SIGTERM to child
1114     }
1115     # the else{} block runs only in the child process
1116     else {
1117         # copy standard input to the socket
1118         while (defined ($line = <STDIN>)) {
1119             print $handle $line;
1120         }
1121     }
1122
1123 The C<kill> function in the parent's C<if> block is there to send a
1124 signal to our child process (current running in the C<else> block)
1125 as soon as the remote server has closed its end of the connection.
1126
1127 If the remote server sends data a byte at time, and you need that
1128 data immediately without waiting for a newline (which might not happen),
1129 you may wish to replace the C<while> loop in the parent with the
1130 following:
1131
1132     my $byte;
1133     while (sysread($handle, $byte, 1) == 1) {
1134         print STDOUT $byte;
1135     }
1136
1137 Making a system call for each byte you want to read is not very efficient
1138 (to put it mildly) but is the simplest to explain and works reasonably
1139 well.
1140
1141 =head1 TCP Servers with IO::Socket
1142
1143 As always, setting up a server is little bit more involved than running a client.
1144 The model is that the server creates a special kind of socket that
1145 does nothing but listen on a particular port for incoming connections.
1146 It does this by calling the C<< IO::Socket::INET->new() >> method with
1147 slightly different arguments than the client did.
1148
1149 =over
1150
1151 =item Proto
1152
1153 This is which protocol to use.  Like our clients, we'll
1154 still specify C<"tcp"> here.
1155
1156 =item LocalPort
1157
1158 We specify a local
1159 port in the C<LocalPort> argument, which we didn't do for the client.
1160 This is service name or port number for which you want to be the
1161 server. (Under Unix, ports under 1024 are restricted to the
1162 superuser.)  In our sample, we'll use port 9000, but you can use
1163 any port that's not currently in use on your system.  If you try
1164 to use one already in used, you'll get an "Address already in use"
1165 message.  Under Unix, the C<netstat -a> command will show
1166 which services current have servers.
1167
1168 =item Listen
1169
1170 The C<Listen> parameter is set to the maximum number of
1171 pending connections we can accept until we turn away incoming clients.
1172 Think of it as a call-waiting queue for your telephone.
1173 The low-level Socket module has a special symbol for the system maximum, which
1174 is SOMAXCONN.
1175
1176 =item Reuse
1177
1178 The C<Reuse> parameter is needed so that we restart our server
1179 manually without waiting a few minutes to allow system buffers to
1180 clear out.
1181
1182 =back
1183
1184 Once the generic server socket has been created using the parameters
1185 listed above, the server then waits for a new client to connect
1186 to it.  The server blocks in the C<accept> method, which eventually an
1187 bidirectional connection to the remote client.  (Make sure to autoflush
1188 this handle to circumvent buffering.)
1189
1190 To add to user-friendliness, our server prompts the user for commands.
1191 Most servers don't do this.  Because of the prompt without a newline,
1192 you'll have to use the C<sysread> variant of the interactive client above.
1193
1194 This server accepts one of five different commands, sending output
1195 back to the client.  Note that unlike most network servers, this one
1196 only handles one incoming client at a time.  Multithreaded servers are
1197 covered in Chapter 6 of the Camel.
1198
1199 Here's the code.  We'll
1200
1201  #!/usr/bin/perl -w
1202  use IO::Socket;
1203  use Net::hostent;              # for OO version of gethostbyaddr
1204
1205  $PORT = 9000;                  # pick something not in use
1206
1207  $server = IO::Socket::INET->new( Proto     => 'tcp',
1208                                   LocalPort => $PORT,
1209                                   Listen    => SOMAXCONN,
1210                                   Reuse     => 1);
1211
1212  die "can't setup server" unless $server;
1213  print "[Server $0 accepting clients]\n";
1214
1215  while ($client = $server->accept()) {
1216    $client->autoflush(1);
1217    print $client "Welcome to $0; type help for command list.\n";
1218    $hostinfo = gethostbyaddr($client->peeraddr);
1219    printf "[Connect from %s]\n", $hostinfo->name || $client->peerhost;
1220    print $client "Command? ";
1221    while ( <$client>) {
1222      next unless /\S/;       # blank line
1223      if    (/quit|exit/i)    { last;                                     }
1224      elsif (/date|time/i)    { printf $client "%s\n", scalar localtime;  }
1225      elsif (/who/i )         { print  $client `who 2>&1`;                }
1226      elsif (/cookie/i )      { print  $client `/usr/games/fortune 2>&1`; }
1227      elsif (/motd/i )        { print  $client `cat /etc/motd 2>&1`;      }
1228      else {
1229        print $client "Commands: quit date who cookie motd\n";
1230      }
1231    } continue {
1232       print $client "Command? ";
1233    }
1234    close $client;
1235  }
1236
1237 =head1 UDP: Message Passing
1238
1239 Another kind of client-server setup is one that uses not connections, but
1240 messages.  UDP communications involve much lower overhead but also provide
1241 less reliability, as there are no promises that messages will arrive at
1242 all, let alone in order and unmangled.  Still, UDP offers some advantages
1243 over TCP, including being able to "broadcast" or "multicast" to a whole
1244 bunch of destination hosts at once (usually on your local subnet).  If you
1245 find yourself overly concerned about reliability and start building checks
1246 into your message system, then you probably should use just TCP to start
1247 with.
1248
1249 Note that UDP datagrams are I<not> a bytestream and should not be treated
1250 as such. This makes using I/O mechanisms with internal buffering
1251 like stdio (i.e. print() and friends) especially cumbersome. Use syswrite(),
1252 or better send(), like in the example below.
1253
1254 Here's a UDP program similar to the sample Internet TCP client given
1255 earlier.  However, instead of checking one host at a time, the UDP version
1256 will check many of them asynchronously by simulating a multicast and then
1257 using select() to do a timed-out wait for I/O.  To do something similar
1258 with TCP, you'd have to use a different socket handle for each host.
1259
1260     #!/usr/bin/perl -w
1261     use strict;
1262     use Socket;
1263     use Sys::Hostname;
1264
1265     my ( $count, $hisiaddr, $hispaddr, $histime,
1266          $host, $iaddr, $paddr, $port, $proto,
1267          $rin, $rout, $rtime, $SECS_of_70_YEARS);
1268
1269     $SECS_of_70_YEARS      = 2208988800;
1270
1271     $iaddr = gethostbyname(hostname());
1272     $proto = getprotobyname('udp');
1273     $port = getservbyname('time', 'udp');
1274     $paddr = sockaddr_in(0, $iaddr); # 0 means let kernel pick
1275
1276     socket(SOCKET, PF_INET, SOCK_DGRAM, $proto)   || die "socket: $!";
1277     bind(SOCKET, $paddr)                          || die "bind: $!";
1278
1279     $| = 1;
1280     printf "%-12s %8s %s\n",  "localhost", 0, scalar localtime time;
1281     $count = 0;
1282     for $host (@ARGV) {
1283         $count++;
1284         $hisiaddr = inet_aton($host)    || die "unknown host";
1285         $hispaddr = sockaddr_in($port, $hisiaddr);
1286         defined(send(SOCKET, 0, 0, $hispaddr))    || die "send $host: $!";
1287     }
1288
1289     $rin = '';
1290     vec($rin, fileno(SOCKET), 1) = 1;
1291
1292     # timeout after 10.0 seconds
1293     while ($count && select($rout = $rin, undef, undef, 10.0)) {
1294         $rtime = '';
1295         ($hispaddr = recv(SOCKET, $rtime, 4, 0))        || die "recv: $!";
1296         ($port, $hisiaddr) = sockaddr_in($hispaddr);
1297         $host = gethostbyaddr($hisiaddr, AF_INET);
1298         $histime = unpack("N", $rtime) - $SECS_of_70_YEARS ;
1299         printf "%-12s ", $host;
1300         printf "%8d %s\n", $histime - time, scalar localtime($histime);
1301         $count--;
1302     }
1303
1304 Note that this example does not include any retries and may consequently
1305 fail to contact a reachable host. The most prominent reason for this
1306 is congestion of the queues on the sending host if the number of
1307 list of hosts to contact is sufficietly large.
1308
1309 =head1 SysV IPC
1310
1311 While System V IPC isn't so widely used as sockets, it still has some
1312 interesting uses.  You can't, however, effectively use SysV IPC or
1313 Berkeley mmap() to have shared memory so as to share a variable amongst
1314 several processes.  That's because Perl would reallocate your string when
1315 you weren't wanting it to.
1316
1317 Here's a small example showing shared memory usage.
1318
1319     use IPC::SysV qw(IPC_PRIVATE IPC_RMID S_IRWXU);
1320
1321     $size = 2000;
1322     $id = shmget(IPC_PRIVATE, $size, S_IRWXU) || die "$!";
1323     print "shm key $id\n";
1324
1325     $message = "Message #1";
1326     shmwrite($id, $message, 0, 60) || die "$!";
1327     print "wrote: '$message'\n";
1328     shmread($id, $buff, 0, 60) || die "$!";
1329     print "read : '$buff'\n";
1330
1331     # the buffer of shmread is zero-character end-padded.
1332     substr($buff, index($buff, "\0")) = '';
1333     print "un" unless $buff eq $message;
1334     print "swell\n";
1335
1336     print "deleting shm $id\n";
1337     shmctl($id, IPC_RMID, 0) || die "$!";
1338
1339 Here's an example of a semaphore:
1340
1341     use IPC::SysV qw(IPC_CREAT);
1342
1343     $IPC_KEY = 1234;
1344     $id = semget($IPC_KEY, 10, 0666 | IPC_CREAT ) || die "$!";
1345     print "shm key $id\n";
1346
1347 Put this code in a separate file to be run in more than one process.
1348 Call the file F<take>:
1349
1350     # create a semaphore
1351
1352     $IPC_KEY = 1234;
1353     $id = semget($IPC_KEY,  0 , 0 );
1354     die if !defined($id);
1355
1356     $semnum = 0;
1357     $semflag = 0;
1358
1359     # 'take' semaphore
1360     # wait for semaphore to be zero
1361     $semop = 0;
1362     $opstring1 = pack("s!s!s!", $semnum, $semop, $semflag);
1363
1364     # Increment the semaphore count
1365     $semop = 1;
1366     $opstring2 = pack("s!s!s!", $semnum, $semop,  $semflag);
1367     $opstring = $opstring1 . $opstring2;
1368
1369     semop($id,$opstring) || die "$!";
1370
1371 Put this code in a separate file to be run in more than one process.
1372 Call this file F<give>:
1373
1374     # 'give' the semaphore
1375     # run this in the original process and you will see
1376     # that the second process continues
1377
1378     $IPC_KEY = 1234;
1379     $id = semget($IPC_KEY, 0, 0);
1380     die if !defined($id);
1381
1382     $semnum = 0;
1383     $semflag = 0;
1384
1385     # Decrement the semaphore count
1386     $semop = -1;
1387     $opstring = pack("s!s!s!", $semnum, $semop, $semflag);
1388
1389     semop($id,$opstring) || die "$!";
1390
1391 The SysV IPC code above was written long ago, and it's definitely
1392 clunky looking.  For a more modern look, see the IPC::SysV module
1393 which is included with Perl starting from Perl 5.005.
1394
1395 A small example demonstrating SysV message queues:
1396
1397     use IPC::SysV qw(IPC_PRIVATE IPC_RMID IPC_CREAT S_IRWXU);
1398
1399     my $id = msgget(IPC_PRIVATE, IPC_CREAT | S_IRWXU);
1400
1401     my $sent = "message";
1402     my $type = 1234;
1403     my $rcvd;
1404     my $type_rcvd;
1405
1406     if (defined $id) {
1407         if (msgsnd($id, pack("l! a*", $type_sent, $sent), 0)) {
1408             if (msgrcv($id, $rcvd, 60, 0, 0)) {
1409                 ($type_rcvd, $rcvd) = unpack("l! a*", $rcvd);
1410                 if ($rcvd eq $sent) {
1411                     print "okay\n";
1412                 } else {
1413                     print "not okay\n";
1414                 }
1415             } else {
1416                 die "# msgrcv failed\n";
1417             }
1418         } else {
1419             die "# msgsnd failed\n";
1420         }
1421         msgctl($id, IPC_RMID, 0) || die "# msgctl failed: $!\n";
1422     } else {
1423         die "# msgget failed\n";
1424     }
1425
1426 =head1 NOTES
1427
1428 Most of these routines quietly but politely return C<undef> when they
1429 fail instead of causing your program to die right then and there due to
1430 an uncaught exception.  (Actually, some of the new I<Socket> conversion
1431 functions  croak() on bad arguments.)  It is therefore essential to
1432 check return values from these functions.  Always begin your socket
1433 programs this way for optimal success, and don't forget to add B<-T>
1434 taint checking flag to the #! line for servers:
1435
1436     #!/usr/bin/perl -Tw
1437     use strict;
1438     use sigtrap;
1439     use Socket;
1440
1441 =head1 BUGS
1442
1443 All these routines create system-specific portability problems.  As noted
1444 elsewhere, Perl is at the mercy of your C libraries for much of its system
1445 behaviour.  It's probably safest to assume broken SysV semantics for
1446 signals and to stick with simple TCP and UDP socket operations; e.g., don't
1447 try to pass open file descriptors over a local UDP datagram socket if you
1448 want your code to stand a chance of being portable.
1449
1450 As mentioned in the signals section, because few vendors provide C
1451 libraries that are safely re-entrant, the prudent programmer will do
1452 little else within a handler beyond setting a numeric variable that
1453 already exists; or, if locked into a slow (restarting) system call,
1454 using die() to raise an exception and longjmp(3) out.  In fact, even
1455 these may in some cases cause a core dump.  It's probably best to avoid
1456 signals except where they are absolutely inevitable.  This 
1457 will be addressed in a future release of Perl.
1458
1459 =head1 AUTHOR
1460
1461 Tom Christiansen, with occasional vestiges of Larry Wall's original
1462 version and suggestions from the Perl Porters.
1463
1464 =head1 SEE ALSO
1465
1466 There's a lot more to networking than this, but this should get you
1467 started.
1468
1469 For intrepid programmers, the indispensable textbook is I<Unix Network
1470 Programming> by W. Richard Stevens (published by Addison-Wesley).  Note
1471 that most books on networking address networking from the perspective of
1472 a C programmer; translation to Perl is left as an exercise for the reader.
1473
1474 The IO::Socket(3) manpage describes the object library, and the Socket(3)
1475 manpage describes the low-level interface to sockets.  Besides the obvious
1476 functions in L<perlfunc>, you should also check out the F<modules> file
1477 at your nearest CPAN site.  (See L<perlmodlib> or best yet, the F<Perl
1478 FAQ> for a description of what CPAN is and where to get it.)
1479
1480 Section 5 of the F<modules> file is devoted to "Networking, Device Control
1481 (modems), and Interprocess Communication", and contains numerous unbundled
1482 modules numerous networking modules, Chat and Expect operations, CGI
1483 programming, DCE, FTP, IPC, NNTP, Proxy, Ptty, RPC, SNMP, SMTP, Telnet,
1484 Threads, and ToolTalk--just to name a few.