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