3 perlipc - Perl interprocess communication (signals, fifos, pipes, safe subprocesses, sockets, and semaphores)
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.
13 Perl uses a simple signal handling model: the %SIG hash contains names
14 or references of user-installed signal handlers. These handlers will
15 be called with an argument which is the name of the signal that
16 triggered it. A signal may be generated intentionally from a
17 particular keyboard sequence like control-C or control-Z, sent to you
18 from another process, or triggered automatically by the kernel when
19 special events transpire, like a child process exiting, your process
20 running out of stack space, or hitting file size limit.
22 For example, to trap an interrupt signal, set up a handler like this:
29 die "Somebody sent me a SIG$signame";
31 $SIG{INT} = 'catch_zap'; # could fail in modules
32 $SIG{INT} = \&catch_zap; # best strategy
34 Prior to Perl 5.7.3 it was necessary to do as little as you possibly
35 could in your handler; notice how all we do is set a global variable
36 and then raise an exception. That's because on most systems,
37 libraries are not re-entrant; particularly, memory allocation and I/O
38 routines are not. That meant that doing nearly I<anything> in your
39 handler could in theory trigger a memory fault and subsequent core
40 dump - see L</Deferred Signals (Safe Signals)> below.
42 The names of the signals are the ones listed out by C<kill -l> on your
43 system, or you can retrieve them from the Config module. Set up an
44 @signame list indexed by number to get the name and a %signo table
45 indexed by name to get the number:
48 defined $Config{sig_name} || die "No sigs?";
49 foreach $name (split(' ', $Config{sig_name})) {
55 So to check whether signal 17 and SIGALRM were the same, do just this:
57 print "signal #17 = $signame[17]\n";
59 print "SIGALRM is $signo{ALRM}\n";
62 You may also choose to assign the strings C<'IGNORE'> or C<'DEFAULT'> as
63 the handler, in which case Perl will try to discard the signal or do the
66 On most Unix platforms, the C<CHLD> (sometimes also known as C<CLD>) signal
67 has special behavior with respect to a value of C<'IGNORE'>.
68 Setting C<$SIG{CHLD}> to C<'IGNORE'> on such a platform has the effect of
69 not creating zombie processes when the parent process fails to C<wait()>
70 on its child processes (i.e. child processes are automatically reaped).
71 Calling C<wait()> with C<$SIG{CHLD}> set to C<'IGNORE'> usually returns
72 C<-1> on such platforms.
74 Some signals can be neither trapped nor ignored, such as
75 the KILL and STOP (but not the TSTP) signals. One strategy for
76 temporarily ignoring signals is to use a local() statement, which will be
77 automatically restored once your block is exited. (Remember that local()
78 values are "inherited" by functions called from within that block.)
81 local $SIG{INT} = 'IGNORE';
85 # interrupts still ignored, for now...
88 Sending a signal to a negative process ID means that you send the signal
89 to the entire Unix process-group. This code sends a hang-up signal to all
90 processes in the current process group (and sets $SIG{HUP} to IGNORE so
91 it doesn't kill itself):
94 local $SIG{HUP} = 'IGNORE';
96 # snazzy writing of: kill('HUP', -$$)
99 Another interesting signal to send is signal number zero. This doesn't
100 actually affect a child process, but instead checks whether it's alive
101 or has changed its UID.
103 unless (kill 0 => $kid_pid) {
104 warn "something wicked happened to $kid_pid";
107 When directed at a process whose UID is not identical to that
108 of the sending process, signal number zero may fail because
109 you lack permission to send the signal, even though the process is alive.
110 You may be able to determine the cause of failure using C<%!>.
112 unless (kill 0 => $pid or $!{EPERM}) {
113 warn "$pid looks dead";
116 You might also want to employ anonymous functions for simple signal
119 $SIG{INT} = sub { die "\nOutta here!\n" };
121 But that will be problematic for the more complicated handlers that need
122 to reinstall themselves. Because Perl's signal mechanism is currently
123 based on the signal(3) function from the C library, you may sometimes be so
124 unfortunate as to run on systems where that function is "broken", that
125 is, it behaves in the old unreliable SysV way rather than the newer, more
126 reasonable BSD and POSIX fashion. So you'll see defensive people writing
127 signal handlers like this:
131 # loathe SysV: it makes us not only reinstate
132 # the handler, but place it after the wait
133 $SIG{CHLD} = \&REAPER;
135 $SIG{CHLD} = \&REAPER;
136 # now do something that forks...
140 use POSIX ":sys_wait_h";
143 # If a second child dies while in the signal handler caused by the
144 # first death, we won't get another signal. So must loop here else
145 # we will leave the unreaped child as a zombie. And the next time
146 # two children die we get another zombie. And so on.
147 while (($child = waitpid(-1,WNOHANG)) > 0) {
148 $Kid_Status{$child} = $?;
150 $SIG{CHLD} = \&REAPER; # still loathe SysV
152 $SIG{CHLD} = \&REAPER;
153 # do something that forks...
155 Note: qx(), system() and some modules for calling external commands do a
156 fork() and wait() for the result. Thus, your signal handler (REAPER in the
157 example) will be called. Since wait() was already called by system() or qx()
158 the wait() in the signal handler will not see any more zombies and therefore
161 The best way to prevent this issue is to use waitpid, as in the following
164 use POSIX ":sys_wait_h"; # for nonblocking read
169 # don't change $! and $? outside handler
171 my $pid = waitpid(-1, WNOHANG);
172 return if $pid == -1;
173 return unless defined $children{$pid};
174 delete $children{$pid};
175 cleanup_child($pid, $?);
191 Signal handling is also used for timeouts in Unix. While safely
192 protected within an C<eval{}> block, you set a signal handler to trap
193 alarm signals and then schedule to have one delivered to you in some
194 number of seconds. Then try your blocking operation, clearing the alarm
195 when it's done but not before you've exited your C<eval{}> block. If it
196 goes off, you'll use die() to jump out of the block, much as you might
197 using longjmp() or throw() in other languages.
202 local $SIG{ALRM} = sub { die "alarm clock restart" };
204 flock(FH, 2); # blocking write lock
207 if ($@ and $@ !~ /alarm clock restart/) { die }
209 If the operation being timed out is system() or qx(), this technique
210 is liable to generate zombies. If this matters to you, you'll
211 need to do your own fork() and exec(), and kill the errant child process.
213 For more complex signal handling, you might see the standard POSIX
214 module. Lamentably, this is almost entirely undocumented, but
215 the F<t/lib/posix.t> file from the Perl source distribution has some
218 =head2 Handling the SIGHUP Signal in Daemons
220 A process that usually starts when the system boots and shuts down
221 when the system is shut down is called a daemon (Disk And Execution
222 MONitor). If a daemon process has a configuration file which is
223 modified after the process has been started, there should be a way to
224 tell that process to re-read its configuration file, without stopping
225 the process. Many daemons provide this mechanism using the C<SIGHUP>
226 signal handler. When you want to tell the daemon to re-read the file
227 you simply send it the C<SIGHUP> signal.
229 Not all platforms automatically reinstall their (native) signal
230 handlers after a signal delivery. This means that the handler works
231 only the first time the signal is sent. The solution to this problem
232 is to use C<POSIX> signal handlers if available, their behaviour
235 The following example implements a simple daemon, which restarts
236 itself every time the C<SIGHUP> signal is received. The actual code is
237 located in the subroutine C<code()>, which simply prints some debug
238 info to show that it works and should be replaced with the real code.
244 use File::Basename ();
245 use File::Spec::Functions;
249 # make the daemon cross-platform, so exec always calls the script
250 # itself with the right path, no matter how the script was invoked.
251 my $script = File::Basename::basename($0);
252 my $SELF = catfile $FindBin::Bin, $script;
254 # POSIX unmasks the sigprocmask properly
255 my $sigset = POSIX::SigSet->new();
256 my $action = POSIX::SigAction->new('sigHUP_handler',
259 POSIX::sigaction(&POSIX::SIGHUP, $action);
262 print "got SIGHUP\n";
263 exec($SELF, @ARGV) or die "Couldn't restart: $!\n";
270 print "ARGV: @ARGV\n";
282 A named pipe (often referred to as a FIFO) is an old Unix IPC
283 mechanism for processes communicating on the same machine. It works
284 just like a regular, connected anonymous pipes, except that the
285 processes rendezvous using a filename and don't have to be related.
287 To create a named pipe, use the C<POSIX::mkfifo()> function.
289 use POSIX qw(mkfifo);
290 mkfifo($path, 0700) or die "mkfifo $path failed: $!";
292 You can also use the Unix command mknod(1) or on some
293 systems, mkfifo(1). These may not be in your normal path.
295 # system return val is backwards, so && not ||
297 $ENV{PATH} .= ":/etc:/usr/etc";
298 if ( system('mknod', $path, 'p')
299 && system('mkfifo', $path) )
301 die "mk{nod,fifo} $path failed";
305 A fifo is convenient when you want to connect a process to an unrelated
306 one. When you open a fifo, the program will block until there's something
309 For example, let's say you'd like to have your F<.signature> file be a
310 named pipe that has a Perl program on the other end. Now every time any
311 program (like a mailer, news reader, finger program, etc.) tries to read
312 from that file, the reading program will block and your program will
313 supply the new signature. We'll use the pipe-checking file test B<-p>
314 to find out whether anyone (or anything) has accidentally removed our fifo.
317 $FIFO = '.signature';
323 POSIX::mkfifo($FIFO, 0700)
324 or die "can't mkfifo $FIFO: $!";
327 # next line blocks until there's a reader
328 open (FIFO, "> $FIFO") || die "can't write $FIFO: $!";
329 print FIFO "John Smith (smith\@host.org)\n", `fortune -s`;
331 sleep 2; # to avoid dup signals
334 =head2 Deferred Signals (Safe Signals)
336 In Perls before Perl 5.7.3 by installing Perl code to deal with
337 signals, you were exposing yourself to danger from two things. First,
338 few system library functions are re-entrant. If the signal interrupts
339 while Perl is executing one function (like malloc(3) or printf(3)),
340 and your signal handler then calls the same function again, you could
341 get unpredictable behavior--often, a core dump. Second, Perl isn't
342 itself re-entrant at the lowest levels. If the signal interrupts Perl
343 while Perl is changing its own internal data structures, similarly
344 unpredictable behaviour may result.
346 There were two things you could do, knowing this: be paranoid or be
347 pragmatic. The paranoid approach was to do as little as possible in your
348 signal handler. Set an existing integer variable that already has a
349 value, and return. This doesn't help you if you're in a slow system call,
350 which will just restart. That means you have to C<die> to longjmp(3) out
351 of the handler. Even this is a little cavalier for the true paranoiac,
352 who avoids C<die> in a handler because the system I<is> out to get you.
353 The pragmatic approach was to say "I know the risks, but prefer the
354 convenience", and to do anything you wanted in your signal handler,
355 and be prepared to clean up core dumps now and again.
357 Perl 5.7.3 and later avoid these problems by "deferring" signals.
358 That is, when the signal is delivered to the process by
359 the system (to the C code that implements Perl) a flag is set, and the
360 handler returns immediately. Then at strategic "safe" points in the
361 Perl interpreter (e.g. when it is about to execute a new opcode) the
362 flags are checked and the Perl level handler from %SIG is
363 executed. The "deferred" scheme allows much more flexibility in the
364 coding of signal handler as we know Perl interpreter is in a safe
365 state, and that we are not in a system library function when the
366 handler is called. However the implementation does differ from
367 previous Perls in the following ways:
371 =item Long-running opcodes
373 As the Perl interpreter only looks at the signal flags when it is about
374 to execute a new opcode, a signal that arrives during a long-running
375 opcode (e.g. a regular expression operation on a very large string) will
376 not be seen until the current opcode completes.
378 N.B. If a signal of any given type fires multiple times during an opcode
379 (such as from a fine-grained timer), the handler for that signal will
380 only be called once after the opcode completes, and all the other
381 instances will be discarded. Furthermore, if your system's signal queue
382 gets flooded to the point that there are signals that have been raised
383 but not yet caught (and thus not deferred) at the time an opcode
384 completes, those signals may well be caught and deferred during
385 subsequent opcodes, with sometimes surprising results. For example, you
386 may see alarms delivered even after calling C<alarm(0)> as the latter
387 stops the raising of alarms but does not cancel the delivery of alarms
388 raised but not yet caught. Do not depend on the behaviors described in
389 this paragraph as they are side effects of the current implementation and
390 may change in future versions of Perl.
393 =item Interrupting IO
395 When a signal is delivered (e.g. INT control-C) the operating system
396 breaks into IO operations like C<read> (used to implement Perls
397 E<lt>E<gt> operator). On older Perls the handler was called
398 immediately (and as C<read> is not "unsafe" this worked well). With
399 the "deferred" scheme the handler is not called immediately, and if
400 Perl is using system's C<stdio> library that library may re-start the
401 C<read> without returning to Perl and giving it a chance to call the
402 %SIG handler. If this happens on your system the solution is to use
403 C<:perlio> layer to do IO - at least on those handles which you want
404 to be able to break into with signals. (The C<:perlio> layer checks
405 the signal flags and calls %SIG handlers before resuming IO operation.)
407 Note that the default in Perl 5.7.3 and later is to automatically use
408 the C<:perlio> layer.
410 Note that some networking library functions like gethostbyname() are
411 known to have their own implementations of timeouts which may conflict
412 with your timeouts. If you are having problems with such functions,
413 you can try using the POSIX sigaction() function, which bypasses the
414 Perl safe signals (note that this means subjecting yourself to
415 possible memory corruption, as described above). Instead of setting
418 local $SIG{ALRM} = sub { die "alarm" };
420 try something like the following:
422 use POSIX qw(SIGALRM);
423 POSIX::sigaction(SIGALRM,
424 POSIX::SigAction->new(sub { die "alarm" }))
425 or die "Error setting SIGALRM handler: $!\n";
427 Another way to disable the safe signal behavior locally is to use
428 the C<Perl::Unsafe::Signals> module from CPAN (which will affect
431 =item Restartable system calls
433 On systems that supported it, older versions of Perl used the
434 SA_RESTART flag when installing %SIG handlers. This meant that
435 restartable system calls would continue rather than returning when
436 a signal arrived. In order to deliver deferred signals promptly,
437 Perl 5.7.3 and later do I<not> use SA_RESTART. Consequently,
438 restartable system calls can fail (with $! set to C<EINTR>) in places
439 where they previously would have succeeded.
441 Note that the default C<:perlio> layer will retry C<read>, C<write>
442 and C<close> as described above and that interrupted C<wait> and
443 C<waitpid> calls will always be retried.
445 =item Signals as "faults"
447 Certain signals, e.g. SEGV, ILL, and BUS, are generated as a result of
448 virtual memory or other "faults". These are normally fatal and there is
449 little a Perl-level handler can do with them, so Perl now delivers them
450 immediately rather than attempting to defer them.
452 =item Signals triggered by operating system state
454 On some operating systems certain signal handlers are supposed to "do
455 something" before returning. One example can be CHLD or CLD which
456 indicates a child process has completed. On some operating systems the
457 signal handler is expected to C<wait> for the completed child
458 process. On such systems the deferred signal scheme will not work for
459 those signals (it does not do the C<wait>). Again the failure will
460 look like a loop as the operating system will re-issue the signal as
461 there are un-waited-for completed child processes.
465 If you want the old signal behaviour back regardless of possible
466 memory corruption, set the environment variable C<PERL_SIGNALS> to
467 C<"unsafe"> (a new feature since Perl 5.8.1).
469 =head1 Using open() for IPC
471 Perl's basic open() statement can also be used for unidirectional
472 interprocess communication by either appending or prepending a pipe
473 symbol to the second argument to open(). Here's how to start
474 something up in a child process you intend to write to:
476 open(SPOOLER, "| cat -v | lpr -h 2>/dev/null")
477 || die "can't fork: $!";
478 local $SIG{PIPE} = sub { die "spooler pipe broke" };
479 print SPOOLER "stuff\n";
480 close SPOOLER || die "bad spool: $! $?";
482 And here's how to start up a child process you intend to read from:
484 open(STATUS, "netstat -an 2>&1 |")
485 || die "can't fork: $!";
487 next if /^(tcp|udp)/;
490 close STATUS || die "bad netstat: $! $?";
492 If one can be sure that a particular program is a Perl script that is
493 expecting filenames in @ARGV, the clever programmer can write something
496 % program f1 "cmd1|" - f2 "cmd2|" f3 < tmpfile
498 and irrespective of which shell it's called from, the Perl program will
499 read from the file F<f1>, the process F<cmd1>, standard input (F<tmpfile>
500 in this case), the F<f2> file, the F<cmd2> command, and finally the F<f3>
501 file. Pretty nifty, eh?
503 You might notice that you could use backticks for much the
504 same effect as opening a pipe for reading:
506 print grep { !/^(tcp|udp)/ } `netstat -an 2>&1`;
507 die "bad netstat" if $?;
509 While this is true on the surface, it's much more efficient to process the
510 file one line or record at a time because then you don't have to read the
511 whole thing into memory at once. It also gives you finer control of the
512 whole process, letting you to kill off the child process early if you'd
515 Be careful to check both the open() and the close() return values. If
516 you're I<writing> to a pipe, you should also trap SIGPIPE. Otherwise,
517 think of what happens when you start up a pipe to a command that doesn't
518 exist: the open() will in all likelihood succeed (it only reflects the
519 fork()'s success), but then your output will fail--spectacularly. Perl
520 can't know whether the command worked because your command is actually
521 running in a separate process whose exec() might have failed. Therefore,
522 while readers of bogus commands return just a quick end of file, writers
523 to bogus command will trigger a signal they'd better be prepared to
526 open(FH, "|bogus") or die "can't fork: $!";
527 print FH "bang\n" or die "can't write: $!";
528 close FH or die "can't close: $!";
530 That won't blow up until the close, and it will blow up with a SIGPIPE.
531 To catch it, you could use this:
533 $SIG{PIPE} = 'IGNORE';
534 open(FH, "|bogus") or die "can't fork: $!";
535 print FH "bang\n" or die "can't write: $!";
536 close FH or die "can't close: status=$?";
540 Both the main process and any child processes it forks share the same
541 STDIN, STDOUT, and STDERR filehandles. If both processes try to access
542 them at once, strange things can happen. You may also want to close
543 or reopen the filehandles for the child. You can get around this by
544 opening your pipe with open(), but on some systems this means that the
545 child process cannot outlive the parent.
547 =head2 Background Processes
549 You can run a command in the background with:
553 The command's STDOUT and STDERR (and possibly STDIN, depending on your
554 shell) will be the same as the parent's. You won't need to catch
555 SIGCHLD because of the double-fork taking place (see below for more
558 =head2 Complete Dissociation of Child from Parent
560 In some cases (starting server processes, for instance) you'll want to
561 completely dissociate the child process from the parent. This is
562 often called daemonization. A well behaved daemon will also chdir()
563 to the root directory (so it doesn't prevent unmounting the filesystem
564 containing the directory from which it was launched) and redirect its
565 standard file descriptors from and to F</dev/null> (so that random
566 output doesn't wind up on the user's terminal).
571 chdir '/' or die "Can't chdir to /: $!";
572 open STDIN, '/dev/null' or die "Can't read /dev/null: $!";
573 open STDOUT, '>/dev/null'
574 or die "Can't write to /dev/null: $!";
575 defined(my $pid = fork) or die "Can't fork: $!";
577 die "Can't start a new session: $!" if setsid == -1;
578 open STDERR, '>&STDOUT' or die "Can't dup stdout: $!";
581 The fork() has to come before the setsid() to ensure that you aren't a
582 process group leader (the setsid() will fail if you are). If your
583 system doesn't have the setsid() function, open F</dev/tty> and use the
584 C<TIOCNOTTY> ioctl() on it instead. See tty(4) for details.
586 Non-Unix users should check their Your_OS::Process module for other
589 =head2 Safe Pipe Opens
591 Another interesting approach to IPC is making your single program go
592 multiprocess and communicate between (or even amongst) yourselves. The
593 open() function will accept a file argument of either C<"-|"> or C<"|-">
594 to do a very interesting thing: it forks a child connected to the
595 filehandle you've opened. The child is running the same program as the
596 parent. This is useful for safely opening a file when running under an
597 assumed UID or GID, for example. If you open a pipe I<to> minus, you can
598 write to the filehandle you opened and your kid will find it in his
599 STDIN. If you open a pipe I<from> minus, you can read from the filehandle
600 you opened whatever your kid writes to his STDOUT.
602 use English '-no_match_vars';
606 $pid = open(KID_TO_WRITE, "|-");
607 unless (defined $pid) {
608 warn "cannot fork: $!";
609 die "bailing out" if $sleep_count++ > 6;
612 } until defined $pid;
615 print KID_TO_WRITE @some_data;
616 close(KID_TO_WRITE) || warn "kid exited $?";
618 ($EUID, $EGID) = ($UID, $GID); # suid progs only
619 open (FILE, "> /safe/file")
620 || die "can't open /safe/file: $!";
622 print FILE; # child's STDIN is parent's KID_TO_WRITE
624 exit; # don't forget this
627 Another common use for this construct is when you need to execute
628 something without the shell's interference. With system(), it's
629 straightforward, but you can't use a pipe open or backticks safely.
630 That's because there's no way to stop the shell from getting its hands on
631 your arguments. Instead, use lower-level control to call exec() directly.
633 Here's a safe backtick or pipe open for read:
635 # add error processing as above
636 $pid = open(KID_TO_READ, "-|");
639 while (<KID_TO_READ>) {
640 # do something interesting
642 close(KID_TO_READ) || warn "kid exited $?";
645 ($EUID, $EGID) = ($UID, $GID); # suid only
646 exec($program, @options, @args)
647 || die "can't exec program: $!";
652 And here's a safe pipe open for writing:
654 # add error processing as above
655 $pid = open(KID_TO_WRITE, "|-");
656 $SIG{PIPE} = sub { die "whoops, $program pipe broke" };
662 close(KID_TO_WRITE) || warn "kid exited $?";
665 ($EUID, $EGID) = ($UID, $GID);
666 exec($program, @options, @args)
667 || die "can't exec program: $!";
671 It is very easy to dead-lock a process using this form of open(), or
672 indeed any use of pipe() and multiple sub-processes. The above
673 example is 'safe' because it is simple and calls exec(). See
674 L</"Avoiding Pipe Deadlocks"> for general safety principles, but there
675 are extra gotchas with Safe Pipe Opens.
677 In particular, if you opened the pipe using C<open FH, "|-">, then you
678 cannot simply use close() in the parent process to close an unwanted
679 writer. Consider this code:
681 $pid = open WRITER, "|-";
682 defined $pid or die "fork failed; $!";
684 if (my $sub_pid = fork()) {
686 # do something else...
694 # do something with STDIN...
698 In the above, the true parent does not want to write to the WRITER
699 filehandle, so it closes it. However, because WRITER was opened using
700 C<open FH, "|-">, it has a special behaviour: closing it will call
701 waitpid() (see L<perlfunc/waitpid>), which waits for the sub-process
702 to exit. If the child process ends up waiting for something happening
703 in the section marked "do something else", then you have a deadlock.
705 This can also be a problem with intermediate sub-processes in more
706 complicated code, which will call waitpid() on all open filehandles
707 during global destruction; in no predictable order.
709 To solve this, you must manually use pipe(), fork(), and the form of
710 open() which sets one file descriptor to another, as below:
712 pipe(READER, WRITER);
714 defined $pid or die "fork failed; $!";
717 if (my $sub_pid = fork()) {
727 open STDIN, "<&READER";
733 Since Perl 5.8.0, you can also use the list form of C<open> for pipes :
736 open KID_PS, "-|", "ps", "aux" or die $!;
738 forks the ps(1) command (without spawning a shell, as there are more than
739 three arguments to open()), and reads its standard output via the
740 C<KID_PS> filehandle. The corresponding syntax to write to command
741 pipes (with C<"|-"> in place of C<"-|">) is also implemented.
743 Note that these operations are full Unix forks, which means they may not be
744 correctly implemented on alien systems. Additionally, these are not true
745 multithreading. If you'd like to learn more about threading, see the
746 F<modules> file mentioned below in the SEE ALSO section.
748 =head2 Avoiding Pipe Deadlocks
750 In general, if you have more than one sub-process, you need to be very
751 careful that any process which does not need the writer half of any
752 pipe you create for inter-process communication does not have it open.
754 The reason for this is that any child process which is reading from
755 the pipe and expecting an EOF will never receive it, and therefore
756 never exit. A single process closing a pipe is not enough to close it;
757 the last process with the pipe open must close it for it to read EOF.
759 Certain built-in Unix features help prevent this most of
760 the time. For instance, filehandles have a 'close on exec' flag (set
761 I<en masse> with Perl using the C<$^F> L<perlvar>), so that any
762 filehandles which you didn't explicitly route to the STDIN, STDOUT or
763 STDERR of a child I<program> will automatically be closed for you.
765 So, always explicitly and immediately call close() on the writable end
766 of any pipe, unless that process is actually writing to it. If you
767 don't explicitly call close() then be warned Perl will still close()
768 all the filehandles during global destruction. As warned above, if
769 those filehandles were opened with Safe Pipe Open, they will also call
770 waitpid() and you might again deadlock.
772 =head2 Bidirectional Communication with Another Process
774 While this works reasonably well for unidirectional communication, what
775 about bidirectional communication? The obvious thing you'd like to do
776 doesn't actually work:
778 open(PROG_FOR_READING_AND_WRITING, "| some program |")
780 and if you forget to use the C<use warnings> pragma or the B<-w> flag,
781 then you'll miss out entirely on the diagnostic message:
783 Can't do bidirectional pipe at -e line 1.
785 If you really want to, you can use the standard open2() library function
786 to catch both ends. There's also an open3() for tridirectional I/O so you
787 can also catch your child's STDERR, but doing so would then require an
788 awkward select() loop and wouldn't allow you to use normal Perl input
791 If you look at its source, you'll see that open2() uses low-level
792 primitives like Unix pipe() and exec() calls to create all the connections.
793 While it might have been slightly more efficient by using socketpair(), it
794 would have then been even less portable than it already is. The open2()
795 and open3() functions are unlikely to work anywhere except on a Unix
796 system or some other one purporting to be POSIX compliant.
798 Here's an example of using open2():
802 $pid = open2(*Reader, *Writer, "cat -u -n" );
803 print Writer "stuff\n";
806 The problem with this is that Unix buffering is really going to
807 ruin your day. Even though your C<Writer> filehandle is auto-flushed,
808 and the process on the other end will get your data in a timely manner,
809 you can't usually do anything to force it to give it back to you
810 in a similarly quick fashion. In this case, we could, because we
811 gave I<cat> a B<-u> flag to make it unbuffered. But very few Unix
812 commands are designed to operate over pipes, so this seldom works
813 unless you yourself wrote the program on the other end of the
816 A solution to this is the nonstandard F<Comm.pl> library. It uses
817 pseudo-ttys to make your program behave more reasonably:
820 $ph = open_proc('cat -n');
822 print $ph "a line\n";
823 print "got back ", scalar <$ph>;
826 This way you don't have to have control over the source code of the
827 program you're using. The F<Comm> library also has expect()
828 and interact() functions. Find the library (and we hope its
829 successor F<IPC::Chat>) at your nearest CPAN archive as detailed
830 in the SEE ALSO section below.
832 The newer Expect.pm module from CPAN also addresses this kind of thing.
833 This module requires two other modules from CPAN: IO::Pty and IO::Stty.
834 It sets up a pseudo-terminal to interact with programs that insist on
835 using talking to the terminal device driver. If your system is
836 amongst those supported, this may be your best bet.
838 =head2 Bidirectional Communication with Yourself
840 If you want, you may make low-level pipe() and fork()
841 to stitch this together by hand. This example only
842 talks to itself, but you could reopen the appropriate
843 handles to STDIN and STDOUT and call other processes.
846 # pipe1 - bidirectional communication using two pipe pairs
847 # designed for the socketpair-challenged
848 use IO::Handle; # thousands of lines just for autoflush :-(
849 pipe(PARENT_RDR, CHILD_WTR); # XXX: failure?
850 pipe(CHILD_RDR, PARENT_WTR); # XXX: failure?
851 CHILD_WTR->autoflush(1);
852 PARENT_WTR->autoflush(1);
855 close PARENT_RDR; close PARENT_WTR;
856 print CHILD_WTR "Parent Pid $$ is sending this\n";
857 chomp($line = <CHILD_RDR>);
858 print "Parent Pid $$ just read this: `$line'\n";
859 close CHILD_RDR; close CHILD_WTR;
862 die "cannot fork: $!" unless defined $pid;
863 close CHILD_RDR; close CHILD_WTR;
864 chomp($line = <PARENT_RDR>);
865 print "Child Pid $$ just read this: `$line'\n";
866 print PARENT_WTR "Child Pid $$ is sending this\n";
867 close PARENT_RDR; close PARENT_WTR;
871 But you don't actually have to make two pipe calls. If you
872 have the socketpair() system call, it will do this all for you.
875 # pipe2 - bidirectional communication using socketpair
876 # "the best ones always go both ways"
879 use IO::Handle; # thousands of lines just for autoflush :-(
880 # We say AF_UNIX because although *_LOCAL is the
881 # POSIX 1003.1g form of the constant, many machines
882 # still don't have it.
883 socketpair(CHILD, PARENT, AF_UNIX, SOCK_STREAM, PF_UNSPEC)
884 or die "socketpair: $!";
887 PARENT->autoflush(1);
891 print CHILD "Parent Pid $$ is sending this\n";
892 chomp($line = <CHILD>);
893 print "Parent Pid $$ just read this: `$line'\n";
897 die "cannot fork: $!" unless defined $pid;
899 chomp($line = <PARENT>);
900 print "Child Pid $$ just read this: `$line'\n";
901 print PARENT "Child Pid $$ is sending this\n";
906 =head1 Sockets: Client/Server Communication
908 While not limited to Unix-derived operating systems (e.g., WinSock on PCs
909 provides socket support, as do some VMS libraries), you may not have
910 sockets on your system, in which case this section probably isn't going to do
911 you much good. With sockets, you can do both virtual circuits (i.e., TCP
912 streams) and datagrams (i.e., UDP packets). You may be able to do even more
913 depending on your system.
915 The Perl function calls for dealing with sockets have the same names as
916 the corresponding system calls in C, but their arguments tend to differ
917 for two reasons: first, Perl filehandles work differently than C file
918 descriptors. Second, Perl already knows the length of its strings, so you
919 don't need to pass that information.
921 One of the major problems with old socket code in Perl was that it used
922 hard-coded values for some of the constants, which severely hurt
923 portability. If you ever see code that does anything like explicitly
924 setting C<$AF_INET = 2>, you know you're in for big trouble: An
925 immeasurably superior approach is to use the C<Socket> module, which more
926 reliably grants access to various constants and functions you'll need.
928 If you're not writing a server/client for an existing protocol like
929 NNTP or SMTP, you should give some thought to how your server will
930 know when the client has finished talking, and vice-versa. Most
931 protocols are based on one-line messages and responses (so one party
932 knows the other has finished when a "\n" is received) or multi-line
933 messages and responses that end with a period on an empty line
934 ("\n.\n" terminates a message/response).
936 =head2 Internet Line Terminators
938 The Internet line terminator is "\015\012". Under ASCII variants of
939 Unix, that could usually be written as "\r\n", but under other systems,
940 "\r\n" might at times be "\015\015\012", "\012\012\015", or something
941 completely different. The standards specify writing "\015\012" to be
942 conformant (be strict in what you provide), but they also recommend
943 accepting a lone "\012" on input (but be lenient in what you require).
944 We haven't always been very good about that in the code in this manpage,
945 but unless you're on a Mac, you'll probably be ok.
947 =head2 Internet TCP Clients and Servers
949 Use Internet-domain sockets when you want to do client-server
950 communication that might extend to machines outside of your own system.
952 Here's a sample TCP client using Internet-domain sockets:
957 my ($remote,$port, $iaddr, $paddr, $proto, $line);
959 $remote = shift || 'localhost';
960 $port = shift || 2345; # random port
961 if ($port =~ /\D/) { $port = getservbyname($port, 'tcp') }
962 die "No port" unless $port;
963 $iaddr = inet_aton($remote) || die "no host: $remote";
964 $paddr = sockaddr_in($port, $iaddr);
966 $proto = getprotobyname('tcp');
967 socket(SOCK, PF_INET, SOCK_STREAM, $proto) || die "socket: $!";
968 connect(SOCK, $paddr) || die "connect: $!";
969 while (defined($line = <SOCK>)) {
973 close (SOCK) || die "close: $!";
976 And here's a corresponding server to go along with it. We'll
977 leave the address as INADDR_ANY so that the kernel can choose
978 the appropriate interface on multihomed hosts. If you want sit
979 on a particular interface (like the external side of a gateway
980 or firewall machine), you should fill this in with your real address
985 BEGIN { $ENV{PATH} = '/usr/ucb:/bin' }
988 my $EOL = "\015\012";
990 sub logmsg { print "$0 $$: @_ at ", scalar localtime, "\n" }
992 my $port = shift || 2345;
993 my $proto = getprotobyname('tcp');
995 ($port) = $port =~ /^(\d+)$/ or die "invalid port";
997 socket(Server, PF_INET, SOCK_STREAM, $proto) || die "socket: $!";
998 setsockopt(Server, SOL_SOCKET, SO_REUSEADDR,
999 pack("l", 1)) || die "setsockopt: $!";
1000 bind(Server, sockaddr_in($port, INADDR_ANY)) || die "bind: $!";
1001 listen(Server,SOMAXCONN) || die "listen: $!";
1003 logmsg "server started on port $port";
1007 $SIG{CHLD} = \&REAPER;
1009 for ( ; $paddr = accept(Client,Server); close Client) {
1010 my($port,$iaddr) = sockaddr_in($paddr);
1011 my $name = gethostbyaddr($iaddr,AF_INET);
1013 logmsg "connection from $name [",
1014 inet_ntoa($iaddr), "]
1017 print Client "Hello there, $name, it's now ",
1018 scalar localtime, $EOL;
1021 And here's a multithreaded version. It's multithreaded in that
1022 like most typical servers, it spawns (forks) a slave server to
1023 handle the client request so that the master server can quickly
1024 go back to service a new client.
1028 BEGIN { $ENV{PATH} = '/usr/ucb:/bin' }
1031 my $EOL = "\015\012";
1033 sub spawn; # forward declaration
1034 sub logmsg { print "$0 $$: @_ at ", scalar localtime, "\n" }
1036 my $port = shift || 2345;
1037 my $proto = getprotobyname('tcp');
1039 ($port) = $port =~ /^(\d+)$/ or die "invalid port";
1041 socket(Server, PF_INET, SOCK_STREAM, $proto) || die "socket: $!";
1042 setsockopt(Server, SOL_SOCKET, SO_REUSEADDR,
1043 pack("l", 1)) || die "setsockopt: $!";
1044 bind(Server, sockaddr_in($port, INADDR_ANY))|| die "bind: $!";
1045 listen(Server,SOMAXCONN) || die "listen: $!";
1047 logmsg "server started on port $port";
1052 use POSIX ":sys_wait_h";
1056 local $!; # don't let waitpid() overwrite current error
1057 while ((my $pid = waitpid(-1,WNOHANG)) > 0 && WIFEXITED($?)) {
1058 logmsg "reaped $waitedpid" . ($? ? " with exit $?" : '');
1060 $SIG{CHLD} = \&REAPER; # loathe SysV
1063 $SIG{CHLD} = \&REAPER;
1066 $paddr = accept(Client, Server) || do {
1067 # try again if accept() returned because a signal was received
1071 my ($port, $iaddr) = sockaddr_in($paddr);
1072 my $name = gethostbyaddr($iaddr, AF_INET);
1074 logmsg "connection from $name [",
1080 print "Hello there, $name, it's now ", scalar localtime, $EOL;
1081 exec '/usr/games/fortune' # XXX: `wrong' line terminators
1082 or confess "can't exec fortune: $!";
1088 my $coderef = shift;
1090 unless (@_ == 0 && $coderef && ref($coderef) eq 'CODE') {
1091 confess "usage: spawn CODEREF";
1095 if (! defined($pid = fork)) {
1096 logmsg "cannot fork: $!";
1100 logmsg "begat $pid";
1101 return; # I'm the parent
1103 # else I'm the child -- go spawn
1105 open(STDIN, "<&Client") || die "can't dup client to stdin";
1106 open(STDOUT, ">&Client") || die "can't dup client to stdout";
1107 ## open(STDERR, ">&STDOUT") || die "can't dup stdout to stderr";
1111 This server takes the trouble to clone off a child version via fork()
1112 for each incoming request. That way it can handle many requests at
1113 once, which you might not always want. Even if you don't fork(), the
1114 listen() will allow that many pending connections. Forking servers
1115 have to be particularly careful about cleaning up their dead children
1116 (called "zombies" in Unix parlance), because otherwise you'll quickly
1117 fill up your process table. The REAPER subroutine is used here to
1118 call waitpid() for any child processes that have finished, thereby
1119 ensuring that they terminate cleanly and don't join the ranks of the
1122 Within the while loop we call accept() and check to see if it returns
1123 a false value. This would normally indicate a system error that needs
1124 to be reported. However the introduction of safe signals (see
1125 L</Deferred Signals (Safe Signals)> above) in Perl 5.7.3 means that
1126 accept() may also be interrupted when the process receives a signal.
1127 This typically happens when one of the forked sub-processes exits and
1128 notifies the parent process with a CHLD signal.
1130 If accept() is interrupted by a signal then $! will be set to EINTR.
1131 If this happens then we can safely continue to the next iteration of
1132 the loop and another call to accept(). It is important that your
1133 signal handling code doesn't modify the value of $! or this test will
1134 most likely fail. In the REAPER subroutine we create a local version
1135 of $! before calling waitpid(). When waitpid() sets $! to ECHILD (as
1136 it inevitably does when it has no more children waiting), it will
1137 update the local copy leaving the original unchanged.
1139 We suggest that you use the B<-T> flag to use taint checking (see L<perlsec>)
1140 even if we aren't running setuid or setgid. This is always a good idea
1141 for servers and other programs run on behalf of someone else (like CGI
1142 scripts), because it lessens the chances that people from the outside will
1143 be able to compromise your system.
1145 Let's look at another TCP client. This one connects to the TCP "time"
1146 service on a number of different machines and shows how far their clocks
1147 differ from the system on which it's being run:
1153 my $SECS_of_70_YEARS = 2208988800;
1154 sub ctime { scalar localtime(shift) }
1156 my $iaddr = gethostbyname('localhost');
1157 my $proto = getprotobyname('tcp');
1158 my $port = getservbyname('time', 'tcp');
1159 my $paddr = sockaddr_in(0, $iaddr);
1163 printf "%-24s %8s %s\n", "localhost", 0, ctime(time());
1165 foreach $host (@ARGV) {
1166 printf "%-24s ", $host;
1167 my $hisiaddr = inet_aton($host) || die "unknown host";
1168 my $hispaddr = sockaddr_in($port, $hisiaddr);
1169 socket(SOCKET, PF_INET, SOCK_STREAM, $proto) || die "socket: $!";
1170 connect(SOCKET, $hispaddr) || die "connect: $!";
1172 read(SOCKET, $rtime, 4);
1174 my $histime = unpack("N", $rtime) - $SECS_of_70_YEARS;
1175 printf "%8d %s\n", $histime - time, ctime($histime);
1178 =head2 Unix-Domain TCP Clients and Servers
1180 That's fine for Internet-domain clients and servers, but what about local
1181 communications? While you can use the same setup, sometimes you don't
1182 want to. Unix-domain sockets are local to the current host, and are often
1183 used internally to implement pipes. Unlike Internet domain sockets, Unix
1184 domain sockets can show up in the file system with an ls(1) listing.
1187 srw-rw-rw- 1 root 0 Oct 31 07:23 /dev/log
1189 You can test for these with Perl's B<-S> file test:
1191 unless ( -S '/dev/log' ) {
1192 die "something's wicked with the log system";
1195 Here's a sample Unix-domain client:
1200 my ($rendezvous, $line);
1202 $rendezvous = shift || 'catsock';
1203 socket(SOCK, PF_UNIX, SOCK_STREAM, 0) || die "socket: $!";
1204 connect(SOCK, sockaddr_un($rendezvous)) || die "connect: $!";
1205 while (defined($line = <SOCK>)) {
1210 And here's a corresponding server. You don't have to worry about silly
1211 network terminators here because Unix domain sockets are guaranteed
1212 to be on the localhost, and thus everything works right.
1219 BEGIN { $ENV{PATH} = '/usr/ucb:/bin' }
1220 sub spawn; # forward declaration
1221 sub logmsg { print "$0 $$: @_ at ", scalar localtime, "\n" }
1223 my $NAME = 'catsock';
1224 my $uaddr = sockaddr_un($NAME);
1225 my $proto = getprotobyname('tcp');
1227 socket(Server,PF_UNIX,SOCK_STREAM,0) || die "socket: $!";
1229 bind (Server, $uaddr) || die "bind: $!";
1230 listen(Server,SOMAXCONN) || die "listen: $!";
1232 logmsg "server started on $NAME";
1236 use POSIX ":sys_wait_h";
1239 while (($waitedpid = waitpid(-1,WNOHANG)) > 0) {
1240 logmsg "reaped $waitedpid" . ($? ? " with exit $?" : '');
1242 $SIG{CHLD} = \&REAPER; # loathe SysV
1245 $SIG{CHLD} = \&REAPER;
1248 for ( $waitedpid = 0;
1249 accept(Client,Server) || $waitedpid;
1250 $waitedpid = 0, close Client)
1253 logmsg "connection on $NAME";
1255 print "Hello there, it's now ", scalar localtime, "\n";
1256 exec '/usr/games/fortune' or die "can't exec fortune: $!";
1261 my $coderef = shift;
1263 unless (@_ == 0 && $coderef && ref($coderef) eq 'CODE') {
1264 confess "usage: spawn CODEREF";
1268 if (!defined($pid = fork)) {
1269 logmsg "cannot fork: $!";
1272 logmsg "begat $pid";
1273 return; # I'm the parent
1275 # else I'm the child -- go spawn
1277 open(STDIN, "<&Client") || die "can't dup client to stdin";
1278 open(STDOUT, ">&Client") || die "can't dup client to stdout";
1279 ## open(STDERR, ">&STDOUT") || die "can't dup stdout to stderr";
1283 As you see, it's remarkably similar to the Internet domain TCP server, so
1284 much so, in fact, that we've omitted several duplicate functions--spawn(),
1285 logmsg(), ctime(), and REAPER()--which are exactly the same as in the
1288 So why would you ever want to use a Unix domain socket instead of a
1289 simpler named pipe? Because a named pipe doesn't give you sessions. You
1290 can't tell one process's data from another's. With socket programming,
1291 you get a separate session for each client: that's why accept() takes two
1294 For example, let's say that you have a long running database server daemon
1295 that you want folks from the World Wide Web to be able to access, but only
1296 if they go through a CGI interface. You'd have a small, simple CGI
1297 program that does whatever checks and logging you feel like, and then acts
1298 as a Unix-domain client and connects to your private server.
1300 =head1 TCP Clients with IO::Socket
1302 For those preferring a higher-level interface to socket programming, the
1303 IO::Socket module provides an object-oriented approach. IO::Socket is
1304 included as part of the standard Perl distribution as of the 5.004
1305 release. If you're running an earlier version of Perl, just fetch
1306 IO::Socket from CPAN, where you'll also find modules providing easy
1307 interfaces to the following systems: DNS, FTP, Ident (RFC 931), NIS and
1308 NISPlus, NNTP, Ping, POP3, SMTP, SNMP, SSLeay, Telnet, and Time--just
1311 =head2 A Simple Client
1313 Here's a client that creates a TCP connection to the "daytime"
1314 service at port 13 of the host name "localhost" and prints out everything
1315 that the server there cares to provide.
1319 $remote = IO::Socket::INET->new(
1321 PeerAddr => "localhost",
1322 PeerPort => "daytime(13)",
1324 or die "cannot connect to daytime port at localhost";
1325 while ( <$remote> ) { print }
1327 When you run this program, you should get something back that
1330 Wed May 14 08:40:46 MDT 1997
1332 Here are what those parameters to the C<new> constructor mean:
1338 This is which protocol to use. In this case, the socket handle returned
1339 will be connected to a TCP socket, because we want a stream-oriented
1340 connection, that is, one that acts pretty much like a plain old file.
1341 Not all sockets are this of this type. For example, the UDP protocol
1342 can be used to make a datagram socket, used for message-passing.
1346 This is the name or Internet address of the remote host the server is
1347 running on. We could have specified a longer name like C<"www.perl.com">,
1348 or an address like C<"204.148.40.9">. For demonstration purposes, we've
1349 used the special hostname C<"localhost">, which should always mean the
1350 current machine you're running on. The corresponding Internet address
1351 for localhost is C<"127.1">, if you'd rather use that.
1355 This is the service name or port number we'd like to connect to.
1356 We could have gotten away with using just C<"daytime"> on systems with a
1357 well-configured system services file,[FOOTNOTE: The system services file
1358 is in I</etc/services> under Unix] but just in case, we've specified the
1359 port number (13) in parentheses. Using just the number would also have
1360 worked, but constant numbers make careful programmers nervous.
1364 Notice how the return value from the C<new> constructor is used as
1365 a filehandle in the C<while> loop? That's what's called an indirect
1366 filehandle, a scalar variable containing a filehandle. You can use
1367 it the same way you would a normal filehandle. For example, you
1368 can read one line from it this way:
1372 all remaining lines from is this way:
1376 and send a line of data to it this way:
1378 print $handle "some data\n";
1380 =head2 A Webget Client
1382 Here's a simple client that takes a remote host to fetch a document
1383 from, and then a list of documents to get from that host. This is a
1384 more interesting client than the previous one because it first sends
1385 something to the server before fetching the server's response.
1389 unless (@ARGV > 1) { die "usage: $0 host document ..." }
1390 $host = shift(@ARGV);
1393 foreach $document ( @ARGV ) {
1394 $remote = IO::Socket::INET->new( Proto => "tcp",
1396 PeerPort => "http(80)",
1398 unless ($remote) { die "cannot connect to http daemon on $host" }
1399 $remote->autoflush(1);
1400 print $remote "GET $document HTTP/1.0" . $BLANK;
1401 while ( <$remote> ) { print }
1405 The web server handing the "http" service, which is assumed to be at
1406 its standard port, number 80. If the web server you're trying to
1407 connect to is at a different port (like 1080 or 8080), you should specify
1408 as the named-parameter pair, C<< PeerPort => 8080 >>. The C<autoflush>
1409 method is used on the socket because otherwise the system would buffer
1410 up the output we sent it. (If you're on a Mac, you'll also need to
1411 change every C<"\n"> in your code that sends data over the network to
1412 be a C<"\015\012"> instead.)
1414 Connecting to the server is only the first part of the process: once you
1415 have the connection, you have to use the server's language. Each server
1416 on the network has its own little command language that it expects as
1417 input. The string that we send to the server starting with "GET" is in
1418 HTTP syntax. In this case, we simply request each specified document.
1419 Yes, we really are making a new connection for each document, even though
1420 it's the same host. That's the way you always used to have to speak HTTP.
1421 Recent versions of web browsers may request that the remote server leave
1422 the connection open a little while, but the server doesn't have to honor
1425 Here's an example of running that program, which we'll call I<webget>:
1427 % webget www.perl.com /guanaco.html
1428 HTTP/1.1 404 File Not Found
1429 Date: Thu, 08 May 1997 18:02:32 GMT
1430 Server: Apache/1.2b6
1432 Content-type: text/html
1434 <HEAD><TITLE>404 File Not Found</TITLE></HEAD>
1435 <BODY><H1>File Not Found</H1>
1436 The requested URL /guanaco.html was not found on this server.<P>
1439 Ok, so that's not very interesting, because it didn't find that
1440 particular document. But a long response wouldn't have fit on this page.
1442 For a more fully-featured version of this program, you should look to
1443 the I<lwp-request> program included with the LWP modules from CPAN.
1445 =head2 Interactive Client with IO::Socket
1447 Well, that's all fine if you want to send one command and get one answer,
1448 but what about setting up something fully interactive, somewhat like
1449 the way I<telnet> works? That way you can type a line, get the answer,
1450 type a line, get the answer, etc.
1452 This client is more complicated than the two we've done so far, but if
1453 you're on a system that supports the powerful C<fork> call, the solution
1454 isn't that rough. Once you've made the connection to whatever service
1455 you'd like to chat with, call C<fork> to clone your process. Each of
1456 these two identical process has a very simple job to do: the parent
1457 copies everything from the socket to standard output, while the child
1458 simultaneously copies everything from standard input to the socket.
1459 To accomplish the same thing using just one process would be I<much>
1460 harder, because it's easier to code two processes to do one thing than it
1461 is to code one process to do two things. (This keep-it-simple principle
1462 a cornerstones of the Unix philosophy, and good software engineering as
1463 well, which is probably why it's spread to other systems.)
1470 my ($host, $port, $kidpid, $handle, $line);
1472 unless (@ARGV == 2) { die "usage: $0 host port" }
1473 ($host, $port) = @ARGV;
1475 # create a tcp connection to the specified host and port
1476 $handle = IO::Socket::INET->new(Proto => "tcp",
1479 or die "can't connect to port $port on $host: $!";
1481 $handle->autoflush(1); # so output gets there right away
1482 print STDERR "[Connected to $host:$port]\n";
1484 # split the program into two processes, identical twins
1485 die "can't fork: $!" unless defined($kidpid = fork());
1487 # the if{} block runs only in the parent process
1489 # copy the socket to standard output
1490 while (defined ($line = <$handle>)) {
1493 kill("TERM", $kidpid); # send SIGTERM to child
1495 # the else{} block runs only in the child process
1497 # copy standard input to the socket
1498 while (defined ($line = <STDIN>)) {
1499 print $handle $line;
1503 The C<kill> function in the parent's C<if> block is there to send a
1504 signal to our child process (current running in the C<else> block)
1505 as soon as the remote server has closed its end of the connection.
1507 If the remote server sends data a byte at time, and you need that
1508 data immediately without waiting for a newline (which might not happen),
1509 you may wish to replace the C<while> loop in the parent with the
1513 while (sysread($handle, $byte, 1) == 1) {
1517 Making a system call for each byte you want to read is not very efficient
1518 (to put it mildly) but is the simplest to explain and works reasonably
1521 =head1 TCP Servers with IO::Socket
1523 As always, setting up a server is little bit more involved than running a client.
1524 The model is that the server creates a special kind of socket that
1525 does nothing but listen on a particular port for incoming connections.
1526 It does this by calling the C<< IO::Socket::INET->new() >> method with
1527 slightly different arguments than the client did.
1533 This is which protocol to use. Like our clients, we'll
1534 still specify C<"tcp"> here.
1539 port in the C<LocalPort> argument, which we didn't do for the client.
1540 This is service name or port number for which you want to be the
1541 server. (Under Unix, ports under 1024 are restricted to the
1542 superuser.) In our sample, we'll use port 9000, but you can use
1543 any port that's not currently in use on your system. If you try
1544 to use one already in used, you'll get an "Address already in use"
1545 message. Under Unix, the C<netstat -a> command will show
1546 which services current have servers.
1550 The C<Listen> parameter is set to the maximum number of
1551 pending connections we can accept until we turn away incoming clients.
1552 Think of it as a call-waiting queue for your telephone.
1553 The low-level Socket module has a special symbol for the system maximum, which
1558 The C<Reuse> parameter is needed so that we restart our server
1559 manually without waiting a few minutes to allow system buffers to
1564 Once the generic server socket has been created using the parameters
1565 listed above, the server then waits for a new client to connect
1566 to it. The server blocks in the C<accept> method, which eventually accepts a
1567 bidirectional connection from the remote client. (Make sure to autoflush
1568 this handle to circumvent buffering.)
1570 To add to user-friendliness, our server prompts the user for commands.
1571 Most servers don't do this. Because of the prompt without a newline,
1572 you'll have to use the C<sysread> variant of the interactive client above.
1574 This server accepts one of five different commands, sending output
1575 back to the client. Note that unlike most network servers, this one
1576 only handles one incoming client at a time. Multithreaded servers are
1577 covered in Chapter 6 of the Camel.
1579 Here's the code. We'll
1583 use Net::hostent; # for OO version of gethostbyaddr
1585 $PORT = 9000; # pick something not in use
1587 $server = IO::Socket::INET->new( Proto => 'tcp',
1589 Listen => SOMAXCONN,
1592 die "can't setup server" unless $server;
1593 print "[Server $0 accepting clients]\n";
1595 while ($client = $server->accept()) {
1596 $client->autoflush(1);
1597 print $client "Welcome to $0; type help for command list.\n";
1598 $hostinfo = gethostbyaddr($client->peeraddr);
1599 printf "[Connect from %s]\n", $hostinfo ? $hostinfo->name : $client->peerhost;
1600 print $client "Command? ";
1601 while ( <$client>) {
1602 next unless /\S/; # blank line
1603 if (/quit|exit/i) { last; }
1604 elsif (/date|time/i) { printf $client "%s\n", scalar localtime; }
1605 elsif (/who/i ) { print $client `who 2>&1`; }
1606 elsif (/cookie/i ) { print $client `/usr/games/fortune 2>&1`; }
1607 elsif (/motd/i ) { print $client `cat /etc/motd 2>&1`; }
1609 print $client "Commands: quit date who cookie motd\n";
1612 print $client "Command? ";
1617 =head1 UDP: Message Passing
1619 Another kind of client-server setup is one that uses not connections, but
1620 messages. UDP communications involve much lower overhead but also provide
1621 less reliability, as there are no promises that messages will arrive at
1622 all, let alone in order and unmangled. Still, UDP offers some advantages
1623 over TCP, including being able to "broadcast" or "multicast" to a whole
1624 bunch of destination hosts at once (usually on your local subnet). If you
1625 find yourself overly concerned about reliability and start building checks
1626 into your message system, then you probably should use just TCP to start
1629 Note that UDP datagrams are I<not> a bytestream and should not be treated
1630 as such. This makes using I/O mechanisms with internal buffering
1631 like stdio (i.e. print() and friends) especially cumbersome. Use syswrite(),
1632 or better send(), like in the example below.
1634 Here's a UDP program similar to the sample Internet TCP client given
1635 earlier. However, instead of checking one host at a time, the UDP version
1636 will check many of them asynchronously by simulating a multicast and then
1637 using select() to do a timed-out wait for I/O. To do something similar
1638 with TCP, you'd have to use a different socket handle for each host.
1645 my ( $count, $hisiaddr, $hispaddr, $histime,
1646 $host, $iaddr, $paddr, $port, $proto,
1647 $rin, $rout, $rtime, $SECS_of_70_YEARS);
1649 $SECS_of_70_YEARS = 2208988800;
1651 $iaddr = gethostbyname(hostname());
1652 $proto = getprotobyname('udp');
1653 $port = getservbyname('time', 'udp');
1654 $paddr = sockaddr_in(0, $iaddr); # 0 means let kernel pick
1656 socket(SOCKET, PF_INET, SOCK_DGRAM, $proto) || die "socket: $!";
1657 bind(SOCKET, $paddr) || die "bind: $!";
1660 printf "%-12s %8s %s\n", "localhost", 0, scalar localtime time;
1664 $hisiaddr = inet_aton($host) || die "unknown host";
1665 $hispaddr = sockaddr_in($port, $hisiaddr);
1666 defined(send(SOCKET, 0, 0, $hispaddr)) || die "send $host: $!";
1670 vec($rin, fileno(SOCKET), 1) = 1;
1672 # timeout after 10.0 seconds
1673 while ($count && select($rout = $rin, undef, undef, 10.0)) {
1675 ($hispaddr = recv(SOCKET, $rtime, 4, 0)) || die "recv: $!";
1676 ($port, $hisiaddr) = sockaddr_in($hispaddr);
1677 $host = gethostbyaddr($hisiaddr, AF_INET);
1678 $histime = unpack("N", $rtime) - $SECS_of_70_YEARS;
1679 printf "%-12s ", $host;
1680 printf "%8d %s\n", $histime - time, scalar localtime($histime);
1684 Note that this example does not include any retries and may consequently
1685 fail to contact a reachable host. The most prominent reason for this
1686 is congestion of the queues on the sending host if the number of
1687 list of hosts to contact is sufficiently large.
1691 While System V IPC isn't so widely used as sockets, it still has some
1692 interesting uses. You can't, however, effectively use SysV IPC or
1693 Berkeley mmap() to have shared memory so as to share a variable amongst
1694 several processes. That's because Perl would reallocate your string when
1695 you weren't wanting it to.
1697 Here's a small example showing shared memory usage.
1699 use IPC::SysV qw(IPC_PRIVATE IPC_RMID S_IRUSR S_IWUSR);
1702 $id = shmget(IPC_PRIVATE, $size, S_IRUSR|S_IWUSR) // die "$!";
1703 print "shm key $id\n";
1705 $message = "Message #1";
1706 shmwrite($id, $message, 0, 60) || die "$!";
1707 print "wrote: '$message'\n";
1708 shmread($id, $buff, 0, 60) || die "$!";
1709 print "read : '$buff'\n";
1711 # the buffer of shmread is zero-character end-padded.
1712 substr($buff, index($buff, "\0")) = '';
1713 print "un" unless $buff eq $message;
1716 print "deleting shm $id\n";
1717 shmctl($id, IPC_RMID, 0) || die "$!";
1719 Here's an example of a semaphore:
1721 use IPC::SysV qw(IPC_CREAT);
1724 $id = semget($IPC_KEY, 10, 0666 | IPC_CREAT ) // die "$!";
1725 print "shm key $id\n";
1727 Put this code in a separate file to be run in more than one process.
1728 Call the file F<take>:
1730 # create a semaphore
1733 $id = semget($IPC_KEY, 0 , 0 );
1734 die if !defined($id);
1740 # wait for semaphore to be zero
1742 $opstring1 = pack("s!s!s!", $semnum, $semop, $semflag);
1744 # Increment the semaphore count
1746 $opstring2 = pack("s!s!s!", $semnum, $semop, $semflag);
1747 $opstring = $opstring1 . $opstring2;
1749 semop($id,$opstring) || die "$!";
1751 Put this code in a separate file to be run in more than one process.
1752 Call this file F<give>:
1754 # 'give' the semaphore
1755 # run this in the original process and you will see
1756 # that the second process continues
1759 $id = semget($IPC_KEY, 0, 0);
1760 die if !defined($id);
1765 # Decrement the semaphore count
1767 $opstring = pack("s!s!s!", $semnum, $semop, $semflag);
1769 semop($id,$opstring) || die "$!";
1771 The SysV IPC code above was written long ago, and it's definitely
1772 clunky looking. For a more modern look, see the IPC::SysV module
1773 which is included with Perl starting from Perl 5.005.
1775 A small example demonstrating SysV message queues:
1777 use IPC::SysV qw(IPC_PRIVATE IPC_RMID IPC_CREAT S_IRUSR S_IWUSR);
1779 my $id = msgget(IPC_PRIVATE, IPC_CREAT | S_IRUSR | S_IWUSR);
1781 my $sent = "message";
1782 my $type_sent = 1234;
1787 if (msgsnd($id, pack("l! a*", $type_sent, $sent), 0)) {
1788 if (msgrcv($id, $rcvd, 60, 0, 0)) {
1789 ($type_rcvd, $rcvd) = unpack("l! a*", $rcvd);
1790 if ($rcvd eq $sent) {
1796 die "# msgrcv failed\n";
1799 die "# msgsnd failed\n";
1801 msgctl($id, IPC_RMID, 0) || die "# msgctl failed: $!\n";
1803 die "# msgget failed\n";
1808 Most of these routines quietly but politely return C<undef> when they
1809 fail instead of causing your program to die right then and there due to
1810 an uncaught exception. (Actually, some of the new I<Socket> conversion
1811 functions croak() on bad arguments.) It is therefore essential to
1812 check return values from these functions. Always begin your socket
1813 programs this way for optimal success, and don't forget to add B<-T>
1814 taint checking flag to the #! line for servers:
1823 All these routines create system-specific portability problems. As noted
1824 elsewhere, Perl is at the mercy of your C libraries for much of its system
1825 behaviour. It's probably safest to assume broken SysV semantics for
1826 signals and to stick with simple TCP and UDP socket operations; e.g., don't
1827 try to pass open file descriptors over a local UDP datagram socket if you
1828 want your code to stand a chance of being portable.
1832 Tom Christiansen, with occasional vestiges of Larry Wall's original
1833 version and suggestions from the Perl Porters.
1837 There's a lot more to networking than this, but this should get you
1840 For intrepid programmers, the indispensable textbook is I<Unix
1841 Network Programming, 2nd Edition, Volume 1> by W. Richard Stevens
1842 (published by Prentice-Hall). Note that most books on networking
1843 address the subject from the perspective of a C programmer; translation
1844 to Perl is left as an exercise for the reader.
1846 The IO::Socket(3) manpage describes the object library, and the Socket(3)
1847 manpage describes the low-level interface to sockets. Besides the obvious
1848 functions in L<perlfunc>, you should also check out the F<modules> file
1849 at your nearest CPAN site. (See L<perlmodlib> or best yet, the F<Perl
1850 FAQ> for a description of what CPAN is and where to get it.)
1852 Section 5 of the F<modules> file is devoted to "Networking, Device Control
1853 (modems), and Interprocess Communication", and contains numerous unbundled
1854 modules numerous networking modules, Chat and Expect operations, CGI
1855 programming, DCE, FTP, IPC, NNTP, Proxy, Ptty, RPC, SNMP, SMTP, Telnet,
1856 Threads, and ToolTalk--just to name a few.