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