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