X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlfaq8.pod;h=8152d49c7e3bc19902d1f51581eb92cb1c9e5881;hb=3f7c398ef4badd9c6ec5b40ea29141484c160f63;hp=e00d007912dfbc40ad7a3cbb5accc189c95ba7fe;hpb=49d635f9372392ae44fe4c5b62b06e41912ae0c9;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlfaq8.pod b/pod/perlfaq8.pod index e00d007..8152d49 100644 --- a/pod/perlfaq8.pod +++ b/pod/perlfaq8.pod @@ -1,6 +1,6 @@ =head1 NAME -perlfaq8 - System Interaction ($Revision: 1.14 $, $Date: 2002/11/10 17:35:47 $) +perlfaq8 - System Interaction ($Revision: 1.23 $, $Date: 2005/01/03 18:43:37 $) =head1 DESCRIPTION @@ -77,7 +77,7 @@ Or like this: Controlling input buffering is a remarkably system-dependent matter. On many systems, you can just use the B command as shown in L, but as you see, that's already getting you into -portability snags. +portability snags. open(TTY, "+/dev/tty 2>&1"; @@ -188,14 +188,14 @@ positions, etc, you might wish to use Term::Cap module: =head2 How do I get the screen size? -If you have Term::ReadKey module installed from CPAN, +If you have Term::ReadKey module installed from CPAN, you can use it to fetch the width and height in characters and in pixels: use Term::ReadKey; ($wchar, $hchar, $wpixels, $hpixels) = GetTerminalSize(); -This is more portable than the raw C, but not as +This is more portable than the raw C, but not as illustrative: require 'sys/ioctl.ph'; @@ -275,7 +275,7 @@ next. If you expect characters to get to your device when you print() them, you'll want to autoflush that filehandle. You can use select() -and the C<$|> variable to control autoflushing (see L +and the C<$|> variable to control autoflushing (see L> and L, or L, ``How do I flush/unbuffer an output filehandle? Why must I do this?''): @@ -383,11 +383,11 @@ not an issue with C. You have to be prepared to "reap" the child process when it finishes. $SIG{CHLD} = sub { wait }; - + $SIG{CHLD} = 'IGNORE'; - -You can also use a double fork. You immediately wait() for your -first child, and the init daemon will wait() for your grandchild once + +You can also use a double fork. You immediately wait() for your +first child, and the init daemon will wait() for your grandchild once it exits. unless ($pid = fork) { @@ -413,31 +413,30 @@ foregrounded process group, which you then trap in your process. Signals are documented in L and the section on ``Signals'' in the Camel. -Be warned that very few C libraries are re-entrant. Therefore, if you -attempt to print() in a handler that got invoked during another stdio -operation your internal structures will likely be in an -inconsistent state, and your program will dump core. You can -sometimes avoid this by using syswrite() instead of print(). +You can set the values of the %SIG hash to be the functions you want +to handle the signal. After perl catches the signal, it looks in %SIG +for a key with the same name as the signal, then calls the subroutine +value for that key. + + # as an anonymous subroutine + + $SIG{INT} = sub { syswrite(STDERR, "ouch\n", 5 ) }; + + # or a reference to a function + + $SIG{INT} = \&ouch; + + # or the name of the function as a string + + $SIG{INT} = "ouch"; + +Perl versions before 5.8 had in its C source code signal handlers which +would catch the signal and possibly run a Perl function that you had set +in %SIG. This violated the rules of signal handling at that level +causing perl to dump core. Since version 5.8.0, perl looks at %SIG +*after* the signal has been caught, rather than while it is being caught. +Previous versions of this answer were incorrect. -Unless you're exceedingly careful, the only safe things to do inside a -signal handler are (1) set a variable and (2) exit. In the first case, -you should only set a variable in such a way that malloc() is not -called (eg, by setting a variable that already has a value). - -For example: - - $Interrupted = 0; # to ensure it has a value - $SIG{INT} = sub { - $Interrupted++; - syswrite(STDERR, "ouch\n", 5); - } - -However, because syscalls restart by default, you'll find that if -you're in a "slow" call, such as , read(), connect(), or -wait(), that the only way to terminate them is by "longjumping" out; -that is, by raising an exception. See the time-out handler for a -blocking flock() in L or the section on ``Signals'' -in the Camel book. =head2 How do I modify the shadow password file on a Unix system? @@ -445,8 +444,8 @@ If perl was installed correctly and your shadow library was written properly, the getpw*() functions described in L should in theory provide (read-only) access to entries in the shadow password file. To change the file, make a new shadow password file (the format -varies from system to system--see L for specifics) and use -pwd_mkdb(8) to install it (see L for more details). +varies from system to system--see L for specifics) and use +pwd_mkdb(8) to install it (see L for more details). =head2 How do I set the time and date? @@ -511,14 +510,14 @@ something like this: Release 5 of Perl added the END block, which can be used to simulate atexit(). Each package's END block is called when the program or -thread ends (see L manpage for more details). +thread ends (see L manpage for more details). For example, you can use this to make sure your filter program managed to finish its output without filling up the disk: END { close(STDOUT) || die "stdout close failed: $!"; - } + } The END block isn't called when untrapped signals kill the program, though, so if you use END blocks you should also use @@ -556,7 +555,10 @@ syscall(), you can use the syscall function (documented in L). Remember to check the modules that came with your distribution, and -CPAN as well--someone may already have written a module to do it. +CPAN as well---someone may already have written a module to do it. On +Windows, try Win32::API. On Macs, try Mac::Carbon. If no module +has an interface to the C function, you can inline a bit of C in your +Perl source with Inline::C. =head2 Where do I get the include files to do ioctl() or syscall()? @@ -594,8 +596,8 @@ scripts inherently insecure. Perl gives you a number of options The IPC::Open2 module (part of the standard perl distribution) is an easy-to-use approach that internally uses pipe(), fork(), and exec() to do the job. Make sure you read the deadlock warnings in its documentation, -though (see L). See -L and +though (see L). See +L and L You may also use the IPC::Open3 module (part of the standard perl @@ -746,10 +748,10 @@ but leave its STDOUT to come out our old STDERR: while () { } # plus a read To read both a command's STDOUT and its STDERR separately, it's easiest -and safest to redirect them separately to files, and then read from those -files when the program is done: +to redirect them separately to files, and then read from those files +when the program is done: - system("program args 1>/tmp/program.stdout 2>/tmp/program.stderr"); + system("program args 1>program.stdout 2>program.stderr"); Ordering is important in all these examples. That's because the shell processes file descriptor redirections in strictly left to right order. @@ -783,7 +785,7 @@ Strictly speaking, nothing. Stylistically speaking, it's not a good way to write maintainable code. Perl has several operators for running external commands. Backticks are one; they collect the output from the command for use in your program. The C function is -another; it doesn't do this. +another; it doesn't do this. Writing backticks in your program sends a clear message to the readers of your code that you wanted to collect the output of the command. @@ -944,7 +946,7 @@ different process from the shell it was started from. Changes to a process are not reflected in its parent--only in any children created after the change. There is shell magic that may allow you to fake it by eval()ing the script's output in your shell; check out the -comp.unix.questions FAQ for details. +comp.unix.questions FAQ for details. =back @@ -965,7 +967,7 @@ module for other solutions. =item * -Open /dev/tty and use the TIOCNOTTY ioctl on it. See L +Open /dev/tty and use the TIOCNOTTY ioctl on it. See L for details. Or better yet, you can just use the POSIX::setsid() function, so you don't have to worry about process groups. @@ -1033,9 +1035,15 @@ in L. =head2 How do I use an SQL database? -There are a number of excellent interfaces to SQL databases. See the -DBD::* modules available from http://www.cpan.org/modules/by-module/DBD/ . -A lot of information on this can be found at http://dbi.perl.org/ +The DBI module provides an abstract interface to most database +servers and types, including Oracle, DB2, Sybase, mysql, Postgresql, +ODBC, and flat files. The DBI module accesses each database type +through a database driver, or DBD. You can see a complete list of +available drivers on CPAN: http://www.cpan.org/modules/by-module/DBD/ . +You can read more about DBI on http://dbi.perl.org . + +Other modules provide more specific access: Win32::ODBC, Alzabo, iodbc, +and others found on CPAN Search: http://search.cpan.org . =head2 How do I make a system() exit on control-C? @@ -1044,7 +1052,7 @@ sample code) and then have a signal handler for the INT signal that passes the signal on to the subprocess. Or you can check for it: $rc = system($cmd); - if ($rc & 127) { die "signal death" } + if ($rc & 127) { die "signal death" } =head2 How do I open a file without blocking? @@ -1054,22 +1062,90 @@ O_NDELAY or O_NONBLOCK flag from the Fcntl module in conjunction with sysopen(): use Fcntl; - sysopen(FH, "/tmp/somefile", O_WRONLY|O_NDELAY|O_CREAT, 0644) - or die "can't open /tmp/somefile: $!": + sysopen(FH, "/foo/somefile", O_WRONLY|O_NDELAY|O_CREAT, 0644) + or die "can't open /foo/somefile: $!": + +=head2 How do I tell the difference between errors from the shell and perl? + +(answer contributed by brian d foy, C<< >> + +When you run a Perl script, something else is running the script for you, +and that something else may output error messages. The script might +emit its own warnings and error messages. Most of the time you cannot +tell who said what. + +You probably cannot fix the thing that runs perl, but you can change how +perl outputs its warnings by defining a custom warning and die functions. + +Consider this script, which has an error you may not notice immediately. + + #!/usr/locl/bin/perl + + print "Hello World\n"; + +I get an error when I run this from my shell (which happens to be +bash). That may look like perl forgot it has a print() function, +but my shebang line is not the path to perl, so the shell runs the +script, and I get the error. + + $ ./test + ./test: line 3: print: command not found + +A quick and dirty fix involves a little bit of code, but this may be all +you need to figure out the problem. + + #!/usr/bin/perl -w + + BEGIN { + $SIG{__WARN__} = sub{ print STDERR "Perl: ", @_; }; + $SIG{__DIE__} = sub{ print STDERR "Perl: ", @_; exit 1}; + } + + $a = 1 + undef; + $x / 0; + __END__ + +The perl message comes out with "Perl" in front. The BEGIN block +works at compile time so all of the compilation errors and warnings +get the "Perl:" prefix too. + + Perl: Useless use of division (/) in void context at ./test line 9. + Perl: Name "main::a" used only once: possible typo at ./test line 8. + Perl: Name "main::x" used only once: possible typo at ./test line 9. + Perl: Use of uninitialized value in addition (+) at ./test line 8. + Perl: Use of uninitialized value in division (/) at ./test line 9. + Perl: Illegal division by zero at ./test line 9. + Perl: Illegal division by zero at -e line 3. + +If I don't see that "Perl:", it's not from perl. + +You could also just know all the perl errors, and although there are +some people who may know all of them, you probably don't. However, they +all should be in the perldiag manpage. If you don't find the error in +there, it probably isn't a perl error. + +Looking up every message is not the easiest way, so let perl to do it +for you. Use the diagnostics pragma with turns perl's normal messages +into longer discussions on the topic. + + use diagnostics; + +If you don't get a paragraph or two of expanded discussion, it +might not be perl's message. =head2 How do I install a module from CPAN? The easiest way is to have a module also named CPAN do it for you. -This module comes with perl version 5.004 and later. +This module comes with perl version 5.004 and later. $ perl -MCPAN -e shell cpan shell -- CPAN exploration and modules installation (v1.59_54) ReadLine support enabled - cpan> install Some::Module + cpan> install Some::Module -To manually install the CPAN module, or any well-behaved CPAN module +To manually install the CPAN module, or any well-behaved CPAN module for that matter, follow these steps: =over 4 @@ -1129,20 +1205,20 @@ In general, you usually want C and a proper Perl module. =head2 How do I keep my own module/library directory? -When you build modules, use the PREFIX option when generating +When you build modules, use the PREFIX and LIB options when generating Makefiles: - perl Makefile.PL PREFIX=/u/mydir/perl + perl Makefile.PL PREFIX=/mydir/perl LIB=/mydir/perl/lib then either set the PERL5LIB environment variable before you run scripts that use the modules/libraries (see L) or say - use lib '/u/mydir/perl'; + use lib '/mydir/perl/lib'; This is almost the same as BEGIN { - unshift(@INC, '/u/mydir/perl'); + unshift(@INC, '/mydir/perl/lib'); } except that the lib module checks for machine-dependent subdirectories. @@ -1154,7 +1230,7 @@ See Perl's L for more information. use lib "$FindBin::Bin"; use your_own_modules; -=head2 How do I add a directory to my include path at runtime? +=head2 How do I add a directory to my include path (@INC) at runtime? Here are the suggested ways of modifying your include path: @@ -1176,8 +1252,8 @@ but other times it is not. Modern programs C instead. =head1 AUTHOR AND COPYRIGHT -Copyright (c) 1997-2002 Tom Christiansen and Nathan Torkington. -All rights reserved. +Copyright (c) 1997-2005 Tom Christiansen, Nathan Torkington, and +other authors as noted. All rights reserved. This documentation is free; you can redistribute it and/or modify it under the same terms as Perl itself.