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