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 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.
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.
32 die "Somebody sent me a SIG$signame";
34 $SIG{INT} = 'catch_zap'; # could fail in modules
35 $SIG{INT} = \&catch_zap; # best strategy
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:
43 defined $Config{sig_name} || die "No sigs?";
44 foreach $name (split(' ', $Config{sig_name})) {
50 So to check whether signal 17 and SIGALRM were the same, do just this:
52 print "signal #17 = $signame[17]\n";
54 print "SIGALRM is $signo{ALRM}\n";
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
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.
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.)
76 local $SIG{INT} = 'IGNORE';
80 # interrupts still ignored, for now...
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):
89 local $SIG{HUP} = 'IGNORE';
91 # snazzy writing of: kill('HUP', -$$)
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.
98 unless (kill 0 => $kid_pid) {
99 warn "something wicked happened to $kid_pid";
102 You might also want to employ anonymous functions for simple signal
105 $SIG{INT} = sub { die "\nOutta here!\n" };
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:
117 # loathe sysV: it makes us not only reinstate
118 # the handler, but place it after the wait
119 $SIG{CHLD} = \&REAPER;
121 $SIG{CHLD} = \&REAPER;
122 # now do something that forks...
124 or even the more elaborate:
126 use POSIX ":sys_wait_h";
129 while (($child = waitpid(-1,WNOHANG)) > 0) {
130 $Kid_Status{$child} = $?;
132 $SIG{CHLD} = \&REAPER; # still loathe sysV
134 $SIG{CHLD} = \&REAPER;
135 # do something that forks...
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.
148 local $SIG{ALRM} = sub { die "alarm clock restart" };
150 flock(FH, 2); # blocking write lock
153 if ($@ and $@ !~ /alarm clock restart/) { die }
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.
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
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.
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.
174 # system return val is backwards, so && not ||
176 $ENV{PATH} .= ":/etc:/usr/etc";
177 if ( system('mknod', $path, 'p')
178 && system('mkfifo', $path) )
180 die "mk{nod,fifo} $path failed";
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
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.
196 $FIFO = '.signature';
197 $ENV{PATH} .= ":/etc:/usr/games";
202 system('mknod', $FIFO, 'p')
203 && die "can't mknod $FIFO: $!";
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`;
210 sleep 2; # to avoid dup signals
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.
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.
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. Their dodginess
238 is expected to be addresses in the 5.005 release.
241 =head1 Using open() for IPC
243 Perl's basic open() statement can also be used for unidirectional interprocess
244 communication by either appending or prepending a pipe symbol to the second
245 argument to open(). Here's how to start something up in a child process you
248 open(SPOOLER, "| cat -v | lpr -h 2>/dev/null")
249 || die "can't fork: $!";
250 local $SIG{PIPE} = sub { die "spooler pipe broke" };
251 print SPOOLER "stuff\n";
252 close SPOOLER || die "bad spool: $! $?";
254 And here's how to start up a child process you intend to read from:
256 open(STATUS, "netstat -an 2>&1 |")
257 || die "can't fork: $!";
259 next if /^(tcp|udp)/;
262 close STATUS || die "bad netstat: $! $?";
264 If one can be sure that a particular program is a Perl script that is
265 expecting filenames in @ARGV, the clever programmer can write something
268 % program f1 "cmd1|" - f2 "cmd2|" f3 < tmpfile
270 and irrespective of which shell it's called from, the Perl program will
271 read from the file F<f1>, the process F<cmd1>, standard input (F<tmpfile>
272 in this case), the F<f2> file, the F<cmd2> command, and finally the F<f3>
273 file. Pretty nifty, eh?
275 You might notice that you could use backticks for much the
276 same effect as opening a pipe for reading:
278 print grep { !/^(tcp|udp)/ } `netstat -an 2>&1`;
279 die "bad netstat" if $?;
281 While this is true on the surface, it's much more efficient to process the
282 file one line or record at a time because then you don't have to read the
283 whole thing into memory at once. It also gives you finer control of the
284 whole process, letting you to kill off the child process early if you'd
287 Be careful to check both the open() and the close() return values. If
288 you're I<writing> to a pipe, you should also trap SIGPIPE. Otherwise,
289 think of what happens when you start up a pipe to a command that doesn't
290 exist: the open() will in all likelihood succeed (it only reflects the
291 fork()'s success), but then your output will fail--spectacularly. Perl
292 can't know whether the command worked because your command is actually
293 running in a separate process whose exec() might have failed. Therefore,
294 while readers of bogus commands return just a quick end of file, writers
295 to bogus command will trigger a signal they'd better be prepared to
298 open(FH, "|bogus") or die "can't fork: $!";
299 print FH "bang\n" or die "can't write: $!";
300 close FH or die "can't close: $!";
302 That won't blow up until the close, and it will blow up with a SIGPIPE.
303 To catch it, you could use this:
305 $SIG{PIPE} = 'IGNORE';
306 open(FH, "|bogus") or die "can't fork: $!";
307 print FH "bang\n" or die "can't write: $!";
308 close FH or die "can't close: status=$?";
312 Both the main process and any child processes it forks share the same
313 STDIN, STDOUT, and STDERR filehandles. If both processes try to access
314 them at once, strange things can happen. You may also want to close
315 or reopen the filehandles for the child. You can get around this by
316 opening your pipe with open(), but on some systems this means that the
317 child process cannot outlive the parent.
319 =head2 Background Processes
321 You can run a command in the background with:
325 The command's STDOUT and STDERR (and possibly STDIN, depending on your
326 shell) will be the same as the parent's. You won't need to catch
327 SIGCHLD because of the double-fork taking place (see below for more
330 =head2 Complete Dissociation of Child from Parent
332 In some cases (starting server processes, for instance) you'll want to
333 completely dissociate the child process from the parent. This is
334 often called daemonization. A well behaved daemon will also chdir()
335 to the root directory (so it doesn't prevent unmounting the filesystem
336 containing the directory from which it was launched) and redirect its
337 standard file descriptors from and to F</dev/null> (so that random
338 output doesn't wind up on the user's terminal).
343 chdir '/' or die "Can't chdir to /: $!";
344 open STDIN, '/dev/null' or die "Can't read /dev/null: $!";
345 open STDOUT, '>/dev/null'
346 or die "Can't write to /dev/null: $!";
347 defined(my $pid = fork) or die "Can't fork: $!";
349 setsid or die "Can't start a new session: $!";
350 open STDERR, '>&STDOUT' or die "Can't dup stdout: $!";
353 The fork() has to come before the setsid() to ensure that you aren't a
354 process group leader (the setsid() will fail if you are). If your
355 system doesn't have the setsid() function, open F</dev/tty> and use the
356 C<TIOCNOTTY> ioctl() on it instead. See L<tty(4)> for details.
358 Non-Unix users should check their Your_OS::Process module for other
361 =head2 Safe Pipe Opens
363 Another interesting approach to IPC is making your single program go
364 multiprocess and communicate between (or even amongst) yourselves. The
365 open() function will accept a file argument of either C<"-|"> or C<"|-">
366 to do a very interesting thing: it forks a child connected to the
367 filehandle you've opened. The child is running the same program as the
368 parent. This is useful for safely opening a file when running under an
369 assumed UID or GID, for example. If you open a pipe I<to> minus, you can
370 write to the filehandle you opened and your kid will find it in his
371 STDIN. If you open a pipe I<from> minus, you can read from the filehandle
372 you opened whatever your kid writes to his STDOUT.
378 $pid = open(KID_TO_WRITE, "|-");
379 unless (defined $pid) {
380 warn "cannot fork: $!";
381 die "bailing out" if $sleep_count++ > 6;
384 } until defined $pid;
387 print KID_TO_WRITE @some_data;
388 close(KID_TO_WRITE) || warn "kid exited $?";
390 ($EUID, $EGID) = ($UID, $GID); # suid progs only
391 open (FILE, "> /safe/file")
392 || die "can't open /safe/file: $!";
394 print FILE; # child's STDIN is parent's KID
396 exit; # don't forget this
399 Another common use for this construct is when you need to execute
400 something without the shell's interference. With system(), it's
401 straightforward, but you can't use a pipe open or backticks safely.
402 That's because there's no way to stop the shell from getting its hands on
403 your arguments. Instead, use lower-level control to call exec() directly.
405 Here's a safe backtick or pipe open for read:
407 # add error processing as above
408 $pid = open(KID_TO_READ, "-|");
411 while (<KID_TO_READ>) {
412 # do something interesting
414 close(KID_TO_READ) || warn "kid exited $?";
417 ($EUID, $EGID) = ($UID, $GID); # suid only
418 exec($program, @options, @args)
419 || die "can't exec program: $!";
424 And here's a safe pipe open for writing:
426 # add error processing as above
427 $pid = open(KID_TO_WRITE, "|-");
428 $SIG{ALRM} = sub { die "whoops, $program pipe broke" };
434 close(KID_TO_WRITE) || warn "kid exited $?";
437 ($EUID, $EGID) = ($UID, $GID);
438 exec($program, @options, @args)
439 || die "can't exec program: $!";
443 Note that these operations are full Unix forks, which means they may not be
444 correctly implemented on alien systems. Additionally, these are not true
445 multithreading. If you'd like to learn more about threading, see the
446 F<modules> file mentioned below in the SEE ALSO section.
448 =head2 Bidirectional Communication with Another Process
450 While this works reasonably well for unidirectional communication, what
451 about bidirectional communication? The obvious thing you'd like to do
452 doesn't actually work:
454 open(PROG_FOR_READING_AND_WRITING, "| some program |")
456 and if you forget to use the C<use warnings> pragma or the B<-w> flag,
457 then you'll miss out entirely on the diagnostic message:
459 Can't do bidirectional pipe at -e line 1.
461 If you really want to, you can use the standard open2() library function
462 to catch both ends. There's also an open3() for tridirectional I/O so you
463 can also catch your child's STDERR, but doing so would then require an
464 awkward select() loop and wouldn't allow you to use normal Perl input
467 If you look at its source, you'll see that open2() uses low-level
468 primitives like Unix pipe() and exec() calls to create all the connections.
469 While it might have been slightly more efficient by using socketpair(), it
470 would have then been even less portable than it already is. The open2()
471 and open3() functions are unlikely to work anywhere except on a Unix
472 system or some other one purporting to be POSIX compliant.
474 Here's an example of using open2():
478 $pid = open2(*Reader, *Writer, "cat -u -n" );
479 print Writer "stuff\n";
482 The problem with this is that Unix buffering is really going to
483 ruin your day. Even though your C<Writer> filehandle is auto-flushed,
484 and the process on the other end will get your data in a timely manner,
485 you can't usually do anything to force it to give it back to you
486 in a similarly quick fashion. In this case, we could, because we
487 gave I<cat> a B<-u> flag to make it unbuffered. But very few Unix
488 commands are designed to operate over pipes, so this seldom works
489 unless you yourself wrote the program on the other end of the
492 A solution to this is the nonstandard F<Comm.pl> library. It uses
493 pseudo-ttys to make your program behave more reasonably:
496 $ph = open_proc('cat -n');
498 print $ph "a line\n";
499 print "got back ", scalar <$ph>;
502 This way you don't have to have control over the source code of the
503 program you're using. The F<Comm> library also has expect()
504 and interact() functions. Find the library (and we hope its
505 successor F<IPC::Chat>) at your nearest CPAN archive as detailed
506 in the SEE ALSO section below.
508 The newer Expect.pm module from CPAN also addresses this kind of thing.
509 This module requires two other modules from CPAN: IO::Pty and IO::Stty.
510 It sets up a pseudo-terminal to interact with programs that insist on
511 using talking to the terminal device driver. If your system is
512 amongst those supported, this may be your best bet.
514 =head2 Bidirectional Communication with Yourself
516 If you want, you may make low-level pipe() and fork()
517 to stitch this together by hand. This example only
518 talks to itself, but you could reopen the appropriate
519 handles to STDIN and STDOUT and call other processes.
522 # pipe1 - bidirectional communication using two pipe pairs
523 # designed for the socketpair-challenged
524 use IO::Handle; # thousands of lines just for autoflush :-(
525 pipe(PARENT_RDR, CHILD_WTR); # XXX: failure?
526 pipe(CHILD_RDR, PARENT_WTR); # XXX: failure?
527 CHILD_WTR->autoflush(1);
528 PARENT_WTR->autoflush(1);
531 close PARENT_RDR; close PARENT_WTR;
532 print CHILD_WTR "Parent Pid $$ is sending this\n";
533 chomp($line = <CHILD_RDR>);
534 print "Parent Pid $$ just read this: `$line'\n";
535 close CHILD_RDR; close CHILD_WTR;
538 die "cannot fork: $!" unless defined $pid;
539 close CHILD_RDR; close CHILD_WTR;
540 chomp($line = <PARENT_RDR>);
541 print "Child Pid $$ just read this: `$line'\n";
542 print PARENT_WTR "Child Pid $$ is sending this\n";
543 close PARENT_RDR; close PARENT_WTR;
547 But you don't actually have to make two pipe calls. If you
548 have the socketpair() system call, it will do this all for you.
551 # pipe2 - bidirectional communication using socketpair
552 # "the best ones always go both ways"
555 use IO::Handle; # thousands of lines just for autoflush :-(
556 # We say AF_UNIX because although *_LOCAL is the
557 # POSIX 1003.1g form of the constant, many machines
558 # still don't have it.
559 socketpair(CHILD, PARENT, AF_UNIX, SOCK_STREAM, PF_UNSPEC)
560 or die "socketpair: $!";
563 PARENT->autoflush(1);
567 print CHILD "Parent Pid $$ is sending this\n";
568 chomp($line = <CHILD>);
569 print "Parent Pid $$ just read this: `$line'\n";
573 die "cannot fork: $!" unless defined $pid;
575 chomp($line = <PARENT>);
576 print "Child Pid $$ just read this: `$line'\n";
577 print PARENT "Child Pid $$ is sending this\n";
582 =head1 Sockets: Client/Server Communication
584 While not limited to Unix-derived operating systems (e.g., WinSock on PCs
585 provides socket support, as do some VMS libraries), you may not have
586 sockets on your system, in which case this section probably isn't going to do
587 you much good. With sockets, you can do both virtual circuits (i.e., TCP
588 streams) and datagrams (i.e., UDP packets). You may be able to do even more
589 depending on your system.
591 The Perl function calls for dealing with sockets have the same names as
592 the corresponding system calls in C, but their arguments tend to differ
593 for two reasons: first, Perl filehandles work differently than C file
594 descriptors. Second, Perl already knows the length of its strings, so you
595 don't need to pass that information.
597 One of the major problems with old socket code in Perl was that it used
598 hard-coded values for some of the constants, which severely hurt
599 portability. If you ever see code that does anything like explicitly
600 setting C<$AF_INET = 2>, you know you're in for big trouble: An
601 immeasurably superior approach is to use the C<Socket> module, which more
602 reliably grants access to various constants and functions you'll need.
604 If you're not writing a server/client for an existing protocol like
605 NNTP or SMTP, you should give some thought to how your server will
606 know when the client has finished talking, and vice-versa. Most
607 protocols are based on one-line messages and responses (so one party
608 knows the other has finished when a "\n" is received) or multi-line
609 messages and responses that end with a period on an empty line
610 ("\n.\n" terminates a message/response).
612 =head2 Internet Line Terminators
614 The Internet line terminator is "\015\012". Under ASCII variants of
615 Unix, that could usually be written as "\r\n", but under other systems,
616 "\r\n" might at times be "\015\015\012", "\012\012\015", or something
617 completely different. The standards specify writing "\015\012" to be
618 conformant (be strict in what you provide), but they also recommend
619 accepting a lone "\012" on input (but be lenient in what you require).
620 We haven't always been very good about that in the code in this manpage,
621 but unless you're on a Mac, you'll probably be ok.
623 =head2 Internet TCP Clients and Servers
625 Use Internet-domain sockets when you want to do client-server
626 communication that might extend to machines outside of your own system.
628 Here's a sample TCP client using Internet-domain sockets:
633 my ($remote,$port, $iaddr, $paddr, $proto, $line);
635 $remote = shift || 'localhost';
636 $port = shift || 2345; # random port
637 if ($port =~ /\D/) { $port = getservbyname($port, 'tcp') }
638 die "No port" unless $port;
639 $iaddr = inet_aton($remote) || die "no host: $remote";
640 $paddr = sockaddr_in($port, $iaddr);
642 $proto = getprotobyname('tcp');
643 socket(SOCK, PF_INET, SOCK_STREAM, $proto) || die "socket: $!";
644 connect(SOCK, $paddr) || die "connect: $!";
645 while (defined($line = <SOCK>)) {
649 close (SOCK) || die "close: $!";
652 And here's a corresponding server to go along with it. We'll
653 leave the address as INADDR_ANY so that the kernel can choose
654 the appropriate interface on multihomed hosts. If you want sit
655 on a particular interface (like the external side of a gateway
656 or firewall machine), you should fill this in with your real address
661 BEGIN { $ENV{PATH} = '/usr/ucb:/bin' }
666 sub logmsg { print "$0 $$: @_ at ", scalar localtime, "\n" }
668 my $port = shift || 2345;
669 my $proto = getprotobyname('tcp');
671 ($port) = $port =~ /^(\d+)$/ || die "invalid port";
673 socket(Server, PF_INET, SOCK_STREAM, $proto) || die "socket: $!";
674 setsockopt(Server, SOL_SOCKET, SO_REUSEADDR,
675 pack("l", 1)) || die "setsockopt: $!";
676 bind(Server, sockaddr_in($port, INADDR_ANY)) || die "bind: $!";
677 listen(Server,SOMAXCONN) || die "listen: $!";
679 logmsg "server started on port $port";
683 $SIG{CHLD} = \&REAPER;
685 for ( ; $paddr = accept(Client,Server); close Client) {
686 my($port,$iaddr) = sockaddr_in($paddr);
687 my $name = gethostbyaddr($iaddr,AF_INET);
689 logmsg "connection from $name [",
690 inet_ntoa($iaddr), "]
693 print Client "Hello there, $name, it's now ",
694 scalar localtime, $EOL;
697 And here's a multithreaded version. It's multithreaded in that
698 like most typical servers, it spawns (forks) a slave server to
699 handle the client request so that the master server can quickly
700 go back to service a new client.
704 BEGIN { $ENV{PATH} = '/usr/ucb:/bin' }
709 sub spawn; # forward declaration
710 sub logmsg { print "$0 $$: @_ at ", scalar localtime, "\n" }
712 my $port = shift || 2345;
713 my $proto = getprotobyname('tcp');
715 ($port) = $port =~ /^(\d+)$/ || die "invalid port";
717 socket(Server, PF_INET, SOCK_STREAM, $proto) || die "socket: $!";
718 setsockopt(Server, SOL_SOCKET, SO_REUSEADDR,
719 pack("l", 1)) || die "setsockopt: $!";
720 bind(Server, sockaddr_in($port, INADDR_ANY)) || die "bind: $!";
721 listen(Server,SOMAXCONN) || die "listen: $!";
723 logmsg "server started on port $port";
730 $SIG{CHLD} = \&REAPER; # loathe sysV
731 logmsg "reaped $waitedpid" . ($? ? " with exit $?" : '');
734 $SIG{CHLD} = \&REAPER;
736 for ( $waitedpid = 0;
737 ($paddr = accept(Client,Server)) || $waitedpid;
738 $waitedpid = 0, close Client)
740 next if $waitedpid and not $paddr;
741 my($port,$iaddr) = sockaddr_in($paddr);
742 my $name = gethostbyaddr($iaddr,AF_INET);
744 logmsg "connection from $name [",
745 inet_ntoa($iaddr), "]
749 print "Hello there, $name, it's now ", scalar localtime, $EOL;
750 exec '/usr/games/fortune' # XXX: `wrong' line terminators
751 or confess "can't exec fortune: $!";
759 unless (@_ == 0 && $coderef && ref($coderef) eq 'CODE') {
760 confess "usage: spawn CODEREF";
764 if (!defined($pid = fork)) {
765 logmsg "cannot fork: $!";
769 return; # I'm the parent
771 # else I'm the child -- go spawn
773 open(STDIN, "<&Client") || die "can't dup client to stdin";
774 open(STDOUT, ">&Client") || die "can't dup client to stdout";
775 ## open(STDERR, ">&STDOUT") || die "can't dup stdout to stderr";
779 This server takes the trouble to clone off a child version via fork() for
780 each incoming request. That way it can handle many requests at once,
781 which you might not always want. Even if you don't fork(), the listen()
782 will allow that many pending connections. Forking servers have to be
783 particularly careful about cleaning up their dead children (called
784 "zombies" in Unix parlance), because otherwise you'll quickly fill up your
787 We suggest that you use the B<-T> flag to use taint checking (see L<perlsec>)
788 even if we aren't running setuid or setgid. This is always a good idea
789 for servers and other programs run on behalf of someone else (like CGI
790 scripts), because it lessens the chances that people from the outside will
791 be able to compromise your system.
793 Let's look at another TCP client. This one connects to the TCP "time"
794 service on a number of different machines and shows how far their clocks
795 differ from the system on which it's being run:
801 my $SECS_of_70_YEARS = 2208988800;
802 sub ctime { scalar localtime(shift) }
804 my $iaddr = gethostbyname('localhost');
805 my $proto = getprotobyname('tcp');
806 my $port = getservbyname('time', 'tcp');
807 my $paddr = sockaddr_in(0, $iaddr);
811 printf "%-24s %8s %s\n", "localhost", 0, ctime(time());
813 foreach $host (@ARGV) {
814 printf "%-24s ", $host;
815 my $hisiaddr = inet_aton($host) || die "unknown host";
816 my $hispaddr = sockaddr_in($port, $hisiaddr);
817 socket(SOCKET, PF_INET, SOCK_STREAM, $proto) || die "socket: $!";
818 connect(SOCKET, $hispaddr) || die "bind: $!";
820 read(SOCKET, $rtime, 4);
822 my $histime = unpack("N", $rtime) - $SECS_of_70_YEARS ;
823 printf "%8d %s\n", $histime - time, ctime($histime);
826 =head2 Unix-Domain TCP Clients and Servers
828 That's fine for Internet-domain clients and servers, but what about local
829 communications? While you can use the same setup, sometimes you don't
830 want to. Unix-domain sockets are local to the current host, and are often
831 used internally to implement pipes. Unlike Internet domain sockets, Unix
832 domain sockets can show up in the file system with an ls(1) listing.
835 srw-rw-rw- 1 root 0 Oct 31 07:23 /dev/log
837 You can test for these with Perl's B<-S> file test:
839 unless ( -S '/dev/log' ) {
840 die "something's wicked with the print system";
843 Here's a sample Unix-domain client:
848 my ($rendezvous, $line);
850 $rendezvous = shift || '/tmp/catsock';
851 socket(SOCK, PF_UNIX, SOCK_STREAM, 0) || die "socket: $!";
852 connect(SOCK, sockaddr_un($rendezvous)) || die "connect: $!";
853 while (defined($line = <SOCK>)) {
858 And here's a corresponding server. You don't have to worry about silly
859 network terminators here because Unix domain sockets are guaranteed
860 to be on the localhost, and thus everything works right.
867 BEGIN { $ENV{PATH} = '/usr/ucb:/bin' }
868 sub logmsg { print "$0 $$: @_ at ", scalar localtime, "\n" }
870 my $NAME = '/tmp/catsock';
871 my $uaddr = sockaddr_un($NAME);
872 my $proto = getprotobyname('tcp');
874 socket(Server,PF_UNIX,SOCK_STREAM,0) || die "socket: $!";
876 bind (Server, $uaddr) || die "bind: $!";
877 listen(Server,SOMAXCONN) || die "listen: $!";
879 logmsg "server started on $NAME";
885 $SIG{CHLD} = \&REAPER; # loathe sysV
886 logmsg "reaped $waitedpid" . ($? ? " with exit $?" : '');
889 $SIG{CHLD} = \&REAPER;
892 for ( $waitedpid = 0;
893 accept(Client,Server) || $waitedpid;
894 $waitedpid = 0, close Client)
897 logmsg "connection on $NAME";
899 print "Hello there, it's now ", scalar localtime, "\n";
900 exec '/usr/games/fortune' or die "can't exec fortune: $!";
904 As you see, it's remarkably similar to the Internet domain TCP server, so
905 much so, in fact, that we've omitted several duplicate functions--spawn(),
906 logmsg(), ctime(), and REAPER()--which are exactly the same as in the
909 So why would you ever want to use a Unix domain socket instead of a
910 simpler named pipe? Because a named pipe doesn't give you sessions. You
911 can't tell one process's data from another's. With socket programming,
912 you get a separate session for each client: that's why accept() takes two
915 For example, let's say that you have a long running database server daemon
916 that you want folks from the World Wide Web to be able to access, but only
917 if they go through a CGI interface. You'd have a small, simple CGI
918 program that does whatever checks and logging you feel like, and then acts
919 as a Unix-domain client and connects to your private server.
921 =head1 TCP Clients with IO::Socket
923 For those preferring a higher-level interface to socket programming, the
924 IO::Socket module provides an object-oriented approach. IO::Socket is
925 included as part of the standard Perl distribution as of the 5.004
926 release. If you're running an earlier version of Perl, just fetch
927 IO::Socket from CPAN, where you'll also find modules providing easy
928 interfaces to the following systems: DNS, FTP, Ident (RFC 931), NIS and
929 NISPlus, NNTP, Ping, POP3, SMTP, SNMP, SSLeay, Telnet, and Time--just
932 =head2 A Simple Client
934 Here's a client that creates a TCP connection to the "daytime"
935 service at port 13 of the host name "localhost" and prints out everything
936 that the server there cares to provide.
940 $remote = IO::Socket::INET->new(
942 PeerAddr => "localhost",
943 PeerPort => "daytime(13)",
945 or die "cannot connect to daytime port at localhost";
946 while ( <$remote> ) { print }
948 When you run this program, you should get something back that
951 Wed May 14 08:40:46 MDT 1997
953 Here are what those parameters to the C<new> constructor mean:
959 This is which protocol to use. In this case, the socket handle returned
960 will be connected to a TCP socket, because we want a stream-oriented
961 connection, that is, one that acts pretty much like a plain old file.
962 Not all sockets are this of this type. For example, the UDP protocol
963 can be used to make a datagram socket, used for message-passing.
967 This is the name or Internet address of the remote host the server is
968 running on. We could have specified a longer name like C<"www.perl.com">,
969 or an address like C<"204.148.40.9">. For demonstration purposes, we've
970 used the special hostname C<"localhost">, which should always mean the
971 current machine you're running on. The corresponding Internet address
972 for localhost is C<"127.1">, if you'd rather use that.
976 This is the service name or port number we'd like to connect to.
977 We could have gotten away with using just C<"daytime"> on systems with a
978 well-configured system services file,[FOOTNOTE: The system services file
979 is in I</etc/services> under Unix] but just in case, we've specified the
980 port number (13) in parentheses. Using just the number would also have
981 worked, but constant numbers make careful programmers nervous.
985 Notice how the return value from the C<new> constructor is used as
986 a filehandle in the C<while> loop? That's what's called an indirect
987 filehandle, a scalar variable containing a filehandle. You can use
988 it the same way you would a normal filehandle. For example, you
989 can read one line from it this way:
993 all remaining lines from is this way:
997 and send a line of data to it this way:
999 print $handle "some data\n";
1001 =head2 A Webget Client
1003 Here's a simple client that takes a remote host to fetch a document
1004 from, and then a list of documents to get from that host. This is a
1005 more interesting client than the previous one because it first sends
1006 something to the server before fetching the server's response.
1010 unless (@ARGV > 1) { die "usage: $0 host document ..." }
1011 $host = shift(@ARGV);
1014 foreach $document ( @ARGV ) {
1015 $remote = IO::Socket::INET->new( Proto => "tcp",
1017 PeerPort => "http(80)",
1019 unless ($remote) { die "cannot connect to http daemon on $host" }
1020 $remote->autoflush(1);
1021 print $remote "GET $document HTTP/1.0" . $BLANK;
1022 while ( <$remote> ) { print }
1026 The web server handing the "http" service, which is assumed to be at
1027 its standard port, number 80. If the web server you're trying to
1028 connect to is at a different port (like 1080 or 8080), you should specify
1029 as the named-parameter pair, C<< PeerPort => 8080 >>. The C<autoflush>
1030 method is used on the socket because otherwise the system would buffer
1031 up the output we sent it. (If you're on a Mac, you'll also need to
1032 change every C<"\n"> in your code that sends data over the network to
1033 be a C<"\015\012"> instead.)
1035 Connecting to the server is only the first part of the process: once you
1036 have the connection, you have to use the server's language. Each server
1037 on the network has its own little command language that it expects as
1038 input. The string that we send to the server starting with "GET" is in
1039 HTTP syntax. In this case, we simply request each specified document.
1040 Yes, we really are making a new connection for each document, even though
1041 it's the same host. That's the way you always used to have to speak HTTP.
1042 Recent versions of web browsers may request that the remote server leave
1043 the connection open a little while, but the server doesn't have to honor
1046 Here's an example of running that program, which we'll call I<webget>:
1048 % webget www.perl.com /guanaco.html
1049 HTTP/1.1 404 File Not Found
1050 Date: Thu, 08 May 1997 18:02:32 GMT
1051 Server: Apache/1.2b6
1053 Content-type: text/html
1055 <HEAD><TITLE>404 File Not Found</TITLE></HEAD>
1056 <BODY><H1>File Not Found</H1>
1057 The requested URL /guanaco.html was not found on this server.<P>
1060 Ok, so that's not very interesting, because it didn't find that
1061 particular document. But a long response wouldn't have fit on this page.
1063 For a more fully-featured version of this program, you should look to
1064 the I<lwp-request> program included with the LWP modules from CPAN.
1066 =head2 Interactive Client with IO::Socket
1068 Well, that's all fine if you want to send one command and get one answer,
1069 but what about setting up something fully interactive, somewhat like
1070 the way I<telnet> works? That way you can type a line, get the answer,
1071 type a line, get the answer, etc.
1073 This client is more complicated than the two we've done so far, but if
1074 you're on a system that supports the powerful C<fork> call, the solution
1075 isn't that rough. Once you've made the connection to whatever service
1076 you'd like to chat with, call C<fork> to clone your process. Each of
1077 these two identical process has a very simple job to do: the parent
1078 copies everything from the socket to standard output, while the child
1079 simultaneously copies everything from standard input to the socket.
1080 To accomplish the same thing using just one process would be I<much>
1081 harder, because it's easier to code two processes to do one thing than it
1082 is to code one process to do two things. (This keep-it-simple principle
1083 a cornerstones of the Unix philosophy, and good software engineering as
1084 well, which is probably why it's spread to other systems.)
1091 my ($host, $port, $kidpid, $handle, $line);
1093 unless (@ARGV == 2) { die "usage: $0 host port" }
1094 ($host, $port) = @ARGV;
1096 # create a tcp connection to the specified host and port
1097 $handle = IO::Socket::INET->new(Proto => "tcp",
1100 or die "can't connect to port $port on $host: $!";
1102 $handle->autoflush(1); # so output gets there right away
1103 print STDERR "[Connected to $host:$port]\n";
1105 # split the program into two processes, identical twins
1106 die "can't fork: $!" unless defined($kidpid = fork());
1108 # the if{} block runs only in the parent process
1110 # copy the socket to standard output
1111 while (defined ($line = <$handle>)) {
1114 kill("TERM", $kidpid); # send SIGTERM to child
1116 # the else{} block runs only in the child process
1118 # copy standard input to the socket
1119 while (defined ($line = <STDIN>)) {
1120 print $handle $line;
1124 The C<kill> function in the parent's C<if> block is there to send a
1125 signal to our child process (current running in the C<else> block)
1126 as soon as the remote server has closed its end of the connection.
1128 If the remote server sends data a byte at time, and you need that
1129 data immediately without waiting for a newline (which might not happen),
1130 you may wish to replace the C<while> loop in the parent with the
1134 while (sysread($handle, $byte, 1) == 1) {
1138 Making a system call for each byte you want to read is not very efficient
1139 (to put it mildly) but is the simplest to explain and works reasonably
1142 =head1 TCP Servers with IO::Socket
1144 As always, setting up a server is little bit more involved than running a client.
1145 The model is that the server creates a special kind of socket that
1146 does nothing but listen on a particular port for incoming connections.
1147 It does this by calling the C<< IO::Socket::INET->new() >> method with
1148 slightly different arguments than the client did.
1154 This is which protocol to use. Like our clients, we'll
1155 still specify C<"tcp"> here.
1160 port in the C<LocalPort> argument, which we didn't do for the client.
1161 This is service name or port number for which you want to be the
1162 server. (Under Unix, ports under 1024 are restricted to the
1163 superuser.) In our sample, we'll use port 9000, but you can use
1164 any port that's not currently in use on your system. If you try
1165 to use one already in used, you'll get an "Address already in use"
1166 message. Under Unix, the C<netstat -a> command will show
1167 which services current have servers.
1171 The C<Listen> parameter is set to the maximum number of
1172 pending connections we can accept until we turn away incoming clients.
1173 Think of it as a call-waiting queue for your telephone.
1174 The low-level Socket module has a special symbol for the system maximum, which
1179 The C<Reuse> parameter is needed so that we restart our server
1180 manually without waiting a few minutes to allow system buffers to
1185 Once the generic server socket has been created using the parameters
1186 listed above, the server then waits for a new client to connect
1187 to it. The server blocks in the C<accept> method, which eventually an
1188 bidirectional connection to the remote client. (Make sure to autoflush
1189 this handle to circumvent buffering.)
1191 To add to user-friendliness, our server prompts the user for commands.
1192 Most servers don't do this. Because of the prompt without a newline,
1193 you'll have to use the C<sysread> variant of the interactive client above.
1195 This server accepts one of five different commands, sending output
1196 back to the client. Note that unlike most network servers, this one
1197 only handles one incoming client at a time. Multithreaded servers are
1198 covered in Chapter 6 of the Camel.
1200 Here's the code. We'll
1204 use Net::hostent; # for OO version of gethostbyaddr
1206 $PORT = 9000; # pick something not in use
1208 $server = IO::Socket::INET->new( Proto => 'tcp',
1210 Listen => SOMAXCONN,
1213 die "can't setup server" unless $server;
1214 print "[Server $0 accepting clients]\n";
1216 while ($client = $server->accept()) {
1217 $client->autoflush(1);
1218 print $client "Welcome to $0; type help for command list.\n";
1219 $hostinfo = gethostbyaddr($client->peeraddr);
1220 printf "[Connect from %s]\n", $hostinfo->name || $client->peerhost;
1221 print $client "Command? ";
1222 while ( <$client>) {
1223 next unless /\S/; # blank line
1224 if (/quit|exit/i) { last; }
1225 elsif (/date|time/i) { printf $client "%s\n", scalar localtime; }
1226 elsif (/who/i ) { print $client `who 2>&1`; }
1227 elsif (/cookie/i ) { print $client `/usr/games/fortune 2>&1`; }
1228 elsif (/motd/i ) { print $client `cat /etc/motd 2>&1`; }
1230 print $client "Commands: quit date who cookie motd\n";
1233 print $client "Command? ";
1238 =head1 UDP: Message Passing
1240 Another kind of client-server setup is one that uses not connections, but
1241 messages. UDP communications involve much lower overhead but also provide
1242 less reliability, as there are no promises that messages will arrive at
1243 all, let alone in order and unmangled. Still, UDP offers some advantages
1244 over TCP, including being able to "broadcast" or "multicast" to a whole
1245 bunch of destination hosts at once (usually on your local subnet). If you
1246 find yourself overly concerned about reliability and start building checks
1247 into your message system, then you probably should use just TCP to start
1250 Here's a UDP program similar to the sample Internet TCP client given
1251 earlier. However, instead of checking one host at a time, the UDP version
1252 will check many of them asynchronously by simulating a multicast and then
1253 using select() to do a timed-out wait for I/O. To do something similar
1254 with TCP, you'd have to use a different socket handle for each host.
1261 my ( $count, $hisiaddr, $hispaddr, $histime,
1262 $host, $iaddr, $paddr, $port, $proto,
1263 $rin, $rout, $rtime, $SECS_of_70_YEARS);
1265 $SECS_of_70_YEARS = 2208988800;
1267 $iaddr = gethostbyname(hostname());
1268 $proto = getprotobyname('udp');
1269 $port = getservbyname('time', 'udp');
1270 $paddr = sockaddr_in(0, $iaddr); # 0 means let kernel pick
1272 socket(SOCKET, PF_INET, SOCK_DGRAM, $proto) || die "socket: $!";
1273 bind(SOCKET, $paddr) || die "bind: $!";
1276 printf "%-12s %8s %s\n", "localhost", 0, scalar localtime time;
1280 $hisiaddr = inet_aton($host) || die "unknown host";
1281 $hispaddr = sockaddr_in($port, $hisiaddr);
1282 defined(send(SOCKET, 0, 0, $hispaddr)) || die "send $host: $!";
1286 vec($rin, fileno(SOCKET), 1) = 1;
1288 # timeout after 10.0 seconds
1289 while ($count && select($rout = $rin, undef, undef, 10.0)) {
1291 ($hispaddr = recv(SOCKET, $rtime, 4, 0)) || die "recv: $!";
1292 ($port, $hisiaddr) = sockaddr_in($hispaddr);
1293 $host = gethostbyaddr($hisiaddr, AF_INET);
1294 $histime = unpack("N", $rtime) - $SECS_of_70_YEARS ;
1295 printf "%-12s ", $host;
1296 printf "%8d %s\n", $histime - time, scalar localtime($histime);
1302 While System V IPC isn't so widely used as sockets, it still has some
1303 interesting uses. You can't, however, effectively use SysV IPC or
1304 Berkeley mmap() to have shared memory so as to share a variable amongst
1305 several processes. That's because Perl would reallocate your string when
1306 you weren't wanting it to.
1308 Here's a small example showing shared memory usage.
1310 use IPC::SysV qw(IPC_PRIVATE IPC_RMID S_IRWXU);
1313 $id = shmget(IPC_PRIVATE, $size, S_IRWXU) || die "$!";
1314 print "shm key $id\n";
1316 $message = "Message #1";
1317 shmwrite($id, $message, 0, 60) || die "$!";
1318 print "wrote: '$message'\n";
1319 shmread($id, $buff, 0, 60) || die "$!";
1320 print "read : '$buff'\n";
1322 # the buffer of shmread is zero-character end-padded.
1323 substr($buff, index($buff, "\0")) = '';
1324 print "un" unless $buff eq $message;
1327 print "deleting shm $id\n";
1328 shmctl($id, IPC_RMID, 0) || die "$!";
1330 Here's an example of a semaphore:
1332 use IPC::SysV qw(IPC_CREAT);
1335 $id = semget($IPC_KEY, 10, 0666 | IPC_CREAT ) || die "$!";
1336 print "shm key $id\n";
1338 Put this code in a separate file to be run in more than one process.
1339 Call the file F<take>:
1341 # create a semaphore
1344 $id = semget($IPC_KEY, 0 , 0 );
1345 die if !defined($id);
1351 # wait for semaphore to be zero
1353 $opstring1 = pack("s!s!s!", $semnum, $semop, $semflag);
1355 # Increment the semaphore count
1357 $opstring2 = pack("s!s!s!", $semnum, $semop, $semflag);
1358 $opstring = $opstring1 . $opstring2;
1360 semop($id,$opstring) || die "$!";
1362 Put this code in a separate file to be run in more than one process.
1363 Call this file F<give>:
1365 # 'give' the semaphore
1366 # run this in the original process and you will see
1367 # that the second process continues
1370 $id = semget($IPC_KEY, 0, 0);
1371 die if !defined($id);
1376 # Decrement the semaphore count
1378 $opstring = pack("s!s!s!", $semnum, $semop, $semflag);
1380 semop($id,$opstring) || die "$!";
1382 The SysV IPC code above was written long ago, and it's definitely
1383 clunky looking. For a more modern look, see the IPC::SysV module
1384 which is included with Perl starting from Perl 5.005.
1386 A small example demonstrating SysV message queues:
1388 use IPC::SysV qw(IPC_PRIVATE IPC_RMID IPC_CREAT S_IRWXU);
1390 my $id = msgget(IPC_PRIVATE, IPC_CREAT | S_IRWXU);
1392 my $sent = "message";
1398 if (msgsnd($id, pack("l! a*", $type_sent, $sent), 0)) {
1399 if (msgrcv($id, $rcvd, 60, 0, 0)) {
1400 ($type_rcvd, $rcvd) = unpack("l! a*", $rcvd);
1401 if ($rcvd eq $sent) {
1407 die "# msgrcv failed\n";
1410 die "# msgsnd failed\n";
1412 msgctl($id, IPC_RMID, 0) || die "# msgctl failed: $!\n";
1414 die "# msgget failed\n";
1419 Most of these routines quietly but politely return C<undef> when they
1420 fail instead of causing your program to die right then and there due to
1421 an uncaught exception. (Actually, some of the new I<Socket> conversion
1422 functions croak() on bad arguments.) It is therefore essential to
1423 check return values from these functions. Always begin your socket
1424 programs this way for optimal success, and don't forget to add B<-T>
1425 taint checking flag to the #! line for servers:
1434 All these routines create system-specific portability problems. As noted
1435 elsewhere, Perl is at the mercy of your C libraries for much of its system
1436 behaviour. It's probably safest to assume broken SysV semantics for
1437 signals and to stick with simple TCP and UDP socket operations; e.g., don't
1438 try to pass open file descriptors over a local UDP datagram socket if you
1439 want your code to stand a chance of being portable.
1441 As mentioned in the signals section, because few vendors provide C
1442 libraries that are safely re-entrant, the prudent programmer will do
1443 little else within a handler beyond setting a numeric variable that
1444 already exists; or, if locked into a slow (restarting) system call,
1445 using die() to raise an exception and longjmp(3) out. In fact, even
1446 these may in some cases cause a core dump. It's probably best to avoid
1447 signals except where they are absolutely inevitable. This
1448 will be addressed in a future release of Perl.
1452 Tom Christiansen, with occasional vestiges of Larry Wall's original
1453 version and suggestions from the Perl Porters.
1457 There's a lot more to networking than this, but this should get you
1460 For intrepid programmers, the indispensable textbook is I<Unix Network
1461 Programming> by W. Richard Stevens (published by Addison-Wesley). Note
1462 that most books on networking address networking from the perspective of
1463 a C programmer; translation to Perl is left as an exercise for the reader.
1465 The IO::Socket(3) manpage describes the object library, and the Socket(3)
1466 manpage describes the low-level interface to sockets. Besides the obvious
1467 functions in L<perlfunc>, you should also check out the F<modules> file
1468 at your nearest CPAN site. (See L<perlmodlib> or best yet, the F<Perl
1469 FAQ> for a description of what CPAN is and where to get it.)
1471 Section 5 of the F<modules> file is devoted to "Networking, Device Control
1472 (modems), and Interprocess Communication", and contains numerous unbundled
1473 modules numerous networking modules, Chat and Expect operations, CGI
1474 programming, DCE, FTP, IPC, NNTP, Proxy, Ptty, RPC, SNMP, SMTP, Telnet,
1475 Threads, and ToolTalk--just to name a few.