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