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