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