Commit | Line | Data |
---|---|---|
68dc0745 | 1 | =head1 NAME |
2 | ||
c195e131 | 3 | perlfaq8 - System Interaction ($Revision: 10183 $) |
68dc0745 | 4 | |
5 | =head1 DESCRIPTION | |
6 | ||
7 | This section of the Perl FAQ covers questions involving operating | |
a6dd486b | 8 | system interaction. Topics include interprocess communication (IPC), |
68dc0745 | 9 | control over the user-interface (keyboard, screen and pointing |
10 | devices), and most anything else not related to data manipulation. | |
11 | ||
12 | Read the FAQs and documentation specific to the port of perl to your | |
46fc3d4c | 13 | operating system (eg, L<perlvms>, L<perlplan9>, ...). These should |
68dc0745 | 14 | contain more detailed information on the vagaries of your perl. |
15 | ||
16 | =head2 How do I find out which operating system I'm running under? | |
17 | ||
d92eb7b0 GS |
18 | The $^O variable ($OSNAME if you use English) contains an indication of |
19 | the name of the operating system (not its release number) that your perl | |
20 | binary was built for. | |
68dc0745 | 21 | |
22 | =head2 How come exec() doesn't return? | |
23 | ||
24 | Because that's what it does: it replaces your currently running | |
25 | program with a different one. If you want to keep going (as is | |
26 | probably the case if you're asking this question) use system() | |
27 | instead. | |
28 | ||
29 | =head2 How do I do fancy stuff with the keyboard/screen/mouse? | |
30 | ||
31 | How you access/control keyboards, screens, and pointing devices | |
32 | ("mice") is system-dependent. Try the following modules: | |
33 | ||
34 | =over 4 | |
35 | ||
36 | =item Keyboard | |
37 | ||
58103a2e RGS |
38 | Term::Cap Standard perl distribution |
39 | Term::ReadKey CPAN | |
40 | Term::ReadLine::Gnu CPAN | |
41 | Term::ReadLine::Perl CPAN | |
42 | Term::Screen CPAN | |
68dc0745 | 43 | |
44 | =item Screen | |
45 | ||
58103a2e RGS |
46 | Term::Cap Standard perl distribution |
47 | Curses CPAN | |
48 | Term::ANSIColor CPAN | |
68dc0745 | 49 | |
50 | =item Mouse | |
51 | ||
58103a2e | 52 | Tk CPAN |
68dc0745 | 53 | |
54 | =back | |
55 | ||
58103a2e RGS |
56 | Some of these specific cases are shown as examples in other answers |
57 | in this section of the perlfaq. | |
c8db1d39 TC |
58 | |
59 | =head2 How do I print something out in color? | |
60 | ||
61 | In general, you don't, because you don't know whether | |
62 | the recipient has a color-aware display device. If you | |
63 | know that they have an ANSI terminal that understands | |
64 | color, you can use the Term::ANSIColor module from CPAN: | |
65 | ||
ac9dac7f RGS |
66 | use Term::ANSIColor; |
67 | print color("red"), "Stop!\n", color("reset"); | |
68 | print color("green"), "Go!\n", color("reset"); | |
c8db1d39 TC |
69 | |
70 | Or like this: | |
71 | ||
ac9dac7f RGS |
72 | use Term::ANSIColor qw(:constants); |
73 | print RED, "Stop!\n", RESET; | |
74 | print GREEN, "Go!\n", RESET; | |
c8db1d39 TC |
75 | |
76 | =head2 How do I read just one key without waiting for a return key? | |
77 | ||
78 | Controlling input buffering is a remarkably system-dependent matter. | |
d92eb7b0 | 79 | On many systems, you can just use the B<stty> command as shown in |
c8db1d39 | 80 | L<perlfunc/getc>, but as you see, that's already getting you into |
197aec24 | 81 | portability snags. |
c8db1d39 | 82 | |
ac9dac7f RGS |
83 | open(TTY, "+</dev/tty") or die "no tty: $!"; |
84 | system "stty cbreak </dev/tty >/dev/tty 2>&1"; | |
85 | $key = getc(TTY); # perhaps this works | |
86 | # OR ELSE | |
87 | sysread(TTY, $key, 1); # probably this does | |
88 | system "stty -cbreak </dev/tty >/dev/tty 2>&1"; | |
c8db1d39 TC |
89 | |
90 | The Term::ReadKey module from CPAN offers an easy-to-use interface that | |
91 | should be more efficient than shelling out to B<stty> for each key. | |
92 | It even includes limited support for Windows. | |
93 | ||
ac9dac7f RGS |
94 | use Term::ReadKey; |
95 | ReadMode('cbreak'); | |
96 | $key = ReadKey(0); | |
97 | ReadMode('normal'); | |
c8db1d39 | 98 | |
a6dd486b JB |
99 | However, using the code requires that you have a working C compiler |
100 | and can use it to build and install a CPAN module. Here's a solution | |
101 | using the standard POSIX module, which is already on your systems | |
102 | (assuming your system supports POSIX). | |
c8db1d39 | 103 | |
ac9dac7f RGS |
104 | use HotKey; |
105 | $key = readkey(); | |
c8db1d39 TC |
106 | |
107 | And here's the HotKey module, which hides the somewhat mystifying calls | |
108 | to manipulate the POSIX termios structures. | |
109 | ||
ac9dac7f RGS |
110 | # HotKey.pm |
111 | package HotKey; | |
c8db1d39 | 112 | |
ac9dac7f RGS |
113 | @ISA = qw(Exporter); |
114 | @EXPORT = qw(cbreak cooked readkey); | |
c8db1d39 | 115 | |
ac9dac7f RGS |
116 | use strict; |
117 | use POSIX qw(:termios_h); | |
118 | my ($term, $oterm, $echo, $noecho, $fd_stdin); | |
c8db1d39 | 119 | |
ac9dac7f RGS |
120 | $fd_stdin = fileno(STDIN); |
121 | $term = POSIX::Termios->new(); | |
122 | $term->getattr($fd_stdin); | |
123 | $oterm = $term->getlflag(); | |
c8db1d39 | 124 | |
ac9dac7f RGS |
125 | $echo = ECHO | ECHOK | ICANON; |
126 | $noecho = $oterm & ~$echo; | |
c8db1d39 | 127 | |
ac9dac7f RGS |
128 | sub cbreak { |
129 | $term->setlflag($noecho); # ok, so i don't want echo either | |
130 | $term->setcc(VTIME, 1); | |
131 | $term->setattr($fd_stdin, TCSANOW); | |
132 | } | |
c8db1d39 | 133 | |
ac9dac7f RGS |
134 | sub cooked { |
135 | $term->setlflag($oterm); | |
136 | $term->setcc(VTIME, 0); | |
137 | $term->setattr($fd_stdin, TCSANOW); | |
138 | } | |
c8db1d39 | 139 | |
ac9dac7f RGS |
140 | sub readkey { |
141 | my $key = ''; | |
142 | cbreak(); | |
143 | sysread(STDIN, $key, 1); | |
144 | cooked(); | |
145 | return $key; | |
146 | } | |
c8db1d39 | 147 | |
ac9dac7f | 148 | END { cooked() } |
c8db1d39 | 149 | |
ac9dac7f | 150 | 1; |
c8db1d39 TC |
151 | |
152 | =head2 How do I check whether input is ready on the keyboard? | |
153 | ||
154 | The easiest way to do this is to read a key in nonblocking mode with the | |
155 | Term::ReadKey module from CPAN, passing it an argument of -1 to indicate | |
156 | not to block: | |
157 | ||
ac9dac7f | 158 | use Term::ReadKey; |
c8db1d39 | 159 | |
ac9dac7f | 160 | ReadMode('cbreak'); |
c8db1d39 | 161 | |
ac9dac7f RGS |
162 | if (defined ($char = ReadKey(-1)) ) { |
163 | # input was waiting and it was $char | |
164 | } else { | |
165 | # no input was waiting | |
166 | } | |
c8db1d39 | 167 | |
ac9dac7f | 168 | ReadMode('normal'); # restore normal tty settings |
c8db1d39 TC |
169 | |
170 | =head2 How do I clear the screen? | |
171 | ||
d92eb7b0 | 172 | If you only have do so infrequently, use C<system>: |
c8db1d39 | 173 | |
ac9dac7f | 174 | system("clear"); |
c8db1d39 TC |
175 | |
176 | If you have to do this a lot, save the clear string | |
177 | so you can print it 100 times without calling a program | |
178 | 100 times: | |
179 | ||
ac9dac7f RGS |
180 | $clear_string = `clear`; |
181 | print $clear_string; | |
c8db1d39 TC |
182 | |
183 | If you're planning on doing other screen manipulations, like cursor | |
184 | positions, etc, you might wish to use Term::Cap module: | |
185 | ||
ac9dac7f RGS |
186 | use Term::Cap; |
187 | $terminal = Term::Cap->Tgetent( {OSPEED => 9600} ); | |
188 | $clear_string = $terminal->Tputs('cl'); | |
c8db1d39 TC |
189 | |
190 | =head2 How do I get the screen size? | |
191 | ||
197aec24 | 192 | If you have Term::ReadKey module installed from CPAN, |
c8db1d39 TC |
193 | you can use it to fetch the width and height in characters |
194 | and in pixels: | |
195 | ||
ac9dac7f RGS |
196 | use Term::ReadKey; |
197 | ($wchar, $hchar, $wpixels, $hpixels) = GetTerminalSize(); | |
c8db1d39 | 198 | |
197aec24 | 199 | This is more portable than the raw C<ioctl>, but not as |
c8db1d39 TC |
200 | illustrative: |
201 | ||
ac9dac7f RGS |
202 | require 'sys/ioctl.ph'; |
203 | die "no TIOCGWINSZ " unless defined &TIOCGWINSZ; | |
204 | open(TTY, "+</dev/tty") or die "No tty: $!"; | |
205 | unless (ioctl(TTY, &TIOCGWINSZ, $winsize='')) { | |
206 | die sprintf "$0: ioctl TIOCGWINSZ (%08x: $!)\n", &TIOCGWINSZ; | |
207 | } | |
208 | ($row, $col, $xpixel, $ypixel) = unpack('S4', $winsize); | |
209 | print "(row,col) = ($row,$col)"; | |
210 | print " (xpixel,ypixel) = ($xpixel,$ypixel)" if $xpixel || $ypixel; | |
211 | print "\n"; | |
c8db1d39 | 212 | |
68dc0745 | 213 | =head2 How do I ask the user for a password? |
214 | ||
215 | (This question has nothing to do with the web. See a different | |
216 | FAQ for that.) | |
217 | ||
a6dd486b JB |
218 | There's an example of this in L<perlfunc/crypt>). First, you put the |
219 | terminal into "no echo" mode, then just read the password normally. | |
220 | You may do this with an old-style ioctl() function, POSIX terminal | |
b73a15ae | 221 | control (see L<POSIX> or its documentation the Camel Book), or a call |
68dc0745 | 222 | to the B<stty> program, with varying degrees of portability. |
223 | ||
224 | You can also do this for most systems using the Term::ReadKey module | |
225 | from CPAN, which is easier to use and in theory more portable. | |
226 | ||
ac9dac7f | 227 | use Term::ReadKey; |
c8db1d39 | 228 | |
ac9dac7f RGS |
229 | ReadMode('noecho'); |
230 | $password = ReadLine(0); | |
c8db1d39 | 231 | |
68dc0745 | 232 | =head2 How do I read and write the serial port? |
233 | ||
234 | This depends on which operating system your program is running on. In | |
235 | the case of Unix, the serial ports will be accessible through files in | |
a6dd486b | 236 | /dev; on other systems, device names will doubtless differ. |
68dc0745 | 237 | Several problem areas common to all device interaction are the |
a6dd486b | 238 | following: |
68dc0745 | 239 | |
240 | =over 4 | |
241 | ||
242 | =item lockfiles | |
243 | ||
244 | Your system may use lockfiles to control multiple access. Make sure | |
a6dd486b | 245 | you follow the correct protocol. Unpredictable behavior can result |
68dc0745 | 246 | from multiple processes reading from one device. |
247 | ||
248 | =item open mode | |
249 | ||
250 | If you expect to use both read and write operations on the device, | |
251 | you'll have to open it for update (see L<perlfunc/"open"> for | |
252 | details). You may wish to open it without running the risk of | |
253 | blocking by using sysopen() and C<O_RDWR|O_NDELAY|O_NOCTTY> from the | |
254 | Fcntl module (part of the standard perl distribution). See | |
255 | L<perlfunc/"sysopen"> for more on this approach. | |
256 | ||
257 | =item end of line | |
258 | ||
259 | Some devices will be expecting a "\r" at the end of each line rather | |
260 | than a "\n". In some ports of perl, "\r" and "\n" are different from | |
261 | their usual (Unix) ASCII values of "\012" and "\015". You may have to | |
262 | give the numeric values you want directly, using octal ("\015"), hex | |
263 | ("0x0D"), or as a control-character specification ("\cM"). | |
264 | ||
ac9dac7f RGS |
265 | print DEV "atv1\012"; # wrong, for some devices |
266 | print DEV "atv1\015"; # right, for some devices | |
68dc0745 | 267 | |
a6dd486b | 268 | Even though with normal text files a "\n" will do the trick, there is |
68dc0745 | 269 | still no unified scheme for terminating a line that is portable |
46fc3d4c | 270 | between Unix, DOS/Win, and Macintosh, except to terminate I<ALL> line |
68dc0745 | 271 | ends with "\015\012", and strip what you don't need from the output. |
272 | This applies especially to socket I/O and autoflushing, discussed | |
273 | next. | |
274 | ||
275 | =item flushing output | |
276 | ||
277 | If you expect characters to get to your device when you print() them, | |
c8db1d39 | 278 | you'll want to autoflush that filehandle. You can use select() |
197aec24 | 279 | and the C<$|> variable to control autoflushing (see L<perlvar/$E<verbar>> |
b432a672 AL |
280 | and L<perlfunc/select>, or L<perlfaq5>, "How do I flush/unbuffer an |
281 | output filehandle? Why must I do this?"): | |
68dc0745 | 282 | |
ac9dac7f RGS |
283 | $oldh = select(DEV); |
284 | $| = 1; | |
285 | select($oldh); | |
68dc0745 | 286 | |
287 | You'll also see code that does this without a temporary variable, as in | |
288 | ||
ac9dac7f | 289 | select((select(DEV), $| = 1)[0]); |
68dc0745 | 290 | |
c8db1d39 TC |
291 | Or if you don't mind pulling in a few thousand lines |
292 | of code just because you're afraid of a little $| variable: | |
293 | ||
ac9dac7f RGS |
294 | use IO::Handle; |
295 | DEV->autoflush(1); | |
c8db1d39 | 296 | |
68dc0745 | 297 | As mentioned in the previous item, this still doesn't work when using |
8305e449 | 298 | socket I/O between Unix and Macintosh. You'll need to hard code your |
68dc0745 | 299 | line terminators, in that case. |
300 | ||
301 | =item non-blocking input | |
302 | ||
303 | If you are doing a blocking read() or sysread(), you'll have to | |
304 | arrange for an alarm handler to provide a timeout (see | |
305 | L<perlfunc/alarm>). If you have a non-blocking open, you'll likely | |
306 | have a non-blocking read, which means you may have to use a 4-arg | |
307 | select() to determine whether I/O is ready on that device (see | |
308 | L<perlfunc/"select">. | |
309 | ||
310 | =back | |
311 | ||
c8db1d39 | 312 | While trying to read from his caller-id box, the notorious Jamie Zawinski |
ac9dac7f | 313 | C<< <jwz@netscape.com> >>, after much gnashing of teeth and fighting with sysread, |
c8db1d39 TC |
314 | sysopen, POSIX's tcgetattr business, and various other functions that |
315 | go bump in the night, finally came up with this: | |
316 | ||
ac9dac7f RGS |
317 | sub open_modem { |
318 | use IPC::Open2; | |
319 | my $stty = `/bin/stty -g`; | |
320 | open2( \*MODEM_IN, \*MODEM_OUT, "cu -l$modem_device -s2400 2>&1"); | |
321 | # starting cu hoses /dev/tty's stty settings, even when it has | |
322 | # been opened on a pipe... | |
323 | system("/bin/stty $stty"); | |
324 | $_ = <MODEM_IN>; | |
325 | chomp; | |
326 | if ( !m/^Connected/ ) { | |
327 | print STDERR "$0: cu printed `$_' instead of `Connected'\n"; | |
328 | } | |
c8db1d39 | 329 | } |
c8db1d39 | 330 | |
68dc0745 | 331 | =head2 How do I decode encrypted password files? |
332 | ||
333 | You spend lots and lots of money on dedicated hardware, but this is | |
334 | bound to get you talked about. | |
335 | ||
a6dd486b | 336 | Seriously, you can't if they are Unix password files--the Unix |
ac003c96 RGS |
337 | password system employs one-way encryption. It's more like hashing |
338 | than encryption. The best you can do is check whether something else | |
339 | hashes to the same string. You can't turn a hash back into the | |
340 | original string. Programs like Crack can forcibly (and intelligently) | |
341 | try to guess passwords, but don't (can't) guarantee quick success. | |
68dc0745 | 342 | |
343 | If you're worried about users selecting bad passwords, you should | |
344 | proactively check when they try to change their password (by modifying | |
345 | passwd(1), for example). | |
346 | ||
347 | =head2 How do I start a process in the background? | |
348 | ||
49d635f9 RGS |
349 | Several modules can start other processes that do not block |
350 | your Perl program. You can use IPC::Open3, Parallel::Jobs, | |
351 | IPC::Run, and some of the POE modules. See CPAN for more | |
352 | details. | |
353 | ||
354 | You could also use | |
68dc0745 | 355 | |
ac9dac7f | 356 | system("cmd &") |
68dc0745 | 357 | |
358 | or you could use fork as documented in L<perlfunc/"fork">, with | |
359 | further examples in L<perlipc>. Some things to be aware of, if you're | |
360 | on a Unix-like system: | |
361 | ||
362 | =over 4 | |
363 | ||
c8db1d39 | 364 | =item STDIN, STDOUT, and STDERR are shared |
68dc0745 | 365 | |
366 | Both the main process and the backgrounded one (the "child" process) | |
367 | share the same STDIN, STDOUT and STDERR filehandles. If both try to | |
368 | access them at once, strange things can happen. You may want to close | |
369 | or reopen these for the child. You can get around this with | |
370 | C<open>ing a pipe (see L<perlfunc/"open">) but on some systems this | |
371 | means that the child process cannot outlive the parent. | |
372 | ||
373 | =item Signals | |
374 | ||
375 | You'll have to catch the SIGCHLD signal, and possibly SIGPIPE too. | |
376 | SIGCHLD is sent when the backgrounded process finishes. SIGPIPE is | |
377 | sent when you write to a filehandle whose child process has closed (an | |
378 | untrapped SIGPIPE can cause your program to silently die). This is | |
379 | not an issue with C<system("cmd&")>. | |
380 | ||
381 | =item Zombies | |
382 | ||
49d635f9 | 383 | You have to be prepared to "reap" the child process when it finishes. |
68dc0745 | 384 | |
ac9dac7f | 385 | $SIG{CHLD} = sub { wait }; |
197aec24 | 386 | |
ac9dac7f | 387 | $SIG{CHLD} = 'IGNORE'; |
197aec24 RGS |
388 | |
389 | You can also use a double fork. You immediately wait() for your | |
390 | first child, and the init daemon will wait() for your grandchild once | |
49d635f9 RGS |
391 | it exits. |
392 | ||
393 | unless ($pid = fork) { | |
ac9dac7f RGS |
394 | unless (fork) { |
395 | exec "what you really wanna do"; | |
396 | die "exec failed!"; | |
397 | } | |
398 | exit 0; | |
399 | } | |
400 | waitpid($pid, 0); | |
68dc0745 | 401 | |
402 | See L<perlipc/"Signals"> for other examples of code to do this. | |
403 | Zombies are not an issue with C<system("prog &")>. | |
404 | ||
405 | =back | |
406 | ||
407 | =head2 How do I trap control characters/signals? | |
408 | ||
c8db1d39 TC |
409 | You don't actually "trap" a control character. Instead, that character |
410 | generates a signal which is sent to your terminal's currently | |
411 | foregrounded process group, which you then trap in your process. | |
b73a15ae | 412 | Signals are documented in L<perlipc/"Signals"> and the |
b432a672 | 413 | section on "Signals" in the Camel. |
68dc0745 | 414 | |
6670e5e7 | 415 | You can set the values of the %SIG hash to be the functions you want |
c98c5709 RGS |
416 | to handle the signal. After perl catches the signal, it looks in %SIG |
417 | for a key with the same name as the signal, then calls the subroutine | |
418 | value for that key. | |
419 | ||
420 | # as an anonymous subroutine | |
6670e5e7 | 421 | |
c98c5709 | 422 | $SIG{INT} = sub { syswrite(STDERR, "ouch\n", 5 ) }; |
6670e5e7 | 423 | |
c98c5709 | 424 | # or a reference to a function |
6670e5e7 | 425 | |
c98c5709 | 426 | $SIG{INT} = \&ouch; |
6670e5e7 | 427 | |
c98c5709 | 428 | # or the name of the function as a string |
6670e5e7 RGS |
429 | |
430 | $SIG{INT} = "ouch"; | |
c98c5709 RGS |
431 | |
432 | Perl versions before 5.8 had in its C source code signal handlers which | |
433 | would catch the signal and possibly run a Perl function that you had set | |
434 | in %SIG. This violated the rules of signal handling at that level | |
435 | causing perl to dump core. Since version 5.8.0, perl looks at %SIG | |
436 | *after* the signal has been caught, rather than while it is being caught. | |
437 | Previous versions of this answer were incorrect. | |
68dc0745 | 438 | |
68dc0745 | 439 | =head2 How do I modify the shadow password file on a Unix system? |
440 | ||
a6dd486b | 441 | If perl was installed correctly and your shadow library was written |
c8db1d39 TC |
442 | properly, the getpw*() functions described in L<perlfunc> should in |
443 | theory provide (read-only) access to entries in the shadow password | |
444 | file. To change the file, make a new shadow password file (the format | |
197aec24 RGS |
445 | varies from system to system--see L<passwd> for specifics) and use |
446 | pwd_mkdb(8) to install it (see L<pwd_mkdb> for more details). | |
68dc0745 | 447 | |
448 | =head2 How do I set the time and date? | |
449 | ||
450 | Assuming you're running under sufficient permissions, you should be | |
451 | able to set the system-wide date and time by running the date(1) | |
452 | program. (There is no way to set the time and date on a per-process | |
453 | basis.) This mechanism will work for Unix, MS-DOS, Windows, and NT; | |
454 | the VMS equivalent is C<set time>. | |
455 | ||
8305e449 | 456 | However, if all you want to do is change your time zone, you can |
68dc0745 | 457 | probably get away with setting an environment variable: |
458 | ||
ac9dac7f RGS |
459 | $ENV{TZ} = "MST7MDT"; # unixish |
460 | $ENV{'SYS$TIMEZONE_DIFFERENTIAL'}="-5" # vms | |
461 | system "trn comp.lang.perl.misc"; | |
68dc0745 | 462 | |
463 | =head2 How can I sleep() or alarm() for under a second? | |
c195e131 | 464 | X<Time::HiRes> X<BSD::Itimer> X<sleep> X<select> |
68dc0745 | 465 | |
c195e131 RGS |
466 | If you want finer granularity than the 1 second that the C<sleep()> |
467 | function provides, the easiest way is to use the C<select()> function as | |
468 | documented in L<perlfunc/"select">. Try the C<Time::HiRes> and | |
469 | the C<BSD::Itimer> modules (available from CPAN, and starting from | |
470 | Perl 5.8 C<Time::HiRes> is part of the standard distribution). | |
68dc0745 | 471 | |
472 | =head2 How can I measure time under a second? | |
c195e131 | 473 | X<Time::HiRes> X<BSD::Itimer> X<sleep> X<select> |
68dc0745 | 474 | |
c195e131 | 475 | (contributed by brian d foy) |
68dc0745 | 476 | |
c195e131 RGS |
477 | The C<Time::HiRes> module (part of the standard distribution as of |
478 | Perl 5.8) measures time with the C<gettimeofday()> system call, which | |
479 | returns the time in microseconds since the epoch. If you can't install | |
480 | C<Time::HiRes> for older Perls and you are on a Unixish system, you | |
481 | may be able to call C<gettimeofday(2)> directly. See | |
482 | L<perlfunc/syscall>. | |
68dc0745 | 483 | |
484 | =head2 How can I do an atexit() or setjmp()/longjmp()? (Exception handling) | |
485 | ||
486 | Release 5 of Perl added the END block, which can be used to simulate | |
487 | atexit(). Each package's END block is called when the program or | |
197aec24 | 488 | thread ends (see L<perlmod> manpage for more details). |
c8db1d39 TC |
489 | |
490 | For example, you can use this to make sure your filter program | |
491 | managed to finish its output without filling up the disk: | |
492 | ||
ac9dac7f RGS |
493 | END { |
494 | close(STDOUT) || die "stdout close failed: $!"; | |
495 | } | |
c8db1d39 | 496 | |
a6dd486b JB |
497 | The END block isn't called when untrapped signals kill the program, |
498 | though, so if you use END blocks you should also use | |
68dc0745 | 499 | |
500 | use sigtrap qw(die normal-signals); | |
501 | ||
502 | Perl's exception-handling mechanism is its eval() operator. You can | |
503 | use eval() as setjmp and die() as longjmp. For details of this, see | |
46fc3d4c | 504 | the section on signals, especially the time-out handler for a blocking |
b432a672 | 505 | flock() in L<perlipc/"Signals"> or the section on "Signals" in |
b73a15ae | 506 | the Camel Book. |
68dc0745 | 507 | |
508 | If exception handling is all you're interested in, try the | |
509 | exceptions.pl library (part of the standard perl distribution). | |
510 | ||
511 | If you want the atexit() syntax (and an rmexit() as well), try the | |
512 | AtExit module available from CPAN. | |
513 | ||
a6dd486b | 514 | =head2 Why doesn't my sockets program work under System V (Solaris)? What does the error message "Protocol not supported" mean? |
68dc0745 | 515 | |
516 | Some Sys-V based systems, notably Solaris 2.X, redefined some of the | |
517 | standard socket constants. Since these were constant across all | |
518 | architectures, they were often hardwired into perl code. The proper | |
519 | way to deal with this is to "use Socket" to get the correct values. | |
520 | ||
521 | Note that even though SunOS and Solaris are binary compatible, these | |
522 | values are different. Go figure. | |
523 | ||
524 | =head2 How can I call my system's unique C functions from Perl? | |
525 | ||
a6dd486b | 526 | In most cases, you write an external module to do it--see the answer |
68dc0745 | 527 | to "Where can I learn about linking C with Perl? [h2xs, xsubpp]". |
528 | However, if the function is a system call, and your system supports | |
529 | syscall(), you can use the syscall function (documented in | |
530 | L<perlfunc>). | |
531 | ||
532 | Remember to check the modules that came with your distribution, and | |
ac9dac7f | 533 | CPAN as well--someone may already have written a module to do it. On |
197aec24 RGS |
534 | Windows, try Win32::API. On Macs, try Mac::Carbon. If no module |
535 | has an interface to the C function, you can inline a bit of C in your | |
536 | Perl source with Inline::C. | |
68dc0745 | 537 | |
538 | =head2 Where do I get the include files to do ioctl() or syscall()? | |
539 | ||
540 | Historically, these would be generated by the h2ph tool, part of the | |
541 | standard perl distribution. This program converts cpp(1) directives | |
542 | in C header files to files containing subroutine definitions, like | |
543 | &SYS_getitimer, which you can use as arguments to your functions. | |
544 | It doesn't work perfectly, but it usually gets most of the job done. | |
545 | Simple files like F<errno.h>, F<syscall.h>, and F<socket.h> were fine, | |
546 | but the hard ones like F<ioctl.h> nearly always need to hand-edited. | |
547 | Here's how to install the *.ph files: | |
548 | ||
ac9dac7f RGS |
549 | 1. become super-user |
550 | 2. cd /usr/include | |
551 | 3. h2ph *.h */*.h | |
68dc0745 | 552 | |
553 | If your system supports dynamic loading, for reasons of portability and | |
554 | sanity you probably ought to use h2xs (also part of the standard perl | |
555 | distribution). This tool converts C header files to Perl extensions. | |
556 | See L<perlxstut> for how to get started with h2xs. | |
557 | ||
558 | If your system doesn't support dynamic loading, you still probably | |
559 | ought to use h2xs. See L<perlxstut> and L<ExtUtils::MakeMaker> for | |
560 | more information (in brief, just use B<make perl> instead of a plain | |
561 | B<make> to rebuild perl with a new static extension). | |
562 | ||
563 | =head2 Why do setuid perl scripts complain about kernel problems? | |
564 | ||
565 | Some operating systems have bugs in the kernel that make setuid | |
566 | scripts inherently insecure. Perl gives you a number of options | |
567 | (described in L<perlsec>) to work around such systems. | |
568 | ||
569 | =head2 How can I open a pipe both to and from a command? | |
570 | ||
571 | The IPC::Open2 module (part of the standard perl distribution) is an | |
c8db1d39 TC |
572 | easy-to-use approach that internally uses pipe(), fork(), and exec() to do |
573 | the job. Make sure you read the deadlock warnings in its documentation, | |
197aec24 RGS |
574 | though (see L<IPC::Open2>). See |
575 | L<perlipc/"Bidirectional Communication with Another Process"> and | |
13a2d996 | 576 | L<perlipc/"Bidirectional Communication with Yourself"> |
c8db1d39 TC |
577 | |
578 | You may also use the IPC::Open3 module (part of the standard perl | |
579 | distribution), but be warned that it has a different order of | |
580 | arguments from IPC::Open2 (see L<IPC::Open3>). | |
68dc0745 | 581 | |
3fe9a6f1 | 582 | =head2 Why can't I get the output of a command with system()? |
583 | ||
46fc3d4c | 584 | You're confusing the purpose of system() and backticks (``). system() |
585 | runs a command and returns exit status information (as a 16 bit value: | |
c8db1d39 | 586 | the low 7 bits are the signal the process died from, if any, and |
46fc3d4c | 587 | the high 8 bits are the actual exit value). Backticks (``) run a |
3fe9a6f1 | 588 | command and return what it sent to STDOUT. |
589 | ||
ac9dac7f RGS |
590 | $exit_status = system("mail-users"); |
591 | $output_string = `ls`; | |
3fe9a6f1 | 592 | |
68dc0745 | 593 | =head2 How can I capture STDERR from an external command? |
594 | ||
595 | There are three basic ways of running external commands: | |
596 | ||
ac9dac7f RGS |
597 | system $cmd; # using system() |
598 | $output = `$cmd`; # using backticks (``) | |
599 | open (PIPE, "cmd |"); # using open() | |
68dc0745 | 600 | |
601 | With system(), both STDOUT and STDERR will go the same place as the | |
a6dd486b | 602 | script's STDOUT and STDERR, unless the system() command redirects them. |
68dc0745 | 603 | Backticks and open() read B<only> the STDOUT of your command. |
604 | ||
49d635f9 RGS |
605 | You can also use the open3() function from IPC::Open3. Benjamin |
606 | Goldberg provides some sample code: | |
607 | ||
608 | To capture a program's STDOUT, but discard its STDERR: | |
609 | ||
ac9dac7f RGS |
610 | use IPC::Open3; |
611 | use File::Spec; | |
612 | use Symbol qw(gensym); | |
613 | open(NULL, ">", File::Spec->devnull); | |
614 | my $pid = open3(gensym, \*PH, ">&NULL", "cmd"); | |
615 | while( <PH> ) { } | |
616 | waitpid($pid, 0); | |
49d635f9 RGS |
617 | |
618 | To capture a program's STDERR, but discard its STDOUT: | |
619 | ||
ac9dac7f RGS |
620 | use IPC::Open3; |
621 | use File::Spec; | |
622 | use Symbol qw(gensym); | |
623 | open(NULL, ">", File::Spec->devnull); | |
624 | my $pid = open3(gensym, ">&NULL", \*PH, "cmd"); | |
625 | while( <PH> ) { } | |
626 | waitpid($pid, 0); | |
49d635f9 RGS |
627 | |
628 | To capture a program's STDERR, and let its STDOUT go to our own STDERR: | |
629 | ||
ac9dac7f RGS |
630 | use IPC::Open3; |
631 | use Symbol qw(gensym); | |
632 | my $pid = open3(gensym, ">&STDERR", \*PH, "cmd"); | |
633 | while( <PH> ) { } | |
634 | waitpid($pid, 0); | |
49d635f9 RGS |
635 | |
636 | To read both a command's STDOUT and its STDERR separately, you can | |
637 | redirect them to temp files, let the command run, then read the temp | |
638 | files: | |
639 | ||
ac9dac7f RGS |
640 | use IPC::Open3; |
641 | use Symbol qw(gensym); | |
642 | use IO::File; | |
643 | local *CATCHOUT = IO::File->new_tmpfile; | |
644 | local *CATCHERR = IO::File->new_tmpfile; | |
645 | my $pid = open3(gensym, ">&CATCHOUT", ">&CATCHERR", "cmd"); | |
646 | waitpid($pid, 0); | |
647 | seek $_, 0, 0 for \*CATCHOUT, \*CATCHERR; | |
648 | while( <CATCHOUT> ) {} | |
649 | while( <CATCHERR> ) {} | |
49d635f9 RGS |
650 | |
651 | But there's no real need for *both* to be tempfiles... the following | |
652 | should work just as well, without deadlocking: | |
653 | ||
ac9dac7f RGS |
654 | use IPC::Open3; |
655 | use Symbol qw(gensym); | |
656 | use IO::File; | |
657 | local *CATCHERR = IO::File->new_tmpfile; | |
658 | my $pid = open3(gensym, \*CATCHOUT, ">&CATCHERR", "cmd"); | |
659 | while( <CATCHOUT> ) {} | |
660 | waitpid($pid, 0); | |
661 | seek CATCHERR, 0, 0; | |
662 | while( <CATCHERR> ) {} | |
49d635f9 RGS |
663 | |
664 | And it'll be faster, too, since we can begin processing the program's | |
665 | stdout immediately, rather than waiting for the program to finish. | |
666 | ||
68dc0745 | 667 | With any of these, you can change file descriptors before the call: |
668 | ||
ac9dac7f RGS |
669 | open(STDOUT, ">logfile"); |
670 | system("ls"); | |
68dc0745 | 671 | |
672 | or you can use Bourne shell file-descriptor redirection: | |
673 | ||
ac9dac7f RGS |
674 | $output = `$cmd 2>some_file`; |
675 | open (PIPE, "cmd 2>some_file |"); | |
68dc0745 | 676 | |
677 | You can also use file-descriptor redirection to make STDERR a | |
678 | duplicate of STDOUT: | |
679 | ||
ac9dac7f RGS |
680 | $output = `$cmd 2>&1`; |
681 | open (PIPE, "cmd 2>&1 |"); | |
68dc0745 | 682 | |
683 | Note that you I<cannot> simply open STDERR to be a dup of STDOUT | |
684 | in your Perl program and avoid calling the shell to do the redirection. | |
685 | This doesn't work: | |
686 | ||
ac9dac7f RGS |
687 | open(STDERR, ">&STDOUT"); |
688 | $alloutput = `cmd args`; # stderr still escapes | |
68dc0745 | 689 | |
690 | This fails because the open() makes STDERR go to where STDOUT was | |
691 | going at the time of the open(). The backticks then make STDOUT go to | |
692 | a string, but don't change STDERR (which still goes to the old | |
693 | STDOUT). | |
694 | ||
695 | Note that you I<must> use Bourne shell (sh(1)) redirection syntax in | |
696 | backticks, not csh(1)! Details on why Perl's system() and backtick | |
06a5f41f JH |
697 | and pipe opens all use the Bourne shell are in the |
698 | F<versus/csh.whynot> article in the "Far More Than You Ever Wanted To | |
49d635f9 | 699 | Know" collection in http://www.cpan.org/misc/olddoc/FMTEYEWTK.tgz . To |
06a5f41f | 700 | capture a command's STDERR and STDOUT together: |
68dc0745 | 701 | |
ac9dac7f RGS |
702 | $output = `cmd 2>&1`; # either with backticks |
703 | $pid = open(PH, "cmd 2>&1 |"); # or with an open pipe | |
704 | while (<PH>) { } # plus a read | |
c8db1d39 TC |
705 | |
706 | To capture a command's STDOUT but discard its STDERR: | |
707 | ||
ac9dac7f RGS |
708 | $output = `cmd 2>/dev/null`; # either with backticks |
709 | $pid = open(PH, "cmd 2>/dev/null |"); # or with an open pipe | |
710 | while (<PH>) { } # plus a read | |
c8db1d39 TC |
711 | |
712 | To capture a command's STDERR but discard its STDOUT: | |
713 | ||
ac9dac7f RGS |
714 | $output = `cmd 2>&1 1>/dev/null`; # either with backticks |
715 | $pid = open(PH, "cmd 2>&1 1>/dev/null |"); # or with an open pipe | |
716 | while (<PH>) { } # plus a read | |
c8db1d39 TC |
717 | |
718 | To exchange a command's STDOUT and STDERR in order to capture the STDERR | |
719 | but leave its STDOUT to come out our old STDERR: | |
720 | ||
ac9dac7f RGS |
721 | $output = `cmd 3>&1 1>&2 2>&3 3>&-`; # either with backticks |
722 | $pid = open(PH, "cmd 3>&1 1>&2 2>&3 3>&-|");# or with an open pipe | |
723 | while (<PH>) { } # plus a read | |
c8db1d39 TC |
724 | |
725 | To read both a command's STDOUT and its STDERR separately, it's easiest | |
2359510d SD |
726 | to redirect them separately to files, and then read from those files |
727 | when the program is done: | |
c8db1d39 | 728 | |
ac9dac7f | 729 | system("program args 1>program.stdout 2>program.stderr"); |
c8db1d39 TC |
730 | |
731 | Ordering is important in all these examples. That's because the shell | |
732 | processes file descriptor redirections in strictly left to right order. | |
733 | ||
ac9dac7f RGS |
734 | system("prog args 1>tmpfile 2>&1"); |
735 | system("prog args 2>&1 1>tmpfile"); | |
c8db1d39 TC |
736 | |
737 | The first command sends both standard out and standard error to the | |
738 | temporary file. The second command sends only the old standard output | |
739 | there, and the old standard error shows up on the old standard out. | |
68dc0745 | 740 | |
741 | =head2 Why doesn't open() return an error when a pipe open fails? | |
742 | ||
49d635f9 | 743 | If the second argument to a piped open() contains shell |
dfdf0730 MJD |
744 | metacharacters, perl fork()s, then exec()s a shell to decode the |
745 | metacharacters and eventually run the desired program. If the program | |
746 | couldn't be run, it's the shell that gets the message, not Perl. All | |
747 | your Perl program can find out is whether the shell itself could be | |
748 | successfully started. You can still capture the shell's STDERR and | |
749 | check it for error messages. See L<"How can I capture STDERR from an | |
750 | external command?"> elsewhere in this document, or use the | |
49d635f9 | 751 | IPC::Open3 module. |
dfdf0730 | 752 | |
49d635f9 | 753 | If there are no shell metacharacters in the argument of open(), Perl |
dfdf0730 MJD |
754 | runs the command directly, without using the shell, and can correctly |
755 | report whether the command started. | |
68dc0745 | 756 | |
757 | =head2 What's wrong with using backticks in a void context? | |
758 | ||
759 | Strictly speaking, nothing. Stylistically speaking, it's not a good | |
dfdf0730 MJD |
760 | way to write maintainable code. Perl has several operators for |
761 | running external commands. Backticks are one; they collect the output | |
762 | from the command for use in your program. The C<system> function is | |
197aec24 | 763 | another; it doesn't do this. |
68dc0745 | 764 | |
dfdf0730 MJD |
765 | Writing backticks in your program sends a clear message to the readers |
766 | of your code that you wanted to collect the output of the command. | |
767 | Why send a clear message that isn't true? | |
68dc0745 | 768 | |
769 | Consider this line: | |
770 | ||
ac9dac7f | 771 | `cat /etc/termcap`; |
68dc0745 | 772 | |
dfdf0730 MJD |
773 | You forgot to check C<$?> to see whether the program even ran |
774 | correctly. Even if you wrote | |
68dc0745 | 775 | |
ac9dac7f | 776 | print `cat /etc/termcap`; |
68dc0745 | 777 | |
a6dd486b | 778 | this code could and probably should be written as |
68dc0745 | 779 | |
ac9dac7f | 780 | system("cat /etc/termcap") == 0 |
68dc0745 | 781 | or die "cat program failed!"; |
782 | ||
ee891a00 RGS |
783 | which will echo the cat command's output as it is generated, instead |
784 | of waiting until the program has completed to print it out. It also | |
785 | checks the return value. | |
68dc0745 | 786 | |
ac9dac7f | 787 | C<system> also provides direct control over whether shell wildcard |
68dc0745 | 788 | processing may take place, whereas backticks do not. |
789 | ||
790 | =head2 How can I call backticks without shell processing? | |
791 | ||
49d635f9 RGS |
792 | This is a bit tricky. You can't simply write the command |
793 | like this: | |
68dc0745 | 794 | |
ac9dac7f | 795 | @ok = `grep @opts '$search_string' @filenames`; |
68dc0745 | 796 | |
ac003c96 RGS |
797 | As of Perl 5.8.0, you can use C<open()> with multiple arguments. |
798 | Just like the list forms of C<system()> and C<exec()>, no shell | |
49d635f9 RGS |
799 | escapes happen. |
800 | ||
ac9dac7f RGS |
801 | open( GREP, "-|", 'grep', @opts, $search_string, @filenames ); |
802 | chomp(@ok = <GREP>); | |
803 | close GREP; | |
49d635f9 RGS |
804 | |
805 | You can also: | |
68dc0745 | 806 | |
ac9dac7f RGS |
807 | my @ok = (); |
808 | if (open(GREP, "-|")) { | |
809 | while (<GREP>) { | |
810 | chomp; | |
811 | push(@ok, $_); | |
ac003c96 RGS |
812 | } |
813 | close GREP; | |
ac9dac7f RGS |
814 | } else { |
815 | exec 'grep', @opts, $search_string, @filenames; | |
816 | } | |
68dc0745 | 817 | |
ac003c96 RGS |
818 | Just as with C<system()>, no shell escapes happen when you C<exec()> a |
819 | list. Further examples of this can be found in L<perlipc/"Safe Pipe | |
820 | Opens">. | |
68dc0745 | 821 | |
ac003c96 RGS |
822 | Note that if you're using Windows, no solution to this vexing issue is |
823 | even possible. Even if Perl were to emulate C<fork()>, you'd still be | |
824 | stuck, because Windows does not have an argc/argv-style API. | |
c8db1d39 | 825 | |
54310121 | 826 | =head2 Why can't my script read from STDIN after I gave it EOF (^D on Unix, ^Z on MS-DOS)? |
68dc0745 | 827 | |
a6dd486b | 828 | Some stdio's set error and eof flags that need clearing. The |
68dc0745 | 829 | POSIX module defines clearerr() that you can use. That is the |
830 | technically correct way to do it. Here are some less reliable | |
831 | workarounds: | |
832 | ||
833 | =over 4 | |
834 | ||
835 | =item 1 | |
836 | ||
837 | Try keeping around the seekpointer and go there, like this: | |
838 | ||
ac9dac7f RGS |
839 | $where = tell(LOG); |
840 | seek(LOG, $where, 0); | |
68dc0745 | 841 | |
842 | =item 2 | |
843 | ||
844 | If that doesn't work, try seeking to a different part of the file and | |
845 | then back. | |
846 | ||
847 | =item 3 | |
848 | ||
849 | If that doesn't work, try seeking to a different part of | |
850 | the file, reading something, and then seeking back. | |
851 | ||
852 | =item 4 | |
853 | ||
854 | If that doesn't work, give up on your stdio package and use sysread. | |
855 | ||
856 | =back | |
857 | ||
858 | =head2 How can I convert my shell script to perl? | |
859 | ||
860 | Learn Perl and rewrite it. Seriously, there's no simple converter. | |
861 | Things that are awkward to do in the shell are easy to do in Perl, and | |
862 | this very awkwardness is what would make a shell->perl converter | |
863 | nigh-on impossible to write. By rewriting it, you'll think about what | |
864 | you're really trying to do, and hopefully will escape the shell's | |
46fc3d4c | 865 | pipeline datastream paradigm, which while convenient for some matters, |
68dc0745 | 866 | causes many inefficiencies. |
867 | ||
868 | =head2 Can I use perl to run a telnet or ftp session? | |
869 | ||
46fc3d4c | 870 | Try the Net::FTP, TCP::Client, and Net::Telnet modules (available from |
a93751fa | 871 | CPAN). http://www.cpan.org/scripts/netstuff/telnet.emul.shar |
46fc3d4c | 872 | will also help for emulating the telnet protocol, but Net::Telnet is |
873 | quite probably easier to use.. | |
874 | ||
875 | If all you want to do is pretend to be telnet but don't need | |
876 | the initial telnet handshaking, then the standard dual-process | |
877 | approach will suffice: | |
878 | ||
ac9dac7f RGS |
879 | use IO::Socket; # new in 5.004 |
880 | $handle = IO::Socket::INET->new('www.perl.com:80') | |
881 | or die "can't connect to port 80 on www.perl.com: $!"; | |
882 | $handle->autoflush(1); | |
883 | if (fork()) { # XXX: undef means failure | |
884 | select($handle); | |
885 | print while <STDIN>; # everything from stdin to socket | |
886 | } else { | |
887 | print while <$handle>; # everything from socket to stdout | |
888 | } | |
889 | close $handle; | |
890 | exit; | |
68dc0745 | 891 | |
892 | =head2 How can I write expect in Perl? | |
893 | ||
894 | Once upon a time, there was a library called chat2.pl (part of the | |
c8db1d39 TC |
895 | standard perl distribution), which never really got finished. If you |
896 | find it somewhere, I<don't use it>. These days, your best bet is to | |
897 | look at the Expect module available from CPAN, which also requires two | |
898 | other modules from CPAN, IO::Pty and IO::Stty. | |
68dc0745 | 899 | |
900 | =head2 Is there a way to hide perl's command line from programs such as "ps"? | |
901 | ||
902 | First of all note that if you're doing this for security reasons (to | |
903 | avoid people seeing passwords, for example) then you should rewrite | |
904 | your program so that critical information is never given as an | |
905 | argument. Hiding the arguments won't make your program completely | |
906 | secure. | |
907 | ||
908 | To actually alter the visible command line, you can assign to the | |
909 | variable $0 as documented in L<perlvar>. This won't work on all | |
910 | operating systems, though. Daemon programs like sendmail place their | |
911 | state there, as in: | |
912 | ||
ac9dac7f | 913 | $0 = "orcus [accepting connections]"; |
68dc0745 | 914 | |
915 | =head2 I {changed directory, modified my environment} in a perl script. How come the change disappeared when I exited the script? How do I get my changes to be visible? | |
916 | ||
917 | =over 4 | |
918 | ||
919 | =item Unix | |
920 | ||
a6dd486b | 921 | In the strictest sense, it can't be done--the script executes as a |
68dc0745 | 922 | different process from the shell it was started from. Changes to a |
a6dd486b | 923 | process are not reflected in its parent--only in any children |
68dc0745 | 924 | created after the change. There is shell magic that may allow you to |
925 | fake it by eval()ing the script's output in your shell; check out the | |
197aec24 | 926 | comp.unix.questions FAQ for details. |
68dc0745 | 927 | |
68dc0745 | 928 | =back |
929 | ||
930 | =head2 How do I close a process's filehandle without waiting for it to complete? | |
931 | ||
932 | Assuming your system supports such things, just send an appropriate signal | |
a6dd486b | 933 | to the process (see L<perlfunc/"kill">). It's common to first send a TERM |
68dc0745 | 934 | signal, wait a little bit, and then send a KILL signal to finish it off. |
935 | ||
936 | =head2 How do I fork a daemon process? | |
937 | ||
938 | If by daemon process you mean one that's detached (disassociated from | |
939 | its tty), then the following process is reported to work on most | |
940 | Unixish systems. Non-Unix users should check their Your_OS::Process | |
941 | module for other solutions. | |
942 | ||
943 | =over 4 | |
944 | ||
945 | =item * | |
946 | ||
197aec24 | 947 | Open /dev/tty and use the TIOCNOTTY ioctl on it. See L<tty> |
c8db1d39 TC |
948 | for details. Or better yet, you can just use the POSIX::setsid() |
949 | function, so you don't have to worry about process groups. | |
68dc0745 | 950 | |
951 | =item * | |
952 | ||
953 | Change directory to / | |
954 | ||
955 | =item * | |
956 | ||
957 | Reopen STDIN, STDOUT, and STDERR so they're not connected to the old | |
958 | tty. | |
959 | ||
960 | =item * | |
961 | ||
962 | Background yourself like this: | |
963 | ||
ac9dac7f | 964 | fork && exit; |
68dc0745 | 965 | |
966 | =back | |
967 | ||
1a91aff4 GS |
968 | The Proc::Daemon module, available from CPAN, provides a function to |
969 | perform these actions for you. | |
970 | ||
68dc0745 | 971 | =head2 How do I find out if I'm running interactively or not? |
972 | ||
ac9dac7f | 973 | Good question. Sometimes C<-t STDIN> and C<-t STDOUT> can give clues, |
68dc0745 | 974 | sometimes not. |
975 | ||
ac9dac7f RGS |
976 | if (-t STDIN && -t STDOUT) { |
977 | print "Now what? "; | |
978 | } | |
68dc0745 | 979 | |
980 | On POSIX systems, you can test whether your own process group matches | |
981 | the current process group of your controlling terminal as follows: | |
982 | ||
ac9dac7f RGS |
983 | use POSIX qw/getpgrp tcgetpgrp/; |
984 | ||
985 | # Some POSIX systems, such as Linux, can be | |
986 | # without a /dev/tty at boot time. | |
987 | if (!open(TTY, "/dev/tty")) { | |
988 | print "no tty\n"; | |
989 | } else { | |
990 | $tpgrp = tcgetpgrp(fileno(*TTY)); | |
991 | $pgrp = getpgrp(); | |
992 | if ($tpgrp == $pgrp) { | |
993 | print "foreground\n"; | |
994 | } else { | |
995 | print "background\n"; | |
996 | } | |
997 | } | |
68dc0745 | 998 | |
999 | =head2 How do I timeout a slow event? | |
1000 | ||
1001 | Use the alarm() function, probably in conjunction with a signal | |
b73a15ae | 1002 | handler, as documented in L<perlipc/"Signals"> and the section on |
b432a672 | 1003 | "Signals" in the Camel. You may instead use the more flexible |
b73a15ae | 1004 | Sys::AlarmCall module available from CPAN. |
68dc0745 | 1005 | |
49d635f9 RGS |
1006 | The alarm() function is not implemented on all versions of Windows. |
1007 | Check the documentation for your specific version of Perl. | |
1008 | ||
68dc0745 | 1009 | =head2 How do I set CPU limits? |
c195e131 RGS |
1010 | X<BSD::Resource> X<limit> X<CPU> |
1011 | ||
1012 | (contributed by Xho) | |
1013 | ||
1014 | Use the C<BSD::Resource> module from CPAN. As an example: | |
68dc0745 | 1015 | |
c195e131 RGS |
1016 | use BSD::Resource; |
1017 | setrlimit(RLIMIT_CPU,10,20) or die $!; | |
1018 | ||
1019 | This sets the soft and hard limits to 10 and 20 seconds, respectively. | |
1020 | After 10 seconds of time spent running on the CPU (not "wall" time), | |
1021 | the process will be sent a signal (XCPU on some systems) which, if not | |
1022 | trapped, will cause the process to terminate. If that signal is | |
1023 | trapped, then after 10 more seconds (20 seconds in total) the process | |
1024 | will be killed with a non-trappable signal. | |
1025 | ||
1026 | See the C<BSD::Resource> and your systems documentation for the gory | |
1027 | details. | |
68dc0745 | 1028 | |
1029 | =head2 How do I avoid zombies on a Unix system? | |
1030 | ||
1031 | Use the reaper code from L<perlipc/"Signals"> to call wait() when a | |
1032 | SIGCHLD is received, or else use the double-fork technique described | |
49d635f9 | 1033 | in L<perlfaq8/"How do I start a process in the background?">. |
68dc0745 | 1034 | |
1035 | =head2 How do I use an SQL database? | |
1036 | ||
04d666b1 RGS |
1037 | The DBI module provides an abstract interface to most database |
1038 | servers and types, including Oracle, DB2, Sybase, mysql, Postgresql, | |
1039 | ODBC, and flat files. The DBI module accesses each database type | |
1040 | through a database driver, or DBD. You can see a complete list of | |
1041 | available drivers on CPAN: http://www.cpan.org/modules/by-module/DBD/ . | |
1042 | You can read more about DBI on http://dbi.perl.org . | |
1043 | ||
1044 | Other modules provide more specific access: Win32::ODBC, Alzabo, iodbc, | |
1045 | and others found on CPAN Search: http://search.cpan.org . | |
68dc0745 | 1046 | |
1047 | =head2 How do I make a system() exit on control-C? | |
1048 | ||
1049 | You can't. You need to imitate the system() call (see L<perlipc> for | |
1050 | sample code) and then have a signal handler for the INT signal that | |
c8db1d39 TC |
1051 | passes the signal on to the subprocess. Or you can check for it: |
1052 | ||
ac9dac7f RGS |
1053 | $rc = system($cmd); |
1054 | if ($rc & 127) { die "signal death" } | |
68dc0745 | 1055 | |
1056 | =head2 How do I open a file without blocking? | |
1057 | ||
1058 | If you're lucky enough to be using a system that supports | |
1059 | non-blocking reads (most Unixish systems do), you need only to use the | |
1060 | O_NDELAY or O_NONBLOCK flag from the Fcntl module in conjunction with | |
1061 | sysopen(): | |
1062 | ||
ac9dac7f RGS |
1063 | use Fcntl; |
1064 | sysopen(FH, "/foo/somefile", O_WRONLY|O_NDELAY|O_CREAT, 0644) | |
1065 | or die "can't open /foo/somefile: $!": | |
68dc0745 | 1066 | |
c98c5709 RGS |
1067 | =head2 How do I tell the difference between errors from the shell and perl? |
1068 | ||
ac003c96 | 1069 | (answer contributed by brian d foy) |
c98c5709 RGS |
1070 | |
1071 | When you run a Perl script, something else is running the script for you, | |
1072 | and that something else may output error messages. The script might | |
1073 | emit its own warnings and error messages. Most of the time you cannot | |
1074 | tell who said what. | |
1075 | ||
1076 | You probably cannot fix the thing that runs perl, but you can change how | |
1077 | perl outputs its warnings by defining a custom warning and die functions. | |
1078 | ||
1079 | Consider this script, which has an error you may not notice immediately. | |
1080 | ||
1081 | #!/usr/locl/bin/perl | |
1082 | ||
1083 | print "Hello World\n"; | |
1084 | ||
1085 | I get an error when I run this from my shell (which happens to be | |
1086 | bash). That may look like perl forgot it has a print() function, | |
1087 | but my shebang line is not the path to perl, so the shell runs the | |
1088 | script, and I get the error. | |
1089 | ||
1090 | $ ./test | |
1091 | ./test: line 3: print: command not found | |
1092 | ||
1093 | A quick and dirty fix involves a little bit of code, but this may be all | |
1094 | you need to figure out the problem. | |
1095 | ||
1096 | #!/usr/bin/perl -w | |
6670e5e7 | 1097 | |
c98c5709 RGS |
1098 | BEGIN { |
1099 | $SIG{__WARN__} = sub{ print STDERR "Perl: ", @_; }; | |
1100 | $SIG{__DIE__} = sub{ print STDERR "Perl: ", @_; exit 1}; | |
1101 | } | |
6670e5e7 | 1102 | |
c98c5709 RGS |
1103 | $a = 1 + undef; |
1104 | $x / 0; | |
1105 | __END__ | |
1106 | ||
1107 | The perl message comes out with "Perl" in front. The BEGIN block | |
1108 | works at compile time so all of the compilation errors and warnings | |
1109 | get the "Perl:" prefix too. | |
1110 | ||
1111 | Perl: Useless use of division (/) in void context at ./test line 9. | |
1112 | Perl: Name "main::a" used only once: possible typo at ./test line 8. | |
1113 | Perl: Name "main::x" used only once: possible typo at ./test line 9. | |
1114 | Perl: Use of uninitialized value in addition (+) at ./test line 8. | |
1115 | Perl: Use of uninitialized value in division (/) at ./test line 9. | |
1116 | Perl: Illegal division by zero at ./test line 9. | |
1117 | Perl: Illegal division by zero at -e line 3. | |
1118 | ||
1119 | If I don't see that "Perl:", it's not from perl. | |
1120 | ||
1121 | You could also just know all the perl errors, and although there are | |
1122 | some people who may know all of them, you probably don't. However, they | |
1123 | all should be in the perldiag manpage. If you don't find the error in | |
1124 | there, it probably isn't a perl error. | |
1125 | ||
1126 | Looking up every message is not the easiest way, so let perl to do it | |
1127 | for you. Use the diagnostics pragma with turns perl's normal messages | |
1128 | into longer discussions on the topic. | |
1129 | ||
1130 | use diagnostics; | |
1131 | ||
1132 | If you don't get a paragraph or two of expanded discussion, it | |
1133 | might not be perl's message. | |
1134 | ||
d92eb7b0 GS |
1135 | =head2 How do I install a module from CPAN? |
1136 | ||
1137 | The easiest way is to have a module also named CPAN do it for you. | |
197aec24 | 1138 | This module comes with perl version 5.004 and later. |
76817d6d | 1139 | |
ac9dac7f | 1140 | $ perl -MCPAN -e shell |
76817d6d | 1141 | |
ac9dac7f RGS |
1142 | cpan shell -- CPAN exploration and modules installation (v1.59_54) |
1143 | ReadLine support enabled | |
76817d6d | 1144 | |
ac9dac7f | 1145 | cpan> install Some::Module |
76817d6d | 1146 | |
197aec24 | 1147 | To manually install the CPAN module, or any well-behaved CPAN module |
76817d6d | 1148 | for that matter, follow these steps: |
68dc0745 | 1149 | |
1150 | =over 4 | |
1151 | ||
1152 | =item 1 | |
1153 | ||
1154 | Unpack the source into a temporary area. | |
1155 | ||
1156 | =item 2 | |
1157 | ||
ac9dac7f | 1158 | perl Makefile.PL |
68dc0745 | 1159 | |
1160 | =item 3 | |
1161 | ||
ac9dac7f | 1162 | make |
68dc0745 | 1163 | |
1164 | =item 4 | |
1165 | ||
ac9dac7f | 1166 | make test |
68dc0745 | 1167 | |
1168 | =item 5 | |
1169 | ||
ac9dac7f | 1170 | make install |
68dc0745 | 1171 | |
1172 | =back | |
1173 | ||
1174 | If your version of perl is compiled without dynamic loading, then you | |
1175 | just need to replace step 3 (B<make>) with B<make perl> and you will | |
1176 | get a new F<perl> binary with your extension linked in. | |
1177 | ||
c8db1d39 | 1178 | See L<ExtUtils::MakeMaker> for more details on building extensions. |
b432a672 AL |
1179 | See also the next question, "What's the difference between require |
1180 | and use?". | |
c8db1d39 TC |
1181 | |
1182 | =head2 What's the difference between require and use? | |
1183 | ||
1184 | Perl offers several different ways to include code from one file into | |
1185 | another. Here are the deltas between the various inclusion constructs: | |
1186 | ||
ac9dac7f | 1187 | 1) do $file is like eval `cat $file`, except the former |
5e3006a4 | 1188 | 1.1: searches @INC and updates %INC. |
c8db1d39 TC |
1189 | 1.2: bequeaths an *unrelated* lexical scope on the eval'ed code. |
1190 | ||
ac9dac7f | 1191 | 2) require $file is like do $file, except the former |
c8db1d39 TC |
1192 | 2.1: checks for redundant loading, skipping already loaded files. |
1193 | 2.2: raises an exception on failure to find, compile, or execute $file. | |
1194 | ||
ac9dac7f | 1195 | 3) require Module is like require "Module.pm", except the former |
c8db1d39 TC |
1196 | 3.1: translates each "::" into your system's directory separator. |
1197 | 3.2: primes the parser to disambiguate class Module as an indirect object. | |
1198 | ||
ac9dac7f | 1199 | 4) use Module is like require Module, except the former |
c8db1d39 TC |
1200 | 4.1: loads the module at compile time, not run-time. |
1201 | 4.2: imports symbols and semantics from that package to the current one. | |
1202 | ||
1203 | In general, you usually want C<use> and a proper Perl module. | |
46fc3d4c | 1204 | |
1205 | =head2 How do I keep my own module/library directory? | |
1206 | ||
ac003c96 RGS |
1207 | When you build modules, tell Perl where to install the modules. |
1208 | ||
1209 | For C<Makefile.PL>-based distributions, use the PREFIX and LIB options | |
1210 | when generating Makefiles: | |
46fc3d4c | 1211 | |
ac9dac7f | 1212 | perl Makefile.PL PREFIX=/mydir/perl LIB=/mydir/perl/lib |
46fc3d4c | 1213 | |
ac003c96 RGS |
1214 | You can set this in your CPAN.pm configuration so modules automatically install |
1215 | in your private library directory when you use the CPAN.pm shell: | |
46fc3d4c | 1216 | |
ac003c96 RGS |
1217 | % cpan |
1218 | cpan> o conf makepl_arg PREFIX=/mydir/perl,LIB=/mydir/perl/lib | |
1219 | cpan> o conf commit | |
46fc3d4c | 1220 | |
ac003c96 | 1221 | For C<Build.PL>-based distributions, use the --install_base option: |
65acb1b1 | 1222 | |
ac003c96 RGS |
1223 | perl Build.PL --install_base /mydir/perl |
1224 | ||
1225 | You can configure CPAN.pm to automatically use this option too: | |
65acb1b1 | 1226 | |
ac003c96 RGS |
1227 | % cpan |
1228 | cpan> o conf mbuild_arg --install_base /mydir/perl | |
1229 | cpan> o conf commit | |
46fc3d4c | 1230 | |
1231 | =head2 How do I add the directory my program lives in to the module/library search path? | |
1232 | ||
ac003c96 RGS |
1233 | (contributed by brian d foy) |
1234 | ||
1235 | If you know the directory already, you can add it to C<@INC> as you would | |
1236 | for any other directory. You might <use lib> if you know the directory | |
1237 | at compile time: | |
1238 | ||
1239 | use lib $directory; | |
1240 | ||
1241 | The trick in this task is to find the directory. Before your script does | |
1242 | anything else (such as a C<chdir>), you can get the current working | |
1243 | directory with the C<Cwd> module, which comes with Perl: | |
1244 | ||
1245 | BEGIN { | |
1246 | use Cwd; | |
1247 | our $directory = cwd; | |
1248 | } | |
1249 | ||
1250 | use lib $directory; | |
1251 | ||
1252 | You can do a similar thing with the value of C<$0>, which holds the | |
1253 | script name. That might hold a relative path, but C<rel2abs> can turn | |
1254 | it into an absolute path. Once you have the | |
1255 | ||
1256 | BEGIN { | |
1257 | use File::Spec::Functions qw(rel2abs); | |
1258 | use File::Basename qw(dirname); | |
1259 | ||
1260 | my $path = rel2abs( $0 ); | |
1261 | our $directory = dirname( $path ); | |
1262 | } | |
1263 | ||
1264 | use lib $directory; | |
1265 | ||
1266 | The C<FindBin> module, which comes with Perl, might work. It searches | |
1267 | through C<$ENV{PATH}> (so your script has to be in one of those | |
1268 | directories). You can then use that directory (in C<$FindBin::Bin>) | |
1269 | to locate nearby directories you want to add: | |
1270 | ||
ac9dac7f | 1271 | use FindBin; |
ac003c96 | 1272 | use lib "$FindBin::Bin/../lib"; |
46fc3d4c | 1273 | |
f0d19b68 | 1274 | =head2 How do I add a directory to my include path (@INC) at runtime? |
46fc3d4c | 1275 | |
ac003c96 RGS |
1276 | Here are the suggested ways of modifying your include path, including |
1277 | environment variables, run-time switches, and in-code statements: | |
1278 | ||
1279 | =over 4 | |
1280 | ||
1281 | =item the PERLLIB environment variable | |
1282 | ||
1283 | $ export PERLLIB=/path/to/my/dir | |
1284 | $ perl program.pl | |
1285 | ||
1286 | =item the PERL5LIB environment variable | |
46fc3d4c | 1287 | |
ac003c96 RGS |
1288 | $ export PERL5LIB=/path/to/my/dir |
1289 | $ perl program.pl | |
1290 | ||
1291 | =item the perl -Idir command line flag | |
1292 | ||
1293 | $ perl -I/path/to/my/dir program.pl | |
1294 | ||
1295 | =item the use lib pragma: | |
1296 | ||
1297 | use lib "$ENV{HOME}/myown_perllib"; | |
1298 | ||
1299 | =back | |
46fc3d4c | 1300 | |
ac003c96 | 1301 | The last is particularly useful because it knows about machine |
46fc3d4c | 1302 | dependent architectures. The lib.pm pragmatic module was first |
1303 | included with the 5.002 release of Perl. | |
68dc0745 | 1304 | |
65acb1b1 TC |
1305 | =head2 What is socket.ph and where do I get it? |
1306 | ||
e9d185f8 | 1307 | It's a Perl 4 style file defining values for system networking |
65acb1b1 TC |
1308 | constants. Sometimes it is built using h2ph when Perl is installed, |
1309 | but other times it is not. Modern programs C<use Socket;> instead. | |
1310 | ||
500071f4 RGS |
1311 | =head1 REVISION |
1312 | ||
c195e131 | 1313 | Revision: $Revision: 10183 $ |
500071f4 | 1314 | |
c195e131 | 1315 | Date: $Date: 2007-11-07 09:35:12 +0100 (Wed, 07 Nov 2007) $ |
500071f4 RGS |
1316 | |
1317 | See L<perlfaq> for source control details and availability. | |
1318 | ||
fc36a67e | 1319 | =head1 AUTHOR AND COPYRIGHT |
1320 | ||
ee891a00 | 1321 | Copyright (c) 1997-2007 Tom Christiansen, Nathan Torkington, and |
7678cced | 1322 | other authors as noted. All rights reserved. |
5a964f20 | 1323 | |
5a7beb56 JH |
1324 | This documentation is free; you can redistribute it and/or modify it |
1325 | under the same terms as Perl itself. | |
5a964f20 TC |
1326 | |
1327 | Irrespective of its distribution, all code examples in this file | |
1328 | are hereby placed into the public domain. You are permitted and | |
1329 | encouraged to use this code in your own programs for fun | |
1330 | or for profit as you see fit. A simple comment in the code giving | |
1331 | credit would be courteous but is not required. |