Penguin
Recent Changes
Annotated edit history of perlipc(1) version 2 showing authors affecting page license. View with all changes included.
Rev Author # Line
1 perry 1 PERLIPC
2 !!!PERLIPC
3 NAME
4 DESCRIPTION
5 Signals
6 Named Pipes
7 Using open() for IPC
8 Sockets: Client/Server Communication
9 TCP Clients with IO::Socket
10 TCP Servers with IO::Socket
11 UDP: Message Passing
12 SysV IPC
13 NOTES
14 BUGS
15 AUTHOR
16 SEE ALSO
17 ----
18 !!NAME
19
20
21 perlipc - Perl interprocess communication (signals, fifos, pipes, safe subprocesses, sockets, and semaphores)
22 !!DESCRIPTION
23
24
25 The basic IPC facilities of Perl are built
26 out of the good old Unix signals, named pipes, pipe opens,
27 the Berkeley socket routines, and SysV IPC
28 calls. Each is used in slightly different
29 situations.
30 !!Signals
31
32
33 Perl uses a simple signal handling model: the %SIG
34 hash contains names or references of user-installed signal
35 handlers. These handlers will be called with an argument
36 which is the name of the signal that triggered it. A signal
37 may be generated intentionally from a particular keyboard
38 sequence like control-C or control-Z, sent to you from
39 another process, or triggered automatically by the kernel
40 when special events transpire, like a child process exiting,
41 your process running out of stack space, or hitting file
42 size limit.
43
44
45 For example, to trap an interrupt signal, set up a handler
46 like this. Do as little as you possibly can in your handler;
47 notice how all we do is set a global variable and then raise
48 an exception. That's because on most systems, libraries are
49 not re-entrant; particularly, memory allocation and I/O
50 routines are not. That means that doing nearly
51 ''anything'' in your handler could in theory trigger a
52 memory fault and subsequent core dump.
53
54
55 sub catch_zap {
56 my $signame = shift;
57 $shucks++;
58 die
59 The names of the signals are the ones listed out by kill -l on your system, or you can retrieve them from the Config module. Set up an @signame list indexed by number to get the name and a %signo table indexed by name to get the number:
60
61
62 use Config;
63 defined $Config{sig_name} die
64 So to check whether signal 17 and SIGALRM were the same, do just this:
65
66
67 print
68 You may also choose to assign the strings 'IGNORE' or 'DEFAULT' as the handler, in which case Perl will try to discard the signal or do the default thing.
69
70
71 On most Unix platforms, the CHLD (sometimes also
72 known as CLD) signal has special behavior with
73 respect to a value of 'IGNORE'. Setting
74 $SIG{CHLD} to 'IGNORE' on such a platform
75 has the effect of not creating zombie processes when the
76 parent process fails to wait() on its child
77 processes (i.e. child processes are automatically reaped).
78 Calling wait() with $SIG{CHLD} set to
79 'IGNORE' usually returns -1 on such
80 platforms.
81
82
83 Some signals can be neither trapped nor ignored, such as the
84 KILL and STOP (but not the
85 TSTP ) signals. One strategy for temporarily
86 ignoring signals is to use a ''local()'' statement, which
87 will be automatically restored once your block is exited.
88 (Remember that ''local()'' values are ``inherited'' by
89 functions called from within that block.)
90
91
92 sub precious {
93 local $SIG{INT} = 'IGNORE';
94 Sending a signal to a negative process ID means that you send the signal to the entire Unix process-group. This code sends a hang-up signal to all processes in the current process group (and sets $SIG{ HUP } to IGNORE so it doesn't kill itself):
95
96
97 {
98 local $SIG{HUP} = 'IGNORE';
99 kill HUP =
100 Another interesting signal to send is signal number zero. This doesn't actually affect another process, but instead checks whether it's alive or has changed its UID .
101
102
103 unless (kill 0 =
104 You might also want to employ anonymous functions for simple signal handlers:
105
106
107 $SIG{INT} = sub { die
108 But that will be problematic for the more complicated handlers that need to reinstall themselves. Because Perl's signal mechanism is currently based on the signal(3) function from the C library, you may sometimes be so misfortunate as to run on systems where that function is ``broken'', that is, it behaves in the old unreliable SysV way rather than the newer, more reasonable BSD and POSIX fashion. So you'll see defensive people writing signal handlers like this:
109
110
111 sub REAPER {
112 $waitedpid = wait;
113 # loathe sysV: it makes us not only reinstate
114 # the handler, but place it after the wait
115 $SIG{CHLD} =
116 or even the more elaborate:
117
118
119 use POSIX
120 Signal handling is also used for timeouts in Unix, While safely protected within an eval{} block, you set a signal handler to trap alarm signals and then schedule to have one delivered to you in some number of seconds. Then try your blocking operation, clearing the alarm when it's done but not before you've exited your eval{} block. If it goes off, you'll use ''die()'' to jump out of the block, much as you might using ''longjmp()'' or ''throw()'' in other languages.
121
122
123 Here's an example:
124
125
126 eval {
127 local $SIG{ALRM} = sub { die
128 If the operation being timed out is ''system()'' or ''qx()'', this technique is liable to generate zombies. If this matters to you, you'll need to do your own ''fork()'' and ''exec()'', and kill the errant child process.
129
130
131 For more complex signal handling, you might see the standard
132 POSIX module. Lamentably, this is almost
133 entirely undocumented, but the ''t/lib/posix.t'' file
134 from the Perl source distribution has some examples in
135 it.
136 !!Named Pipes
137
138
139 A named pipe (often referred to as a FIFO )
140 is an old Unix IPC mechanism for processes
141 communicating on the same machine. It works just like a
142 regular, connected anonymous pipes, except that the
143 processes rendezvous using a filename and don't have to be
144 related.
145
146
147 To create a named pipe, use the Unix command mknod(1)
148 or on some systems, mkfifo(1). These may not be in
149 your normal path.
150
151
152 # system return val is backwards, so
153 A fifo is convenient when you want to connect a process to an unrelated one. When you open a fifo, the program will block until there's something on the other end.
154
155
156 For example, let's say you'd like to have your
157 ''.signature'' file be a named pipe that has a Perl
158 program on the other end. Now every time any program (like a
159 mailer, news reader, finger program, etc.) tries to read
160 from that file, the reading program will block and your
161 program will supply the new signature. We'll use the
162 pipe-checking file test __-p__ to find out whether anyone
163 (or anything) has accidentally removed our
164 fifo.
165
166
167 chdir; # go home
168 $FIFO = '.signature';
169 $ENV{PATH} .=
170 while (1) {
171 unless (-p $FIFO) {
172 unlink $FIFO;
173 system('mknod', $FIFO, 'p')
174 # next line blocks until there's a reader
175 open (FIFO,
176
177
178 __WARNING__
179
180
181 By installing Perl code to deal with signals, you're
182 exposing yourself to danger from two things. First, few
183 system library functions are re-entrant. If the signal
184 interrupts while Perl is executing one function (like
185 malloc(3) or printf(3)), and your signal
186 handler then calls the same function again, you could get
187 unpredictable behavior--often, a core dump. Second, Perl
188 isn't itself re-entrant at the lowest levels. If the signal
189 interrupts Perl while Perl is changing its own internal data
190 structures, similarly unpredictable behaviour may
191 result.
192
193
194 There are two things you can do, knowing this: be paranoid
195 or be pragmatic. The paranoid approach is to do as little as
196 possible in your signal handler. Set an existing integer
197 variable that already has a value, and return. This doesn't
198 help you if you're in a slow system call, which will just
199 restart. That means you have to die to
200 longjump(3) out of the handler. Even this is a little
201 cavalier for the true paranoiac, who avoids die in
202 a handler because the system ''is'' out to get you. The
203 pragmatic approach is to say ``I know the risks, but prefer
204 the convenience'', and to do anything you want in your
205 signal handler, prepared to clean up core dumps now and
206 again.
207
208
209 To forbid signal handlers altogether would bars you from
210 many interesting programs, including virtually everything in
211 this manpage, since you could no longer even write
212 SIGCHLD handlers.
213 !!Using open() for IPC
214
215
216 Perl's basic ''open()'' statement can also be used for
217 unidirectional interprocess communication by either
218 appending or prepending a pipe symbol to the second argument
219 to ''open()''. Here's how to start something up in a
220 child process you intend to write to:
221
222
223 open(SPOOLER,
224 And here's how to start up a child process you intend to read from:
225
226
227 open(STATUS,
228 If one can be sure that a particular program is a Perl script that is expecting filenames in @ARGV, the clever programmer can write something like this:
229
230
231 % program f1
232 and irrespective of which shell it's called from, the Perl program will read from the file ''f1'', the process ''cmd1'', standard input (''tmpfile'' in this case), the ''f2'' file, the ''cmd2'' command, and finally the ''f3'' file. Pretty nifty, eh?
233
234
235 You might notice that you could use backticks for much the
236 same effect as opening a pipe for reading:
237
238
239 print grep { !/^(tcpudp)/ } `netstat -an 2
240 While this is true on the surface, it's much more efficient to process the file one line or record at a time because then you don't have to read the whole thing into memory at once. It also gives you finer control of the whole process, letting you to kill off the child process early if you'd like.
241
242
243 Be careful to check both the ''open()'' and the
244 ''close()'' return values. If you're ''writing'' to a
245 pipe, you should also trap SIGPIPE .
246 Otherwise, think of what happens when you start up a pipe to
247 a command that doesn't exist: the ''open()'' will in all
248 likelihood succeed (it only reflects the ''fork()'''s
249 success), but then your output will fail--spectacularly.
250 Perl can't know whether the command worked because your
251 command is actually running in a separate process whose
252 ''exec()'' might have failed. Therefore, while readers of
253 bogus commands return just a quick end of file, writers to
254 bogus command will trigger a signal they'd better be
255 prepared to handle. Consider:
256
257
258 open(FH,
259 That won't blow up until the close, and it will blow up with a SIGPIPE . To catch it, you could use this:
260
261
262 $SIG{PIPE} = 'IGNORE';
263 open(FH,
264
265
266 __Filehandles__
267
268
269 Both the main process and any child processes it forks share
270 the same STDIN , STDOUT , and
271 STDERR filehandles. If both processes try to
272 access them at once, strange things can happen. You may also
273 want to close or reopen the filehandles for the child. You
274 can get around this by opening your pipe with ''open()'',
275 but on some systems this means that the child process cannot
276 outlive the parent.
277
278
279 __Background Processes__
280
281
282 You can run a command in the background with:
283
284
285 system(
286 The command's STDOUT and STDERR (and possibly STDIN , depending on your shell) will be the same as the parent's. You won't need to catch SIGCHLD because of the double-fork taking place (see below for more details).
287
288
289 __Complete Dissociation of Child from
290 Parent__
291
292
293 In some cases (starting server processes, for instance)
294 you'll want to completely dissociate the child process from
295 the parent. This is often called daemonization. A well
296 behaved daemon will also ''chdir()'' to the root
297 directory (so it doesn't prevent unmounting the filesystem
298 containing the directory from which it was launched) and
299 redirect its standard file descriptors from and to
300 ''/dev/null'' (so that random output doesn't wind up on
301 the user's terminal).
302
303
304 use POSIX 'setsid';
305 sub daemonize {
306 chdir '/' or die
307 The ''fork()'' has to come before the ''setsid()'' to ensure that you aren't a process group leader (the ''setsid()'' will fail if you are). If your system doesn't have the ''setsid()'' function, open ''/dev/tty'' and use the TIOCNOTTY ''ioctl()'' on it instead. See tty(4) for details.
308
309
310 Non-Unix users should check their Your_OS::Process module
311 for other solutions.
312
313
314 __Safe Pipe Opens__
315
316
317 Another interesting approach to IPC is making
318 your single program go multiprocess and communicate between
319 (or even amongst) yourselves. The ''open()'' function
320 will accept a file argument of either
321 or to do a very interesting thing: it
322 forks a child connected to the filehandle you've opened. The
323 child is running the same program as the parent. This is
324 useful for safely opening a file when running under an
325 assumed UID or GID , for
326 example. If you open a pipe ''to'' minus, you can write
327 to the filehandle you opened and your kid will find it in
328 his STDIN . If you open a pipe ''from''
329 minus, you can read from the filehandle you opened whatever
330 your kid writes to his STDOUT .
331
332
333 use English;
334 my $sleep_count = 0;
335 do {
336 $pid = open(KID_TO_WRITE,
337 if ($pid) { # parent
338 print KID_TO_WRITE @some_data;
339 close(KID_TO_WRITE) warn
340 Another common use for this construct is when you need to execute something without the shell's interference. With ''system()'', it's straightforward, but you can't use a pipe open or backticks safely. That's because there's no way to stop the shell from getting its hands on your arguments. Instead, use lower-level control to call ''exec()'' directly.
341
342
343 Here's a safe backtick or pipe open for read:
344
345
346 # add error processing as above
347 $pid = open(KID_TO_READ,
348 if ($pid) { # parent
349 while (
350 } else { # child
351 ($EUID, $EGID) = ($UID, $GID); # suid only
352 exec($program, @options, @args)
353 die
354 And here's a safe pipe open for writing:
355
356
357 # add error processing as above
358 $pid = open(KID_TO_WRITE,
359 if ($pid) { # parent
360 for (@data) {
361 print KID_TO_WRITE;
362 }
363 close(KID_TO_WRITE) warn
364 } else { # child
365 ($EUID, $EGID) = ($UID, $GID);
366 exec($program, @options, @args)
367 die
368 Note that these operations are full Unix forks, which means they may not be correctly implemented on alien systems. Additionally, these are not true multithreading. If you'd like to learn more about threading, see the ''modules'' file mentioned below in the SEE ALSO section.
369
370
371 __Bidirectional Communication with Another
372 Process__
373
374
375 While this works reasonably well for unidirectional
376 communication, what about bidirectional communication? The
377 obvious thing you'd like to do doesn't actually
378 work:
379
380
381 open(PROG_FOR_READING_AND_WRITING,
382 and if you forget to use the use warnings pragma or the __-w__ flag, then you'll miss out entirely on the diagnostic message:
383
384
385 Can't do bidirectional pipe at -e line 1.
386 If you really want to, you can use the standard ''open2()'' library function to catch both ends. There's also an ''open3()'' for tridirectional I/O so you can also catch your child's STDERR , but doing so would then require an awkward ''select()'' loop and wouldn't allow you to use normal Perl input operations.
387
388
389 If you look at its source, you'll see that ''open2()''
390 uses low-level primitives like Unix ''pipe()'' and
391 ''exec()'' calls to create all the connections. While it
392 might have been slightly more efficient by using
393 ''socketpair()'', it would have then been even less
394 portable than it already is. The ''open2()'' and
395 ''open3()'' functions are unlikely to work anywhere
396 except on a Unix system or some other one purporting to be
397 POSIX compliant.
398
399
400 Here's an example of using ''open2()'':
401
402
403 use !FileHandle;
404 use IPC::Open2;
405 $pid = open2(*Reader, *Writer,
406 The problem with this is that Unix buffering is really going to ruin your day. Even though your Writer filehandle is auto-flushed, and the process on the other end will get your data in a timely manner, you can't usually do anything to force it to give it back to you in a similarly quick fashion. In this case, we could, because we gave ''cat'' a __-u__ flag to make it unbuffered. But very few Unix commands are designed to operate over pipes, so this seldom works unless you yourself wrote the program on the other end of the double-ended pipe.
407
408
409 A solution to this is the nonstandard ''Comm.pl''
410 library. It uses pseudo-ttys to make your program behave
411 more reasonably:
412
413
414 require 'Comm.pl';
415 $ph = open_proc('cat -n');
416 for (1..10) {
417 print $ph
418 This way you don't have to have control over the source code of the program you're using. The ''Comm'' library also has ''expect()'' and ''interact()'' functions. Find the library (and we hope its successor ''IPC::Chat'') at your nearest CPAN archive as detailed in the SEE ALSO section below.
419
420
421 The newer Expect.pm module from CPAN also
422 addresses this kind of thing. This module requires two other
423 modules from CPAN: IO::Pty and IO::Stty. It
424 sets up a pseudo-terminal to interact with programs that
425 insist on using talking to the terminal device driver. If
426 your system is amongst those supported, this may be your
427 best bet.
428
429
430 __Bidirectional Communication with
431 Yourself__
432
433
434 If you want, you may make low-level ''pipe()'' and
435 ''fork()'' to stitch this together by hand. This example
436 only talks to itself, but you could reopen the appropriate
437 handles to STDIN and STDOUT
438 and call other processes.
439
440
441 #!/usr/bin/perl -w
442 # pipe1 - bidirectional communication using two pipe pairs
443 # designed for the socketpair-challenged
444 use IO::Handle; # thousands of lines just for autoflush :-(
445 pipe(PARENT_RDR, CHILD_WTR); # XXX: failure?
446 pipe(CHILD_RDR, PARENT_WTR); # XXX: failure?
447 CHILD_WTR-
448 if ($pid = fork) {
449 close PARENT_RDR; close PARENT_WTR;
450 print CHILD_WTR
451 But you don't actually have to make two pipe calls. If you have the ''socketpair()'' system call, it will do this all for you.
452
453
454 #!/usr/bin/perl -w
455 # pipe2 - bidirectional communication using socketpair
456 #
457 use Socket;
458 use IO::Handle; # thousands of lines just for autoflush :-(
459 # We say AF_UNIX because although *_LOCAL is the
460 # POSIX 1003.1g form of the constant, many machines
461 # still don't have it.
462 socketpair(CHILD, PARENT, AF_UNIX, SOCK_STREAM, PF_UNSPEC)
463 or die
464 CHILD-
465 if ($pid = fork) {
466 close PARENT;
467 print CHILD
468 !!Sockets: Client/Server Communication
469
470
471 While not limited to Unix-derived operating systems (e.g.,
472 !WinSock on PCs provides socket support, as do some
473 VMS libraries), you may not have sockets on
474 your system, in which case this section probably isn't going
475 to do you much good. With sockets, you can do both virtual
476 circuits (i.e., TCP streams) and datagrams
477 (i.e., UDP packets). You may be able to do
478 even more depending on your system.
479
480
481 The Perl function calls for dealing with sockets have the
482 same names as the corresponding system calls in C, but their
483 arguments tend to differ for two reasons: first, Perl
484 filehandles work differently than C file descriptors.
485 Second, Perl already knows the length of its strings, so you
486 don't need to pass that information.
487
488
489 One of the major problems with old socket code in Perl was
490 that it used hard-coded values for some of the constants,
491 which severely hurt portability. If you ever see code that
492 does anything like explicitly setting $AF_INET = 2,
493 you know you're in for big trouble: An immeasurably superior
494 approach is to use the Socket module, which more
495 reliably grants access to various constants and functions
496 you'll need.
497
498
499 If you're not writing a server/client for an existing
500 protocol like NNTP or SMTP ,
501 you should give some thought to how your server will know
502 when the client has finished talking, and vice-versa. Most
503 protocols are based on one-line messages and responses (so
504 one party knows the other has finished when a ``n'' is
505 received) or multi-line messages and responses that end with
506 a period on an empty line (``n.n'' terminates a
507 message/response).
508
509
510 __Internet Line Terminators__
511
512
513 The Internet line terminator is ``015012''. Under
514 ASCII variants of Unix, that could usually be
515 written as ``rn'', but under other systems, ``rn'' might at
516 times be ``015015012'', ``012012015'', or something
517 completely different. The standards specify writing
518 ``015012'' to be conformant (be strict in what you provide),
519 but they also recommend accepting a lone ``012'' on input
520 (but be lenient in what you require). We haven't always been
521 very good about that in the code in this manpage, but unless
522 you're on a Mac, you'll probably be ok.
523
524
525 __Internet TCP Clients and
526 Servers__
527
528
529 Use Internet-domain sockets when you want to do
530 client-server communication that might extend to machines
531 outside of your own system.
532
533
534 Here's a sample TCP client using
535 Internet-domain sockets:
536
537
538 #!/usr/bin/perl -w
539 use strict;
540 use Socket;
541 my ($remote,$port, $iaddr, $paddr, $proto, $line);
542 $remote = shift 'localhost';
543 $port = shift 2345; # random port
544 if ($port =~ /D/) { $port = getservbyname($port, 'tcp') }
545 die
546 $proto = getprotobyname('tcp');
547 socket(SOCK, PF_INET, SOCK_STREAM, $proto) die
548 close (SOCK) die
549 And here's a corresponding server to go along with it. We'll leave the address as INADDR_ANY so that the kernel can choose the appropriate interface on multihomed hosts. If you want sit on a particular interface (like the external side of a gateway or firewall machine), you should fill this in with your real address instead.
550
551
552 #!/usr/bin/perl -Tw
553 use strict;
554 BEGIN { $ENV{PATH} = '/usr/ucb:/bin' }
555 use Socket;
556 use Carp;
557 my $EOL =
558 sub logmsg { print
559 my $port = shift 2345;
560 my $proto = getprotobyname('tcp');
561 ($port) = $port =~ /^(d+)$/ or die
562 socket(Server, PF_INET, SOCK_STREAM, $proto) die
563 logmsg
564 my $paddr;
565 $SIG{CHLD} =
566 for ( ; $paddr = accept(Client,Server); close Client) {
567 my($port,$iaddr) = sockaddr_in($paddr);
568 my $name = gethostbyaddr($iaddr,AF_INET);
569 logmsg
570 print Client
571 And here's a multithreaded version. It's multithreaded in that like most typical servers, it spawns (forks) a slave server to handle the client request so that the master server can quickly go back to service a new client.
572
573
574 #!/usr/bin/perl -Tw
575 use strict;
576 BEGIN { $ENV{PATH} = '/usr/ucb:/bin' }
577 use Socket;
578 use Carp;
579 my $EOL =
580 sub spawn; # forward declaration
581 sub logmsg { print
582 my $port = shift 2345;
583 my $proto = getprotobyname('tcp');
584 ($port) = $port =~ /^(d+)$/ or die
585 socket(Server, PF_INET, SOCK_STREAM, $proto) die
586 logmsg
587 my $waitedpid = 0;
588 my $paddr;
589 sub REAPER {
590 $waitedpid = wait;
591 $SIG{CHLD} =
592 $SIG{CHLD} =
593 for ( $waitedpid = 0;
594 ($paddr = accept(Client,Server)) $waitedpid;
595 $waitedpid = 0, close Client)
596 {
597 next if $waitedpid and not $paddr;
598 my($port,$iaddr) = sockaddr_in($paddr);
599 my $name = gethostbyaddr($iaddr,AF_INET);
600 logmsg
601 spawn sub {
602 $=1;
603 print
604 }
605 sub spawn {
606 my $coderef = shift;
607 unless (@_ == 0
608 my $pid;
609 if (!defined($pid = fork)) {
610 logmsg
611 open(STDIN,
612 This server takes the trouble to clone off a child version via ''fork()'' for each incoming request. That way it can handle many requests at once, which you might not always want. Even if you don't ''fork()'', the ''listen()'' will allow that many pending connections. Forking servers have to be particularly careful about cleaning up their dead children (called ``zombies'' in Unix parlance), because otherwise you'll quickly fill up your process table.
613
614
615 We suggest that you use the __-T__ flag to use taint
616 checking (see perlsec) even if we aren't running setuid or
617 setgid. This is always a good idea for servers and other
618 programs run on behalf of someone else (like
619 CGI scripts), because it lessens the chances
620 that people from the outside will be able to compromise your
621 system.
622
623
624 Let's look at another TCP client. This one
625 connects to the TCP ``time'' service on a
626 number of different machines and shows how far their clocks
627 differ from the system on which it's being run:
628
629
630 #!/usr/bin/perl -w
631 use strict;
632 use Socket;
633 my $SECS_of_70_YEARS = 2208988800;
634 sub ctime { scalar localtime(shift) }
635 my $iaddr = gethostbyname('localhost');
636 my $proto = getprotobyname('tcp');
637 my $port = getservbyname('time', 'tcp');
638 my $paddr = sockaddr_in(0, $iaddr);
639 my($host);
640 $ = 1;
641 printf
642 foreach $host (@ARGV) {
643 printf
644
645
646 __Unix-Domain TCP Clients and
647 Servers__
648
649
650 That's fine for Internet-domain clients and servers, but
651 what about local communications? While you can use the same
652 setup, sometimes you don't want to. Unix-domain sockets are
653 local to the current host, and are often used internally to
654 implement pipes. Unlike Internet domain sockets, Unix domain
655 sockets can show up in the file system with an ls(1)
656 listing.
657
658
659 % ls -l /dev/log
660 srw-rw-rw- 1 root 0 Oct 31 07:23 /dev/log
661 You can test for these with Perl's __-S__ file test:
662
663
664 unless ( -S '/dev/log' ) {
665 die
666 Here's a sample Unix-domain client:
667
668
669 #!/usr/bin/perl -w
670 use Socket;
671 use strict;
672 my ($rendezvous, $line);
673 $rendezvous = shift '/tmp/catsock';
674 socket(SOCK, PF_UNIX, SOCK_STREAM, 0) die
675 And here's a corresponding server. You don't have to worry about silly network terminators here because Unix domain sockets are guaranteed to be on the localhost, and thus everything works right.
676
677
678 #!/usr/bin/perl -Tw
679 use strict;
680 use Socket;
681 use Carp;
682 BEGIN { $ENV{PATH} = '/usr/ucb:/bin' }
683 sub spawn; # forward declaration
684 sub logmsg { print
685 my $NAME = '/tmp/catsock';
686 my $uaddr = sockaddr_un($NAME);
687 my $proto = getprotobyname('tcp');
688 socket(Server,PF_UNIX,SOCK_STREAM,0) die
689 logmsg
690 my $waitedpid;
691 sub REAPER {
692 $waitedpid = wait;
693 $SIG{CHLD} =
694 $SIG{CHLD} =
695 for ( $waitedpid = 0;
696 accept(Client,Server) $waitedpid;
697 $waitedpid = 0, close Client)
698 {
699 next if $waitedpid;
700 logmsg
701 sub spawn {
702 my $coderef = shift;
703 unless (@_ == 0
704 my $pid;
705 if (!defined($pid = fork)) {
706 logmsg
707 open(STDIN,
708 As you see, it's remarkably similar to the Internet domain TCP server, so much so, in fact, that we've omitted several duplicate functions--''spawn()'', ''logmsg()'', ''ctime()'', and ''REAPER ()''--which are exactly the same as in the other server.
709
710
711 So why would you ever want to use a Unix domain socket
712 instead of a simpler named pipe? Because a named pipe
713 doesn't give you sessions. You can't tell one process's data
714 from another's. With socket programming, you get a separate
715 session for each client: that's why ''accept()'' takes
716 two arguments.
717
718
719 For example, let's say that you have a long running database
720 server daemon that you want folks from the World Wide Web to
721 be able to access, but only if they go through a
722 CGI interface. You'd have a small, simple
723 CGI program that does whatever checks and
724 logging you feel like, and then acts as a Unix-domain client
725 and connects to your private server.
726 !!TCP Clients with IO::Socket
727
728
729 For those preferring a higher-level interface to socket
730 programming, the IO::Socket module provides an
731 object-oriented approach. IO::Socket is included as part of
732 the standard Perl distribution as of the 5.004 release. If
733 you're running an earlier version of Perl, just fetch
734 IO::Socket from CPAN , where you'll also find
735 modules providing easy interfaces to the following systems:
736 DNS , FTP , Ident (
737 RFC 931), NIS and NISPlus,
738 NNTP , Ping, POP3 ,
739 SMTP , SNMP , SSLeay, Telnet,
740 and Time--just to name a few.
741
742
743 __A Simple Client__
744
745
746 Here's a client that creates a TCP connection
747 to the ``daytime'' service at port 13 of the host name
748 ``localhost'' and prints out everything that the server
749 there cares to provide.
750
751
752 #!/usr/bin/perl -w
753 use IO::Socket;
754 $remote = IO::Socket::INET-
755 When you run this program, you should get something back that looks like this:
756
757
758 Wed May 14 08:40:46 MDT 1997
759 Here are what those parameters to the new constructor mean:
760
761
762 Proto
763
764
765 This is which protocol to use. In this case, the socket
766 handle returned will be connected to a TCP
767 socket, because we want a stream-oriented connection, that
768 is, one that acts pretty much like a plain old file. Not all
769 sockets are this of this type. For example, the
770 UDP protocol can be used to make a datagram
771 socket, used for message-passing.
772
773
774 !PeerAddr
775
776
777 This is the name or Internet address of the remote host the
778 server is running on. We could have specified a longer name
779 like , or an address like
780 . For demonstration
781 purposes, we've used the special hostname
782 , which should always mean the
783 current machine you're running on. The corresponding
784 Internet address for localhost is
785 , if you'd rather use
786 that.
787
788
789 !PeerPort
790
791
792 This is the service name or port number we'd like to connect
793 to. We could have gotten away with using just
794 on systems with a
795 well-configured system services file,[[
796 FOOTNOTE: The system services file is in
797 ''/etc/services'' under Unix] but just in case, we've
798 specified the port number (13) in parentheses. Using just
799 the number would also have worked, but constant numbers make
800 careful programmers nervous.
801
802
803 Notice how the return value from the new
804 constructor is used as a filehandle in the while
805 loop? That's what's called an indirect filehandle, a scalar
806 variable containing a filehandle. You can use it the same
807 way you would a normal filehandle. For example, you can read
808 one line from it this way:
809
810
811 $line =
812 all remaining lines from is this way:
813
814
815 @lines =
816 and send a line of data to it this way:
817
818
819 print $handle
820
821
822 __A Webget Client__
823
824
825 Here's a simple client that takes a remote host to fetch a
826 document from, and then a list of documents to get from that
827 host. This is a more interesting client than the previous
828 one because it first sends something to the server before
829 fetching the server's response.
830
831
832 #!/usr/bin/perl -w
833 use IO::Socket;
834 unless (@ARGV
835 The web server handing the ``http'' service, which is assumed to be at its standard port, number 80. If the web server you're trying to connect to is at a different port (like 1080 or 8080), you should specify as the named-parameter pair, !PeerPort =. The autoflush method is used on the socket because otherwise the system would buffer up the output we sent it. (If you're on a Mac, you'll also need to change every in your code that sends data over the network to be a instead.)
836
837
838 Connecting to the server is only the first part of the
839 process: once you have the connection, you have to use the
840 server's language. Each server on the network has its own
841 little command language that it expects as input. The string
842 that we send to the server starting with ``
843 GET '' is in HTTP syntax. In
844 this case, we simply request each specified document. Yes,
845 we really are making a new connection for each document,
846 even though it's the same host. That's the way you always
847 used to have to speak HTTP . Recent versions
848 of web browsers may request that the remote server leave the
849 connection open a little while, but the server doesn't have
850 to honor such a request.
851
852
853 Here's an example of running that program, which we'll call
854 ''webget'':
855
856
857 % webget www.perl.com /guanaco.html
858 HTTP/1.1 404 File Not Found
859 Date: Thu, 08 May 1997 18:02:32 GMT
860 Server: Apache/1.2b6
861 Connection: close
862 Content-type: text/html
863
864 Ok, so that's not very interesting, because it didn't find that particular document. But a long response wouldn't have fit on this page.
865
866
867 For a more fully-featured version of this program, you
868 should look to the ''lwp-request'' program included with
869 the LWP modules from CPAN
870 .
871
872
873 __Interactive Client with IO::Socket__
874
875
876 Well, that's all fine if you want to send one command and
877 get one answer, but what about setting up something fully
878 interactive, somewhat like the way ''telnet'' works? That
879 way you can type a line, get the answer, type a line, get
880 the answer, etc.
881
882
883 This client is more complicated than the two we've done so
884 far, but if you're on a system that supports the powerful
885 fork call, the solution isn't that rough. Once
886 you've made the connection to whatever service you'd like to
887 chat with, call fork to clone your process. Each of
888 these two identical process has a very simple job to do: the
889 parent copies everything from the socket to standard output,
890 while the child simultaneously copies everything from
891 standard input to the socket. To accomplish the same thing
892 using just one process would be ''much'' harder, because
893 it's easier to code two processes to do one thing than it is
894 to code one process to do two things. (This keep-it-simple
895 principle a cornerstones of the Unix philosophy, and good
896 software engineering as well, which is probably why it's
897 spread to other systems.)
898
899
900 Here's the code:
901
902
903 #!/usr/bin/perl -w
904 use strict;
905 use IO::Socket;
906 my ($host, $port, $kidpid, $handle, $line);
907 unless (@ARGV == 2) { die
908 # create a tcp connection to the specified host and port
909 $handle = IO::Socket::INET-
910 $handle-
911 # split the program into two processes, identical twins
912 die
913 # the if{} block runs only in the parent process
914 if ($kidpid) {
915 # copy the socket to standard output
916 while (defined ($line =
917 The kill function in the parent's if block is there to send a signal to our child process (current running in the else block) as soon as the remote server has closed its end of the connection.
918
919
920 If the remote server sends data a byte at time, and you need
921 that data immediately without waiting for a newline (which
922 might not happen), you may wish to replace the
923 while loop in the parent with the
924 following:
925
926
927 my $byte;
928 while (sysread($handle, $byte, 1) == 1) {
929 print STDOUT $byte;
930 }
931 Making a system call for each byte you want to read is not very efficient (to put it mildly) but is the simplest to explain and works reasonably well.
932 !!TCP Servers with IO::Socket
933
934
935 As always, setting up a server is little bit more involved
936 than running a client. The model is that the server creates
937 a special kind of socket that does nothing but listen on a
938 particular port for incoming connections. It does this by
939 calling the IO::Socket::INET- method with
940 slightly different arguments than the client
941 did.
942
943
944 Proto
945
946
947 This is which protocol to use. Like our clients, we'll still
948 specify here.
949
950
951 !LocalPort
952
953
954 We specify a local port in the !LocalPort argument,
955 which we didn't do for the client. This is service name or
956 port number for which you want to be the server. (Under
957 Unix, ports under 1024 are restricted to the superuser.) In
958 our sample, we'll use port 9000, but you can use any port
959 that's not currently in use on your system. If you try to
960 use one already in used, you'll get an ``Address already in
961 use'' message. Under Unix, the netstat -a command
962 will show which services current have servers.
963
964
965 Listen
966
967
968 The Listen parameter is set to the maximum number
969 of pending connections we can accept until we turn away
970 incoming clients. Think of it as a call-waiting queue for
971 your telephone. The low-level Socket module has a special
972 symbol for the system maximum, which is
973 SOMAXCONN .
974
975
976 Reuse
977
978
979 The Reuse parameter is needed so that we restart
980 our server manually without waiting a few minutes to allow
981 system buffers to clear out.
982
983
984 Once the generic server socket has been created using the
985 parameters listed above, the server then waits for a new
986 client to connect to it. The server blocks in the
987 accept method, which eventually an bidirectional
988 connection to the remote client. (Make sure to autoflush
989 this handle to circumvent buffering.)
990
991
992 To add to user-friendliness, our server prompts the user for
993 commands. Most servers don't do this. Because of the prompt
994 without a newline, you'll have to use the sysread
995 variant of the interactive client above.
996
997
998 This server accepts one of five different commands, sending
999 output back to the client. Note that unlike most network
1000 servers, this one only handles one incoming client at a
1001 time. Multithreaded servers are covered in Chapter 6 of the
1002 Camel.
1003
1004
1005 Here's the code. We'll
1006
1007
1008 #!/usr/bin/perl -w
1009 use IO::Socket;
1010 use Net::hostent; # for OO version of gethostbyaddr
1011 $PORT = 9000; # pick something not in use
1012 $server = IO::Socket::INET-
1013 die
1014 while ($client = $server-
1015 !!UDP: Message Passing
1016
1017
1018 Another kind of client-server setup is one that uses not
1019 connections, but messages. UDP communications
1020 involve much lower overhead but also provide less
1021 reliability, as there are no promises that messages will
1022 arrive at all, let alone in order and unmangled. Still,
1023 UDP offers some advantages over
1024 TCP , including being able to ``broadcast''
1025 or ``multicast'' to a whole bunch of destination hosts at
1026 once (usually on your local subnet). If you find yourself
1027 overly concerned about reliability and start building checks
1028 into your message system, then you probably should use just
1029 TCP to start with.
1030
1031
1032 Note that UDP datagrams are ''not'' a
1033 bytestream and should not be treated as such. This makes
1034 using I/O mechanisms with internal buffering like stdio
1035 (i.e. ''print()'' and friends) especially cumbersome. Use
1036 ''syswrite()'', or better ''send()'', like in the
1037 example below.
1038
1039
1040 Here's a UDP program similar to the sample
1041 Internet TCP client given earlier. However,
1042 instead of checking one host at a time, the
1043 UDP version will check many of them
1044 asynchronously by simulating a multicast and then using
1045 ''select()'' to do a timed-out wait for I/O. To do
1046 something similar with TCP , you'd have to
1047 use a different socket handle for each host.
1048
1049
1050 #!/usr/bin/perl -w
1051 use strict;
1052 use Socket;
1053 use Sys::Hostname;
1054 my ( $count, $hisiaddr, $hispaddr, $histime,
1055 $host, $iaddr, $paddr, $port, $proto,
1056 $rin, $rout, $rtime, $SECS_of_70_YEARS);
1057 $SECS_of_70_YEARS = 2208988800;
1058 $iaddr = gethostbyname(hostname());
1059 $proto = getprotobyname('udp');
1060 $port = getservbyname('time', 'udp');
1061 $paddr = sockaddr_in(0, $iaddr); # 0 means let kernel pick
1062 socket(SOCKET, PF_INET, SOCK_DGRAM, $proto) die
1063 $ = 1;
1064 printf
1065 $rin = '';
1066 vec($rin, fileno(SOCKET), 1) = 1;
1067 # timeout after 10.0 seconds
1068 while ($count
1069 Note that this example does not include any retries and may consequently fail to contact a reachable host. The most prominent reason for this is congestion of the queues on the sending host if the number of list of hosts to contact is sufficiently large.
1070 !!SysV IPC
1071
1072
1073 While System V IPC isn't so widely used as
1074 sockets, it still has some interesting uses. You can't,
1075 however, effectively use SysV IPC or Berkeley
1076 ''mmap()'' to have shared memory so as to share a
1077 variable amongst several processes. That's because Perl
1078 would reallocate your string when you weren't wanting it
1079 to.
1080
1081
1082 Here's a small example showing shared memory
1083 usage.
1084
1085
1086 use IPC::SysV qw(IPC_PRIVATE IPC_RMID S_IRWXU);
1087 $size = 2000;
1088 $id = shmget(IPC_PRIVATE, $size, S_IRWXU) die
1089 $message =
1090 # the buffer of shmread is zero-character end-padded.
1091 substr($buff, index($buff,
1092 print
1093 Here's an example of a semaphore:
1094
1095
1096 use IPC::SysV qw(IPC_CREAT);
1097 $IPC_KEY = 1234;
1098 $id = semget($IPC_KEY, 10, 0666 IPC_CREAT ) die
1099 Put this code in a separate file to be run in more than one process. Call the file ''take'':
1100
1101
1102 # create a semaphore
1103 $IPC_KEY = 1234;
1104 $id = semget($IPC_KEY, 0 , 0 );
1105 die if !defined($id);
1106 $semnum = 0;
1107 $semflag = 0;
1108 # 'take' semaphore
1109 # wait for semaphore to be zero
1110 $semop = 0;
1111 $opstring1 = pack(
1112 # Increment the semaphore count
1113 $semop = 1;
1114 $opstring2 = pack(
1115 semop($id,$opstring) die
1116 Put this code in a separate file to be run in more than one process. Call this file ''give'':
1117
1118
1119 # 'give' the semaphore
1120 # run this in the original process and you will see
1121 # that the second process continues
1122 $IPC_KEY = 1234;
1123 $id = semget($IPC_KEY, 0, 0);
1124 die if !defined($id);
1125 $semnum = 0;
1126 $semflag = 0;
1127 # Decrement the semaphore count
1128 $semop = -1;
1129 $opstring = pack(
1130 semop($id,$opstring) die
1131 The SysV IPC code above was written long ago, and it's definitely clunky looking. For a more modern look, see the IPC::SysV module which is included with Perl starting from Perl 5.005.
1132
1133
1134 A small example demonstrating SysV message
1135 queues:
1136
1137
1138 use IPC::SysV qw(IPC_PRIVATE IPC_RMID IPC_CREAT S_IRWXU);
1139 my $id = msgget(IPC_PRIVATE, IPC_CREAT S_IRWXU);
1140 my $sent =
1141 if (defined $id) {
1142 if (msgsnd($id, pack(
1143 !!NOTES
1144
1145
1146 Most of these routines quietly but politely return
1147 undef when they fail instead of causing your
1148 program to die right then and there due to an uncaught
1149 exception. (Actually, some of the new ''Socket''
1150 conversion functions ''croak()'' on bad arguments.) It is
1151 therefore essential to check return values from these
1152 functions. Always begin your socket programs this way for
1153 optimal success, and don't forget to add __-T__ taint
1154 checking flag to the #! line for servers:
1155
1156
1157 #!/usr/bin/perl -Tw
1158 use strict;
1159 use sigtrap;
1160 use Socket;
1161 !!BUGS
1162
1163
1164 All these routines create system-specific portability
1165 problems. As noted elsewhere, Perl is at the mercy of your C
1166 libraries for much of its system behaviour. It's probably
1167 safest to assume broken SysV semantics for signals and to
1168 stick with simple TCP and UDP
1169 socket operations; e.g., don't try to pass open file
1170 descriptors over a local UDP datagram socket
1171 if you want your code to stand a chance of being
1172 portable.
1173
1174
1175 As mentioned in the signals section, because few vendors
1176 provide C libraries that are safely re-entrant, the prudent
1177 programmer will do little else within a handler beyond
1178 setting a numeric variable that already exists; or, if
1179 locked into a slow (restarting) system call, using
1180 ''die()'' to raise an exception and longjmp(3)
1181 out. In fact, even these may in some cases cause a core
1182 dump. It's probably best to avoid signals except where they
1183 are absolutely inevitable. This will be addressed in a
1184 future release of Perl.
1185 !!AUTHOR
1186
1187
1188 Tom Christiansen, with occasional vestiges of Larry Wall's
1189 original version and suggestions from the Perl
1190 Porters.
1191 !!SEE ALSO
1192
1193
1194 There's a lot more to networking than this, but this should
1195 get you started.
1196
1197
1198 For intrepid programmers, the indispensable textbook is
1199 ''Unix Network Programming'' by W. Richard Stevens
1200 (published by Addison-Wesley). Note that most books on
1201 networking address networking from the perspective of a C
1202 programmer; translation to Perl is left as an exercise for
1203 the reader.
1204
1205
1206 The ''IO::Socket''(3) manpage describes the object
1207 library, and the ''Socket''(3) manpage describes the
1208 low-level interface to sockets. Besides the obvious
1209 functions in perlfunc, you should also check out the
1210 ''modules'' file at your nearest CPAN
1211 site. (See perlmodlib or best yet, the ''Perl
1212 FAQ'' for a description of what
1213 CPAN is and where to get it.)
1214
1215
1216 Section 5 of the ''modules'' file is devoted to
1217 ``Networking, Device Control (modems), and Interprocess
1218 Communication'', and contains numerous unbundled modules
1219 numerous networking modules, Chat and Expect operations,
1220 CGI programming, DCE ,
1221 FTP , IPC ,
1222 NNTP , Proxy, Ptty, RPC ,
1223 SNMP , SMTP , Telnet, Threads,
1224 and !ToolTalk--just to name a few.
1225 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.