This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perlipc: #109408
[perl5.git] / pod / perlipc.pod
CommitLineData
a0d0e21e
LW
1=head1 NAME
2
184e9718 3perlipc - Perl interprocess communication (signals, fifos, pipes, safe subprocesses, sockets, and semaphores)
a0d0e21e
LW
4
5=head1 DESCRIPTION
6
4633a7c4
LW
7The basic IPC facilities of Perl are built out of the good old Unix
8signals, named pipes, pipe opens, the Berkeley socket routines, and SysV
9IPC calls. Each is used in slightly different situations.
10
11=head1 Signals
12
490f90af
JH
13Perl uses a simple signal handling model: the %SIG hash contains names
14or references of user-installed signal handlers. These handlers will
15be called with an argument which is the name of the signal that
16triggered it. A signal may be generated intentionally from a
17particular keyboard sequence like control-C or control-Z, sent to you
18from another process, or triggered automatically by the kernel when
cf21866a
TC
19special events transpire, like a child process exiting, your own process
20running out of stack space, or hitting a process file-size limit.
4633a7c4 21
a11adca0 22For example, to trap an interrupt signal, set up a handler like this:
4633a7c4 23
73af1a12
DG
24 our $shucks;
25
4633a7c4 26 sub catch_zap {
322c2516
SF
27 my $signame = shift;
28 $shucks++;
29 die "Somebody sent me a SIG$signame";
54310121 30 }
cf21866a 31 $SIG{INT} = __PACKAGE__ . "::catch_zap";
4633a7c4
LW
32 $SIG{INT} = \&catch_zap; # best strategy
33
e6aa8b84 34Prior to Perl 5.8.0 it was necessary to do as little as you possibly
490f90af
JH
35could in your handler; notice how all we do is set a global variable
36and then raise an exception. That's because on most systems,
37libraries are not re-entrant; particularly, memory allocation and I/O
38routines are not. That meant that doing nearly I<anything> in your
39handler could in theory trigger a memory fault and subsequent core
ec488bcf 40dump - see L</Deferred Signals (Safe Signals)> below.
a11adca0 41
4633a7c4 42The names of the signals are the ones listed out by C<kill -l> on your
de7ba517 43system, or you can retrieve them using the CPAN module L<IPC::Signal>.
4633a7c4 44
cf21866a 45You may also choose to assign the strings C<"IGNORE"> or C<"DEFAULT"> as
4633a7c4 46the handler, in which case Perl will try to discard the signal or do the
f648820c
GS
47default thing.
48
19799a22 49On most Unix platforms, the C<CHLD> (sometimes also known as C<CLD>) signal
cf21866a
TC
50has special behavior with respect to a value of C<"IGNORE">.
51Setting C<$SIG{CHLD}> to C<"IGNORE"> on such a platform has the effect of
f648820c 52not creating zombie processes when the parent process fails to C<wait()>
cf21866a
TC
53on its child processes (i.e., child processes are automatically reaped).
54Calling C<wait()> with C<$SIG{CHLD}> set to C<"IGNORE"> usually returns
f648820c
GS
55C<-1> on such platforms.
56
cf21866a 57Some signals can be neither trapped nor ignored, such as the KILL and STOP
de7ba517
LT
58(but not the TSTP) signals. Note that ignoring signals makes them disappear.
59If you only want them blocked temporarily without them getting lost you'll
60have to use POSIX' sigprocmask.
4633a7c4
LW
61
62Sending a signal to a negative process ID means that you send the signal
cf21866a
TC
63to the entire Unix process group. This code sends a hang-up signal to all
64processes in the current process group, and also sets $SIG{HUP} to C<"IGNORE">
65so it doesn't kill itself:
4633a7c4 66
cf21866a 67 # block scope for local
4633a7c4 68 {
cf21866a 69 local $SIG{HUP} = "IGNORE";
322c2516 70 kill HUP => -$$;
cf21866a 71 # snazzy writing of: kill("HUP", -$$)
4633a7c4 72 }
a0d0e21e 73
4633a7c4 74Another interesting signal to send is signal number zero. This doesn't
1e9c1022 75actually affect a child process, but instead checks whether it's alive
de7ba517 76or has changed its UIDs.
a0d0e21e 77
4633a7c4 78 unless (kill 0 => $kid_pid) {
322c2516 79 warn "something wicked happened to $kid_pid";
54310121 80 }
a0d0e21e 81
de7ba517
LT
82Signal number zero may fail because you lack permission to send the
83signal when directed at a process whose real or saved UID is not
84identical to the real or effective UID of the sending process, even
85though the process is alive. You may be able to determine the cause of
86failure using C<$!> or C<%!>.
1e9c1022 87
cf21866a 88 unless (kill(0 => $pid) || $!{EPERM}) {
322c2516 89 warn "$pid looks dead";
1e9c1022
JL
90 }
91
4633a7c4
LW
92You might also want to employ anonymous functions for simple signal
93handlers:
a0d0e21e 94
4633a7c4 95 $SIG{INT} = sub { die "\nOutta here!\n" };
a0d0e21e 96
de7ba517
LT
97SIGCHLD handlers require some special care. If a second child dies
98while in the signal handler caused by the first death, we won't get
99another signal. So must loop here else we will leave the unreaped child
100as a zombie. And the next time two children die we get another zombie.
101And so on.
4633a7c4 102
6a3992aa 103 use POSIX ":sys_wait_h";
de7ba517
LT
104 $SIG{CHLD} = sub {
105 while ((my $child = waitpid(-1, WNOHANG)) > 0) {
322c2516
SF
106 $Kid_Status{$child} = $?;
107 }
de7ba517 108 };
4633a7c4
LW
109 # do something that forks...
110
cf21866a
TC
111Be careful: qx(), system(), and some modules for calling external commands
112do a fork(), then wait() for the result. Thus, your signal handler
de7ba517
LT
113will be called. Because wait() was already called by system() or qx(),
114the wait() in the signal handler will see no more zombies and will
115therefore block.
0a18a49b 116
cf21866a 117The best way to prevent this issue is to use waitpid(), as in the following
0a18a49b
MH
118example:
119
120 use POSIX ":sys_wait_h"; # for nonblocking read
121
122 my %children;
123
124 $SIG{CHLD} = sub {
125 # don't change $! and $? outside handler
cf21866a 126 local ($!, $?);
0a18a49b
MH
127 my $pid = waitpid(-1, WNOHANG);
128 return if $pid == -1;
129 return unless defined $children{$pid};
130 delete $children{$pid};
131 cleanup_child($pid, $?);
132 };
133
134 while (1) {
135 my $pid = fork();
cf21866a 136 die "cannot fork" unless defined $pid;
0a18a49b
MH
137 if ($pid == 0) {
138 # ...
139 exit 0;
140 } else {
cf21866a 141 $children{$pid}=1;
0a18a49b
MH
142 # ...
143 system($command);
144 # ...
145 }
146 }
147
148Signal handling is also used for timeouts in Unix. While safely
4633a7c4
LW
149protected within an C<eval{}> block, you set a signal handler to trap
150alarm signals and then schedule to have one delivered to you in some
151number of seconds. Then try your blocking operation, clearing the alarm
152when it's done but not before you've exited your C<eval{}> block. If it
de7ba517 153goes off, you'll use die() to jump out of the block.
4633a7c4
LW
154
155Here's an example:
156
cf21866a 157 my $ALARM_EXCEPTION = "alarm clock restart";
54310121 158 eval {
cf21866a 159 local $SIG{ALRM} = sub { die $ALARM_EXCEPTION };
54310121 160 alarm 10;
cf21866a
TC
161 flock(FH, 2) # blocking write lock
162 || die "cannot flock: $!";
54310121 163 alarm 0;
4633a7c4 164 };
cf21866a 165 if ($@ && $@ !~ quotemeta($ALARM_EXCEPTION)) { die }
4633a7c4 166
8a4f6ac2
GS
167If the operation being timed out is system() or qx(), this technique
168is liable to generate zombies. If this matters to you, you'll
169need to do your own fork() and exec(), and kill the errant child process.
170
4633a7c4
LW
171For more complex signal handling, you might see the standard POSIX
172module. Lamentably, this is almost entirely undocumented, but
173the F<t/lib/posix.t> file from the Perl source distribution has some
174examples in it.
175
28494392
SB
176=head2 Handling the SIGHUP Signal in Daemons
177
178A process that usually starts when the system boots and shuts down
179when the system is shut down is called a daemon (Disk And Execution
180MONitor). If a daemon process has a configuration file which is
181modified after the process has been started, there should be a way to
cf21866a
TC
182tell that process to reread its configuration file without stopping
183the process. Many daemons provide this mechanism using a C<SIGHUP>
184signal handler. When you want to tell the daemon to reread the file,
185simply send it the C<SIGHUP> signal.
28494392 186
28494392
SB
187The following example implements a simple daemon, which restarts
188itself every time the C<SIGHUP> signal is received. The actual code is
cf21866a
TC
189located in the subroutine C<code()>, which just prints some debugging
190info to show that it works; it should be replaced with the real code.
28494392
SB
191
192 #!/usr/bin/perl -w
d6fd60d6 193
28494392
SB
194 use POSIX ();
195 use FindBin ();
196 use File::Basename ();
197 use File::Spec::Functions;
d6fd60d6 198
cf21866a 199 $| = 1;
d6fd60d6 200
28494392
SB
201 # make the daemon cross-platform, so exec always calls the script
202 # itself with the right path, no matter how the script was invoked.
203 my $script = File::Basename::basename($0);
cf21866a 204 my $SELF = catfile($FindBin::Bin, $script);
d6fd60d6 205
28494392 206 # POSIX unmasks the sigprocmask properly
de7ba517 207 $SIG{HUP} = sub {
28494392 208 print "got SIGHUP\n";
cf21866a 209 exec($SELF, @ARGV) || die "$0: couldn't restart: $!";
de7ba517 210 };
d6fd60d6 211
28494392 212 code();
d6fd60d6 213
28494392
SB
214 sub code {
215 print "PID: $$\n";
216 print "ARGV: @ARGV\n";
cf21866a
TC
217 my $count = 0;
218 while (++$count) {
28494392 219 sleep 2;
cf21866a 220 print "$count\n";
28494392
SB
221 }
222 }
28494392
SB
223
224
ffc145e8 225=head2 Deferred Signals (Safe Signals)
5a964f20 226
e6aa8b84 227Before Perl 5.8.0, installing Perl code to deal with signals exposed you to
cf21866a
TC
228danger from two things. First, few system library functions are
229re-entrant. If the signal interrupts while Perl is executing one function
230(like malloc(3) or printf(3)), and your signal handler then calls the same
231function again, you could get unpredictable behavior--often, a core dump.
232Second, Perl isn't itself re-entrant at the lowest levels. If the signal
233interrupts Perl while Perl is changing its own internal data structures,
234similarly unpredictable behavior may result.
5a964f20 235
a11adca0
NIS
236There were two things you could do, knowing this: be paranoid or be
237pragmatic. The paranoid approach was to do as little as possible in your
5a964f20
TC
238signal handler. Set an existing integer variable that already has a
239value, and return. This doesn't help you if you're in a slow system call,
7b34eba2 240which will just restart. That means you have to C<die> to longjmp(3) out
5a964f20
TC
241of the handler. Even this is a little cavalier for the true paranoiac,
242who avoids C<die> in a handler because the system I<is> out to get you.
b432a672
AL
243The pragmatic approach was to say "I know the risks, but prefer the
244convenience", and to do anything you wanted in your signal handler,
a11adca0
NIS
245and be prepared to clean up core dumps now and again.
246
e6aa8b84 247Perl 5.8.0 and later avoid these problems by "deferring" signals. That is,
cf21866a
TC
248when the signal is delivered to the process by the system (to the C code
249that implements Perl) a flag is set, and the handler returns immediately.
250Then at strategic "safe" points in the Perl interpreter (e.g. when it is
251about to execute a new opcode) the flags are checked and the Perl level
252handler from %SIG is executed. The "deferred" scheme allows much more
253flexibility in the coding of signal handlers as we know the Perl
de7ba517
LT
254interpreter is in a safe state, and that we are not in a system library
255function when the handler is called. However the implementation does
cf21866a 256differ from previous Perls in the following ways:
5a964f20 257
a11adca0 258=over 4
5a964f20 259
e188fdae
CB
260=item Long-running opcodes
261
cf21866a 262As the Perl interpreter looks at signal flags only when it is about
e188fdae
CB
263to execute a new opcode, a signal that arrives during a long-running
264opcode (e.g. a regular expression operation on a very large string) will
265not be seen until the current opcode completes.
266
cf21866a 267If a signal of any given type fires multiple times during an opcode
e188fdae 268(such as from a fine-grained timer), the handler for that signal will
cf21866a 269be called only once, after the opcode completes; all other
e188fdae
CB
270instances will be discarded. Furthermore, if your system's signal queue
271gets flooded to the point that there are signals that have been raised
272but not yet caught (and thus not deferred) at the time an opcode
273completes, those signals may well be caught and deferred during
274subsequent opcodes, with sometimes surprising results. For example, you
275may see alarms delivered even after calling C<alarm(0)> as the latter
276stops the raising of alarms but does not cancel the delivery of alarms
277raised but not yet caught. Do not depend on the behaviors described in
278this paragraph as they are side effects of the current implementation and
279may change in future versions of Perl.
a11adca0 280
a11adca0
NIS
281=item Interrupting IO
282
cf21866a
TC
283When a signal is delivered (e.g., SIGINT from a control-C) the operating
284system breaks into IO operations like I<read>(2), which is used to
285implement Perl's readline() function, the C<< <> >> operator. On older
286Perls the handler was called immediately (and as C<read> is not "unsafe",
287this worked well). With the "deferred" scheme the handler is I<not> called
288immediately, and if Perl is using the system's C<stdio> library that
289library may restart the C<read> without returning to Perl to give it a
290chance to call the %SIG handler. If this happens on your system the
291solution is to use the C<:perlio> layer to do IO--at least on those handles
292that you want to be able to break into with signals. (The C<:perlio> layer
293checks the signal flags and calls %SIG handlers before resuming IO
294operation.)
295
e6aa8b84 296The default in Perl 5.8.0 and later is to automatically use
490f90af 297the C<:perlio> layer.
a11adca0 298
abf9167d
DM
299Note that it is not advisable to access a file handle within a signal
300handler where that signal has interrupted an I/O operation on that same
301handle. While perl will at least try hard not to crash, there are no
302guarantees of data integrity; for example, some data might get dropped or
303written twice.
304
cf21866a
TC
305Some networking library functions like gethostbyname() are known to have
306their own implementations of timeouts which may conflict with your
307timeouts. If you have problems with such functions, try using the POSIX
308sigaction() function, which bypasses Perl safe signals. Be warned that
309this does subject you to possible memory corruption, as described above.
310
311Instead of setting C<$SIG{ALRM}>:
91d81acc 312
e399c6ae
SB
313 local $SIG{ALRM} = sub { die "alarm" };
314
315try something like the following:
316
de7ba517
LT
317 use POSIX qw(SIGALRM);
318 POSIX::sigaction(SIGALRM, POSIX::SigAction->new(sub { die "alarm" }))
319 || die "Error setting SIGALRM handler: $!\n";
91d81acc 320
a1966b02 321Another way to disable the safe signal behavior locally is to use
cf21866a
TC
322the C<Perl::Unsafe::Signals> module from CPAN, which affects
323all signals.
a1966b02 324
9ce5b4ad
SG
325=item Restartable system calls
326
327On systems that supported it, older versions of Perl used the
328SA_RESTART flag when installing %SIG handlers. This meant that
329restartable system calls would continue rather than returning when
330a signal arrived. In order to deliver deferred signals promptly,
e6aa8b84 331Perl 5.8.0 and later do I<not> use SA_RESTART. Consequently,
9ce5b4ad
SG
332restartable system calls can fail (with $! set to C<EINTR>) in places
333where they previously would have succeeded.
334
cf21866a
TC
335The default C<:perlio> layer retries C<read>, C<write>
336and C<close> as described above; interrupted C<wait> and
9ce5b4ad
SG
337C<waitpid> calls will always be retried.
338
a11adca0
NIS
339=item Signals as "faults"
340
cf21866a 341Certain signals like SEGV, ILL, and BUS are generated by virtual memory
c69ca1d4 342addressing errors and similar "faults". These are normally fatal: there is
de7ba517 343little a Perl-level handler can do with them. So Perl delivers them
e188fdae 344immediately rather than attempting to defer them.
a11adca0
NIS
345
346=item Signals triggered by operating system state
347
490f90af 348On some operating systems certain signal handlers are supposed to "do
cf21866a 349something" before returning. One example can be CHLD or CLD, which
490f90af
JH
350indicates a child process has completed. On some operating systems the
351signal handler is expected to C<wait> for the completed child
352process. On such systems the deferred signal scheme will not work for
cf21866a
TC
353those signals: it does not do the C<wait>. Again the failure will
354look like a loop as the operating system will reissue the signal because
355there are completed child processes that have not yet been C<wait>ed for.
a11adca0 356
818c4caa 357=back
a0d0e21e 358
cf21866a 359If you want the old signal behavior back despite possible
4ffa73a3 360memory corruption, set the environment variable C<PERL_SIGNALS> to
cf21866a 361C<"unsafe">. This feature first appeared in Perl 5.8.1.
4ffa73a3 362
9eed50dc
DM
363=head1 Named Pipes
364
365A named pipe (often referred to as a FIFO) is an old Unix IPC
366mechanism for processes communicating on the same machine. It works
367just like regular anonymous pipes, except that the
368processes rendezvous using a filename and need not be related.
369
370To create a named pipe, use the C<POSIX::mkfifo()> function.
371
372 use POSIX qw(mkfifo);
373 mkfifo($path, 0700) || die "mkfifo $path failed: $!";
374
375You can also use the Unix command mknod(1), or on some
376systems, mkfifo(1). These may not be in your normal path, though.
377
378 # system return val is backwards, so && not ||
379 #
380 $ENV{PATH} .= ":/etc:/usr/etc";
381 if ( system("mknod", $path, "p")
382 && system("mkfifo", $path) )
383 {
384 die "mk{nod,fifo} $path failed";
385 }
386
387
388A fifo is convenient when you want to connect a process to an unrelated
389one. When you open a fifo, the program will block until there's something
390on the other end.
391
392For example, let's say you'd like to have your F<.signature> file be a
393named pipe that has a Perl program on the other end. Now every time any
394program (like a mailer, news reader, finger program, etc.) tries to read
395from that file, the reading program will read the new signature from your
396program. We'll use the pipe-checking file-test operator, B<-p>, to find
397out whether anyone (or anything) has accidentally removed our fifo.
398
399 chdir(); # go home
400 my $FIFO = ".signature";
401
402 while (1) {
403 unless (-p $FIFO) {
404 unlink $FIFO; # discard any failure, will catch later
405 require POSIX; # delayed loading of heavy module
406 POSIX::mkfifo($FIFO, 0700)
407 || die "can't mkfifo $FIFO: $!";
408 }
409
410 # next line blocks till there's a reader
411 open (FIFO, "> $FIFO") || die "can't open $FIFO: $!";
412 print FIFO "John Smith (smith\@host.org)\n", `fortune -s`;
413 close(FIFO) || die "can't close $FIFO: $!";
414 sleep 2; # to avoid dup signals
415 }
416
4633a7c4
LW
417=head1 Using open() for IPC
418
490f90af
JH
419Perl's basic open() statement can also be used for unidirectional
420interprocess communication by either appending or prepending a pipe
421symbol to the second argument to open(). Here's how to start
422something up in a child process you intend to write to:
4633a7c4 423
54310121 424 open(SPOOLER, "| cat -v | lpr -h 2>/dev/null")
cf21866a 425 || die "can't fork: $!";
4633a7c4
LW
426 local $SIG{PIPE} = sub { die "spooler pipe broke" };
427 print SPOOLER "stuff\n";
cf21866a 428 close SPOOLER || die "bad spool: $! $?";
4633a7c4
LW
429
430And here's how to start up a child process you intend to read from:
431
432 open(STATUS, "netstat -an 2>&1 |")
cf21866a 433 || die "can't fork: $!";
4633a7c4 434 while (<STATUS>) {
322c2516
SF
435 next if /^(tcp|udp)/;
436 print;
54310121 437 }
cf21866a 438 close STATUS || die "bad netstat: $! $?";
4633a7c4 439
cf21866a
TC
440If one can be sure that a particular program is a Perl script expecting
441filenames in @ARGV, the clever programmer can write something like this:
4633a7c4 442
5a964f20 443 % program f1 "cmd1|" - f2 "cmd2|" f3 < tmpfile
4633a7c4 444
cf21866a 445and no matter which sort of shell it's called from, the Perl program will
4633a7c4
LW
446read from the file F<f1>, the process F<cmd1>, standard input (F<tmpfile>
447in this case), the F<f2> file, the F<cmd2> command, and finally the F<f3>
448file. Pretty nifty, eh?
449
54310121 450You might notice that you could use backticks for much the
4633a7c4
LW
451same effect as opening a pipe for reading:
452
453 print grep { !/^(tcp|udp)/ } `netstat -an 2>&1`;
cf21866a 454 die "bad netstatus ($?)" if $?;
4633a7c4
LW
455
456While this is true on the surface, it's much more efficient to process the
457file one line or record at a time because then you don't have to read the
19799a22 458whole thing into memory at once. It also gives you finer control of the
cf21866a 459whole process, letting you kill off the child process early if you'd like.
4633a7c4 460
cf21866a 461Be careful to check the return values from both open() and close(). If
4633a7c4
LW
462you're I<writing> to a pipe, you should also trap SIGPIPE. Otherwise,
463think of what happens when you start up a pipe to a command that doesn't
464exist: the open() will in all likelihood succeed (it only reflects the
465fork()'s success), but then your output will fail--spectacularly. Perl
cf21866a 466can't know whether the command worked, because your command is actually
4633a7c4 467running in a separate process whose exec() might have failed. Therefore,
cf21866a
TC
468while readers of bogus commands return just a quick EOF, writers
469to bogus commands will get hit with a signal, which they'd best be prepared
470to handle. Consider:
4633a7c4 471
cf21866a
TC
472 open(FH, "|bogus") || die "can't fork: $!";
473 print FH "bang\n"; # neither necessary nor sufficient
474 # to check print retval!
475 close(FH) || die "can't close: $!";
5a964f20 476
cf21866a
TC
477The reason for not checking the return value from print() is because of
478pipe buffering; physical writes are delayed. That won't blow up until the
479close, and it will blow up with a SIGPIPE. To catch it, you could use
480this:
5a964f20 481
cf21866a
TC
482 $SIG{PIPE} = "IGNORE";
483 open(FH, "|bogus") || die "can't fork: $!";
484 print FH "bang\n";
485 close(FH) || die "can't close: status=$?";
4633a7c4 486
68dc0745
PP
487=head2 Filehandles
488
5a964f20
TC
489Both the main process and any child processes it forks share the same
490STDIN, STDOUT, and STDERR filehandles. If both processes try to access
45bc9206 491them at once, strange things can happen. You may also want to close
5a964f20
TC
492or reopen the filehandles for the child. You can get around this by
493opening your pipe with open(), but on some systems this means that the
494child process cannot outlive the parent.
68dc0745
PP
495
496=head2 Background Processes
497
498You can run a command in the background with:
499
7b05b7e3 500 system("cmd &");
68dc0745
PP
501
502The command's STDOUT and STDERR (and possibly STDIN, depending on your
503shell) will be the same as the parent's. You won't need to catch
cf21866a 504SIGCHLD because of the double-fork taking place; see below for details.
68dc0745
PP
505
506=head2 Complete Dissociation of Child from Parent
507
508In some cases (starting server processes, for instance) you'll want to
893af57a 509completely dissociate the child process from the parent. This is
cf21866a
TC
510often called daemonization. A well-behaved daemon will also chdir()
511to the root directory so it doesn't prevent unmounting the filesystem
512containing the directory from which it was launched, and redirect its
513standard file descriptors from and to F</dev/null> so that random
514output doesn't wind up on the user's terminal.
893af57a 515
cf21866a 516 use POSIX "setsid";
893af57a
RS
517
518 sub daemonize {
cf21866a
TC
519 chdir("/") || die "can't chdir to /: $!";
520 open(STDIN, "< /dev/null") || die "can't read /dev/null: $!";
521 open(STDOUT, "> /dev/null") || die "can't write to /dev/null: $!";
522 defined(my $pid = fork()) || die "can't fork: $!";
c0919ef1 523 exit if $pid; # non-zero now means I am the parent
cf21866a
TC
524 (setsid() != -1) || die "Can't start a new session: $!"
525 open(STDERR, ">&STDOUT") || die "can't dup stdout: $!";
893af57a 526 }
5a964f20 527
cf21866a
TC
528The fork() has to come before the setsid() to ensure you aren't a
529process group leader; the setsid() will fail if you are. If your
893af57a 530system doesn't have the setsid() function, open F</dev/tty> and use the
f979aebc 531C<TIOCNOTTY> ioctl() on it instead. See tty(4) for details.
5a964f20 532
cf21866a
TC
533Non-Unix users should check their C<< I<Your_OS>::Process >> module for
534other possible solutions.
68dc0745 535
4633a7c4
LW
536=head2 Safe Pipe Opens
537
538Another interesting approach to IPC is making your single program go
cf21866a 539multiprocess and communicate between--or even amongst--yourselves. The
4633a7c4
LW
540open() function will accept a file argument of either C<"-|"> or C<"|-">
541to do a very interesting thing: it forks a child connected to the
542filehandle you've opened. The child is running the same program as the
543parent. This is useful for safely opening a file when running under an
544assumed UID or GID, for example. If you open a pipe I<to> minus, you can
cf21866a 545write to the filehandle you opened and your kid will find it in I<his>
4633a7c4 546STDIN. If you open a pipe I<from> minus, you can read from the filehandle
cf21866a 547you opened whatever your kid writes to I<his> STDOUT.
4633a7c4 548
cf21866a
TC
549 use English qw[ -no_match_vars ];
550 my $PRECIOUS = "/path/to/some/safe/file";
551 my $sleep_count;
552 my $pid;
4633a7c4 553
54310121 554 do {
322c2516
SF
555 $pid = open(KID_TO_WRITE, "|-");
556 unless (defined $pid) {
557 warn "cannot fork: $!";
558 die "bailing out" if $sleep_count++ > 6;
559 sleep 10;
560 }
4633a7c4
LW
561 } until defined $pid;
562
cf21866a 563 if ($pid) { # I am the parent
322c2516 564 print KID_TO_WRITE @some_data;
cf21866a
TC
565 close(KID_TO_WRITE) || warn "kid exited $?";
566 } else { # I am the child
567 # drop permissions in setuid and/or setgid programs:
568 ($EUID, $EGID) = ($UID, $GID);
569 open (OUTFILE, "> $PRECIOUS")
570 || die "can't open $PRECIOUS: $!";
322c2516 571 while (<STDIN>) {
cf21866a 572 print OUTFILE; # child's STDIN is parent's KID_TO_WRITE
322c2516 573 }
cf21866a
TC
574 close(OUTFILE) || die "can't close $PRECIOUS: $!";
575 exit(0); # don't forget this!!
54310121 576 }
4633a7c4
LW
577
578Another common use for this construct is when you need to execute
579something without the shell's interference. With system(), it's
54310121 580straightforward, but you can't use a pipe open or backticks safely.
4633a7c4
LW
581That's because there's no way to stop the shell from getting its hands on
582your arguments. Instead, use lower-level control to call exec() directly.
583
54310121 584Here's a safe backtick or pipe open for read:
4633a7c4 585
cf21866a
TC
586 my $pid = open(KID_TO_READ, "-|");
587 defined($pid) || die "can't fork: $!";
4633a7c4 588
cf21866a 589 if ($pid) { # parent
322c2516 590 while (<KID_TO_READ>) {
cf21866a 591 # do something interesting
322c2516 592 }
cf21866a 593 close(KID_TO_READ) || warn "kid exited $?";
4633a7c4 594
cf21866a 595 } else { # child
322c2516
SF
596 ($EUID, $EGID) = ($UID, $GID); # suid only
597 exec($program, @options, @args)
cf21866a 598 || die "can't exec program: $!";
322c2516 599 # NOTREACHED
54310121 600 }
4633a7c4 601
4633a7c4
LW
602And here's a safe pipe open for writing:
603
cf21866a
TC
604 my $pid = open(KID_TO_WRITE, "|-");
605 defined($pid) || die "can't fork: $!";
606
76c0e0db 607 $SIG{PIPE} = sub { die "whoops, $program pipe broke" };
4633a7c4 608
cf21866a
TC
609 if ($pid) { # parent
610 print KID_TO_WRITE @data;
322c2516 611 close(KID_TO_WRITE) || warn "kid exited $?";
4633a7c4 612
cf21866a 613 } else { # child
322c2516
SF
614 ($EUID, $EGID) = ($UID, $GID);
615 exec($program, @options, @args)
cf21866a 616 || die "can't exec program: $!";
322c2516 617 # NOTREACHED
54310121 618 }
4633a7c4 619
c40e8e9b 620It is very easy to dead-lock a process using this form of open(), or
cf21866a
TC
621indeed with any use of pipe() with multiple subprocesses. The
622example above is "safe" because it is simple and calls exec(). See
c40e8e9b
SV
623L</"Avoiding Pipe Deadlocks"> for general safety principles, but there
624are extra gotchas with Safe Pipe Opens.
625
626In particular, if you opened the pipe using C<open FH, "|-">, then you
627cannot simply use close() in the parent process to close an unwanted
628writer. Consider this code:
629
cf21866a
TC
630 my $pid = open(WRITER, "|-"); # fork open a kid
631 defined($pid) || die "first fork failed: $!";
c40e8e9b
SV
632 if ($pid) {
633 if (my $sub_pid = fork()) {
cf21866a
TC
634 defined($sub_pid) || die "second fork failed: $!";
635 close(WRITER) || die "couldn't close WRITER: $!";
636 # now do something else...
c40e8e9b
SV
637 }
638 else {
cf21866a
TC
639 # first write to WRITER
640 # ...
641 # then when finished
642 close(WRITER) || die "couldn't close WRITER: $!";
643 exit(0);
c40e8e9b
SV
644 }
645 }
646 else {
cf21866a
TC
647 # first do something with STDIN, then
648 exit(0);
c40e8e9b
SV
649 }
650
cf21866a 651In the example above, the true parent does not want to write to the WRITER
c40e8e9b 652filehandle, so it closes it. However, because WRITER was opened using
cf21866a
TC
653C<open FH, "|-">, it has a special behavior: closing it calls
654waitpid() (see L<perlfunc/waitpid>), which waits for the subprocess
c40e8e9b 655to exit. If the child process ends up waiting for something happening
cf21866a 656in the section marked "do something else", you have deadlock.
c40e8e9b 657
cf21866a 658This can also be a problem with intermediate subprocesses in more
c40e8e9b 659complicated code, which will call waitpid() on all open filehandles
cf21866a 660during global destruction--in no predictable order.
c40e8e9b
SV
661
662To solve this, you must manually use pipe(), fork(), and the form of
cf21866a 663open() which sets one file descriptor to another, as shown below:
c40e8e9b 664
cf21866a 665 pipe(READER, WRITER) || die "pipe failed: $!";
c40e8e9b 666 $pid = fork();
cf21866a 667 defined($pid) || die "first fork failed: $!";
c40e8e9b 668 if ($pid) {
322c2516 669 close READER;
c40e8e9b 670 if (my $sub_pid = fork()) {
cf21866a
TC
671 defined($sub_pid) || die "first fork failed: $!";
672 close(WRITER) || die "can't close WRITER: $!";
c40e8e9b
SV
673 }
674 else {
675 # write to WRITER...
cf21866a
TC
676 # ...
677 # then when finished
678 close(WRITER) || die "can't close WRITER: $!";
679 exit(0);
c40e8e9b
SV
680 }
681 # write to WRITER...
682 }
683 else {
cf21866a
TC
684 open(STDIN, "<&READER") || die "can't reopen STDIN: $!";
685 close(WRITER) || die "can't close WRITER: $!";
c40e8e9b 686 # do something...
cf21866a 687 exit(0);
c40e8e9b
SV
688 }
689
cf21866a
TC
690Since Perl 5.8.0, you can also use the list form of C<open> for pipes.
691This is preferred when you wish to avoid having the shell interpret
692metacharacters that may be in your command string.
307eac13 693
cf21866a 694So for example, instead of using:
307eac13 695
cf21866a 696 open(PS_PIPE, "ps aux|") || die "can't open ps pipe: $!";
307eac13 697
cf21866a 698One would use either of these:
4633a7c4 699
cf21866a
TC
700 open(PS_PIPE, "-|", "ps", "aux")
701 || die "can't open ps pipe: $!";
c40e8e9b 702
cf21866a
TC
703 @ps_args = qw[ ps aux ];
704 open(PS_PIPE, "-|", @ps_args)
705 || die "can't open @ps_args|: $!";
c40e8e9b 706
cf21866a
TC
707Because there are more than three arguments to open(), forks the ps(1)
708command I<without> spawning a shell, and reads its standard output via the
709C<PS_PIPE> filehandle. The corresponding syntax to I<write> to command
710pipes is to use C<"|-"> in place of C<"-|">.
c40e8e9b 711
cf21866a
TC
712This was admittedly a rather silly example, because you're using string
713literals whose content is perfectly safe. There is therefore no cause to
faa783ac 714resort to the harder-to-read, multi-argument form of pipe open(). However,
cf21866a
TC
715whenever you cannot be assured that the program arguments are free of shell
716metacharacters, the fancier form of open() should be used. For example:
c40e8e9b 717
cf21866a
TC
718 @grep_args = ("egrep", "-i", $some_pattern, @many_files);
719 open(GREP_PIPE, "-|", @grep_args)
720 || die "can't open @grep_args|: $!";
721
722Here the multi-argument form of pipe open() is preferred because the
723pattern and indeed even the filenames themselves might hold metacharacters.
724
725Be aware that these operations are full Unix forks, which means they may
726not be correctly implemented on all alien systems. Additionally, these are
727not true multithreading. To learn more about threading, see the F<modules>
728file mentioned below in the SEE ALSO section.
729
730=head2 Avoiding Pipe Deadlocks
731
732Whenever you have more than one subprocess, you must be careful that each
733closes whichever half of any pipes created for interprocess communication
734it is not using. This is because any child process reading from the pipe
735and expecting an EOF will never receive it, and therefore never exit. A
736single process closing a pipe is not enough to close it; the last process
737with the pipe open must close it for it to read EOF.
738
739Certain built-in Unix features help prevent this most of the time. For
740instance, filehandles have a "close on exec" flag, which is set I<en masse>
741under control of the C<$^F> variable. This is so any filehandles you
742didn't explicitly route to the STDIN, STDOUT or STDERR of a child
743I<program> will be automatically closed.
744
745Always explicitly and immediately call close() on the writable end of any
746pipe, unless that process is actually writing to it. Even if you don't
747explicitly call close(), Perl will still close() all filehandles during
748global destruction. As previously discussed, if those filehandles have
749been opened with Safe Pipe Open, this will result in calling waitpid(),
750which may again deadlock.
c40e8e9b 751
7b05b7e3 752=head2 Bidirectional Communication with Another Process
4633a7c4
LW
753
754While this works reasonably well for unidirectional communication, what
cf21866a 755about bidirectional communication? The most obvious approach doesn't work:
4633a7c4 756
cf21866a 757 # THIS DOES NOT WORK!!
c07a80fd 758 open(PROG_FOR_READING_AND_WRITING, "| some program |")
4633a7c4 759
cf21866a
TC
760If you forget to C<use warnings>, you'll miss out entirely on the
761helpful diagnostic message:
4633a7c4
LW
762
763 Can't do bidirectional pipe at -e line 1.
764
cf21866a
TC
765If you really want to, you can use the standard open2() from the
766C<IPC::Open2> module to catch both ends. There's also an open3() in
767C<IPC::Open3> for tridirectional I/O so you can also catch your child's
768STDERR, but doing so would then require an awkward select() loop and
769wouldn't allow you to use normal Perl input operations.
4633a7c4
LW
770
771If you look at its source, you'll see that open2() uses low-level
cf21866a
TC
772primitives like the pipe() and exec() syscalls to create all the
773connections. Although it might have been more efficient by using
774socketpair(), this would have been even less portable than it already
775is. The open2() and open3() functions are unlikely to work anywhere
776except on a Unix system, or at least one purporting POSIX compliance.
777
778=for TODO
779Hold on, is this even true? First it says that socketpair() is avoided
780for portability, but then it says it probably won't work except on
781Unixy systems anyway. Which one of those is true?
4633a7c4
LW
782
783Here's an example of using open2():
784
785 use FileHandle;
786 use IPC::Open2;
cf21866a 787 $pid = open2(*Reader, *Writer, "cat -un");
4633a7c4
LW
788 print Writer "stuff\n";
789 $got = <Reader>;
790
cf21866a
TC
791The problem with this is that buffering is really going to ruin your
792day. Even though your C<Writer> filehandle is auto-flushed so the process
793on the other end gets your data in a timely manner, you can't usually do
794anything to force that process to give its data to you in a similarly quick
795fashion. In this special case, we could actually so, because we gave
796I<cat> a B<-u> flag to make it unbuffered. But very few commands are
797designed to operate over pipes, so this seldom works unless you yourself
798wrote the program on the other end of the double-ended pipe.
799
800A solution to this is to use a library which uses pseudottys to make your
801program behave more reasonably. This way you don't have to have control
802over the source code of the program you're using. The C<Expect> module
803from CPAN also addresses this kind of thing. This module requires two
804other modules from CPAN, C<IO::Pty> and C<IO::Stty>. It sets up a pseudo
805terminal to interact with programs that insist on talking to the terminal
806device driver. If your system is supported, this may be your best bet.
c8db1d39 807
5a964f20
TC
808=head2 Bidirectional Communication with Yourself
809
cf21866a
TC
810If you want, you may make low-level pipe() and fork() syscalls to stitch
811this together by hand. This example only talks to itself, but you could
812reopen the appropriate handles to STDIN and STDOUT and call other processes.
813(The following example lacks proper error checking.)
5a964f20
TC
814
815 #!/usr/bin/perl -w
816 # pipe1 - bidirectional communication using two pipe pairs
817 # designed for the socketpair-challenged
322c2516 818 use IO::Handle; # thousands of lines just for autoflush :-(
cf21866a
TC
819 pipe(PARENT_RDR, CHILD_WTR); # XXX: check failure?
820 pipe(CHILD_RDR, PARENT_WTR); # XXX: check failure?
5a964f20
TC
821 CHILD_WTR->autoflush(1);
822 PARENT_WTR->autoflush(1);
823
cf21866a
TC
824 if ($pid = fork()) {
825 close PARENT_RDR;
826 close PARENT_WTR;
322c2516
SF
827 print CHILD_WTR "Parent Pid $$ is sending this\n";
828 chomp($line = <CHILD_RDR>);
ccf3535a 829 print "Parent Pid $$ just read this: '$line'\n";
322c2516 830 close CHILD_RDR; close CHILD_WTR;
cf21866a 831 waitpid($pid, 0);
5a964f20 832 } else {
322c2516 833 die "cannot fork: $!" unless defined $pid;
cf21866a
TC
834 close CHILD_RDR;
835 close CHILD_WTR;
322c2516 836 chomp($line = <PARENT_RDR>);
ccf3535a 837 print "Child Pid $$ just read this: '$line'\n";
322c2516 838 print PARENT_WTR "Child Pid $$ is sending this\n";
cf21866a
TC
839 close PARENT_RDR;
840 close PARENT_WTR;
841 exit(0);
5a964f20
TC
842 }
843
a11adca0 844But you don't actually have to make two pipe calls. If you
5a964f20
TC
845have the socketpair() system call, it will do this all for you.
846
847 #!/usr/bin/perl -w
848 # pipe2 - bidirectional communication using socketpair
849 # "the best ones always go both ways"
850
851 use Socket;
322c2516 852 use IO::Handle; # thousands of lines just for autoflush :-(
cf21866a 853
5a964f20
TC
854 # We say AF_UNIX because although *_LOCAL is the
855 # POSIX 1003.1g form of the constant, many machines
856 # still don't have it.
857 socketpair(CHILD, PARENT, AF_UNIX, SOCK_STREAM, PF_UNSPEC)
cf21866a 858 || die "socketpair: $!";
5a964f20
TC
859
860 CHILD->autoflush(1);
861 PARENT->autoflush(1);
862
cf21866a 863 if ($pid = fork()) {
322c2516
SF
864 close PARENT;
865 print CHILD "Parent Pid $$ is sending this\n";
866 chomp($line = <CHILD>);
ccf3535a 867 print "Parent Pid $$ just read this: '$line'\n";
322c2516 868 close CHILD;
cf21866a 869 waitpid($pid, 0);
5a964f20 870 } else {
322c2516
SF
871 die "cannot fork: $!" unless defined $pid;
872 close CHILD;
873 chomp($line = <PARENT>);
cf21866a 874 print "Child Pid $$ just read this: '$line'\n";
322c2516
SF
875 print PARENT "Child Pid $$ is sending this\n";
876 close PARENT;
cf21866a 877 exit(0);
5a964f20
TC
878 }
879
4633a7c4 880=head1 Sockets: Client/Server Communication
a0d0e21e 881
cf21866a
TC
882While not entirely limited to Unix-derived operating systems (e.g., WinSock
883on PCs provides socket support, as do some VMS libraries), you might not have
884sockets on your system, in which case this section probably isn't going to
885do you much good. With sockets, you can do both virtual circuits like TCP
886streams and datagrams like UDP packets. You may be able to do even more
4633a7c4
LW
887depending on your system.
888
cf21866a 889The Perl functions for dealing with sockets have the same names as
4633a7c4 890the corresponding system calls in C, but their arguments tend to differ
cf21866a 891for two reasons. First, Perl filehandles work differently than C file
4633a7c4
LW
892descriptors. Second, Perl already knows the length of its strings, so you
893don't need to pass that information.
a0d0e21e 894
cf21866a
TC
895One of the major problems with ancient, antemillennial socket code in Perl
896was that it used hard-coded values for some of the constants, which
897severely hurt portability. If you ever see code that does anything like
898explicitly setting C<$AF_INET = 2>, you know you're in for big trouble.
899An immeasurably superior approach is to use the C<Socket> module, which more
900reliably grants access to the various constants and functions you'll need.
a0d0e21e 901
68dc0745
PP
902If you're not writing a server/client for an existing protocol like
903NNTP or SMTP, you should give some thought to how your server will
904know when the client has finished talking, and vice-versa. Most
905protocols are based on one-line messages and responses (so one party
4a6725af 906knows the other has finished when a "\n" is received) or multi-line
68dc0745
PP
907messages and responses that end with a period on an empty line
908("\n.\n" terminates a message/response).
909
5a964f20
TC
910=head2 Internet Line Terminators
911
912The Internet line terminator is "\015\012". Under ASCII variants of
913Unix, that could usually be written as "\r\n", but under other systems,
914"\r\n" might at times be "\015\015\012", "\012\012\015", or something
915completely different. The standards specify writing "\015\012" to be
916conformant (be strict in what you provide), but they also recommend
cf21866a 917accepting a lone "\012" on input (be lenient in what you require).
5a964f20 918We haven't always been very good about that in the code in this manpage,
cf21866a
TC
919but unless you're on a Mac from way back in its pre-Unix dark ages, you'll
920probably be ok.
5a964f20 921
4633a7c4 922=head2 Internet TCP Clients and Servers
a0d0e21e 923
4633a7c4
LW
924Use Internet-domain sockets when you want to do client-server
925communication that might extend to machines outside of your own system.
926
927Here's a sample TCP client using Internet-domain sockets:
928
929 #!/usr/bin/perl -w
4633a7c4
LW
930 use strict;
931 use Socket;
cf21866a 932 my ($remote, $port, $iaddr, $paddr, $proto, $line);
4633a7c4 933
cf21866a 934 $remote = shift || "localhost";
4633a7c4 935 $port = shift || 2345; # random port
cf21866a 936 if ($port =~ /\D/) { $port = getservbyname($port, "tcp") }
4633a7c4 937 die "No port" unless $port;
322c2516 938 $iaddr = inet_aton($remote) || die "no host: $remote";
4633a7c4
LW
939 $paddr = sockaddr_in($port, $iaddr);
940
cf21866a 941 $proto = getprotobyname("tcp");
322c2516 942 socket(SOCK, PF_INET, SOCK_STREAM, $proto) || die "socket: $!";
cf21866a
TC
943 connect(SOCK, $paddr) || die "connect: $!";
944 while ($line = <SOCK>) {
322c2516 945 print $line;
54310121 946 }
4633a7c4 947
cf21866a
TC
948 close (SOCK) || die "close: $!";
949 exit(0);
4633a7c4
LW
950
951And here's a corresponding server to go along with it. We'll
cf21866a 952leave the address as C<INADDR_ANY> so that the kernel can choose
54310121 953the appropriate interface on multihomed hosts. If you want sit
c07a80fd 954on a particular interface (like the external side of a gateway
cf21866a 955or firewall machine), fill this in with your real address instead.
c07a80fd
PP
956
957 #!/usr/bin/perl -Tw
c07a80fd 958 use strict;
cf21866a 959 BEGIN { $ENV{PATH} = "/usr/bin:/bin" }
c07a80fd
PP
960 use Socket;
961 use Carp;
5865a7df 962 my $EOL = "\015\012";
c07a80fd 963
cf21866a 964 sub logmsg { print "$0 $$: @_ at ", scalar localtime(), "\n" }
c07a80fd 965
cf21866a
TC
966 my $port = shift || 2345;
967 die "invalid port" unless if $port =~ /^ \d+ $/x;
51ee6500 968
cf21866a 969 my $proto = getprotobyname("tcp");
6a3992aa 970
322c2516 971 socket(Server, PF_INET, SOCK_STREAM, $proto) || die "socket: $!";
cf21866a
TC
972 setsockopt(Server, SOL_SOCKET, SO_REUSEADDR, pack("l", 1))
973 || die "setsockopt: $!";
322c2516 974 bind(Server, sockaddr_in($port, INADDR_ANY)) || die "bind: $!";
cf21866a 975 listen(Server, SOMAXCONN) || die "listen: $!";
c07a80fd
PP
976
977 logmsg "server started on port $port";
978
979 my $paddr;
980
981 $SIG{CHLD} = \&REAPER;
982
cf21866a
TC
983 for ( ; $paddr = accept(Client, Server); close Client) {
984 my($port, $iaddr) = sockaddr_in($paddr);
985 my $name = gethostbyaddr($iaddr, AF_INET);
c07a80fd 986
322c2516
SF
987 logmsg "connection from $name [",
988 inet_ntoa($iaddr), "]
989 at port $port";
c07a80fd 990
322c2516 991 print Client "Hello there, $name, it's now ",
cf21866a 992 scalar localtime(), $EOL;
54310121 993 }
c07a80fd 994
54310121 995And here's a multithreaded version. It's multithreaded in that
cf21866a 996like most typical servers, it spawns (fork()s) a slave server to
c07a80fd
PP
997handle the client request so that the master server can quickly
998go back to service a new client.
4633a7c4
LW
999
1000 #!/usr/bin/perl -Tw
4633a7c4 1001 use strict;
cf21866a 1002 BEGIN { $ENV{PATH} = "/usr/bin:/bin" }
a0d0e21e 1003 use Socket;
4633a7c4 1004 use Carp;
5865a7df 1005 my $EOL = "\015\012";
a0d0e21e 1006
4633a7c4 1007 sub spawn; # forward declaration
cf21866a 1008 sub logmsg { print "$0 $$: @_ at ", scalar localtime(), "\n" }
a0d0e21e 1009
cf21866a
TC
1010 my $port = shift || 2345;
1011 die "invalid port" unless if $port =~ /^ \d+ $/x;
51ee6500 1012
cf21866a 1013 my $proto = getprotobyname("tcp");
54310121 1014
322c2516 1015 socket(Server, PF_INET, SOCK_STREAM, $proto) || die "socket: $!";
cf21866a
TC
1016 setsockopt(Server, SOL_SOCKET, SO_REUSEADDR, pack("l", 1))
1017 || die "setsockopt: $!";
1018 bind(Server, sockaddr_in($port, INADDR_ANY)) || die "bind: $!";
1019 listen(Server, SOMAXCONN) || die "listen: $!";
a0d0e21e 1020
4633a7c4 1021 logmsg "server started on port $port";
a0d0e21e 1022
4633a7c4
LW
1023 my $waitedpid = 0;
1024 my $paddr;
a0d0e21e 1025
816229cf 1026 use POSIX ":sys_wait_h";
c5ae6365
AW
1027 use Errno;
1028
54310121 1029 sub REAPER {
c5ae6365 1030 local $!; # don't let waitpid() overwrite current error
cf21866a
TC
1031 while ((my $pid = waitpid(-1, WNOHANG)) > 0 && WIFEXITED($?)) {
1032 logmsg "reaped $waitedpid" . ($? ? " with exit $?" : "");
c5ae6365 1033 }
abf724c9 1034 $SIG{CHLD} = \&REAPER; # loathe SysV
4633a7c4
LW
1035 }
1036
1037 $SIG{CHLD} = \&REAPER;
1038
cf21866a 1039 while (1) {
c5ae6365 1040 $paddr = accept(Client, Server) || do {
cf21866a 1041 # try again if accept() returned because got a signal
c5ae6365
AW
1042 next if $!{EINTR};
1043 die "accept: $!";
1044 };
1045 my ($port, $iaddr) = sockaddr_in($paddr);
1046 my $name = gethostbyaddr($iaddr, AF_INET);
1047
1048 logmsg "connection from $name [",
1049 inet_ntoa($iaddr),
1050 "] at port $port";
1051
1052 spawn sub {
cf21866a
TC
1053 $| = 1;
1054 print "Hello there, $name, it's now ", scalar localtime(), $EOL;
1055 exec "/usr/games/fortune" # XXX: "wrong" line terminators
c5ae6365
AW
1056 or confess "can't exec fortune: $!";
1057 };
1058 close Client;
54310121 1059 }
a0d0e21e 1060
4633a7c4 1061 sub spawn {
c5ae6365
AW
1062 my $coderef = shift;
1063
cf21866a 1064 unless (@_ == 0 && $coderef && ref($coderef) eq "CODE") {
c5ae6365
AW
1065 confess "usage: spawn CODEREF";
1066 }
1067
1068 my $pid;
cf21866a 1069 unless (defined($pid = fork())) {
c5ae6365
AW
1070 logmsg "cannot fork: $!";
1071 return;
1072 }
1073 elsif ($pid) {
1074 logmsg "begat $pid";
1075 return; # I'm the parent
1076 }
1077 # else I'm the child -- go spawn
1078
cf21866a
TC
1079 open(STDIN, "<&Client") || die "can't dup client to stdin";
1080 open(STDOUT, ">&Client") || die "can't dup client to stdout";
c5ae6365 1081 ## open(STDERR, ">&STDOUT") || die "can't dup stdout to stderr";
cf21866a 1082 exit($coderef->());
54310121 1083 }
4633a7c4 1084
c5ae6365
AW
1085This server takes the trouble to clone off a child version via fork()
1086for each incoming request. That way it can handle many requests at
1087once, which you might not always want. Even if you don't fork(), the
1088listen() will allow that many pending connections. Forking servers
1089have to be particularly careful about cleaning up their dead children
1090(called "zombies" in Unix parlance), because otherwise you'll quickly
1091fill up your process table. The REAPER subroutine is used here to
1092call waitpid() for any child processes that have finished, thereby
1093ensuring that they terminate cleanly and don't join the ranks of the
1094living dead.
1095
1096Within the while loop we call accept() and check to see if it returns
cf21866a
TC
1097a false value. This would normally indicate a system error needs
1098to be reported. However, the introduction of safe signals (see
e6aa8b84 1099L</Deferred Signals (Safe Signals)> above) in Perl 5.8.0 means that
cf21866a
TC
1100accept() might also be interrupted when the process receives a signal.
1101This typically happens when one of the forked subprocesses exits and
c5ae6365
AW
1102notifies the parent process with a CHLD signal.
1103
cf21866a
TC
1104If accept() is interrupted by a signal, $! will be set to EINTR.
1105If this happens, we can safely continue to the next iteration of
c5ae6365 1106the loop and another call to accept(). It is important that your
cf21866a
TC
1107signal handling code not modify the value of $!, or else this test
1108will likely fail. In the REAPER subroutine we create a local version
1109of $! before calling waitpid(). When waitpid() sets $! to ECHILD as
1110it inevitably does when it has no more children waiting, it
1111updates the local copy and leaves the original unchanged.
4633a7c4 1112
cf21866a 1113You should use the B<-T> flag to enable taint checking (see L<perlsec>)
4633a7c4 1114even if we aren't running setuid or setgid. This is always a good idea
cf21866a 1115for servers or any program run on behalf of someone else (like CGI
4633a7c4
LW
1116scripts), because it lessens the chances that people from the outside will
1117be able to compromise your system.
1118
1119Let's look at another TCP client. This one connects to the TCP "time"
1120service on a number of different machines and shows how far their clocks
1121differ from the system on which it's being run:
1122
1123 #!/usr/bin/perl -w
4633a7c4
LW
1124 use strict;
1125 use Socket;
1126
cf21866a
TC
1127 my $SECS_OF_70_YEARS = 2208988800;
1128 sub ctime { scalar localtime(shift() || time()) }
4633a7c4 1129
cf21866a
TC
1130 my $iaddr = gethostbyname("localhost");
1131 my $proto = getprotobyname("tcp");
1132 my $port = getservbyname("time", "tcp");
4633a7c4
LW
1133 my $paddr = sockaddr_in(0, $iaddr);
1134 my($host);
1135
1136 $| = 1;
cf21866a 1137 printf "%-24s %8s %s\n", "localhost", 0, ctime();
4633a7c4
LW
1138
1139 foreach $host (@ARGV) {
322c2516
SF
1140 printf "%-24s ", $host;
1141 my $hisiaddr = inet_aton($host) || die "unknown host";
1142 my $hispaddr = sockaddr_in($port, $hisiaddr);
cf21866a
TC
1143 socket(SOCKET, PF_INET, SOCK_STREAM, $proto)
1144 || die "socket: $!";
322c2516 1145 connect(SOCKET, $hispaddr) || die "connect: $!";
cf21866a 1146 my $rtime = pack("C4", ());
322c2516
SF
1147 read(SOCKET, $rtime, 4);
1148 close(SOCKET);
cf21866a
TC
1149 my $histime = unpack("N", $rtime) - $SECS_OF_70_YEARS;
1150 printf "%8d %s\n", $histime - time(), ctime($histime);
a0d0e21e
LW
1151 }
1152
4633a7c4
LW
1153=head2 Unix-Domain TCP Clients and Servers
1154
a2eb9003 1155That's fine for Internet-domain clients and servers, but what about local
4633a7c4
LW
1156communications? While you can use the same setup, sometimes you don't
1157want to. Unix-domain sockets are local to the current host, and are often
54310121 1158used internally to implement pipes. Unlike Internet domain sockets, Unix
4633a7c4
LW
1159domain sockets can show up in the file system with an ls(1) listing.
1160
5a964f20 1161 % ls -l /dev/log
4633a7c4 1162 srw-rw-rw- 1 root 0 Oct 31 07:23 /dev/log
a0d0e21e 1163
4633a7c4
LW
1164You can test for these with Perl's B<-S> file test:
1165
cf21866a 1166 unless (-S "/dev/log") {
322c2516 1167 die "something's wicked with the log system";
54310121 1168 }
4633a7c4
LW
1169
1170Here's a sample Unix-domain client:
1171
1172 #!/usr/bin/perl -w
4633a7c4
LW
1173 use Socket;
1174 use strict;
1175 my ($rendezvous, $line);
1176
cf21866a 1177 $rendezvous = shift || "catsock";
322c2516
SF
1178 socket(SOCK, PF_UNIX, SOCK_STREAM, 0) || die "socket: $!";
1179 connect(SOCK, sockaddr_un($rendezvous)) || die "connect: $!";
54310121 1180 while (defined($line = <SOCK>)) {
322c2516 1181 print $line;
54310121 1182 }
cf21866a 1183 exit(0);
4633a7c4 1184
5a964f20
TC
1185And here's a corresponding server. You don't have to worry about silly
1186network terminators here because Unix domain sockets are guaranteed
1187to be on the localhost, and thus everything works right.
4633a7c4
LW
1188
1189 #!/usr/bin/perl -Tw
4633a7c4
LW
1190 use strict;
1191 use Socket;
1192 use Carp;
1193
cf21866a 1194 BEGIN { $ENV{PATH} = "/usr/bin:/bin" }
5865a7df 1195 sub spawn; # forward declaration
cf21866a 1196 sub logmsg { print "$0 $$: @_ at ", scalar localtime(), "\n" }
4633a7c4 1197
cf21866a 1198 my $NAME = "catsock";
4633a7c4 1199 my $uaddr = sockaddr_un($NAME);
cf21866a 1200 my $proto = getprotobyname("tcp");
4633a7c4 1201
cf21866a 1202 socket(Server, PF_UNIX, SOCK_STREAM, 0) || die "socket: $!";
4633a7c4 1203 unlink($NAME);
322c2516 1204 bind (Server, $uaddr) || die "bind: $!";
cf21866a 1205 listen(Server, SOMAXCONN) || die "listen: $!";
4633a7c4
LW
1206
1207 logmsg "server started on $NAME";
1208
5a964f20
TC
1209 my $waitedpid;
1210
816229cf 1211 use POSIX ":sys_wait_h";
5a964f20 1212 sub REAPER {
322c2516 1213 my $child;
cf21866a
TC
1214 while (($waitedpid = waitpid(-1, WNOHANG)) > 0) {
1215 logmsg "reaped $waitedpid" . ($? ? " with exit $?" : "");
322c2516
SF
1216 }
1217 $SIG{CHLD} = \&REAPER; # loathe SysV
5a964f20
TC
1218 }
1219
4633a7c4
LW
1220 $SIG{CHLD} = \&REAPER;
1221
5a964f20 1222
54310121 1223 for ( $waitedpid = 0;
cf21866a 1224 accept(Client, Server) || $waitedpid;
322c2516 1225 $waitedpid = 0, close Client)
4633a7c4 1226 {
322c2516
SF
1227 next if $waitedpid;
1228 logmsg "connection on $NAME";
1229 spawn sub {
cf21866a
TC
1230 print "Hello there, it's now ", scalar localtime(), "\n";
1231 exec("/usr/games/fortune") || die "can't exec fortune: $!";
322c2516 1232 };
54310121 1233 }
4633a7c4 1234
5865a7df 1235 sub spawn {
cf21866a 1236 my $coderef = shift();
322c2516 1237
cf21866a 1238 unless (@_ == 0 && $coderef && ref($coderef) eq "CODE") {
322c2516
SF
1239 confess "usage: spawn CODEREF";
1240 }
1241
1242 my $pid;
cf21866a 1243 unless (defined($pid = fork())) {
322c2516
SF
1244 logmsg "cannot fork: $!";
1245 return;
cf21866a
TC
1246 }
1247 elsif ($pid) {
322c2516
SF
1248 logmsg "begat $pid";
1249 return; # I'm the parent
cf21866a
TC
1250 }
1251 else {
1252 # I'm the child -- go spawn
322c2516 1253 }
322c2516 1254
cf21866a
TC
1255 open(STDIN, "<&Client") || die "can't dup client to stdin";
1256 open(STDOUT, ">&Client") || die "can't dup client to stdout";
322c2516 1257 ## open(STDERR, ">&STDOUT") || die "can't dup stdout to stderr";
cf21866a 1258 exit($coderef->());
5865a7df
NC
1259 }
1260
4633a7c4
LW
1261As you see, it's remarkably similar to the Internet domain TCP server, so
1262much so, in fact, that we've omitted several duplicate functions--spawn(),
cf21866a 1263logmsg(), ctime(), and REAPER()--which are the same as in the other server.
4633a7c4
LW
1264
1265So why would you ever want to use a Unix domain socket instead of a
1266simpler named pipe? Because a named pipe doesn't give you sessions. You
1267can't tell one process's data from another's. With socket programming,
cf21866a 1268you get a separate session for each client; that's why accept() takes two
4633a7c4
LW
1269arguments.
1270
cf21866a
TC
1271For example, let's say that you have a long-running database server daemon
1272that you want folks to be able to access from the Web, but only
4633a7c4
LW
1273if they go through a CGI interface. You'd have a small, simple CGI
1274program that does whatever checks and logging you feel like, and then acts
1275as a Unix-domain client and connects to your private server.
1276
7b05b7e3
TC
1277=head1 TCP Clients with IO::Socket
1278
1279For those preferring a higher-level interface to socket programming, the
e6aa8b84
BF
1280IO::Socket module provides an object-oriented approach. If for some reason
1281you lack this module, you can just fetch IO::Socket from CPAN, where you'll also
cf21866a
TC
1282find modules providing easy interfaces to the following systems: DNS, FTP,
1283Ident (RFC 931), NIS and NISPlus, NNTP, Ping, POP3, SMTP, SNMP, SSLeay,
1284Telnet, and Time--to name just a few.
7b05b7e3
TC
1285
1286=head2 A Simple Client
1287
1288Here's a client that creates a TCP connection to the "daytime"
1289service at port 13 of the host name "localhost" and prints out everything
1290that the server there cares to provide.
1291
1292 #!/usr/bin/perl -w
1293 use IO::Socket;
1294 $remote = IO::Socket::INET->new(
322c2516
SF
1295 Proto => "tcp",
1296 PeerAddr => "localhost",
1297 PeerPort => "daytime(13)",
1298 )
cf21866a
TC
1299 || die "can't connect to daytime service on localhost";
1300 while (<$remote>) { print }
7b05b7e3
TC
1301
1302When you run this program, you should get something back that
1303looks like this:
1304
1305 Wed May 14 08:40:46 MDT 1997
1306
cf21866a 1307Here are what those parameters to the new() constructor mean:
7b05b7e3 1308
13a2d996 1309=over 4
7b05b7e3
TC
1310
1311=item C<Proto>
1312
1313This is which protocol to use. In this case, the socket handle returned
1314will be connected to a TCP socket, because we want a stream-oriented
1315connection, that is, one that acts pretty much like a plain old file.
1316Not all sockets are this of this type. For example, the UDP protocol
1317can be used to make a datagram socket, used for message-passing.
1318
1319=item C<PeerAddr>
1320
1321This is the name or Internet address of the remote host the server is
1322running on. We could have specified a longer name like C<"www.perl.com">,
cf21866a 1323or an address like C<"207.171.7.72">. For demonstration purposes, we've
7b05b7e3
TC
1324used the special hostname C<"localhost">, which should always mean the
1325current machine you're running on. The corresponding Internet address
cf21866a 1326for localhost is C<"127.0.0.1">, if you'd rather use that.
7b05b7e3
TC
1327
1328=item C<PeerPort>
1329
1330This is the service name or port number we'd like to connect to.
1331We could have gotten away with using just C<"daytime"> on systems with a
1332well-configured system services file,[FOOTNOTE: The system services file
cf21866a
TC
1333is found in I</etc/services> under Unixy systems.] but here we've specified the
1334port number (13) in parentheses. Using just the number would have also
1335worked, but numeric literals make careful programmers nervous.
7b05b7e3
TC
1336
1337=back
1338
1339Notice how the return value from the C<new> constructor is used as
cf21866a
TC
1340a filehandle in the C<while> loop? That's what's called an I<indirect
1341filehandle>, a scalar variable containing a filehandle. You can use
7b05b7e3
TC
1342it the same way you would a normal filehandle. For example, you
1343can read one line from it this way:
1344
1345 $line = <$handle>;
1346
1347all remaining lines from is this way:
1348
1349 @lines = <$handle>;
1350
1351and send a line of data to it this way:
1352
1353 print $handle "some data\n";
1354
1355=head2 A Webget Client
1356
1357Here's a simple client that takes a remote host to fetch a document
cf21866a 1358from, and then a list of files to get from that host. This is a
7b05b7e3
TC
1359more interesting client than the previous one because it first sends
1360something to the server before fetching the server's response.
1361
1362 #!/usr/bin/perl -w
1363 use IO::Socket;
cf21866a 1364 unless (@ARGV > 1) { die "usage: $0 host url ..." }
7b05b7e3 1365 $host = shift(@ARGV);
5a964f20
TC
1366 $EOL = "\015\012";
1367 $BLANK = $EOL x 2;
cf21866a 1368 for my $document (@ARGV) {
322c2516
SF
1369 $remote = IO::Socket::INET->new( Proto => "tcp",
1370 PeerAddr => $host,
1371 PeerPort => "http(80)",
cf21866a 1372 ) || die "cannot connect to httpd on $host";
322c2516
SF
1373 $remote->autoflush(1);
1374 print $remote "GET $document HTTP/1.0" . $BLANK;
1375 while ( <$remote> ) { print }
1376 close $remote;
7b05b7e3
TC
1377 }
1378
cf21866a
TC
1379The web server handling the HTTP service is assumed to be at
1380its standard port, number 80. If the server you're trying to
1381connect to is at a different port, like 1080 or 8080, you should specify it
c47ff5f1 1382as the named-parameter pair, C<< PeerPort => 8080 >>. The C<autoflush>
7b05b7e3 1383method is used on the socket because otherwise the system would buffer
cf21866a
TC
1384up the output we sent it. (If you're on a prehistoric Mac, you'll also
1385need to change every C<"\n"> in your code that sends data over the network
1386to be a C<"\015\012"> instead.)
7b05b7e3
TC
1387
1388Connecting to the server is only the first part of the process: once you
1389have the connection, you have to use the server's language. Each server
1390on the network has its own little command language that it expects as
1391input. The string that we send to the server starting with "GET" is in
1392HTTP syntax. In this case, we simply request each specified document.
1393Yes, we really are making a new connection for each document, even though
1394it's the same host. That's the way you always used to have to speak HTTP.
1395Recent versions of web browsers may request that the remote server leave
1396the connection open a little while, but the server doesn't have to honor
1397such a request.
1398
1399Here's an example of running that program, which we'll call I<webget>:
1400
5a964f20 1401 % webget www.perl.com /guanaco.html
7b05b7e3
TC
1402 HTTP/1.1 404 File Not Found
1403 Date: Thu, 08 May 1997 18:02:32 GMT
1404 Server: Apache/1.2b6
1405 Connection: close
1406 Content-type: text/html
1407
1408 <HEAD><TITLE>404 File Not Found</TITLE></HEAD>
1409 <BODY><H1>File Not Found</H1>
1410 The requested URL /guanaco.html was not found on this server.<P>
1411 </BODY>
1412
1413Ok, so that's not very interesting, because it didn't find that
1414particular document. But a long response wouldn't have fit on this page.
1415
cf21866a 1416For a more featureful version of this program, you should look to
7b05b7e3
TC
1417the I<lwp-request> program included with the LWP modules from CPAN.
1418
1419=head2 Interactive Client with IO::Socket
1420
1421Well, that's all fine if you want to send one command and get one answer,
1422but what about setting up something fully interactive, somewhat like
1423the way I<telnet> works? That way you can type a line, get the answer,
1424type a line, get the answer, etc.
1425
1426This client is more complicated than the two we've done so far, but if
1427you're on a system that supports the powerful C<fork> call, the solution
1428isn't that rough. Once you've made the connection to whatever service
1429you'd like to chat with, call C<fork> to clone your process. Each of
1430these two identical process has a very simple job to do: the parent
1431copies everything from the socket to standard output, while the child
1432simultaneously copies everything from standard input to the socket.
1433To accomplish the same thing using just one process would be I<much>
1434harder, because it's easier to code two processes to do one thing than it
1435is to code one process to do two things. (This keep-it-simple principle
5a964f20
TC
1436a cornerstones of the Unix philosophy, and good software engineering as
1437well, which is probably why it's spread to other systems.)
7b05b7e3
TC
1438
1439Here's the code:
1440
1441 #!/usr/bin/perl -w
1442 use strict;
1443 use IO::Socket;
1444 my ($host, $port, $kidpid, $handle, $line);
1445
1446 unless (@ARGV == 2) { die "usage: $0 host port" }
1447 ($host, $port) = @ARGV;
1448
1449 # create a tcp connection to the specified host and port
1450 $handle = IO::Socket::INET->new(Proto => "tcp",
322c2516
SF
1451 PeerAddr => $host,
1452 PeerPort => $port)
cf21866a 1453 || die "can't connect to port $port on $host: $!";
7b05b7e3 1454
cf21866a 1455 $handle->autoflush(1); # so output gets there right away
7b05b7e3
TC
1456 print STDERR "[Connected to $host:$port]\n";
1457
1458 # split the program into two processes, identical twins
1459 die "can't fork: $!" unless defined($kidpid = fork());
1460
1461 # the if{} block runs only in the parent process
1462 if ($kidpid) {
322c2516
SF
1463 # copy the socket to standard output
1464 while (defined ($line = <$handle>)) {
1465 print STDOUT $line;
1466 }
cf21866a 1467 kill("TERM", $kidpid); # send SIGTERM to child
7b05b7e3
TC
1468 }
1469 # the else{} block runs only in the child process
1470 else {
322c2516
SF
1471 # copy standard input to the socket
1472 while (defined ($line = <STDIN>)) {
1473 print $handle $line;
1474 }
cf21866a 1475 exit(0); # just in case
7b05b7e3
TC
1476 }
1477
1478The C<kill> function in the parent's C<if> block is there to send a
cf21866a 1479signal to our child process, currently running in the C<else> block,
7b05b7e3
TC
1480as soon as the remote server has closed its end of the connection.
1481
7b05b7e3
TC
1482If the remote server sends data a byte at time, and you need that
1483data immediately without waiting for a newline (which might not happen),
1484you may wish to replace the C<while> loop in the parent with the
1485following:
1486
1487 my $byte;
1488 while (sysread($handle, $byte, 1) == 1) {
322c2516 1489 print STDOUT $byte;
7b05b7e3
TC
1490 }
1491
1492Making a system call for each byte you want to read is not very efficient
1493(to put it mildly) but is the simplest to explain and works reasonably
1494well.
1495
1496=head1 TCP Servers with IO::Socket
1497
5a964f20 1498As always, setting up a server is little bit more involved than running a client.
7b05b7e3
TC
1499The model is that the server creates a special kind of socket that
1500does nothing but listen on a particular port for incoming connections.
c47ff5f1 1501It does this by calling the C<< IO::Socket::INET->new() >> method with
7b05b7e3
TC
1502slightly different arguments than the client did.
1503
13a2d996 1504=over 4
7b05b7e3
TC
1505
1506=item Proto
1507
1508This is which protocol to use. Like our clients, we'll
1509still specify C<"tcp"> here.
1510
1511=item LocalPort
1512
1513We specify a local
1514port in the C<LocalPort> argument, which we didn't do for the client.
1515This is service name or port number for which you want to be the
1516server. (Under Unix, ports under 1024 are restricted to the
1517superuser.) In our sample, we'll use port 9000, but you can use
1518any port that's not currently in use on your system. If you try
1519to use one already in used, you'll get an "Address already in use"
19799a22 1520message. Under Unix, the C<netstat -a> command will show
7b05b7e3
TC
1521which services current have servers.
1522
1523=item Listen
1524
1525The C<Listen> parameter is set to the maximum number of
1526pending connections we can accept until we turn away incoming clients.
1527Think of it as a call-waiting queue for your telephone.
1528The low-level Socket module has a special symbol for the system maximum, which
1529is SOMAXCONN.
1530
1531=item Reuse
1532
1533The C<Reuse> parameter is needed so that we restart our server
1534manually without waiting a few minutes to allow system buffers to
1535clear out.
1536
1537=back
1538
1539Once the generic server socket has been created using the parameters
1540listed above, the server then waits for a new client to connect
d1be9408
JF
1541to it. The server blocks in the C<accept> method, which eventually accepts a
1542bidirectional connection from the remote client. (Make sure to autoflush
7b05b7e3
TC
1543this handle to circumvent buffering.)
1544
1545To add to user-friendliness, our server prompts the user for commands.
1546Most servers don't do this. Because of the prompt without a newline,
1547you'll have to use the C<sysread> variant of the interactive client above.
1548
cf21866a
TC
1549This server accepts one of five different commands, sending output back to
1550the client. Unlike most network servers, this one handles only one
1551incoming client at a time. Multithreaded servers are covered in
faa783ac 1552Chapter 16 of the Camel.
7b05b7e3
TC
1553
1554Here's the code. We'll
1555
1556 #!/usr/bin/perl -w
1557 use IO::Socket;
cf21866a 1558 use Net::hostent; # for OOish version of gethostbyaddr
7b05b7e3 1559
322c2516 1560 $PORT = 9000; # pick something not in use
7b05b7e3 1561
cf21866a 1562 $server = IO::Socket::INET->new( Proto => "tcp",
7b05b7e3
TC
1563 LocalPort => $PORT,
1564 Listen => SOMAXCONN,
1565 Reuse => 1);
1566
1567 die "can't setup server" unless $server;
1568 print "[Server $0 accepting clients]\n";
1569
1570 while ($client = $server->accept()) {
1571 $client->autoflush(1);
1572 print $client "Welcome to $0; type help for command list.\n";
1573 $hostinfo = gethostbyaddr($client->peeraddr);
78fc38e1 1574 printf "[Connect from %s]\n", $hostinfo ? $hostinfo->name : $client->peerhost;
7b05b7e3
TC
1575 print $client "Command? ";
1576 while ( <$client>) {
322c2516 1577 next unless /\S/; # blank line
cf21866a
TC
1578 if (/quit|exit/i) { last }
1579 elsif (/date|time/i) { printf $client "%s\n", scalar localtime() }
1580 elsif (/who/i ) { print $client `who 2>&1` }
1581 elsif (/cookie/i ) { print $client `/usr/games/fortune 2>&1` }
1582 elsif (/motd/i ) { print $client `cat /etc/motd 2>&1` }
7b05b7e3
TC
1583 else {
1584 print $client "Commands: quit date who cookie motd\n";
1585 }
1586 } continue {
1587 print $client "Command? ";
1588 }
1589 close $client;
1590 }
1591
1592=head1 UDP: Message Passing
4633a7c4
LW
1593
1594Another kind of client-server setup is one that uses not connections, but
1595messages. UDP communications involve much lower overhead but also provide
1596less reliability, as there are no promises that messages will arrive at
1597all, let alone in order and unmangled. Still, UDP offers some advantages
1598over TCP, including being able to "broadcast" or "multicast" to a whole
1599bunch of destination hosts at once (usually on your local subnet). If you
1600find yourself overly concerned about reliability and start building checks
6a3992aa 1601into your message system, then you probably should use just TCP to start
4633a7c4
LW
1602with.
1603
cf21866a
TC
1604UDP datagrams are I<not> a bytestream and should not be treated as such.
1605This makes using I/O mechanisms with internal buffering like stdio (i.e.
1606print() and friends) especially cumbersome. Use syswrite(), or better
1607send(), like in the example below.
90034919 1608
4633a7c4 1609Here's a UDP program similar to the sample Internet TCP client given
7b05b7e3 1610earlier. However, instead of checking one host at a time, the UDP version
4633a7c4
LW
1611will check many of them asynchronously by simulating a multicast and then
1612using select() to do a timed-out wait for I/O. To do something similar
1613with TCP, you'd have to use a different socket handle for each host.
1614
1615 #!/usr/bin/perl -w
1616 use strict;
4633a7c4
LW
1617 use Socket;
1618 use Sys::Hostname;
1619
54310121 1620 my ( $count, $hisiaddr, $hispaddr, $histime,
322c2516 1621 $host, $iaddr, $paddr, $port, $proto,
cf21866a 1622 $rin, $rout, $rtime, $SECS_OF_70_YEARS);
4633a7c4 1623
cf21866a 1624 $SECS_OF_70_YEARS = 2_208_988_800;
4633a7c4
LW
1625
1626 $iaddr = gethostbyname(hostname());
cf21866a
TC
1627 $proto = getprotobyname("udp");
1628 $port = getservbyname("time", "udp");
4633a7c4
LW
1629 $paddr = sockaddr_in(0, $iaddr); # 0 means let kernel pick
1630
1631 socket(SOCKET, PF_INET, SOCK_DGRAM, $proto) || die "socket: $!";
1632 bind(SOCKET, $paddr) || die "bind: $!";
1633
1634 $| = 1;
cf21866a 1635 printf "%-12s %8s %s\n", "localhost", 0, scalar localtime();
4633a7c4
LW
1636 $count = 0;
1637 for $host (@ARGV) {
322c2516 1638 $count++;
cf21866a 1639 $hisiaddr = inet_aton($host) || die "unknown host";
322c2516
SF
1640 $hispaddr = sockaddr_in($port, $hisiaddr);
1641 defined(send(SOCKET, 0, 0, $hispaddr)) || die "send $host: $!";
4633a7c4
LW
1642 }
1643
cf21866a 1644 $rin = "";
4633a7c4
LW
1645 vec($rin, fileno(SOCKET), 1) = 1;
1646
1647 # timeout after 10.0 seconds
1648 while ($count && select($rout = $rin, undef, undef, 10.0)) {
cf21866a
TC
1649 $rtime = "";
1650 $hispaddr = recv(SOCKET, $rtime, 4, 0) || die "recv: $!";
322c2516
SF
1651 ($port, $hisiaddr) = sockaddr_in($hispaddr);
1652 $host = gethostbyaddr($hisiaddr, AF_INET);
cf21866a 1653 $histime = unpack("N", $rtime) - $SECS_OF_70_YEARS;
322c2516 1654 printf "%-12s ", $host;
cf21866a 1655 printf "%8d %s\n", $histime - time(), scalar localtime($histime);
322c2516 1656 $count--;
4633a7c4
LW
1657 }
1658
cf21866a
TC
1659This example does not include any retries and may consequently fail to
1660contact a reachable host. The most prominent reason for this is congestion
1661of the queues on the sending host if the number of hosts to contact is
1662sufficiently large.
90034919 1663
4633a7c4
LW
1664=head1 SysV IPC
1665
1666While System V IPC isn't so widely used as sockets, it still has some
cf21866a
TC
1667interesting uses. However, you cannot use SysV IPC or Berkeley mmap() to
1668have a variable shared amongst several processes. That's because Perl
1669would reallocate your string when you weren't wanting it to. You might
1670look into the C<IPC::Shareable> or C<threads::shared> modules for that.
4633a7c4 1671
54310121 1672Here's a small example showing shared memory usage.
a0d0e21e 1673
7b34eba2 1674 use IPC::SysV qw(IPC_PRIVATE IPC_RMID S_IRUSR S_IWUSR);
0ade1984 1675
a0d0e21e 1676 $size = 2000;
cf21866a
TC
1677 $id = shmget(IPC_PRIVATE, $size, S_IRUSR | S_IWUSR);
1678 defined($id) || die "shmget: $!";
41d6edb2 1679 print "shm key $id\n";
a0d0e21e
LW
1680
1681 $message = "Message #1";
cf21866a 1682 shmwrite($id, $message, 0, 60) || die "shmwrite: $!";
0ade1984 1683 print "wrote: '$message'\n";
cf21866a 1684 shmread($id, $buff, 0, 60) || die "shmread: $!";
0ade1984 1685 print "read : '$buff'\n";
a0d0e21e 1686
0ade1984 1687 # the buffer of shmread is zero-character end-padded.
b18b5ffd 1688 substr($buff, index($buff, "\0")) = "";
0ade1984
JH
1689 print "un" unless $buff eq $message;
1690 print "swell\n";
a0d0e21e 1691
41d6edb2 1692 print "deleting shm $id\n";
cf21866a 1693 shmctl($id, IPC_RMID, 0) || die "shmctl: $!";
a0d0e21e
LW
1694
1695Here's an example of a semaphore:
1696
0ade1984
JH
1697 use IPC::SysV qw(IPC_CREAT);
1698
a0d0e21e 1699 $IPC_KEY = 1234;
cf21866a 1700 $id = semget($IPC_KEY, 10, 0666 | IPC_CREAT);
3389bcf7
JL
1701 defined($id) || die "semget: $!";
1702 print "sem id $id\n";
a0d0e21e 1703
a2eb9003 1704Put this code in a separate file to be run in more than one process.
a0d0e21e
LW
1705Call the file F<take>:
1706
1707 # create a semaphore
1708
1709 $IPC_KEY = 1234;
cf21866a 1710 $id = semget($IPC_KEY, 0, 0);
3389bcf7 1711 defined($id) || die "semget: $!";
a0d0e21e 1712
cf21866a 1713 $semnum = 0;
a0d0e21e
LW
1714 $semflag = 0;
1715
cf21866a 1716 # "take" semaphore
a0d0e21e
LW
1717 # wait for semaphore to be zero
1718 $semop = 0;
41d6edb2 1719 $opstring1 = pack("s!s!s!", $semnum, $semop, $semflag);
a0d0e21e
LW
1720
1721 # Increment the semaphore count
1722 $semop = 1;
41d6edb2 1723 $opstring2 = pack("s!s!s!", $semnum, $semop, $semflag);
cf21866a 1724 $opstring = $opstring1 . $opstring2;
a0d0e21e 1725
cf21866a 1726 semop($id, $opstring) || die "semop: $!";
a0d0e21e 1727
a2eb9003 1728Put this code in a separate file to be run in more than one process.
a0d0e21e
LW
1729Call this file F<give>:
1730
cf21866a 1731 # "give" the semaphore
a0d0e21e
LW
1732 # run this in the original process and you will see
1733 # that the second process continues
1734
1735 $IPC_KEY = 1234;
41d6edb2 1736 $id = semget($IPC_KEY, 0, 0);
cf21866a 1737 die unless defined($id);
a0d0e21e 1738
cf21866a 1739 $semnum = 0;
a0d0e21e
LW
1740 $semflag = 0;
1741
1742 # Decrement the semaphore count
1743 $semop = -1;
41d6edb2 1744 $opstring = pack("s!s!s!", $semnum, $semop, $semflag);
a0d0e21e 1745
cf21866a 1746 semop($id, $opstring) || die "semop: $!";
a0d0e21e 1747
7b05b7e3 1748The SysV IPC code above was written long ago, and it's definitely
e6aa8b84 1749clunky looking. For a more modern look, see the IPC::SysV module.
4633a7c4 1750
41d6edb2
JH
1751A small example demonstrating SysV message queues:
1752
7b34eba2 1753 use IPC::SysV qw(IPC_PRIVATE IPC_RMID IPC_CREAT S_IRUSR S_IWUSR);
41d6edb2 1754
7b34eba2 1755 my $id = msgget(IPC_PRIVATE, IPC_CREAT | S_IRUSR | S_IWUSR);
cf21866a 1756 defined($id) || die "msgget failed: $!";
41d6edb2 1757
cf21866a 1758 my $sent = "message";
e343e2e2 1759 my $type_sent = 1234;
cf21866a
TC
1760
1761 msgsnd($id, pack("l! a*", $type_sent, $sent), 0)
1762 || die "msgsnd failed: $!";
1763
1764 msgrcv($id, my $rcvd_buf, 60, 0, 0)
1765 || die "msgrcv failed: $!";
1766
1767 my($type_rcvd, $rcvd) = unpack("l! a*", $rcvd_buf);
1768
1769 if ($rcvd eq $sent) {
1770 print "okay\n";
41d6edb2 1771 } else {
cf21866a 1772 print "not okay\n";
41d6edb2
JH
1773 }
1774
cf21866a
TC
1775 msgctl($id, IPC_RMID, 0) || die "msgctl failed: $!\n";
1776
4633a7c4
LW
1777=head1 NOTES
1778
5a964f20
TC
1779Most of these routines quietly but politely return C<undef> when they
1780fail instead of causing your program to die right then and there due to
1781an uncaught exception. (Actually, some of the new I<Socket> conversion
cf21866a 1782functions do croak() on bad arguments.) It is therefore essential to
5a964f20 1783check return values from these functions. Always begin your socket
cf21866a
TC
1784programs this way for optimal success, and don't forget to add the B<-T>
1785taint-checking flag to the C<#!> line for servers:
4633a7c4 1786
5a964f20 1787 #!/usr/bin/perl -Tw
4633a7c4
LW
1788 use strict;
1789 use sigtrap;
1790 use Socket;
1791
1792=head1 BUGS
1793
cf21866a 1794These routines all create system-specific portability problems. As noted
4633a7c4 1795elsewhere, Perl is at the mercy of your C libraries for much of its system
cf21866a 1796behavior. It's probably safest to assume broken SysV semantics for
6a3992aa 1797signals and to stick with simple TCP and UDP socket operations; e.g., don't
a2eb9003 1798try to pass open file descriptors over a local UDP datagram socket if you
4633a7c4
LW
1799want your code to stand a chance of being portable.
1800
4633a7c4
LW
1801=head1 AUTHOR
1802
1803Tom Christiansen, with occasional vestiges of Larry Wall's original
7b05b7e3 1804version and suggestions from the Perl Porters.
4633a7c4
LW
1805
1806=head1 SEE ALSO
1807
7b05b7e3
TC
1808There's a lot more to networking than this, but this should get you
1809started.
1810
cf21866a
TC
1811For intrepid programmers, the indispensable textbook is I<Unix Network
1812Programming, 2nd Edition, Volume 1> by W. Richard Stevens (published by
1813Prentice-Hall). Most books on networking address the subject from the
1814perspective of a C programmer; translation to Perl is left as an exercise
1815for the reader.
7b05b7e3
TC
1816
1817The IO::Socket(3) manpage describes the object library, and the Socket(3)
1818manpage describes the low-level interface to sockets. Besides the obvious
cf21866a
TC
1819functions in L<perlfunc>, you should also check out the F<modules> file at
1820your nearest CPAN site, especially
1821L<http://www.cpan.org/modules/00modlist.long.html#ID5_Networking_>.
1822See L<perlmodlib> or best yet, the F<Perl FAQ> for a description
1823of what CPAN is and where to get it if the previous link doesn't work
1824for you.
1825
1826Section 5 of CPAN's F<modules> file is devoted to "Networking, Device
1827Control (modems), and Interprocess Communication", and contains numerous
1828unbundled modules numerous networking modules, Chat and Expect operations,
1829CGI programming, DCE, FTP, IPC, NNTP, Proxy, Ptty, RPC, SNMP, SMTP, Telnet,
1830Threads, and ToolTalk--to name just a few.